Package Management
When developing new processes in Automic Automation Engine, it is helpful for developers if certain versions can be saved. This is helpful, for example, when developers implement new versions of processes with new capabilities and have to create a correction for the production version in the meantime.
Once development is complete, the finished versions must be "frozen" so that they can be restored at any time and installed in other environments. The concept of releases is familiar from software development. best4Automic also provides modules for this.
Definitions
Package management combines the areas of automation and software development. This requires terms from both areas and also defines new ones. These terms are explained below in order to better understand the ideas and functions of the modules.
b4A Packages
The term b4A Package refers to a collection of objects that are located in a directory and are subject to a defined folder structure. This definition is based on the Automic Action Packs, which are supported by the Automic Package Manager.
The Action Packs of the Automic Package Manager are located below the PACKAGES folder. A folder is created in this directory for each Action Pack. The objects that are part of the Action Pack are located below this folder. These are only parts of the definition of the Automic Action Pack. They form the basic framework for the operation of these b4A modules. The other structures below the package folders are only partially relevant for these modules. Everything below such a folder is considered part of the package.
b4A Packages are the basis for a concept that makes it possible to set up a deployment procedure based on modern software development principles. It includes configuration management, post-deployment functionalities, integration into version control systems and other functionalities that make it possible to equate development in automation with the development of software through to deployment. It can also be used to implement methods and processes such as DevOps.
When creating releases of b4A Packages, the objects in the subfolder for configuration objects are treated specially. This folder is used to define the client- and environment-specific configuration. If the name of an object contains the character string "$$$" (configurable), this is identified as a configuration object for a specific client or a specific environment. The following rules apply to these objects:
- <object name>$$$<environment name>: The environment name must correspond to a server definition in defaults.conf. In this case, this configuration object is installed as <object name> if the target is in the environment <environment name>
- <object name>$$$<b4A connection name>: If the target client of the installation corresponds to the name of the b4A connection <b4A connection name>, then this configuration object is installed as <object name>.
- If there is neither an environment-specific nor client-specific configuration object for a configuration object <object name>, then the object <object name> is used. This must always exist, otherwise the other two objects will not be recognized either.
The following additional rules apply to static variables and XML variables:
- If the name of such a variable ends with #RUNTIME (configurable), it is considered a runtime variable.
- If the name of such a variable ends with @TEMPLATES@, it defines object templates to be registered (only for static variables).
- If the name of such a variable ends with @SCHEDULE@, this static variable defines schedule entries (only for static variables).
The content of the b4A Packages or the structure may differ between the versions of best4Automic, as the format is also being further developed. From format version 2, the b4A Packages contain an additional file package.info which contains this information. The following list shows which package format versions are supported:
| Format Version | Special feature |
|---|---|
| 1 | All configuration variables are saved as CSV files |
| 2 | The package.info file is included in every package and contains the format version; configuration variables are saved as XML files |
| 3 | Further information has been added to the package.info file, such as the object name of the metadata variable |
| 4 | This version supports multiple base folders for packages |
| 5 | Supports object permissions and storage objects (STORE) |
Each release of a b4A Package is given a version number. These have three or four digits and each component is separated from the others by a dot (except for the last digit).
X.Y.Z or X.Y.Z-N
This version system is widely used in the field of software development and is also called Semantic Versioning. The components of the version number are to be interpreted as follows.
- X (major version): If this component is incremented, then changes have been made in the
that are incompatible with previous versions. - Y (minor version): If this component is increased, then changes have been made in the
that bring new functions but do not affect compatibility with previous versions in the process. - Z (revision or correction version): If this component is incremented, then changes have been made in the
that are exclusively corrections and therefore do not contain any new functions or incompatibilities. If no fourth digit is used, configuration changes are also specified with this digit. - N (configuration change version): If this fourth digit is used, then only changes in the configuration are indicated with it.
Runtime objects
There are additional rules for some configuration objects. The so-called runtime objects are objects that are only installed in the target client if they have not yet been brought along by a previous version of the
- static variable
- XML variable
- Calendar object
Such objects are used to store runtime information that must not be overwritten during an update. This can be status information such as timestamps, for example. With calendar objects, this can be used to maintain static calendar events manually for each environment.
Dependencies
b4A Packages can have dependencies on other b4A Packages. This means that the objects of one b4A Package access the objects of another b4A Package. For example, include objects for frequently occurring tasks can be provided by a
A predefined format must be used to specify the dependencies in the metadata variable, which is composed as follows
<package name> <comparison operator> <version pattern>
If a
PCK.BEST4AUTOMIC_BASE ~> 1.4.0;PCK.BEST4AUTOMIC_DEMO >= 2.0.0
The following comparison operators are available:
- >=
- The version of the b4A Package must be exactly the same as or greater than the specified version
- 1.8.0 >= 2.0.0 -> false
- 1.8.20 >= 2.0.0 -> false
- 2.0.0 >= 2.0.0 -> correct
- 5.1.0 >= 2.0.0 -> correct
- <=
- The version of the
must be exactly the same or lower than the specified version
- 1.8.0 <= 2.0.0 -> correct
- 1.8.20 <= 2.0.0 -> correct
- 2.0.0 <= 2.0.0 -> correct
- 2.1.2 <= 2.0.0 -> incorrect
- ~>
- The version of the b4A Package must correspond to the specified version, i.e. all non-zero digits must be equal. Only the digits with a zero must be greater.
- 1.3.0 ~> 1.4.0 -> false
- 1.4.0 ~> 1.4.0 -> incorrect
- 1.4.1 ~> 1.4.0 -> correct
- 1.5.0 ~> 1.4.0 -> incorrect
- ~=
- The version of the b4A Package must correspond to the specified version, i.e. all non-zero digits must be the same. Only the digits with a zero must be greater than or equal to zero.
- 1.3.0 ~= 1.4.0 -> false
- 1.4.0 ~= 1.4.0 -> correct
- 1.4.7 ~= 1.4.0 -> correct
- 1.5.0 ~= 1.4.0 -> incorrect
There are also the simple operators > (greater than), < (less than) and = (equal to).
Schedule entries
If a b4A Package is to include schedule entries, these are to be found in a static or XML variable, which must correspond to a defined naming scheme. The entries must be specified as follows in the static variable:
- Key: unique key (e.g. a sequential number)
- Value 1: Start time in the format HH:MM
- Value 2: A comma-separated list of calendar conditions. Each element consists of a calendar object name and a keyword separated by a colon (e.g. CALE1:KEY1,CALE2:KEY2)
- Value 3: defines the rule for the calendar conditions. One of the keywords: ALL, NONE or ONE can be used here
- Value 4: Object name that is to be started
- Value 5: Name of the schedule object
In addition to the calendar terms, all other properties of a task in a scheduler can also be defined in the XML variable. The following is an example of a definition in which all possible properties for a task are set:
<best4Automic version="6.1.0">
<pm>
<scheduling>
<scheduler object="B4A.DEMO.JSCH.DEMO">
<entry object="B4A.DEMO.JOBP.MASTER" active="true">
<time start="12:00" offset="0"/>
<calendar active="true">
<executeIf>ONE</executeIf>
<conditions>
<condition object="B4A.DEMO#DE.CALE.KALENDER" key="SATURDAYS"/>
<condition object="B4A.DEMO#EN.CALE.CALENDAR" key="SUNDAYS"/>
</conditions>
</calendar>
<variables>
<entry key="HELLO#" value="Hello world"/>
</variables>
<promptSets>
<promptSet name="B4A.DEMO.PRPT.MASTER">
<entry key="FOO#" value="BAR"/>
<entry key="CHECKBOX1#" value="Value1;Value2"/>
<entry key="CHECKBOX2#">
<value>Value1</value>
<value>Value2</value>
<value>Value3</value>
</entry>
</promptSet>
</promptSets>
<runtime active="true">
<mrt method="FIXED" duration="05:00:12"/>
<srt method="ERT" additionalDuration="50"/>
<action>
<cancel active="true"/>
<execute object="B4A.DEMO.JOBP.ALARMING" active="true"/>
</action>
</runtime>
<result active="true" okState="ENDED_OK">
<action>
<elseRepeat active="true" repetitions="3" frequency="5"/>
<elseExecute active="true" object="B4A.DEMO.JOBP.RUNTIME-ERROR" mode="AFTER_LAST"/>
</action>
</result>
</entry>
</scheduler>
</scheduling>
</pm>
</best4Automic>
Several tasks (entries) can be stored for a scheduler. The entry node is used to specify the object name and decide whether the task should be set to active or not. The default value for the active field is "true". The time is the only mandatory entry. The start time must be entered in the format HH:MM. The default value for the start delay in days (offset) is 0 and does not have to be specified.
The calendar conditions can be switched on and off using the active field. The possible values for executeIf are ALL, ONE and NONE. As soon as the active field for the calendar conditions is set, the executeIf field and at least one calendar condition must also exist. The calendar conditions are then made up of the object name (object) and the calendar term (key).
The variable node contains a list of entries with variable name (key) and value (value). The key must always be specified without the "ampersand" (&). For the pre-assignment of the PromptSets of the task, a list of entries must again be specified below a PromptSet node with the attribute object for the name of the PromptSet. Checkboxes have a special feature when setting the default value. If the Array option is not set for the checkbox, the default value must be a character string with the values separated by the separator defined for this field. However, if the Array option is set, the value is not to be transferred as an attribute, but as a list of values below the entry node.
There is also an active field for the runtime information. If this is set to true, at least one of the two nodes mrt or srt must exist. There are three different methods for the maximum runtime (mrt). These are FIXED (fixed value), ERT (ERT + additional duration) and REAL (real date + additional duration). For the minimum runtime (srt) there are only the two methods FIXED and ERT. The attributes to be set differ depending on the method. An example is therefore given below for each case:
<mrt method="FIXED" duration="01:23:45"/>
<mrt method="ERT" additionalDuration="50"/>
<mrt method="REAL" days="1" finishTime="05:00" timeZone="TZ.CET"/>
<srt method="FIXED" duration="05:00:12"/>
<srt method="ERT" additionalDuration="50"/>
The duration must be specified in the format HH:MM:SS. The timezone can be omitted if it is not to be defined. For the actions in the event of a runtime deviation (action), the tasks can be canceled (cancel) if the runtime is exceeded and another task can be executed (execute) if the runtime is exceeded or not reached. If the latter is set to true, an object to be executed must also be defined.
Finally, the result check can be configured. If the active field (active) is set to true, an OK status (okState) must also be defined. The actions can then be optionally configured. If the task is to be repeated if the OK status does not apply (elseRepeat), the node must be set to active. The repetitions and the repetition rate (frequency) can also be optionally transferred. Otherwise they are set to 0. If another object is to be executed when the OK status does not apply, elseExecute must be set to true. The object (object) and the mode (mode) are then mandatory fields. The modes are either AFTER_EVERY (execute object after every unsuccessful repetition) or AFTER_LAST (execute object only after the last unsuccessful repetition).
A custom solution is provided for the migration of static schedule variables to XML variables.
Access data storage
Login and connection objects can be transported like all other objects. However, these objects lose the values of attributes that contain passwords. As such data must be treated very sensitively, b4A Deployment offers the option of storing this information separately from the release archives and only in a central location in encrypted form. During the installation process, this data is retrieved via an encrypted connection and entered into the installed login and connection objects.
The central storage location supported by b4A Package Management is a storage object. An entry is stored in this for each login and connection object. These entries each contain a small text file that contains all relevant information for the access data of an object. For example, if there is a login object PCK.B4A_CREDENTIALS.LOGIN.WIN and a connection object PCK.B4A_CREDENTIALS.CONN.REST, then a storage object with the access data can look like this.
| name | file name | type |
|---|---|---|
| PCK.B4A_CREDENTIALS.LOGIN.WIN | login.win.credentials | TEXT |
| PCK.B4A_CREDENTIALS.CONN.REST | conn.rest.credentials | TEXT |
The entries in the storage object can either be added with the pm.CredentialStorageAdd module or created manually. In order to create these entries correctly, different file formats must be observed for the supported object types. The basic format for all data is the Java properties format.
*Login objects
For these objects, files can be created that contain any number of lines in the following format.
<host>/<host type> = <username>;<encrypted password>
Example:
*/UNIX = techuser01;--10B41571A6ED5B9D28
*/WINDOWS = domain\\techwin01;--10B41571A6ED5B9D28
WIN01/WINDOWS = domain\\user2;--10B41571A6ED5B9D28
RA-Connection (WEBSERVICEREST, WEBSERVICESOAP, WEBSERVICE, MAILAGENT, FTPAGENT, INFORMATICA)
For these object types, only two entries must be written to the file that correspond to the following format.
username = <username>
password = <encrypted password>
Example:
username = techwebservice01
password = --10B41571A6ED5B9D28
Other RA-Connection objects are currently not supported.
For Informatica connection objects, the domain user and their password can also be specified.
domain-username = <username>
domain-password = <encrypted password>
For FTPAGENT connection objects, a passphrase for the GPG key can also be specified.
passphrase = <encrypted password>
*database connection
The format for this type of connection object is similar to the format for the RA connection objects described above.
username = <username>
password = <encrypted password>
Example:
user = usersql
password = --10B41571A6ED5B9D28
*R3-Connection
The format of these connection objects is the same as the format of the previous connection objects. In addition, further entries are supported that are only required if the SMSE interface is used.
ae-user = <AE user name>
ae-department = <AE department of the user>
ae-password = <encrypted password for the AE user>
ae-client = <AE client>
Example:
user = userr3
password = --10B41571A6ED5B9D28
ae-user = WRITER
ae-department = B4A
ae-password = --10B41571B7ED5B9D40
ae-client = 10
Once the data has been created in the correct format, it can be inserted as an entry in a storage object. The following rules must be observed.
- The entry must have the same name as the login or connection object for which this access data is intended
- The type must be set to TEXT
As access data usually differs in the environments, b4A Deployment offers the option of saving the access data in an environment-specific and even client-specific manner. The same naming concept is used for this that is also used for configuration variables. For example, if there is a central storage object SYSTEMS.CREDENTIALS and an environment AE12PROD has been defined in the b4A configuration, then access data for the environment AE12PROD can be stored in the storage object SYSTEM.CREDENTIALS$$$AE12PROD. If there is access data that is intended exclusively for client 1200 in the environment and the b4A connection to it is called AE12PROD-1200, then the access data can be stored in the storage object SYSTEM.CREDENTIALS$$AE12PROD-1200.
Special object types
Special rules apply to some object types.
*Object links
Object links are not supported in packages.
*Login and connection objects
The objects can be transported, but the passwords they contain are not transported (see previous section). In addition, these are only imported if they do not yet exist in the target environment. Depending on whether a storage object with access data was specified during installation or whether the option to force installation for connection objects was specified, the behavior may change. The various cases are considered separately below.
-
Connection objects
-
First installation
- Without a storage object, only the object is imported
- With a storage object, the access data is restored after the import if it is found
-
Update
-
Without forced import option
-
Without storage object, the object is not imported
- If the previous version has access data, this leads to an error
-
With storage object, the object is not imported, only the access data is updated
-
-
With option for forced import
- Without storage object, the object is not imported if the currently installed version contains access data
- With storage object, the object is installed if access data is found in the storage object
-
-
-
Login objects
-
First installation
- Without a storage object, only the object is imported
- With a storage object, the access data is restored after the import if it is found
-
Update
- Without storage object, the object is not imported
- With a storage object, the object is not imported, only the access data is updated. To do this, all access data is first removed from the login object and then the access data from the storage object is entered.
-
*Schedule objects
After installation, these objects are automatically reloaded when the period changes
*Sync and queue objects
These objects contain status information in their object definition. Therefore, these objects are only installed in the pre-configuration if they do not yet exist. This is configurable.
*Calendar objects
If several calendar objects are rolled out in a package whose calendar terms depend on each other, the sequential import of objects may mean that individual calendar terms cannot yet be calculated after the import. These are identified and a warning is displayed in the report. Once all objects (including configuration folders) have been imported, another attempt is made to calculate the calendar terms of those calendar objects for which it did not work after the import. If this still does not work at this point, there are dependencies to calendar items outside the package that are not yet in the client. The installation process then terminates at this point.
Object authorizations
Separate authorizations can be defined for the individual objects. These override the global rules that are set for users or groups. These authorizations are not part of the object definitions, but are saved separately. This data is also transported with b4A Package Management. The following rules apply.
-
If object authorizations are assigned, the user used by b4A must still have rights to the object, otherwise the transport is no longer possible.
-
For configuration objects, the object authorizations of the respective standard configuration object are used. This means that object authorizations for client and environment-specific objects have no effect
-
The object authorizations are also taken into account during Git integration. The pm.Push module saves these in the repository and they are restored using the pm.Pull module.
Index
If the number of
To use the b4A Package index, it must initially be created once with the pm.Index module. The b4A Module pm.Build, pm.Install, pm.DependencyDefinitionCreate and pm.Init then automatically update the index of the respective client. All these modules require exclusive access to the index object. If the variable is currently open for writing, these modules wait until the variable can be opened for writing.
Object types
The b4A Package index can be stored in two different object types. While the XML variable can be used well for small and medium-sized environments, storing the index in a storage object is recommended for larger or growing package numbers.
Variants
The b4A Package index can be operated in two different variants, which are described in more detail below.
Local
With this variant, an XML variable or a storage object is used in each client to write the index. The key used is defined in the configuration file pm.conf.
Global
In this mode, a client is selected in an environment in the configuration file pm.conf (naming of a b4A connection) in which the index is written for all clients. A key is used for the XML variable or the storage object for each client. This is named after the b4A connection.
Configuration
There is a configuration file pm.conf for the modules in this area, which defines some specifications for the behavior of the modules. As a rule, these settings should be left at the default values. In exceptional cases, they can be adjusted.
| Variable | Type | Description |
|---|---|---|
| pm-runtime-variables | Object name pattern | Pattern for object names of runtime variables |
| pm-config-separator | Character string | A character string that identifies configuration variables as a client configuration |
| pm-config-folder | Folder | Name of the folder in which the configuration variables are located |
| pm-base-folder | Folder | Default base folder in which the packages are located. A base folder can be located at any level of the folder structure. For example, PACKAGES, PACKAGES/SYSTEM or INTERN/TEST/B4A. |
| pm-alternative-base-folders | List of folders | Other base folders in which packages can be located. |
| pm-bin-folder | Folder | Folder in which the public executable objects (actions) are located |
| pm-source-folder | Folder | Folder in which the used objects (e.g. tasks in workflows) are located |
| pm-deprecated-folder | Folder | Folder to which obsolete objects are moved |
| pm-deprecated-pattern | b4A Expression | Pattern for renaming obsolete objects. The attributes %(object_name) (old object name) and %(timestamp) can be used in the pattern. The timestamp has the format yyyy-MM-ddTHHmmss. |
| pm-templates-pattern | b4A Expression | Pattern for the object name of the variable with templates to be registered. The attribute %(package) can be used in the pattern |
| pm-metadata-pattern | b4A Expression | A comma-separated list with patterns for the object name of the metadata variable. The attribute %(package) can be used in the patterns. The first pattern is the preferred name and is used by the pm.Init module, for example. A list of patterns can become relevant if several types are used. For example, Automic's own package format and actions packs. |
| pm-schedule-pattern | b4A Expression | Pattern for the object name of the variable with schedule definitions. The attribute %(package) can be used in the pattern |
| pm-releasenotes-pattern | b4A Expression | Pattern for the object name of the Release Notes variable. The attribute %(package) can be used in the pattern |
| pm-metadata-key-dependencies | Character string | Name for the entry with the dependency definitions |
| pm-metadata-key-categories | Character string | Name for the entry of the categories that can be used when registering the actions |
| pm-metadata-key-version | Character string | Name for the entry of the package version number |
| pm-metadata-key-built-on | Character string | Name for the entry of the build timestamp of the package |
| pm-metadata-key-installed-on | String | Name for the entry of the installation timestamp of the package |
| pm-metadata-key-initialized-on | String | Name for the entry of the initialization timestamp of the package |
| pm-actions-folder | Folder | Folder in which registered publicly executable objects (actions) are linked (AWI) |
| pm-createonly-objecttypes | List of object types | A comma-separated list of object types that are only installed if they do not yet exist in the target client. This rule is only applied if they are not in the folder for configuration variables. |
| pm-index-folder | Folder | Folder in which the object of the b4A Package index is stored |
| pm-index-variable | object-name | name of the object for the b4A Package index |
| pm-index-type | object type | object type of the index object. Possible values are VARA.XML or STORE |
| pm-index-packages-key | String | Key in the index object in which the |
| pm-index-basefolders-key | Character string | Key in the index object in which the base folder index can be found |
| pm-index-additional-entries | List of strings | A comma-separated list of entries from the metadata that should also be stored in the index |
| pm-index-mode | local, global | The local value defines the mode in which the index object is maintained in each client and the global value is used for a central index object for all indices. |
| pm-index-connection | b4A connection | If the global mode is used for the index, this setting defines the connection in which the index object is to be found. |
| pm-index-exclusive-open-interval | An interval in milliseconds that is used to define how long to wait between attempts when opening the index exclusively. | |
| pm-package-name-regex | regular-expression | A regular expression that defines the permitted package names. This expression is used to check package names for correctness. This can be used, for example, for the package folder and the name in the metadata variables. The expression must describe the entire name. |
| pm-object-name-regex | regular expression | A regular expression that is used to extract the package name from object names. The name must be enclosed by the named group package. If desired, the regular expression for package names can be referenced via the b4A expression attribute package-name. |
| pm-package-ownership-fallback | Boolean value | If modules are to determine the affiliation of objects to packages and the package cannot be derived from the object name, this option can be used to activate a fallback that checks whether the object is located below a package folder. |
| pm-object-references-with-variable-ignore | Boolean value | If this option is active, modules that use object references to find package dependencies will ignore references that contain script or object variables. |