Creating Custom Packages

Learn how to create custom packages using the packaging engine. As part of the Unified Assurance platform, the packaging engine allows administrators 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 the different types of packages, how to support updatable packages, 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, post-install actions, etc. 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, etc.
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.0.5.0.0.def
coreDatabase-processDB-6.0.5.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 includes a prefix, base name, and type suffix (for example, coreWeb-ui) in lower camel case. Use custom as the prefix name for custom packages to avoid naming conflicts with Unified Assurance stock packages. The type suffix depends on the package contents. There is only one type per package. If multiple types are required for a project (for example, "-ui" and "-schemaDB"), multiple packages are recommended and the project should then be bundled for maintainability.

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 prior to 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.

Package.def

The Package.def file is the only required file for a package. It is in JSON format and must be present at the root level of the package folder structure prior to building. It contains several sections that give the package engine information: how to install, where to install, as well as documentation, dependencies, etc. A Package.def can vary widely based on the package type of file contents. See each of the package type sections for examples of their Package.def. Because the Package.def contains the installation directives for a package, it is separated out of the folder structure during the build process and kept outside the resulting built .pkg file (i.e. the build process will result in two files generated, the Package.def and the aAA.pkg file. Both are required by Unified Assurance for installation).

The following sections are the required JSON keys that must be present in any Package.def, even if empty. Comments can be added using the #Comment<N> key, where <N> is the comment number for the section.

Package.def template:

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

After running the Unified Assurance package utility:

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

About

Checksum: Auto-populated by package utility with checksum of the resulting *.def (just prior to adding this field) during the packaging process. DO NOT MODIFY.
FullName: Package full "pretty" name (for example, Custom Device UI).
PackageName: On-disk package folder name (for example, 'customDevice').
License: Unified Assurance license required to install and use this package. Custom packages should always be "none".
Server: Unified Assurance server restriction for this package. Acceptable values are "Any", "Presentation", and "Database".
Type: Unified Assurance package type. Acceptable value is "Package" only.
Directory: Directory to install package contents to. Location is heavily based on type, please refer to type sections for location specifics.
Description: Free-form description.

ReleaseNotes: Array of lines for additional release notes or change lists. For example:

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

Version: Semantic Version of the package. Custom packages should keep the Unified Assurance Major version as "6", Minor, Patch, and Build parts are at maintainer's discretion (for example, 6.0.5.0.0). See Semantic Versioning for more information on the convention.
ServiceImpact: Indication that this package initiates application or third-party service restarts that may impact service. "true" if it does, "false" if not.
Rollback: Reserved for future enhancement. In general, "-schemaDB" and "-processDB" should be false, all other package types are true.
Dependencies: List of package dependencies that the package engine must have installed prior. Used to ensure all required package components are installed (for example, if the UI package customDevice-ui depends on customDevice-schemaDB changes to be present, customDevice-ui would have a dependency of customDevice-schemaDB).
Platforms: Auto-populated by package installer with checksum of the resulting *.pkg file during the packaging process. DO NOT MODIFY.
PackageFormatVersion: Package format indicator. DO NOT MODIFY.

Pre/Post Install

List of custom actions to perform during pre-install and post-install of the package. See Actions for details on all available action functions. These actions vary greatly based on the type of package and many have required default actions. Refer to each package type section for the required default actions.

Pre/Post Uninstall

Reserved for future enhancement. DO NOT MODIFY

Tokens

The Unified Assurance Package Utility supports several tokens that are replaced at install time for the Package.def as well as in config files sent through the updateConfig() action.

Pre/Post Actions

