Creating Custom Packages

Learn how to create custom packages using the packaging engine. As part of the Unified Assurance platform, the packaging engine allows you to create a collection of configurations, custom UIs, and customizations to Unified Assurance, which can then be easily migrated to another Unified Assurance instance.

An advantage to using Unified Assurance packaging architecture over static files is the inherent update capability it possesses. Through the Package Management interface, files can be automatically updated, and the database configurations can be run in a sequential series.

This chapter details the standards for different types of packages, how to support updatable packages, the utilities available for packages, and best practices.

For the Unified Assurance packaging engine to recognize and process a package, it requires a Package.def file. This file is a JSON formatted definition that contains information about the package and any install actions that need to be performed, such as licensing, pre-install actions, and post-install actions. Package.def is the only required file that a package must contain at the root level, and it must contain the standard Package.def directives.

To create a package:

(Optional) Create the contents of the package type: rules, custom UIs, vendor binaries, and so on.
Define the Package.def file based on package type and requirements.
Run the Unified Assurance Package utility:

$A1BASEDIR/bin/Package create coreDatabase-processDB

You should now have two new files in $A1BASEDIR/tmp:

-   coreDatabase-processDB-6.1.0.0.0.def

-   coreDatabase-processDB-6.1.0.0.0-l64.pkg

To install the newly created package:

Copy the new .pkg and .def files into $A1BASEDIR/distrib/packages.

Run the following command:

$A1BASEDIR/bin/Package install coreDatabase-processDB-6.0.5.0.0 --depot /$A1BASEDIR/tmp

Naming Conventions

The standard package name uses lower camel case and is made up of:

A prefix. To avoid naming conflicts with Unified Assurance default packages, use the custom prefix for custom packages.
A base name.
A type suffix. Each package can only have one type. If your project needs multiple types of package, for example, -ui and -schemaDB, use multiple packages bundled together for maintainability.

For example, in the default coreWeb-ui package, the prefix is core, the base name is Web, and the type suffix is -ui.

Dependencies and Bundling

If a package requires another package to be installed first in order to run, you can use dependencies to ensure everything is present before installation. The entire tree of dependencies is checked before install and this determines the order the packages are installed. For example, if coreDiscovery-ui requires coreDiscovery-schemaDB, which requires vendorMySQL-app, the order of install would be: vendorMySQL-app -> coreDiscovery-schemaDB -> coreDiscovery-ui.

Bundling can be used to simplify package installations for a group of custom packages by bringing together, as dependencies, all the required pieces for a project at the top-level.

About Package.def Files

A Package.def file is the only file required to build a package. It is in JSON format and must be present at the root level of the package folder structure before you build the package. It provides information to the package engine about how and where to install the package, as well as documentation and dependencies for the package.

The contents of Package.def files vary based on the package type. See Package Types for examples of different Package.def files.

Because Package.def contains the installation instructions for a package, the build process separates it from the folder structure and does not include it in the built package file. The build process results in two files, Package.def and the .pkg file, both of which Unified Assurance needs to install the package.

The following Package.def template shows the required JSON keys that must be present in any Package.def, even if the values are empty:

