Plug-in Documentation

IBM UrbanCode Release

Overview

Use the IBM UrbanCode Release plug-in to manage the integration of IBM UrbanCode Deploy with IBM UrbanCode Release. The plug-in includes steps to retrieve the active release for an environment, add comments to tasks, add statuses to snapshots and updating the IBM UrbanCode Release inventory for an application.

To add the IBM UrbanCode Release plug-in steps to processes, click IBM UrbanCode Release in the step palette of the process editor.

This plug-in includes these steps:

Compatibility

This plug-in requires IBM UrbanCode Deploy version 6.0.1.2 or later.

This plug-in runs on all operating systems that the IBM UrbanCode Deploy agent supports except for IBM z/OS.

Installation

No special steps are required for installation. See Installing plug-ins in UrbanCode products.

History

Version 9

Version 9 includes the following changes:

  • The Password property is now a secure field.
  • Added HTTP statusLine and body responses for failed Status Snapshot deployments in the Add Snapshot Status step.

Version 8

Version 8 includes the following change:

  • Support property file encryption.

Version 7

Version 7 includes the following changes:

  • Revised descriptions and names.
  • A check for valid UUID in the Check Gate Status step

Version 5

Version 5 includes the Check Gate Status step, which checks lifecycle phase gates when deploying in IBM UrbanCode Deploy.

Version 4

Version 4 fixes a defect with compatibility with IBM UrbanCode Deploy 6.1.0.4 and later.

Usage

IBM UrbanCode Release

Before you begin

Optionally, you can define authentication properties that the plug-in requires as system properties. System properties are accessible from anywhere and are automatically updated throughout all process steps that use them.

Applying a status to an application version

Use the Add Snapshot Status step to apply a status or stamp to an application version during an IBM UrbanCode Deploy application process. For example, a deployment process might perform a quality test on an application version and add a status based on test results, along with comments and attachments. The inventories of both IBM UrbanCode Release and IBM UrbanCode Deploy can be automatically updated.

You can manually add statuses, comments, and attachments to application versions in IBM UrbanCode Release. With the Add Snapshot Status step, you can automate those manual steps with a single deployment process.

Before you start

The Add Snapshot Status step requires the ID of the target snapshot. This value is found in the snapshot.id property accessible at the application process scope. To make it available at the component process scope, create a component process property by using the same process as in the Add Comment to Task step.

If the selected snapshot does not exist in IBM UrbanCode Release, the process fails. You can ensure that the snapshot exists by running an integration process before you run the application or use the Update Application step to the workflow. By using the Update Application step, you ensure that the snapshot exists in the IBM UrbanCode Release inventory before it is referred to.

Example: Add a status to a snapshot

In this example, the Add Snapshot Status step is used to apply a status to a snapshot, based on the test results of the Install Notification Manager application. This application is an automated Selenium test that is run on a snapshot version. The application process is triggered by a scheduled deployment in IBM UrbanCode Release. When the test runs, the results are posted to an external web page. Using the Add Snapshot steps also provides the external URL as a comment and attaches a file that contains additional test details.

The version statuses previously created in IBM UrbanCode Release are as follows:

SELENIUM TEST PASSED
SELENIUM TEST FAILED

The component property name for the target snapshot ID is snapshotid and is assigned a value of ${p:snapshot.id}. The snapshotid property contains the ID of the snapshot that the user selects when the application is run.

When you run the process in IBM UrbanCode Deploy, the snapshot field in the Install Notification Manager automatically contains the property reference that was defined earlier.

After completion of the Selenium test, the SELENIUM TEST PASSED status is added to the snapshot. The following figure shows the status applied to the Install Notification Manager application version in IBM UrbanCode Release.


release-plugin-add-status-snapshot-result

In the following figure, you see that the comment and the attachment have been added to the status.


release-plugin-add-status-snapshot-status-detail

Obtaining the appropriate release for an environment

Use the Get Release for Environment step to facilitates auto progression for IBM UrbanCode Release releases. With IBM UrbanCode Release, you can create a recurring rule for a release that automatically promotes and deploys an application version from one phase of the lifecycle to the next. As soon as an application acquires the required statuses and degree of readiness, it is automatically deployed to the next phase.