Field	Description	Example
$A1BASEDIR	Linux Install directory of Unified Assurance from etc/Assure1.conf: BaseDir	/opt/assure1
$PACKAGEDIR	package install directory based on Package.def	coreDiscovery-app -> $A1BASEDIR/apps/coreDiscovery
$PACKAGE	Package name	coreDiscovery-app
$PACKAGEVERSION	Package version	1.2.3.4.5
$PACKAGEFULLVERSION	Alias for $PACKAGEVERSION	1.2.3.4.5
$PACKAGEBASEVERSION	Base portion of version	full: 1.2.3.4.5 -> base: 1.2.3
$PACKAGEBUILDVERSION	Build portion of version	full: 1.2.3.4.5 -> build: 4
$INSTALLERPLATFORM	replaced with "x86_64" or "x86" if system is 64-bit or not	x86_64
$HOSTFQDN	HostFQDN of server	abc.example.com
$ISINSTALL	1 if initial install on server, 0 if not	N/A
$ISUPDATE	1 if package installed already on server, 0 if not	N/A
$ISUPGRADE	1 if it is an upgrade, 0 if not	N/A
$WEBFQDN	WebFQDN of server based on license	abc.example.com
$ALTCNOPTION	Autopopulated with the correct value for --AltCN (unused if WebFQDN & HostFQDN are the same). Only applicable in SSL Certificate and Key Creation Utility	N/A
$SHORTPLATFORM	The OS version	el8 or rhel7
$ISDBPRIMARY	1 if server is primary DB server	N/A
$ISDBBACKUP	1 if server is redundant DB server	N/A
$ISPRIMARY	1 if server is primary server	N/A
$ISBACKUP	1 if server is redundant server	N/A
$ISSTANDALONE	1 if server is standalone, only one of $ISSTANDALONE, $ISPRIMARY and $ISBACKUP will ever be true	N/A
$ISNEO4JREDUNDANT	1 if Neo4j is redundant setup	N/A

updateConfig

Field	Description	Example Value
$A1BASEDIR	Linux Install directory of Unified Assurance from etc/Assure1.conf: BaseDir	/opt/assure1
$HOSTFQDN	HostFQDN of server based on license	abc.example.com
$SERVER_TIMEZONE	Time zone name for the server	UTC
$WEBFQDN	WebFQDN of server based on license	abc.example.com
$PARTNERHOSTFQDN	Partner server HostFQDN (for example, if the local server is primary, this holds the backups and vice versa)	local: primary.example.com -> partner: backup.example.com
$PRIMARYHOSTFQDN	Primary server HostFQDN, not necessarily the same as partner (for example, if local host is the primary, this will be the local HostFQDN)	local: primary.example.com -> primary: primary.example.com
$REDUNDANTHOSTFQDN	Redundant server HostFQDN if present	local: primary.example.com -> redundant: backup.example.com
#$UNCOMMENTFORREDUNDANT#	Will be replaced with a blank when run on a redundant server	N/A

Package Types & Suffixes

You can create several types of packages, with each type following a specific set of standards:

SchemaDB
ProcessDB
Rules
Application
User Interface
Config

Schema DB

The schema database ("-schemaDB") package type is used to hold all the Unified Assurance configuration database element changes. After a package has been created, database updates require a sequential schema-*.sql file for each built version. The package utility will execute each file in numerical order (1 to n) using the dbRunVersioned function call in the "Post Install" package attributes.

Note:

This type of package is a differentially updated package which means any previously run schema files will not be re-run when the package is updated. Any updates require a new schema-N.sql file to be created (for example, v1 has a schema-1.sql; later a v2 must add a schema-2.sql since schema-1.sql has already been installed and run). If subsequent updates invalidate a previous numbered schema file, the file may be emptied out but it MUST remain on disk. Oracle recommends that you keep the line "-- file intentionally left blank --" in the blanked out schema file to prevent confusion.
This package only runs the containing SQL once per redundant pair.
INSERT statements should include the field names to ensure they work even if the table schema changes for future enhancements.

Package.def:

<SERVER>: should always be "Database"
<DIRECTORY>: distrib/db/schema/<PACKAGENAME> where <PACKAGENAME> is without the type suffix (for example, coreDevice)
<ACTIONS>
- dbRunVersioned

Example SchemaDB:

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

USE Assure1;

Example Package.def prior to packaging:

{
    "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": {
            "RHEL7": {
                "Checksum": ""
            },
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "dbRunVersioned('$PACKAGE', '$PACKAGEDIR/schema-*.sql')"
    ],
    "PostUninstall": []
}

Process DB

The process database ("-processDB") package type is used to hold all the broker configuration database elements of an application package for a specific broker. After a package has been created, database updates require a sequential process-*.sql file for each built version. The package installer will execute each in natural sort order (1 to n) using the dbRunVersioned function call in the "Post Install" package attributes. Process database package best practices dictate that you only configure broker components, component configurations, requests, scheduled jobs, and services. Process database packages must be a dependency of the "-app" package they provide configs for.

Note:

