Overview

The Bundles and Promotion feature is designed to facilitate migrating (promoting) groups (bundles) of workload automation definitions (Triggers, Workflows, Tasks, Calendars, Custom Days, Variables, Business Services, Credentials, Agent Clusters, Virtual Resources, Scripts, Email Templates, Email Connections, Database Connections, SNMP Managers, SAP Connections, PeopleSoft Connections, Applications, and Universal Templates) between Universal Controller instances.

This allows you to develop, modify, and test changes in a non-production environment and migrate them to your production environment in a fully secure and audited manner (with back-out capabilities, if required).

One or more Workload automation definitions of the same type can be promoted without going through the process of creating a bundle, or you can use a bundle to group together related workload automation definitions of different types for promotion at the same time.

Bundles can be promoted manually or scheduled to be promoted at a specific date and time. If you choose to schedule a bundle promotion, you can either promote the definitions as they stand at promotion time or use a snapshot of the definitions as they stand when the promotion schedule is created. This can be useful if you have completed changes that need to be promoted out-of-hours but want to allow more changes to be made on the source system without having to wait until the promotion is complete.

CLI (Command Line Interface) and API (Application Programming Interface) functions are provided to allow you to integrate the bundles and promotion feature with your external application life-cycle, source management, and change control systems.

If you plan on using the Bundles and Promotion feature, it is important that you review the recommended best practices for this feature.

Bundle and Promotion Security

Use of the Bundle and Promotion feature requires some thought, based on which users require the feature and what functions they need access to.

Bundle Security

The ops_bundle_admin role, which automatically is encompassed within the ops_admin role, grants the following functions:

Create, read, update, and delete Bundles.
View Promotion Targets, including agent mappings.
View Promotion History.
View a record's list of bundles.
View Promotion Schedules.
Add a record to a bundle.
Create bundles by date.
Generate a Bundle Report.

Users can be granted more granular permissions to Bundles via their User or Group permissions:

Read - View bundles based on name and/or membership of business service.
Update - View, and Modify bundles based on name and/or membership of business service.
Create - Create, View, and Modify bundles based on name and/or membership of business service.
Delete - Delete bundles based on name and/or membership of business service.
The Promote command for a bundle can be granted or denied via the Bundle permission.

Users can select definitions only for Bundles that they can at least view.

Promotion Security

The ops_promotion_admin role, which automatically is encompassed within the ops_admin role, grants the following functions:

Create, read, update, and delete Promotion Targets, including agent mappings.
View Bundles.
Refresh Target Agents.
Promote records.
Promote or schedule the promotion of a bundle.
Reschedule, cancel, and delete Promotion Schedules.
Generate a Bundle report.
Accept bundles being promoted to a target server. (The Accept Bundle command is executed on the target server automatically as part of the Promote and Promote Bundle commands and does not involve user interaction.)

Note

By default, the ops_promotion_admin role also grants Read permission for any type of definition that can be added to a Bundle, given the expectation that a promotion administrator would review the content of a Bundle before promoting it. To change this default behaviour, see the Promotion Read Permission Required Universal Controller system property.

Users can be granted more granular permissions to Promotion Targets via their User or Group permissions:

Read - View promotion targets based on name and/or membership of business service
Update - View, and Modify promotion targets based on name and/or membership of business service
Create - Create, View, and Modify promotion targets based on name and/or membership of business service
Delete - Delete promotion targets based on name and/or membership of business service
The Refresh Target Agents command for a promotion target can be granted or denied via the bundle permission.

The ability to Promote a Bundle without the ops_promotion_admin role requires:

Read permission to the Bundle
Permission to the Promote command for the Bundle
Execute permission to the Promotion Target
ops_promotion_accept_bundle role assigned to the target user; specifically, the user specified on the Promotion Target or on the Promote Bundle command dialog.

Bundleless Promotion

With the ops_promotion_admin role, users can promote definitions by clicking Promote... in the Action menu.

The Bundleless Promotion With Execute Permission Permitted Universal Controller system property can be set to true (default = false) to allow promotion of definitions outside of a Bundle without requiring the ops_promotion_admin role if the users also have Execute permission to at least one Promotion Target.

Universal Controller Properties

The following Universal Controller system properties also should be reviewed in accordance with the desired behavior of the Bundles and Promotion feature:

Promotion Accept Bundle Create/Update Permission Required
Promotion History Retention Period in Days
Promotion Read Permission Required
Promotion Schedule Retention Period In Days
Promotion Strict Mode

Best Practices

Shared Records

Because workload automation definitions have many inter-related records (for example a single task may reference an agent, a credential, and virtual resources), it is important that care is taken to avoid breaking these links between Universal Controller instances when promoting.

For Agents, you can specify agent mappings on the promotion target definition to translate between an agent connected to the source Universal Controller instance and a different agent connected to the target Universal Controller instance.

For other definitions, you should ensure that each definition's UUID (Universally Unique IDentifier) is the same on all Universal Controller instances involved in your promotion hierarchy (Production, QA, Development, etc.).

One best practice for this is to create the definitions on one Universal Controller instance and promote them to the other Universal Controller instances. In some cases, these definitions will need to be different on each Universal Controller instance; for example, a credentials password will be different between the test and production instances. In these cases, you would need to modify them after the initial promotion, and you will need to take care not to promote the test definition and overwrite the production definition with the wrong password.

Another approach would be to use variables for the related definition; for example, a Task definition could use variables to identify its agent and credential definition. Note that variables can be nested, so you can use an instance identifier within the variable.

For example:

On the PROD instance, the Agent name is PROD_APP_Server and the following global variable exists: ENV = PROD
On the TEST instance, the Agent name is TEST_APP_Server and the following global variable exists: ENV = TEST

In this case, for the Agent within a Task definition, you would specify the following variable: ${ENV}_APP_Server.

Follow References

When promoting workload automation definitions between Universal Controller instances, you have the option to Follow References, which automatically includes inter-related records when promoting.

In other words, you do not have to build a bundle definition with all of the inter-related records; you can just specify a high-level item such as a trigger or workflow.

Caution should be used when considering the Follow References feature in relation to the shared records you may have on different Universal Controller instances. As of version 6.4.2.0 of the Controller, you have the ability to exclude certain definition types from the promotion when using the Follow References feature. For example, you can follow references and exclude variables.

Note that for some workload automation definitions, there are references that are followed implicitly, even if Follow References is not specified. For example, a workflow will always also promote the tasks within the workflow.

For additional information on Follow References behavior, see Records Promoted When Follow References is Selected or Not Selected.

Modifying Task Names

When modifying a task name, Universal Controller ensures that the vertex data of any workflow task containing that task is updated, assuming a vertex alias is not being used.

To promote the task name modification to another system, promote both the task and any workflow task that would have been modified by the change. You can use the View Parents operation to determine parent workflow tasks. In the case where you modify a task name and do not promote the parent workflow tasks, the vertex names can become out-of-sync.

Promoting Between Different Controller Versions

Promotion of workload automation definitions between Universal Controller instances at different versions is supported from version 6.3.0.0 and later. Promotion can be performed to earlier or later versions as long as both Universal Controller instances are at least at the 6.3.0.0 version.

Note

Promoting to an earlier version, when supported, requires that the promotion payload not include features or options that are unknown to the target promotion server. Any violation of this will prevent the promotion from continuing, as promoting those changes could have unintentional consequences.

Promoting to Same or Later Versions

Supported

Promotion from a source Controller to a target Controller of the same or later version, release, modification, and maintenance level is supported.

For example:

6.9.0.0 to 6.9.0.1
6.9.0.1 to 7.0.0.0
7.0.0.0 to 7.0.0.0

Promoting to Earlier Versions

Supported

Promotion from a source Controller to a target Controller of an earlier version, release, modification, or maintenance level is supported if the target Controller has not reached an End of Support Date.

For example:

6.9.0.1 to 6.9.0.0
7.0.0.0 to 6.9.0.1

Not Supported

Promotion from a source Controller to a target Controller of an earlier version, release, modification, or maintenance level is not supported if the target Controller has reached an End of Support Date.

For example:

7.0.0.0 to 6.6.0.1

Bundling and Promoting Process

The general process for bundling and promoting your data is:

Step 1	Prepare a Bundle for Promotion record.
Step 2	Add records to a Bundle.
Step 3	Create a Promotion Target record for each target Controller.
Step 4	Specify Agent mappings between the source and target Controllers.
Step 5	Promote the Bundle to the target Controller.