When you deploy an application version to a DEV environment, say, a snapshot is created of all component versions that are deployed in the environment. This snapshot is automatically included in the IBM UrbanCode Release inventory. As soon as the snapshot acquires the required statuses, the recurring rule creates a scheduled deployment of that version for the next phase. By using recurring rules, application versions can be automatically deployed to every phase in the lifecycle through to production as shown in the following figure.


release-plugin-release-for-environment-autoprogression

The Get Release for Environment step addresses several issues.

  • Recurring rules can use patterns, such as simple naming patterns or a regular expression, to select versions automatically. By naming snapshots after releases, a recurring rule can be used to determine the intended release for a snapshot. For example, the following naming pattern can be used by a recurring rule. Using this simple pattern, a recurring rule can select only those versions that follow the pattern.

    Snapshot_[ReleaseName]
  • You can reserve an environment by using the IBM UrbanCode Release environment reservation feature. A release environment is reserved for a specific period. After an environment is reserved, the Get Release for Environment step can identify the release that has a reservation for the current time.

    After the release is identified and its name retrieved, the value can be stored in an output property and passed to the next step in the process.

Before you start

The Add Snapshot Status step requires the environment ID, which is located in the snapshot.id property and accessible at the application process scope. To make it available at the component process scope, create a component process property by using the same process as in the Add Comment to Task step.

Example: Determine the active release for an environment

This example demonstrates how to use the Get Release for Environment step in a process that creates a snapshot that can be used by a recurring rule for auto progression. It uses a naming pattern to name a snapshot and depends on the IBM UrbanCode Release reservation feature being used.

The following figure shows the settings for the Get Release for Environment step. In this example, the Output Property Name property is named releaseName.


release-plugin-release-for-environment-step

The releaseName output property is passed to the next step in the workflow as ${p:GetReleaseForEnvironment/releaseName}, as shown in the following figure. The Create For Environment step creates a snapshot by using the naming pattern that the recurring rule expects.


release-plugin-release-for-environment-step2

When this sample process runs, it captures the name of the release, as shown in the following illustration.


release-plugin-release-for-environment-trace

The following figure shows the snapshot in the IBM UrbanCode inventory after an integration process is run.


release-plugin-release-for-environment-result2
The recurring rule configuration in IBM UrbanCode Release is shown in the following figure:


release-plugin-release-for-environment-recurring

Using dates in naming patterns

In addition to the simple naming pattern that was used earlier, other patterns can be used to generate snapshot names. For example, you can generate a date to be used in snapshot names:

  1. Create a shell step that displays the system date.
  2. Use a post-processing script (described in Adding comments to a task) to read the output date. Then make the date available to the following step by storing it in an output property. This figure shows a shell step that captures the system date:


    release-plugin-tips-generate-date

    The following figure shows a post-processing script that stores the date in an output property named GeneratedDate.


    release-plugin-tips-generate-date-post-script

    The date can be accessed by the following step that uses these properties: Snapshot_${p:environment.name}_${p:GenerateDate/GeneratedDate}. The generated name will be similar to Snapshot_DEV_ 20142702.

Updating an application inventory

Use the Update Application step to update the inventory in IBM Urbancode Release to match the inventory in IBM UrbanCode Deploy during an integration process. An integration process can be run manually or automatically based on defined specifications. For example, an integration process can be scheduled to run on a defined time interval such as every 30 minutes.

An IBM UrbanCode Deploy application can also run an integration process as part of its process workflow. For example, if an application creates a snapshot during deployment processing, it can use the Update Application step to update the IBM UrbanCode Release inventory and access the snapshot later in the workflow. This can be important if the next scheduled integration is minutes or hours away.

Example: Update inventory during processing

This example shows how to update the inventory without using the Update Application step. In the example, an IBM UrbanCode Deploy deployment process creates a snapshot that contains all component versions that are deployed to a DEV environment. By using the Update Application step, the IBM UrbanCode Release inventory is updated as soon as the snapshot is created.