{
    "#Comment<N>": "<COMMENT>",
    "About": {
        "FullName":      "<FULLNAME>",
        "PackageName":   "<PACKAGENAME>",
        "License":       "none",
        "Server":        "<SERVER>",
        "Type":          "Package",
        "Directory":     "<DIRECTORY>",
        "Description":   "<DESCRIPTION>",
        "ReleaseNotes":  [
            "<RELEASENOTES>"
            ...
        ],
        "Version":       "<VERSION>",
        "ServiceImpact": <IMPACT>,
        "Rollback":      true,
        "Dependencies": [
            {
                "<DEPPACKAGE>": "<DEPVERSION>"
            },
            ...
        ],
        "Platforms": {
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [
        <ACTIONS>
    ],
    "PreUninstall":  [],
    "PostInstall":   [
        <ACTIONS>
    ],
    "PostUninstall": []
}

where:

<N> is the unique number for a comment.
<COMMENT> is a comment for the package.
<FULLNAME> is the full display name of the package. For example, Custom Device UI.
<PACKAGENAME> is the name of the package folder. For example, customDevice.
License identifies the Unified Assurance license required to install and use this package. Use none for custom packages.
<SERVER> is the Unified Assurance server type to install the package on. Allowed values are Any, Presentation, or Database.
<TYPE> is the Unified Assurance package type. Use Package.
<DIRECTORY> is the directory to install package contents to. The location depends on the package type. See Package Types for information about the location for each package type.
<DESCRIPTION> is the package description. For example, Package for a custom device UI.

<RELEASENOTES> is an array of lines for package release notes or change lists. For example:

"ReleaseNotes": [  
    "Version:  6.0.5.3000",  
    "Packaged: September 30, 2024",  
    "",  
    "- Enhancements",  
    " - Initial Release"  
],

<VERSION> is the semantic version of the package. For example, 6.0.5.0.0. Use 6 for the Unified Assurance major version and increment minor, patch, and build numbers at your discretion. See the Semantic Versioning documentation for more information about semantic versioning conventions.
<IMPACT> indicates whether the package restarts applications or third-party services, which may impact service. Use true if it does or false if not.
Rollback is not currently used but may be required for future enhancements. In general, use false for -schemaDB and -processDB package types, and true for all other package types.
<DEPPACKAGE>: <DEPVERSION> is a package and version that the package depends on. The package engine checks that you have installed all dependencies before installing the package. For example, if the customDevice-ui package depends on customDevice-schemaDB package updates, the Dependencies array for the .def file for customDevice-ui must include an entry for the customDevice-schemaDB package.
Checksum under Platforms is blank before running the package utility. The package utility auto-populates it with the checksum for the generated .pkg file. Do not modify this field.
<Actions> are the actions for the package utility to perform before or after installing the package. The actions to include depend on the type of package, many of which have required default actions. See Package Types for the required default actions for each package type and Actions for information about available action functions.

When you run the Unified Assurance package utility, it populates the Checksum and PackageFormatVersion fields. The following shows a template of a generated .def file:

{
    "#Comment<N>": "<COMMENTS>",
    "About": {
        "Checksum": "<DEFCHECKSUM>",
        "Dependencies": [
            {
                "<PACKAGEDEP>": "<DEPVERSION>"
            },
            ...
        ],
        "Description": "<DESCRIPTION>",
        "Directory": "<DIRECTORY>",
        "FullName": "<FULLNAME>",
        "License": "none",
        "PackageFormatVersion": "2",
        "PackageName": "<PACKAGENAME>",
        "Platforms": {
            "RHEL8": {
                "Checksum": "<PKGCHECKSUM>",
            }
        },
        "ReleaseNotes": [
            "<RELEASENOTES>"
            ...
        ],
        "Rollback": true,
        "Server": "<SERVER>",
        "ServiceImpact": <IMPACT>,
        "Type": "Package",
        "Version": "<VERSION>"
    },
    "PostInstall": [],
    "PostUninstall": [],
    "PreInstall": [],
    "PreUninstall": []
}

where:

<DEFCHECKSUM> is the auto-populated checksum for the generated .def file, generated by the package utility immediately before adding this field. Do not modify this field.
PackageFormatVersion is the package format indicator. Do not modify this field.
<PKGCHECKSUM> is the auto-populated checksum for the generated .pkg file, generated by the package utility. Do not modify this field.

Package Tokens

The Unified Assurance Package Utility supports tokens that it replaces with actual values in Package.def when installing and in configuration files sent with the updateConfig action.

This table describes tokens for pre or post-install actions.

Token	Description	Example
$A1BASEDIR	The directory where Unified Assurance is installed, based on the value of BaseDir in etc/Assure1.conf.	/opt/assure1
$PACKAGEDIR	The directory where the package is installed, based on the value of Directory in the About object of Package.def.	For the coreDiscovery-app package: $A1BASEDIR/apps/coreDiscovery
$PACKAGE	The package name.	coreDiscovery-app
$PACKAGEVERSION	The package version.	1.2.3.4.5
$PACKAGEFULLVERSION	An alias for $PACKAGEVERSION.	1.2.3.4.5
$PACKAGEBASEVERSION	The base part of the version.	For version 1.2.3.4.5, the base would be 1.2.3.
$PACKAGEBUILDVERSION	The build part of the version.	For version 1.2.3.4.5, the build would be 4.
$INSTALLERPLATFORM	Replaced with x86_64 or x86, depending on the platform.	x86_64
$HOSTFQDN	The HostFQDN of the server.	abc.example.com
$ISINSTALL	Indicates whether this is the initial installation of the package on the server (1) or not (**0).	1
$ISUPDATE	Indicates whether the package is already installed on the server (1) or not (**0).	1
$ISUPGRADE	Indicates whether this is an upgrade (1) or not (**0).	1
$WEBFQDN	The WebFQDN of server, based on the license.	abc.example.com
$ALTCNOPTION	Autopopulated with the correct value for --AltCN. Unused if WebFQDN and HostFQDN are the same. Only applicable for the SSL Certificate and Key Creation Utility.	abc2.example.com
$SHORTPLATFORM	The short form of the operating system version. version	el8
$ISDBPRIMARY	Whether the server is a primary database server (1) or not (0).	1
$ISDBBACKUP	Whether the server is a redundant database server (1) or not (0).	0
$ISPRIMARY	Whether the server is a primary server (1) or not (0).	1
$ISBACKUP	Whether the server is a redundant server (1) or not (0).	0
$ISSTANDALONE	Whether the server is a standalone server (1) or not (0). Only one of $ISSTANDALONE, $ISPRIMARY and $ISBACKUP will ever be 1.	0
$ISNEO4JREDUNDANT	Whether Neo4j is operating in a redundant setup (1) or not (0).	0

This table describes tokens for the updateConfig action.

Field	Description	Example Value
$A1BASEDIR	The directory where Unified Assurance is installed. Replaced based on etc/Assure1.conf: BaseDir.	/opt/assure1
$HOSTFQDN	The HostFQDN of the server, based on the license.	abc.example.com
$SERVER_TIMEZONE	The time zone name for the server.	UTC
$WEBFQDN	The WebFQDN of server, based on the license.	abc.example.com
$PARTNERHOSTFQDN	The partner server's HostFQDN. If the local server is the primary server, this holds the backup server. If the local server is a backup server, this holds the primary server.	backup.example.com
$PRIMARYHOSTFQDN	The primary server's HostFQDN. If local host is the primary, this will be the local HostFQDN.	primary.example.com
$REDUNDANTHOSTFQDN	The redundant server's HostFQDN, in redundant environments.	backup.example.com
#$UNCOMMENTFORREDUNDANT#	Will be replaced with a blank when run on a redundant server	N/A

Package Types

You can create the following types of packages, each of which follows a specific set of standards:

SchemaDB
ProcessDB
Rules
Application
User Interface
Config

Schema DB Packages

The schema database (-schemaDB) package type contains Unified Assurance configuration database element changes.

Schema database packages are differentially updated. After a package has been created, any database updates require sequential schema-<N>.sql files for each built version. The package utility runs each file in numerical order (1 to <N>) using the dbRunVersioned action in the PostInstall attribute in Package.def.

Any previously run schema files are not re-run when the package is updated. You must create a new schema-<N>.sql file for any updates. For example, if version 1 installed and ran schema-1.sql, a version 2 update must add a schema-2.sql. If subsequent updates invalidate a previous numbered schema file, the file can be emptied, but it must remain on the system. Oracle recommends keeping the following line in the blanked out schema file to prevent confusion:

-- file intentionally left blank --

In redundant environments, the package only runs the containing SQL once for the redundant pair.

As a best practice, include field names with INSERT statements to preserve functionality in case of changes to the table schema.

Use the following values in Package.def for -schemaDB:

<SERVER>: Use Database.
<DIRECTORY>: Use distrib/db/schema/<PACKAGENAME>, where <PACKAGENAME> is the on-disk package folder name without the type suffix (for example, coreDevice).
PostInstall: Use the dbRunVersioned action.

An example SchemaDB is:

/*!40014 SET UNIQUE_CHECKS=0 */;
/*!40014 SET FOREIGN_KEY_CHECKS=0 */;

USE Assure1;

An example Package.def before packaging is:

{
    "About": {
        "FullName":      "Core Discovery Schema DB",
        "PackageName":   "coreDiscovery-schemaDB",
        "License":       "coreDiscovery",
        "Server":        "Database",
        "Type":          "Package",
        "Directory":     "distrib/db/schema/coreDiscovery",
        "Description":   "",
        "ReleaseNotes":  "",
        "Version":       "",
        "ServiceImpact": true,
        "Rollback":      true,
        "Dependencies":  [
            {
                "coreAAA-schemaDB": ""
            },
            {
                "coreConfigurationNavigation-schemaDB": ""
            }
        ],
        "Platforms": {
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "dbRunVersioned('$PACKAGE', '$PACKAGEDIR/schema-*.sql')"
    ],
    "PostUninstall": []
}

Process DB Packages

The process database (-processDB) package type contains the broker configuration database elements of an application package for a specific broker. This means that an -app package will have dependency on these -processDB packages. Oracle recommends that you use process database packages to configure broker components, component configurations, requests, scheduled jobs, and services only.

Process database packages are differentially updated. After a package has been created, database updates require sequential process-<N>.sql files for each built version. The package utility runs each file in numerical order (1 to <N>) using the dbRunVersioned action in the PostInstall attribute in Package.def.

Any previously run schema files are not re-run when the package is updated. You must create a new process-<N>.sql file for any updates. For example, if version 1 installed and ran process-1.sql, a version 2 update must add a process-2.sql. If subsequent updates invalidate a previous numbered schema file, the file can be emptied, but it must remain on the system. Oracle recommends keeping the following line in the blanked out schema file to prevent confusion:

-- file intentionally left blank --

The package runs the containing SQL on all installed servers, but this can cause duplicate key errors in redundant environments.

As a best practice, include field names with INSERT statements to preserve functionality in case of changes to the table schema.

Use the following values in Package.def for -processDB:

<SERVER>: Use Any, unless the associated application package can only be run on a specific server type (for example, Presentation server).
<DIRECTORY>: Use distrib/db/process/<PACKAGENAME>, where <PACKAGENAME> is the on-disk package folder name without the type suffix (for example, coreDevice).
<ACTIONS>: Use the dbRunVersioned and reloadBroker actions.

An example ProcessDB is:

/*!40014 SET UNIQUE_CHECKS=0 */;
/*!40014 SET FOREIGN_KEY_CHECKS=0 */;

USE Assure1;

An example Package.def before packaging is:

{
    "About": {
        "FullName":      "Core Discovery Process DB",
        "PackageName":   "coreDiscovery-processDB",
        "License":       "coreDiscovery",
        "Server":        "Any",
        "Type":          "Package",
        "Directory":     "distrib/db/process/coreDiscovery",
        "Description":   "",
        "ReleaseNotes":  "",
        "Version":       "",
        "ServiceImpact": true,
        "Rollback":      true,
        "Dependencies": [
            {
                "broker-schemaDB": "6.0.5.0.0"
            }
        ],
        "Platforms": {
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "dbRunVersioned('$PACKAGE', '$PACKAGEDIR/process-*.sql')",
        "reloadBroker()"
    ],
    "PostUninstall": []
}

Rules Packages

The rules (-rules) package type contains the rules configuration files for Apache Subversion. Most rules packages use the Post Install function calls for updateSVN to insert the files into Subversion and integrateRules to automatically deploy rules. The package utility can execute multiple Subversion commits, so one rules package can be installed into many rules directories. However, Oracle recommends limiting the number of rule directories a single rules package can be installed into as much as possible. Updates to rules files will be placed in the default read-only repository; the default repository will only be modified on the initial installation.

Use the following values in Package.def for -rules:

<SERVER>: Use Presentation because all rules are on the presentation servers.
<DIRECTORY>: Use distrib/rules/<PACKAGENAME>, where <PACKAGENAME> is the on-disk package folder name without the type suffix (for example, coreDevice).
<ACTIONS>: Use the updateSVN and integrateRules actions. The updateSVN action facilitates loading of any rules files into the rules repository, which will then sync to all servers. The integrateRules action is used for integration packages where a partial rules file is provided.

An example Package.def is:

{
    "About": {
        "FullName":      "Core Discovery Rules",
        "PackageName":   "coreDiscovery-rules",
        "License":       "coreDiscovery",
        "Server":        "Presentation",
        "Type":          "Package",
        "Directory":     "distrib/rules/coreDiscovery",
        "Description":   "",
        "ReleaseNotes":  "",
        "Version":       "",
        "ServiceImpact": false,
        "Rollback":      true,
        "Dependencies":  [
            {
                "vendorSVN-app": ""
            }
        ],
        "Platforms": {
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "updateSVN({'package' => '$PACKAGE', 'repoPath' => 'core', 'repoName' => 'Core Rules', 'rulesPathPrefix' => 'coreDiscovery', 'hooks' => { 'post-commit' => '$A1BASEDIR/distrib/hooks/post-commit'}})"
    ],
    "PostUninstall": []
}

Application Packages

The application (-app) package type contains the Unified Assurance compiled applications or custom scripts. This includes scripts in Perl and other languages. The package copies these script files to the directory configured as part of the installation.

Use the following values in Package.def for -app:

<SERVER>: Use Any, unless the application can only be run on a specific server type (for example, Presentation server).
<DIRECTORY>: Use app/<PACKAGENAME>, where <PACKAGENAME> is the on-disk package folder name without the type suffix (for example, coreDevice).
<ACTIONS>: Use the checkoutSVN action so that the rules-based applications can ensure the latest version of the rules repository is available.

An example Package.def is:

{
    "About": {
        "FullName":      "Core Discovery Applications",
        "PackageName":   "coreDiscovery-app",
        "License":       "coreDiscovery",
        "Server":        "Any",
        "Type":          "Package",
        "Directory":     "apps/coreDiscovery",
        "Description":   "",
        "ReleaseNotes":  "",
        "Version":       "",
        "ServiceImpact": true,
        "Rollback":      true,
        "Dependencies": [
            {
                "corePerl-lib": ""
            },
            {
                "coreDevice-schemaDB": ""
            },
            {
                "coreDiscovery-schemaDB": ""
            },
            {
                "coreDiscovery-processDB": ""
            },
            {
                "coreDiscovery-rules": ""
            },
            {
                "vendorSVN-app": ""
            }
        ],
        "Platforms": {
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "checkoutSVN('$PACKAGE', 'core');"
    ],
    "PostUninstall": []
}

User Interface Packages

The user interface (-ui) package type contains user interfaces, APIs, knowledge base articles, and images. The package copies these files to the directory configured as part of the installation.

Use the following values in Package.def for -ui:

<SERVER>: Use Presentation because all UIs are on the presentation servers.
<DIRECTORY>: Use www/ui/<PACKAGENAME>, where <PACKAGENAME> is the on-disk package folder name without the type suffix (for example, coreDevice).
There are no recommended actions for <ACTIONS>.

An example Package.def is:

{
    "About": {
        "FullName":      "Core Discovery UI",
        "PackageName":   "coreDiscovery-ui",
        "License":       "coreDiscovery",
        "Server":        "Presentation",
        "Type":          "Package",
        "Directory":     "www/ui/coreDiscovery",
        "Description":   "",
        "ReleaseNotes":  "",
        "Version":       "",
        "ServiceImpact": false,
        "Rollback":      true,
        "Dependencies": [
            {
                "coreDiscovery-schemaDB": ""
            },
            {
                "coreWebAPI-lib": ""
            }
        ],
        "Platforms": {
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [],
    "PostUninstall": []
}

Configuration Packages

The configuration (-config) package type contains configuration files for the corresponding vendor or application package.

Oracle recommends copying any stock configurations to a .local file before running token replacement, and then copying them from the .local file to the final destination in $A1BASEDIR/etc. This allows you to use the .local copy to revert any changes made to the $A1BASEDIR/etc. config file.

Use the following values in Package.def for -config:

<SERVER>: Use Any, unless the associated vendor or application package can only be run on a specific server type (for example, Presentation server).
<DIRECTORY>: Use distrib/config/<PACKAGENAME>, where <PACKAGENAME> is the on-disk package folder name without the type suffix (for example, vendorApache).
<ACTIONS>: Use the updateConfig and copy actions. The updateConfig action replaces any install-time tokens. See Package Tokens for the list of replaced configuration tokens. Use the copy action to copy configurations to a .local file and then from the .local file to the final destination after token replacement.

An example Package.def is:

{
    "About": {
        "FullName":      "Vendor Apache Configuration",
        "PackageName":   "vendorApache-config",
        "License":       "none",
        "Server":        "Presentation",
        "Type":          "Package",
        "Directory":     "distrib/config/vendorApache",
        "Description":   "Configuration files for Apache",
        "ReleaseNotes":  "",
        "Version":       "",
        "ServiceImpact": true,
        "Rollback":      true,
        "Dependencies": [
            {
                "vendorOpenSSL-app": ""
            }
        ],
        "Platforms": {
            "RHEL8": {
                "Checksum": ""
            }
        },
        "StaticDoc": [
            "== CONFIGURATION FILE ==",
            "",
            " $A1BASEDIR/etc/httpd.conf",
            "",
            "'''<span style="color: red">WARNING: DO NOT MODIFY THIS CONFIGURATION FILE!!</span>'''",
            "",
            "Package updates are guaranteed to overwrite any modifications.",
            "",
            "== CUSTOMIZATIONS ==",
            "",
            "The configuration can be customized by including any base*.conf or ssl*.conf file in the $A1BASEDIR/etc/apache directory. base*.conf files are included in the primary configuration section and ssl*.conf files are included in the VirtualHost configuration section. This package distributes several example customizations located in the $A1BASEDIR/distrib/config/vendorApache/apache directory.",
            "",
            "'''Example: ''' Enable debugging with non-minified Javascript libraries",
            "# Copy $A1BASEDIR/distrib/config/vendorApache/apache/base-ui-debug.conf to $A1BASEDIR/etc/apache",
            "# Restart Apache"
        ]
    },
    "PreInstall":   [],
    "PreUninstall": [],
    "PostInstall":  [
        "copy('$PACKAGEDIR/apache/base-cluster.conf', '$PACKAGEDIR/apache/base-cluster.conf.local')",
        "copy('$PACKAGEDIR/apache/ssl-cluster.conf', '$PACKAGEDIR/apache/ssl-cluster.conf.local')",
        "copy('$PACKAGEDIR/httpd.conf', '$PACKAGEDIR/httpd.conf.local')",
        "updateConfig('$PACKAGEDIR/apache/base-cluster.conf.local')",
        "updateConfig('$PACKAGEDIR/apache/ssl-cluster.conf.local')",
        "updateConfig('$PACKAGEDIR/httpd.conf.local')",
        "copy('$PACKAGEDIR/httpd.conf.local', '$A1BASEDIR/etc/httpd.conf')",
        "makePath('$A1BASEDIR/etc/apache')",
        "makePath('$A1BASEDIR/www')",
        "cmd('$A1BASEDIR/bin/CreateSSLCertificate --Type Web --CN $WEBFQDN $ALTCNOPTION')         if '$HOSTFQDN' ne '$WEBFQDN' && $ISINSTALL == 1",
        "cmd('$A1BASEDIR/bin/CreateSSLCertificate --Type Web --CN $WEBFQDN $ALTCNOPTION --Force') if '$HOSTFQDN' ne '$WEBFQDN' && $ISUPGRADE == 1",
        "copy('$A1BASEDIR/etc/ssl/Host.key.pem', '$A1BASEDIR/etc/ssl/Web.key.pem')                  if '$HOSTFQDN' eq '$WEBFQDN'",
        "copy('$A1BASEDIR/etc/ssl/Host.crt.pem', '$A1BASEDIR/etc/ssl/Web.crt.pem')                  if '$HOSTFQDN' eq '$WEBFQDN'",
        "setOwnership('$A1BASEDIR/etc/ssl')"
    ],
    "PostUninstall": [
        "remove('$A1BASEDIR/etc/httpd.conf')"
    ]
}

Dashboard Packages

The dashboard (-dashboard) package type contains pre-created dashboard files and any custom images used. Scalable Vector Graphics (SVGs) should be in a subfolder called dashboards and custom images in a subfolder called images.

Oracle recommends creating dashboards within Unified Assurance first and then downloading the SVG and any custom images from the Files interface to add to the package.

Use the following values in Package.def for -dashboard:

<SERVER>: Use Presentation because dashboards reside on presentation servers.
<DIRECTORY>: Use distrib/svgs/<PACKAGENAME>, where <PACKAGENAME> is the on-disk package folder name without the type suffix (for example, dashboardBase).
<ACTIONS>: Use the updateSVN action to add SVG files to the dashboards repository.

An example Package.def is:

{
    "About": {
        "FullName":      "Dashboard Examples",
        "PackageName":   "dashboardBase-dashboard",
        "License":       "dashboardBase",
        "Server":        "Presentation",
        "Type":          "Package",
        "Directory":     "distrib/svgs/dashboards",
        "Description":   "Unified Assurance Dashboard SVG Files",
        "ReleaseNotes":  "",
        "Version":       "",
        "ServiceImpact": false,
        "Rollback":      true,
        "Dependencies": [
            {
                "dashboardBase-ui": ""
            }
        ],
        "Platforms": {
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "updateFiles('$PACKAGEDIR/images')",
        "updateSVN({'package' => '$PACKAGE', 'repoPath' => 'dashboards', 'repoName' => 'Dashboards', 'sourceSubDir' => 'dashboards', 'hooks' => { 'post-commit' => '$A1BASEDIR/distrib/hooks/post-commit'}})"
    ],
    "PostUninstall": []
}

Third-Party Vendor

The packaging engine in Unified Assurance allows installation of third-party applications. This is usually a group of packages that fulfil the need for extra configuration files and init.d scripts. These should follow the naming convention vendor<VENDORAPP><SUFFIX> (for example, vendorMySQL-app, or vendorMySQL-config), where:

<VENDORAPP> is the third-party application name in upper camel case.
<SUFFIX> is the appropriate package type suffix based on contents.

An example Package.def is:

{
    "About": {
        "FullName":      "Vendor Shellinabox Application",
        "PackageName":   "vendorShellinabox-app",
        "License":       "none",
        "Server":        "Presentation",
        "Type":          "Package",
        "Directory":     "vendor/shellinabox",
        "Description":   "Application files for Shellinabox",
        "ReleaseNotes":  "",
        "Version":       "",
        "ServiceImpact": true,
        "Rollback":      true,
        "Dependencies": [],
        "Platforms": {
            "RHEL7": {
                "Checksum": ""
            },
            "RHEL8": {
                "Checksum": ""
            }
        },
        "VendorInfo": [
            {
                "Product":     "Shellinabox",
                "Version":     "2.15-rc2",
                "Link":        "https://github.com/shellinabox/shellinabox/releases",
                "License":     "vendorinfo/shellinabox/COPYING",
                "LicenseType": "GPL v2",
                "Source":      "vendorinfo/shellinabox/shellinabox-2.15-rc2.tar.gz"
            }
        ]
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "relocate('$A1BASEDIR/vendor/shellinabox', '/opt/src/_______________________________________________________________________INSTALLER-BUILD-PATH_______________________________________________________________________/vendorOpenSSL-app', '$A1BASEDIR/vendor/openssl', { 'filelist' => '$A1BASEDIR/logs/relocate.vendorShellinabox-app' })"
    ],
    "PostUninstall": []
}

Best Practices

Beware of catch 22's (also known as dependency loops) where two packages depend on each other to be installed first. This will cause an error during installation.
Be aware that you may not have a license for a dependency (for example, Unified Assurance) which can cause you to receive a dependency error when you try to install it.

Appendix

Actions

batchAPIRun [ARGUMENTS]

This action calls the batch API with the passed in JSON file.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE !DEPRECATED! 
FILENAME    -> Name of the file to send to the batch API

RETURNS

Any errors from batch API or File Reading.

SYNOPSIS

"batchAPIRun('$PACKAGE', '$PACKAGEDIR_records/batchAPIFile.json')"

batchAPIRunIncremental [ARGUMENTS]

This action iterates through all matching JSON files in the directory and calls the batch API.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE
GLOB        -> Used to determine selection of files to send to batch API

RETURNS

Any errors from batch API or File Reading.

SYNOPSIS

"batchAPIRunIncremental('$PACKAGE', '$PACKAGEDIR_records/process-\*.json')"

branchSVN [ARGUMENTS]

This action creates a branch from the RO_LOCKED branch of the given rules repository.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE  
REPO        -> Repo name  
NEWBRANCH   -> Branch directory name  
BRANCHNAME  -> Branch pretty name

RETURNS

none

SYNOPSIS

"branchSVN('$PACKAGE', 'event', 'TEST', 'Event Test')"

brokerRequest [ARGUMENTS]

This action calls the broker method with the arguments passed in.

ARGUMENTS

HOST FQDN   -> FQDN of server to call broker on, supports localhost 
METHOD      -> Broker method to call  
ARGUMENTS   -> All other params will be passed to the Broker method as an array

RETURNS

Data or Message returned by a successful Broker Method.

SYNOPSIS

"brokerRequest('localhost', 'UpdateVendorConfig', ['abc', ... , 1234])"

checkoutSVN [ARGUMENTS]

This action checks out the given Unified Assurance SVN repository. If a working copy already exists, it gets updated.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE  
REPO        -> Repo name to checkout

RETURNS

none

SYNOPSIS

"checkoutSVN('$PACKAGE', 'event')"

cmd [ARGUMENTS]

This action runs the command line command.

ARGUMENTS

COMMAND     -> Command line command to be run  
OUTPUT      -> If it is a scalar ref, the output of Command will be stored here

RETURNS

1 for success, 0 for failure

SYNOPSIS

"cmd('chmod +x $A1BASEDIR/tmp/example.sh', '$Scalar')"

copy [ARGUMENTS]

This action copies a file from one folder to another. If TOFILE is within $A1BASEDIR, Unified Assurance user ownership and permissions are applied automatically.

ARGUMENTS

FROMFILE -> Source file (full path required)  
TOFILE   -> Destination file (full path required)

RETURNS

none

SYNOPSIS

"copy('$PACKAGEDIR/apache/base-cluster.conf', '$PACKAGEDIR/apache/base-cluster.conf.local')"

dbAdd [ARGUMENTS]

This action adds an entry into CoreDatabases for the given schema. It detects whether an entry already exists for the server and will skip if it does. If not, it will decide whether to add as another shard or as a redundant entry automatically.

ARGUMENTS

PACKAGENAME  -> Full package name, use token $PACKAGE  
SCHEMA       -> Database schema to add  
DATABASENAME -> Database name  
DESCRIPTION  -> Description of database

RETURNS

none

SYNOPSIS

"dbAdd('$PACKAGE', 'Assure1', '$FAILOVERTYPE Assure1 Configuration Database on $HOSTFQDN', 'Assure1 configuration repository for devices, users, hse, and more')",

dbRunVersioned [ARGUMENTS]

This action runs the package's schema-* or process-* files. It will continue from the last update.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE  
SQLFILEGLOB -> Full path + file pattern to run (should be $PACKAGEDIR/schema-*.sql or $PACKAGEDIR/process-*.sql)

RETURNS

none

SYNOPSIS

"dbRunVersioned('$PACKAGE', '$PACKAGEDIR/schema-*.sql')"  
OR  
"dbRunVersioned('$PACKAGE', '$PACKAGEDIR/process-*.sql')"

dbSyncTable [ARGUMENTS]

This action synchronizes a database table across multiple shards (for non-Unified Assurance schemas only).

ARGUMENTS

$DB    -> Schema to connect to (Non-Assure1)  
$TABLE -> Table to sync data across (overwrites, does not merge)  
$DST   -> (Optional) Destination shard HostFQDN, defaults to local HostFQDN  
$SRC   -> (Optional) Source shard HostFQDN, defaults to shard 1's HostFQDN

RETURNS

none

SYNOPSIS

"dbSyncTable('Events', 'EventDisplayConversions')"

dockerLoadImages [ARGUMENTS]

This action loads the compressed images into docker.

ARGUMENTS

IMAGESFILE -> File containing images to load

RETURNS

none

SYNOPSIS

"dockerLoadImages('$PACKAGEDIR_img/IMAGES.tgz')"

influxdbRunIncremental [ARGUMENTS]

This action iterates through all matching InfluxQL files and runs them against the Influx database.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE 
GLOB        -> Used to determine selection of files to use to run against the Influx database

RETURNS

none

SYNOPSIS

"influxdbRunIncremental('$PACKAGE', '$PACKAGEDIR/schema-\*.iql')"

integrateRules [ARGUMENTS]

This action takes an integration base.rules snippet and integrates it into the given ruleset programmatically. Integration "*base.rules" snippets are inserted into the "base.rules" of the destination ruleset after the following placeholder (if present):

## INTEGRATION RULES HERE - DO NOT REMOVE OR CHANGE THIS LINE! ##

If the placeholder is not present, the snippet will be added at the end of the file.

Any integration "*.includes" snippets will be inserted at the end of the "base.includes" of the destination ruleset.

Note:

The integrateRules functionality will only integrate the new rules logic if the ProductionEnvironment Global Property is set to 0. If the property is set to any other value, any new rules logic will have to be manually added into the existing rules files. This setting can be viewed on the Properties UI: Configuration -> Global -> Properties.

ARGUMENTS

PACKAGENAME    -> Full package name, use token $PACKAGE  
REPO           -> Repo path (e.g. event, core, and so on)  
BRANCH         -> Branch path (default, etc)  
FROMRULESETDIR -> package's directory holding rules set to integrate  
TORULESETDIR   -> Ruleset directory to integrate into

RETURNS

none

SYNOPSIS

"integrateRules('$PACKAGE', 'event', 'default', 'integrationCiscoNetwork/syslog', 'eventStdAggregator/syslog')",

makePath [ARGUMENTS]

This action creates the given directory tree if it is not present, and ignores the command if it is already present.

ARGUMENTS

PATH -> Full path to create

RETURNS

none

SYNOPSIS

"makePath('$PACKAGEDIR/t')"

move [ARGUMENTS]

This action moves a file from one folder to another. If TOFILE is within $A1BASEDIR, Unified Assurance user ownership is applied automatically.

ARGUMENTS

FROMFILE -> Source file (full path required)  
TOFILE   -> Destination file (full path required)

RETURNS

none

SYNOPSIS

"move('$A1BASEDIR/vendor/infinidb/distrib/logs',  '$A1BASEDIR/vendor/infinidb/logs')     if (!-d '$A1BASEDIR/vendor/infinidb/logs')"

neo4jRunIncremental [ARGUMENTS]

This action iterates through all the matching cypher files and runs them against the Neo4j database.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE 
GLOB        -> Used to determine selection of files to use to run against the Neo4j database

RETURNS

none

SYNOPSIS

"neo4jRunIncremental('$PACKAGE', '$PACKAGEDIR/schema-\*.cypher')"

opensearchdashboardsRunIncremental [ARGUMENTS]

This action iterates through all matching JSON files in the directory and calls the method in the JSON file on the OpenSearch Dashboards REST API.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE 
GLOB        -> Used to determine selection of files to use to call the OpenSearch Dashboards REST API

RETURNS

none

SYNOPSIS

"opensearchdashboardsRunIncremental('$PACKAGE', '$PACKAGEDIR/opensearchdashboards/actions\*.json')"

opensearchEventAnalyticsRunIncremental [ARGUMENTS]

This action iterates through all matching JSON files in the directory and calls the method in the JSON file on the OpenSearch REST API.

ARGUMENTS

PACKAGENAME -> Full package name, use token $PACKAGE 
GLOB        -> Used to determine selection of files to use to call the OpenSearch REST API

RETURNS

none

SYNOPSIS

"opensearchEventAnalyticsRunIncremental('$PACKAGE', '$PACKAGEDIR/opensearch/actions\*.json')"

registryLoadImages [ARGUMENTS]

This action loads the listed images into the registry.

ARGUMENTS

IMAGESLISTFILE -> File containing list of images to load

RETURNS

none

SYNOPSIS

"registryLoadImages ('$PACKAGEDIR_img/IMAGES.txt')"

reloadBroker

This action initiates a force reload of processes. It is usually used after a dbRunVersioned() action in a processDB package to ensure new processes are seen immediately by the broker.

RETURNS

none

SYNOPSIS

"reloadBroker()"

remove [ARGUMENTS]

This action removes a file from disk. It is commonly used to clean up temporary files after installation.

ARGUMENTS

FILE -> Full path to file

RETURNS

none

SYNOPSIS

"remove('$A1BASEDIR/etc/freetds.conf')"

removeTree [ARGUMENTS]

This action removes the given directory tree (recursive) if it is present, and ignores the command if it has already been removed. It is usually used for removing temporary directories after installation.

ARGUMENTS

PATH -> Full path to remove

RETURNS

none

SYNOPSIS

"removeTree('$PACKAGEDIR/t')"

service [ARGUMENTS]

Service call with the ACTION provided. It is used to stop and start services.

ARGUMENTS

ACTION  -> action to perform for the service, usually stop, start, and restart  
SERVICE -> service name

RETURNS

none

SYNOPSIS

"service('stop', 'assure1-web') if OS('linux')",

setOwnership [ARGUMENTS]

This action forces Unified Assurance user ownership on a given path. it is used to ensure that any created files are owned by Unified Assurance.

ARGUMENTS

PATH -> file or directory to apply recursive assure1 user ownershipupdateSVN [OPTIONS]

RETURNS

none

SYNOPSIS

"setOwnership('$A1BASEDIR/etc/ssl')"

sleep [ARGUMENTS]

This action makes the current process wait for the duration specified in SLEEPAMOUNT.

ARGUMENTS

SLEEPAMOUNT -> Time in seconds to wait

RETURNS

none

SYNOPSIS

"sleep (30)"

startProcess [ARGUMENTS]

This action calls BrokerRequest for a local host broker for the StartProcess method with the PROCESSNAME and TYPE passed in.

ARGUMENTS

PROCESSNAME -> Name of the process to start
TYPE        -> Type of process that is being started

RETURNS

none

SYNOPSIS

"startProcess ('Docker', 'Service')"

stopProcess [ARGUMENTS]

This action calls BrokerRequest for a local host broker for the StopProcess method with the PROCESSNAME and TYPE passed in.

ARGUMENTS

PROCESSNAME -> Name of the process to stop
TYPE        -> Type of process that is being stopped

RETURNS

none

SYNOPSIS

"stopProcess ('Docker', 'Service')"

touchFile [ARGUMENTS]

This action creates an empty file at the given path relative to $A1BASEDIR.

ARGUMENTS

FILE -> File to create

RETURNS

none

SYNOPSIS

"touchFile('$A1BASEDIR/etc/unison/Custom')"

updateConfig [ARGUMENTS]

This action replaces all tokens in the configuration file and saves it. It should be run on all configuration files to ensure that tokens are replaced. See Tokens for list of available replacement tokens.

ARGUMENTS

CONFIGFILE -> Full path to config file

RETURNS

none

SYNOPSIS

"updateConfig('$PACKAGEDIR/httpd.conf.local')"

updateSVN [OPTIONS]

This action adds rules files to SVN if they are not there currently, or updates existing ones if there are changes.

OPTIONS

package         -> Full package name, use token $PACKAGE  
repoPath        -> Repo path (core, event, files, and so on)  
repoName        -> Repo path pretty name  
rulesPathPrefix -> Path prefix (usually the package name without the type suffix)  
forceCopy       -> Used for forcing updates to rules files. Will copy files to the default branch, possibly overwriting local changes. This option is used when packaging rules that the end customer is not allowed to update.  
                   -  If forceCopy points to an array reference (eg 'forceCopy' => [ 'subdir1', 'subdir2/file1.txt' ]), each file and directory in the array will be copied to the default branch.  
                   -  If forceCopy otherwise evaluates to true (eq 'forceCopy' => 1), every file in the package will be copied to the default branch.  
hooks           -> Hash of any svn hooks to install (e.g. {'post-commit' => 'PATH'}, etc)

RETURNS

none

SYNOPSIS

"updateSVN({'package' => '$PACKAGE', 'repoPath' => 'event', 'repoName' => 'Event Rules', 'rulesPathPrefix' => 'eventStdAggregator', 'forceCopy' => 1, 'hooks' => { 'post-commit' => '$A1BASEDIR/distrib/hooks/post-commit'}})"

Additional Resources

Package in Unified Assurance Implementation Guide
Semantic Versioning
JSON

Title and Copyright Information

Developer’s Guide

G18222-01