These features use web services calls to communicate when you are promoting Bundles of records from one Controller to another.

Diagnosing Promotion Failures

The following error messages are provided for various promotion failure scenarios.

Note

For a Bundle promotion, the beginning of each error message is: Promotion of bundle "bundle-name" failed with the following error(s):

For a Bundle-less promotion, the beginning of each error message is: Promotion failed with the following error(s):

Error Message	Diagnosis
Acceptance of bundle "<bundle-name>" from <node-id> prohibited because a payload from a bundle with the same name is currently being processed by another Universal Controller process.	Accept Bundle command invoked on the target for a bundle with a bundle name for which another Universal Controller process has already acquired a lock.
Bundle "Member of Business Services" option requires a minimum promotion target release level of 6600.	Attempt to promote a Bundle that is a member of a Business Service to a target that is not 6.6.0.0. or higher.
Cannot update Universal Template <Template Name>: Universal Template cannot be updated; System Template cannot be changed.	Attempt to promote a Universal Task that references a Universal Template (not built-in) and the incoming Universal Template matches a Universal Template on the Promotion Target and it is a built-in Universal Template.
Cluster node information could not be determined for the promotion target because the host is unknown (hostname).	Invalid hostname.
Cluster node information could not be determined for the promotion target (Connection refused: connect).	Valid hostname, but no service to accept the connection.
Cluster node information could not be determined for the promotion target because the Web Service is unavailable; the target Universal Controller may still be initializing.	Attempt to promote to a target Universal Controller that is still initializing (starting up).
Cluster node information could not be determined for the promotion target because the user is not authorized; please verify the promotion target user and password.	Invalid user name and/or password.
Cluster node information could not be determined for the promotion target because the user is not authorized for Web Service Access; please verify the promotion target user has Web Service Access enabled.	Valid user name and password, but the user is not authorized for Web Service Access.
Cluster node release level for the promotion target could not be determined and one or more items being promoted require a minimum release level of 6300.	Attempt to promote to a pre-6.3.0.0 release from a 6.3.0.0 or later release.
Cluster node release level for the promotion target is 6xxx, which does not meet the required release level of 6xxx.	Attempt to promote a definition, or a definition using a particular feature, that is not recognized by the promotion target. This message will be followed by one or more messages, each detailing a specific definition or specific feature used by a definition that is not recognized by the promotion target. For example: Cluster node release level for the promotion target is 6403, which does not meet the required release level of 6420. Windows Task "Resolve Name Immediately" option requires a minimum promotion target release level of 6420. Web Service Tasks require a minimum promotion target release level of 6410. OR Cluster node release level for the promotion target is 6601, which does not meet the required release level of 6700. <task-type> Task "Cluster Broadcast Variable" option requires a minimum promotion target release level of 6700.
Command Accept Bundle prohibited due to security constraints.	Valid user name and password, but the user is not authorized for the Accept Bundle command, which requires the ops_promotion_admin role.
Command Accept Bundle prohibited due to security constraints. User on target server requires "ops_bundle_admin" role if "Promote Bundle Definition" option is enabled.	Valid user name and password, but the user is not authorized for the Accept Bundle command with the Promote Bundle Definition option enabled, which requires both the ops_promotion_admin role and the ops_bundle_admin role.*
Command Promote (or Promote Bundle) has been routed to the Active server and continues to run in the background.	Promote (or Promote Bundle) command was issued to a Passive server and routed to the Active server, where the Promote (or Promote Bundle) command will run, however, the Promote (or Promote Bundle) command did not complete within approximately 2 minutes. The Promote (or Promote Bundle) command will continue to run in the background and the Audit can be consulted to determine the outcome of the command.
Command Promote Bundle cannot be executed because Promote Members of Business Services or Visible To is not empty, and Universal Controller property “Promote By Business Service Membership Permitted” is not enabled.	Attempt to promote a bundle with Promote Members of Business Services or Visible To non-empty when Promote By Business Service Membership property is false.
Command Schedule Promotion cannot be executed because Promote Members of Business Services or Visible To is not empty, and Universal Controller property “Promote By Business Service Membership Permitted” is not enabled.	Attempt to schedule a bundle promotion (using Snapshot) with Promote Members of Business Services or Visible To non-empty when Promote By Business Service Membership property is false.
Credential "<credential-name>" cannot be promoted because web service credentials are not permitted; Universal Controller property Web Service Credentials Permitted is not enabled.	Attempt to promote to a target Controller where the Web Service Credentials Permitted Universal Controller system property is set to false.
Field "Default Value", when greater than 4000 characters, requires a minimum promotion target release level of 7200.	Attempt to promote a Universal Template with a Default Value field value greater than 4000 to a target that is not a 7.2.0.0 or later release.
File Transfer Task "Transfer Protocol" option "FTPES" requires a minimum promotion target release level of 7200.	Attempt to promote a File Transfer Task with Transfer Protocol = FTPES to a release earlier than 7.2.0.0.
File Transfer Task "Authenticate Peer" option requires a minimum promotion target release level of 7200.	Attempts to promote a File Transfer Task with "Authenticate Peer" option requires a minimum promotion target release level of 7200.
File Transfer Task "Verify Host Name" option requires a minimum promotion target release level of 7200.	Attempt to promote a File Transfer Task with "Verify Host Name" option requires a minimum promotion target release level of 7200.
Promoted {EMAIL CONNECTION: Incoming} with name "Gmail" and id 04e5e1074c1f42908d9b3f62f36fff50 is a different type than the original {EMAIL CONNECTION: Outgoing} with name "Gmail" and id 195fc662df8447dc90dec02ea8be0cb4	Attempt to promote an Incoming email connection type and the email connection on the target system is an Outgoing email connection type.
Promoted {EMAIL CONNECTION: Outgoing} with name "Gmail" and id ab36222512cf4ae4afa7e59a8ccbd684 is a different type than the original {EMAIL CONNECTION: Incoming} with name "Gmail" and id a037048f7c4b4e3f9e8691e3f664e5a7	Attempt to promote an Outgoing email connection type and the email connection on the target system is an Incoming email connection type.
Promoted {TASK: Universal} with name "ABC", id 8ee785079fcc4142873486e921bfe789, and universal template id 04cbe858ba7a4bc8bdb26202f359e318 has a different universal template id than the original "ABC" with id 8ee785079fcc4142873486e921bfe789, and universal template id 04cbe858ba7a4bc8bdb26202f359e319.	Attempt to promote a Universal Task with an associated Universal Template that is not equivalent to the Universal Template associated with the target Universal Task.
Promoted {TASK: Universal} with name "<Task Name>" and id <Task UUID> references a built-in Universal Template with name "<Template Name>" and id <Template UUID> that is not loaded on the target server. Use the "List/Load Built-in Universal Templates" Server Operation to load built-in Universal Templates.	Attempt to promote a Universal Task that references a built-in Universal Template and the built-in Universal Template does not exist on the Promotion Target.
Promoted {TASK: Universal, TaskUniversalBean} with name "ABC" and id 8ee785079fcc4142873486e921bfe789 is a different type and/or class than the original {TASK: Timer, TaskSleepBean} with name "ABC" and id dfbd23df8ab24b2a9a0891ae2f8ca22f.	Attempt to promote any item of a specific type (or Java class) that matches another item of a different type (or Java class).
Promoted {UNIVERSAL TEMPLATE} with name "<Template Name>" and id <Template UUID> has a different id than the original "<Template Name>" with id <Template UUID>.	Attempt to promote a Universal Task that references a built-in Universal Template and the incoming built-in Universal Template matches a Universal Template on the Promotion Target by name only (that is; UUID mismatch).
Promoted {UNIVERSAL TEMPLATE} with name "<Template Name>" and id <Template UUID> is a built-in universal template; however, the original "<Template Name>" with id <Template UUID> is not.	Attempt to promote a Universal Task that references a built-in Universal Template and the incoming built-in Universal Template matches a Universal Template on the Promotion Target and it is not a built-in Universal Template.
Promoted {UNIVERSAL TEMPLATE} with name "<Template Name>" and id <Template UUID> matches both "<Template 1 Name>" with id <Template 1 UUID> by name and "<Template 2 Name>" with <Template 2 UUID> by id.	Attempt to promote a Universal Task that references a built-in Universal Template and the incoming built-in Universal Template matches a Universal Template on the Promotion Target by both name and id. In other words, Promotion Strict Mode is always used for built-in Universal Templates.
Promotion of bundle “bundle-name” failed with the following error(s): Bundle “<bundle-name>” cannot be promoted because Promote Members of Business Services or Visible To is not empty, and Universal Controller property “Promote By Business Service Membership Permitted” is not enabled.	Attempt to promote a bundle with Promote Members of Business Services or Visible To non-empty to a target system where Promote By Business Service Membership property is false. (The target system rejects the promotion). Note: This is applicable only if Promote Bundle Definition = true.
Promotion of bundle "<bundle-name>" with id <bundle-uuid> prohibited because the bundle is in use by another Universal Controller process.	Promote Bundle command invoked on the source for a bundle with a bundle id for which another Universal Controller process has already acquired a lock.
Promotion Schedule operation for bundle "<bundle-name>" with id <bundle-uuid> prohibited because the bundle is in use by another Universal Controller process.	Schedule Promotion command requires the bundle id lock, but another Universal Controller process has already acquired that lock.
Promotion target "promotion-target-name" has routed the promotion payload to the Active server and the Accept Bundle command continues to run in the background.	Upon receiving the promotion payload, the promotion target determined it was a Passive server and routed the payload to the Active server, where the Accept Bundle command will run, however, the Accept Bundle command did not complete within approximately 2 minutes. The Accept Bundle command will continue to run in the background and the Audit can be consulted to determine the outcome of the command.
Promotion to an earlier release only supported for target releases starting with 6300.	Attempt to promote to a pre-6.3.0.0 release from a 6.3.0.0 or later release.
Protocol <protocol name> is not allowed since it is being excluded by Universal Controller property "File Transfer Task Exclude Protocols".	Attempt to promote a File Transfer Task that has a protocol currently being excluded by the target server.
Protocol <protocol name> is not allowed since it is being excluded by Universal Controller property "FTP File Monitor Task Exclude Protocols".	Attempt to promote an FTP File Monitor Task that has a protocol currently being excluded by the target server.
Recurring Task "Override Variables" delimited name/value pairs, when exceeds the combined maximum of 4000 characters, requires a minimum promotion target release of 7100.	Attempt to promote a Recurring Task with Override Variables delimited name/value pairs that exceeds the combined maximum of 4000 characters to a Promotion Target release that is not 7.1.0.0 or higher.
Remote File Monitor "Server Type" option "FTPES" requires a minimum promotion target release level of 7200.	Attempt to promote a Remote File Monitor with Server Type = FTPES to a release earlier than 7.2.0.0.
Remote File Monitor "Authenticate Peer" option requires a minimum promotion target release level of 7200.	Attempt to promote a Remote File Monitor with Authenticate Peer = true to a release earlier than 7.2.0.0.
Remote File Monitor "Verify Host Name" option requires a minimum promotion target release level of 7200.	Attempt to promote a Remote File Monitor with Verify Host Name = true to a release earlier than 7.2.0.0.
SAP Connection "Client" option requires a minimum promotion target release level of 6700.	Attempt to promote an SAP Connection to a release prior to 6.7.0.0 when the Connection Type is Load Balancing and a Client is specified.
SAP Task "<job-id-field-name>" requires a minimum promotion target release level of 6450 when unspecified.	Attempt to promote an SAP Task with an unspecified SAP Job ID field to a pre-6.4.5.0 release of the Controller.
Script "<script-name>" cannot be promoted because scripts are not permitted; Universal Controller property "Windows/Linux Scripts Permitted" is not enabled.	Attempt to promote a Script Script Type from a source server to a target server, where the target server is configured with the Windows/Linux Scripts Permitted Universal Controller system property set to false.
<task-type> Task "Exit Codes" requires a minimum promotion target release level of 6700 when unresolved.	Attempt to promote a task with an unresolved Exit Codes field to a release prior to 6.7.0.0.
<task-type> Task "Retry Exit Codes" requires a minimum promotion target release level of 6700 when unresolved.	Attempt to promote a task with an unresolved Retry Exit Codes field to a release prior to 6.7.0.0.
Unable to promote {APPLICATION: Windows Service} with name "<application-name>" and id 0f84fbb388c04bd09a2c7d5a0ac06c70 because an application cannot be promoted with a name change while generated application control tasks are being excluded.	Attempt to promote an Application with a name change while excluding generated Application Control Tasks.
Unable to promote <credential-type> credential "<credential-name>" since original Resolvable credential is referenced by one or more Universal Tasks.	Attempt to promote a Credential that has been converted from a Resolvable type and at least one reference on the target system by a Universal Task requires it to remain a Resolvable type.
Unable to promote <credential-type> credential "<credential-name>" since original Resolvable credential is specified as a default value for one or more Universal Template Fields.	Attempt to promote a Credential that has been converted from a Resolvable type and at least one reference on the target system by a Universal Template Field default value requires it to remain a Resolvable type.
Unable to promote <credential-type> credential "<credential-name>" since original Web Service credential is referenced by one or more Web Service Tasks.	Attempt to promote a Credential that has been converted from a Web Service type and at least one reference on the target system by a Web Service Task requires it to remain a Web Service type.
Unable to promote {CUSTOM DAY} with name "<custom-day-name>" and id 343f68c60cef48279647a45055349c47 because global custom days are not permitted; Universal Controller property "Custom Day Global Permitted" is not enabled.	Attempt to promote a global Custom Day when the Custom Day Global Permitted system property is set to false.
Unable to promote {SCRIPT: Web Service Payload} with name "Data2.txt" and id 1a9f0bbad53b4ca9a6d6076c5970586e since original {SCRIPT: Data} with name "Data2.txt" and id 1a9f0bbad53b4ca9a6d6076c5970586e is referenced by one or more Universal Tasks.	Attempt to promote a non-Data script type and the script on the target system is a Data script type currently referenced by a Universal Task (unless all references are included in the promotion payload).
Unable to promote {SCRIPT: Script} with name "Data1.txt" and id c78a9fe3748549808ac5f6248eb4bcc2 since original {SCRIPT: Data} with name "Data1.txt" and id 4d7d06e87aef4461aeabbb21191b4c61 is specified as a default value for one or more Universal Template Fields.	Attempt to promote a non-Data script type and the script on the target system is a Data script type currently referenced by a Universal Template (via Universal Template Field).
Unable to promote {TASK: Application Control} with name "<application-name> #QUERY#" and id e9632e6024324d619b3122832e84c8b0 because a generated application control task cannot be promoted with a name change while applications are being excluded.	Attempt to promote a generated Application Control Task with a name change while excluding Applications.
Unable to promote {TASK: Universal} with name "<Task Name>" and id <Task UUID> since the built-in Universal Template with name "<Template Name>" and <Template UUID> has changed; Universal Controller property "Reconcile Built-in Universal Template Changes On Promotion" is not enabled.	Attempt to promote a Universal Task that references a built-in Universal Template and the incoming built-in Universal Template differs from the original built-in Universal Template on the Promotion Target.
Universal Task “<field label>” option requires a minimum promotion target release level of 7200.	Attempt to promote a Universal Task with a non-blank Large Text Field 3 or Large Text Field 4 to a Universal Controller release prior to 7200.
Universal Task "<field label>", when greater than 4000 characters, requires a minimum promotion target release level of 7200.	Attempt to promote a Universal Task with a Large Text field 1 or Large Text field 2 with value greater than 4000 to a Universal Controller release prior to 7200.
Universal Task "Universal Template" with built-in universal template reference requires a minimum promotion target release level of 6800.	Attempt to promote a Universal Task that references a built-in Universal Template to a Promotion Target release that is not 6.8.0.0 or higher.
Universal Template "<template-name>" cannot be promoted because [it is a new template \| the template has changed] and the promotion was performed without the "Allow Universal Template Changes" option enabled. Universal Template changes must be promoted by a user with either the "ops_universal_template_admin" role or the "ops_admin" role and with the Allow Universal Template Changes option enabled.	Attempt to promote a new or changed Universal Template without proper authorization or with proper authorization but without proper option usage.
Universal Template "<template-name>" cannot be promoted because [it is a new template \| the template has changed] and the promotion user does not have either the "ops_universal_template_admin" role or the "ops_admin" role required to perform the promotion with the "Allow Universal Template Changes" option enabled.	Attempt to promote a new or changed Universal Template without proper authorization (on Promotion Target) but with proper option usage.
Variable "Value", when greater than 4000 characters, requires a minimum promotion target release level of 7100.	Attempt to promote a variable greater than 4000 character to a Promotion Target release that is not 7.1.0.0 or higher.

Browser not supported