release-plugin-update-application-workflow

On the IBM UrbanCode Deploy Properties page, specify ${p:application:id} in the Application UUID property. This is a unique number that is assigned when a new application is created in IBM UrbanCode Deploy.

Adding comments to a task

Use the Add Comment to Task step to add comments to automated tasks that are started from a scheduled deployment. This step displays the output of IBM UrbanCode Deploy deployment processes directly in IBM UrbanCode Release task rows. On the IBM UrbanCode Release scheduled deployment page, you can access IBM UrbanCode Deploy task execution logs by clicking the View Process Request link that is associated with the task. The link redirects you to the IBM UrbanCode Deploy Process Request logs, where you can update task comments in real time. When IBM UrbanCode Release starts an automated task, an application process request that contains task-related properties is sent to IBM UrbanCode Deploy.

Before you start

The task ID is a required input to the Add Comment to Task step. The task ID is contained in the post-deploy-message property. You can view this property on the Properties tab for the application process request.

The post-deploy-message property is accessible within the application process request scope but is not directly accessible by the component process. To provide the ID to the component process, you can create a component process property that the application uses to pass the value of the post-deploy-message property.

To create the component process:

  1. In IBM UrbanCode Deploy, create a component process property without a default value for the property. In the example, the created property is called taskPostMessage.

    release-plugin-property
  2. In the application process, use the new property to pass the value of the post-deploy-message property. On the Edit Properties page for the application process, specify ${p:post-deploy-message} as the value for the created property.

    release-plugin-add-comment-task-form
  3. Example: Add a comment to automated task

    In this example, comments are added to an IBM UrbanCode Release automated task in a scheduled deployment. The comments are generated from the output logs of two steps in an IBM UrbanCode Deploy component process. The following figure shows the requesting automated task in IBM UrbanCode Release.


    release-plugin-add-comment-task-sd

    The following figure shows the workflow of the corresponding component process in IBM UrbanCode Deploy. The output logs of the ExportBackupLogs and SendNotification steps are examined and passed to the steps that follow them in the workflow, Add Comment with backup logs URL and Add Email Notification Comment, which are highlighted in the illustration.


    release-plugin-add-comment-task-workflow

    The ExportBackupLogs step uses an external tool to archive backup logs to a web server during processing. An automatically-generated URL is included in the steps output. By using a post processing script, you can scan the steps output and retrieve the URL and save it to a property that can be passed to the subsequent step. The following step, Add Comment with backup logs URL, uses the output property to create a comment in IBM UrbanCode Release.

    Example: Scan step output by using post-processing script

    This example demonstrates how to scan the output of a step and save it to an output property that is accessible by the subsequent step. Every automation plug-in step has a post-processing element. By using a post-processing script, you can save the step output to an output property.

    In this example, the post-processing script is called exportOutputLogs.
    A post-processing script is a JavaScript script that automatically runs when a step completes processing. In this example, the script scans the output logs of the step.

    properties.put(Status, Success)
    if (properties.get(exitCode) !=0) {
    properties.put(Status, Failure);
    }

    scanner.register (Output;, function(lineNumber, line) {
    var value = line.replace(Output;,);
    )};
    scanner.scan();

    In this example, the backup log tool has the following output message format. The message contains the URL of the logs where the backup process can be accessed:
    Output: http://xxxx/xxx.html

    The following snippet retrieves the row and saves it to an output property that is named outputlogs. The outputlogs property can be referred to by the next step: ${p:NameOfTheStep/outputlogs}.

    ${p:NameOfTheStep/outputlogs}

    scanner.register(Output:, function(lineNumber, line) {
    var value = line.replace(Output:, );
    properties.put(outputlogs, value);
    });
    scanner.scan();

    The following figure below shows the configuration for an Add Comment to Task step, using the properties created earlier. The step retrieves the output log of the previous step and sends it to IBM UrbanCode Release.


    release-plugin-add-comment-task-step

    During the execution of the IBM UrbanCode Deploy deployment process, the comments are created and added to the task row in IBM UrbanCode Release. By expanding the row, the comments are displayed, as shown in the following figure:


    release-plugin-add-comment-task-result