This type of package is a differentially updated package and previously run process files will not be re-run. Any updates require a new process-N.sql file to be created (for example, v1 has a process-1.sql; later a v2 must add a process-2.sql since process-1.sql has already been installed and run). If subsequent updates invalidate a previous numbered process file, the file may be emptied out but it MUST remain on disk. Oracle recommends that you keep the line "-- file intentionally left blank --" in the blanked out process file to prevent confusion.
This package will run containing SQL on all servers installed, but be aware as this can cause "duplicate key" errors on the redundant system.
INSERT statements should include the field names to ensure they work even if the table schema changes for future enhancements.

Package.def:

<SERVER>: should be "Any", unless the "-app" package associated can only be run on a specific server type such as the "Presentation".
<DIRECTORY>: distrib/db/process/<PACKAGENAME> where <PACKAGENAME> is without the type suffix (for example, customDevice)
<ACTIONS>
- dbRunVersioned
- reloadBroker

Example ProcessDB:

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

USE Assure1;

Example Package.def:

{
    "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": {
            "RHEL7": {
                "Checksum": ""
            },
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "dbRunVersioned('$PACKAGE', '$PACKAGEDIR/process-*.sql')",
        "reloadBroker()"
    ],
    "PostUninstall": []
}

Rules

The rules ("-rules") package type is used to hold all the rules configuration files for subversion. Most rules packages use the "PostInstall" function calls for "updateSVN" to insert the files into subversion and "integrateRules" to automatically deploy rules (see below). The package utility can execute multiple subversion commits, so one rules package can install into many rules directories, however, best practice is to limit this as much as possible. Updates to rules files will only be placed in the "RO" or read-only repository; the "default" repository will only be modified on the initial installation.

Package.def:

<SERVER>: should be "Presentation" because all rules are on the presentation servers.
<DIRECTORY>: distrib/rules/<PACKAGENAME> where <PACKAGENAME> is without the type suffix (for example, customDevice)
<ACTIONS>: requires load of any rules files into rules repository which will sync to all servers. In the case of integration packages where a partial rules file is provided, integrateRules() action may be required.
- updateSVN
- integrateRules

Example Package.def:

{
    "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": {
            "RHEL7": {
                "Checksum": ""
            },
            "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

The application ("-app") package type is used to hold all the Unified Assurance compiled applications or custom scripts. It may include scripts in any language not just Perl. The package will simply copy the files to the directory configured as part of the installation.

Package.def:

<SERVER>: should always be "Any" unless the application should only be run on a specific type
<DIRECTORY>: app/<PACKAGENAME> where <PACKAGENAME> is without the type suffix (for example, customDevice)
<ACTIONS>: rules-based applications should ensure the latest version of the rules repo is available with "checkoutSVN"
- checkoutSVN

Example Package.def:

{
    "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": {
            "RHEL7": {
                "Checksum": ""
            },
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [
        "checkoutSVN('$PACKAGE', 'core');"
    ],
    "PostUninstall": []
}

User Interface

The user interface ("-ui") package type is used to hold all the user interfaces, APIs, knowledge base articles, and images. The package will simply copy the files to the directory configured as part of the installation.

Package.def:

<SERVER>: should always be "Presentation" because all UIs have to be on the presentation servers
<DIRECTORY>: www/ui/<PACKAGENAME> where <PACKAGENAME> is without the type suffix (for example, customDevice)
<ACTIONS>: no recommended actions

Example Package.def:

{
    "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": {
            "RHEL7": {
                "Checksum": ""
            },
            "RHEL8": {
                "Checksum": ""
            }
        }
    },
    "PreInstall":    [],
    "PreUninstall":  [],
    "PostInstall":   [],
    "PostUninstall": []
}

Config

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

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

Package.def:

<SERVER>: should always be the same as the associated vendor or application package
<DIRECTORY>: distrib/config/<PACKAGENAME> where <PACKAGENAME> is without the type suffix (for example, vendorApache)
<ACTIONS>
- updateConfig: replace any install-time tokens. See Tokens for the list of replaced configuration tokens.
- copy: recommended to copy configurations to .local and then on after token replacement.

Example Package.def:

{
    "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": {
            "RHEL7": {
                "Checksum": ""
            },
            "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

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

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

Package.def:

<SERVER>: should always be "Presentation" because dashboards reside only on the presentation servers
<DIRECTORY>: distrib/svgs/<PACKAGENAME> where <PACKAGENAME> is without the type suffix (for example, dashboardBase)
<ACTIONS>
- updateSVN: add SVG files to Dashboards repo

Example Package.def:

{
    "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": {
            "RHEL7": {
                "Checksum": ""
            },
            "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

Allows installation of third-party applications. Should follow the naming convention of vendor<VENDORAPP><SUFFIX> (for example, vendorMySQL-app, vendorMySQL-config). This is usually a group of packages depending on if the app requires config files, has init.d scripts, etc.

<VENDORAPP>: third-party application name upper camel case
<SUFFIX>: appropriate package type suffix based on contents

Example Package.def:

{
    "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" (dependency loops) where two packages depend on the other to be installed first. This will cause an error during installation.
Be aware that a customer may not have a license for a dependency (for example, Unified Assurance) which can cause them to receive a dependency error when they try to install it.

Appendix

Actions

batchAPIRun [ARGUMENTS]

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]

Iterates through all matching JSON files in 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]

Branch from the RO_LOCKED branch of the given rules repo.

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]

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]

Checkout the given Unified Assurance SVN repo. If working copy already exists, update it.

ARGUMENTS

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

RETURNS

none

SYNOPSIS

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

cmd [ARGUMENTS]

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]

Copy a file from one folder to another. If TOFILE is within $A1BASEDIR, apply assure1 user ownership and permissions 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]

Adds an entry into CoreDatabases for the given schema. Detects whether entry already exists for the server and will skip if it does. If not, will detect whether to add as another shard or 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]

Runs the package's schema- or process- files. Will continue from 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]

Synchronize a database table across multiple shards (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]

Loads the compressed images into docker.

ARGUMENTS

IMAGESFILE -> File containing images to load

RETURNS

none

SYNOPSIS

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

eventAnalyticsRunIncremental [ARGUMENTS]

Iterates through all matching JSON files in directory and calls the method in the JSON file on the ElasticSearch REST API.

ARGUMENTS

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

RETURNS

none

SYNOPSIS

"eventAnalyticsRunIncremental('$PACKAGE', '$PACKAGEDIR/elasticsearch/actions\*.json')"

influxdbRunIncremental [ARGUMENTS]

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]

Take an integration base.rules snippet and integrate 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 in to 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, etc.)  
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')",

kibanaRunIncremental [ARGUMENTS]

Iterates through all matching JSON files in directory and calls the method in the JSON file on the Kibana REST API.

ARGUMENTS

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

RETURNS

none

SYNOPSIS

"kibanaRunIncremental('$PACKAGE', '$PACKAGEDIR/kibana/actions\*.json')"

makePath [ARGUMENTS]

Create the given directory tree if not present. Ignores if already present.

ARGUMENTS

PATH -> Full path to create

RETURNS

none

SYNOPSIS

"makePath('$PACKAGEDIR/t')"

move [ARGUMENTS]

Move a file from one folder to another. If TOFILE is within $A1BASEDIR, apply assure1 user ownership 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]

Iterates through all 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')"

registryLoadImages [ARGUMENTS]

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

Force reload of processes. Usually used after a dbRunVersioned() in a processDB package to ensure new processes are seen by the broker right away.

RETURNS

none

SYNOPSIS

"reloadBroker()"

remove [ARGUMENTS]

Removes a file from disk. Commonly used to clean up temporary files after install.

ARGUMENTS

FILE -> Full path to file

RETURNS

none

SYNOPSIS

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

removeTree [ARGUMENTS]

Remove the given directory tree (recursive) if not present. Ignores if already removed. Usually used for removing temporary directories after install.

ARGUMENTS

PATH -> Full path to remove

RETURNS

none

SYNOPSIS

"removeTree('$PACKAGEDIR/t')"

service [ARGUMENTS]

Service call with the action provided. Used to stop and start services.

ARGUMENTS

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

RETURNS

none

SYNOPSIS

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

setOwnership [ARGUMENTS]

Force Unified Assurance user ownership on given path. Used to ensure 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]

Makes the current process wait for passed in duration.

ARGUMENTS

SLEEPAMOUNT -> Time in seconds to wait

RETURNS

none

SYNOPSIS

"sleep (30)"

startProcess [ARGUMENTS]

Calls BrokerRequest for 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]

Calls BrokerRequest for 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]

Create 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]

Replace all tokens in the config file and save. Should be run on any config file to ensure 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]

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, etc.)  
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

G10628-01