Steps

Process steps in the IBM UrbanCode Release plug-in

Add Comment to Task

Use this step to add a comment to an automated task that was started from a scheduled
deployment.

Input properties for the Add Comment to Task step
Name Type Description Required
Comment String The text to add as a comment to the task execution. No
Password String The password to access IBM UrbanCode Release. Yes
Post Message String The post message that is sent from IBM UrbanCode Release containing the taskID. Create
the taskPostMessage property at the component process level without a default value.
The application process sets the taskPostMessage property during execution with ${p:post-deploy-message}
property value.
Yes
URL String The URL to the IBM UrbanCode Release server web user interface. Yes
User Name String The user name to access IBM UrbanCode Release. Yes

Add Snapshot Status

Use this step to add a version status to a snapshot.

Input properties for the Add Snapshot Status step
Name Type Description Required
Attachment Description String A description of the file to be uploaded as attachment to the snapshot status. No
Attachment Path String The path of the file to be uploaded as attachment to the snapshot status. No
Comment String The comment text to be added to the snapshot status. No
Password String The password to access IBM UrbanCode Release. Yes
Snapshot ID String The unique ID of the snapshot. To obtain the snapshot ID that is being deployed, you
can create a component process property called snapshotId. Specify ${p:snapshot.id}
as the default value in the component process property.
Yes
Status Name String The name of the status to be applied to the snapshot. Yes
URL String The URL of the IBM UrbanCode Release server web user interface. Yes
User Name String The user name to access IBM UrbanCode Release. Yes

Check Gate Status

Use this step to check if a snasphot is passing the gates for a specific lifecycle
and phase.

Input properties for the Check Gate Status step
Name Type Description Required
Lifecycle Name String The name of the lifecycle in IBM UrbanCode Release Yes
Password String The password to access IBM UrbanCode Release. Yes
Phase Name String The name of the lifecycle phase to check against in IBM UrbanCode Release. Yes
Snapshot ID String The snapshot ID to check gates for. Yes
Timeout Value String The time in seconds to wait for a response from the IBM UrbanCode Release server. Yes
URL String The URL of the IBM UrbanCode Release server web user interface. Yes
User Name String The user name to access IBM UrbanCode Release. Yes

Get Release for Environment

Use this step to find the active release for the current environment and save the
name as an output property.

Input properties for the Get Release for Environment step
Name Type Description Required
Environment ID String The unique environment identifier that the process step is running against. Yes
Output Property For Phase Name String The name of the property containing the phase name to be passed to the next step as
this value: ${p:actualStepName/propertyName}.
Yes
Output Property for Release Name String The name of the property that contains the release name to be passed to the next step
as this value:${p:actualStepName/propertyName}.
Yes
Password String The password to access IBM UrbanCode Release. Yes
URL String The URL of the IBM UrbanCode Release server web user interface. Yes
User Name String The user name to access IBM UrbanCode Release. Yes

Sync Snapshot

Use this step to create or update a snapshot in IBM UrbanCode Release.

Input properties for the Sync Snapshot step
Name Type Description Required
Application ID String The application unique ID of the inventory to update in IBM UrbanCode Release. Yes
Password String The password to access IBM UrbanCode Release. Yes
Snapshot ID String The snapshot unique ID to create or update in IBM UrbanCode Release. Yes
URL String The URL of the IBM UrbanCode Release server web user interface. Yes
User Name String The user name to access IBM UrbanCode Release. Yes

Update Application

Use this step to update the inventory for an application in IBM UrbanCode Release.

Input properties for the Update Application step
Name Type Description Required
Application ID String The unique IBM UrbanCode Deploy application ID (UUID), for the inventory to be updated. Yes
Password String The password to access IBM UrbanCode Release. Yes
URL String The base URL of the IBM UrbanCode Release server web user interface. Yes
User Name String The user name to access IBM UrbanCode Release. Yes