Plug-in Documentation

IBM UrbanCode Deploy Environments

Overview

This plug-in includes steps that create and manage environments on the IBM UrbanCode Deploy server.

Compatibility

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

This plug-in is supported to run on all operating systems that are supported by the IBM UrbanCode Deploy agent, including z/OS with UNIX System Services.

Installation

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

History

Version 79

RFE 121148 Removed isSecure property from Set Component Environment Property to support property definition type.

Version 78

Plugin name changed.

Version 77

Update for API changes in server.

Version 76

Fixed typo in Create Multiple Environments description.

Version 75

  • RFE 100937 Added Create Multiple Environments step to create multiple environments using json.
  • RFE 100937 Altered Add Environment to Team step to allow for multiple environments.

Version 74

RFE 83705 Added Create Environment from Template step.

Version 73

Support property file encryption.

Version 72

Version 72 includes a fix for APAR PI45948, Set environment property step may fail if run simultaneously.

Version 68

  • This version includes a step that retrieves basic information about an environment.
  • The Create Environment step can now provision environments with blueprints.
  • You can specify an environment profile when you create an environment.

Usage

Create Multiple Environments

The Create Multiple Environments step provides the ability to create multiple environments using one JSON file or JSON text body. The format of this JSON body allows you to either create environments from a template or without a template. When creating from a template, the format of this JSON body follows the IBM UrbanCode Deploy createEnvironmentFromTemplate REST endpoint. The documentation for this endpoint can be found in the knowledge center: IBM UrbanCode Deploy createEnvironmentFromTemplate REST endpoint

When not using a template to create an environment, the format of the JSON body follows the IBM UrbanCodeDeploy createEnvironment REST endpoint. The documentation for this endpoint can be found in the knowledge center: IBM UrbanCode Deploy createEnvironment REST endpoint

Note that if either the templateName or templateId fields are supplied in the JSON text for an environment, the createEnvironmentFromTemplate will be used automatically.

To create multiple environments, create multiple JSON environment objects inside of a JSON array as follows:

[{"application": "Application assigned to the environment.",
"name": "Environment name or ID.",
"description": "Description of the environment",
"requireApprovals": "True/false to specify whether environment requires approvals.",
"noSelfApprovals": "True/false to specify whether environment allows self approvals.",
"nodeProperties": {"Node property name": "Property value"},
"properties": {"Environment property name": "Property value"},
"templateName": "(Optional) Supply either the templateId or templateName to use a template.",
"templateId": "(Optional) Supply either the templateId or templateName to use a template."},
{"application": "Application assigned to the environment.",
"name": "Environment name or ID.",
"description": "Description of the environment",
"requireApprovals": "True/false to specify whether environment requires approvals.",
"noSelfApprovals": "True/false to specify whether environment allows self approvals.",
"nodeProperties": {"Node property name": "Property value"},
"properties": {"Environment property name": "Property value"},
"templateName": "(Optional) Supply either the templateId or templateName to use a template.",
"templateId": "(Optional) Supply either the templateId or templateName to use a template."}]

Steps

Process steps in the UrbanCode Deploy Environments plug-in

Add Base Resource To Environment

Adds a base resource to an environment as a deployment target.

Input properties for the Add Base Resource To Environment step
Name Type Description Required
Application String Required unless you are specifying the environment by its ID. No
Environment String Yes
Resource Path String Yes

Add Environment To Team

Adds an environment or list of environments delimited by commas to a team for a
given application and type classification.

Input properties for the Add Environment To Team step
Name Type Description Required
Application String Required unless you are specifying the environment by its ID. No
Environment/Environments String A comma delimited list of environment names/ids to add to the team. Yes
Team String Yes
Type String The type classification to add. Leave blank to use the type Standard Environment. No

Check If Environment Exists

This step will succeed if the environment exists and fail if it does not.

Input properties for the Check If Environment Exists step
Name Type Description Required
Application String name/ID of the application that the environment belongs to. Not needed if you refer
to environment by ID instead of name.
No
Environment String name/ID of the environment. If you specify ID you dont need to specify the application. Yes

Create Environment

Creates an environment for the specified application.

Input properties for the Create Environment step
Name Type Description Required
Append Unique Suffix Boolean Check this box if you want to guarantee your environment name is unique. No
Application Name String The name of the application the environment will be created for. Yes
Base Resource Path String Specify the path to a base resource to put the new environments resources in if using
a blueprint. This field must be provided when using a blueprint. Example: /Provisioned
Environments
No
Blueprint Name String Specify a blueprint name if this environment should be created based on an application
blueprint.
No
Description String A description of of the environment to be created. No
Environment Name String The name of the environment to be created. Yes
Environment Profile String Specify the name of the environment profile to use to provision the new environment.
This field is only valid for blueprints backed by resource templates imported from
the cloud.
No
Node Resource Properties String Properties that configure cloud resource nodes. Syntax: [node or script package name]/propertyName=propertyValue
Examples: OS Node/HWAttributes.numvcpus=2 install_ucd_agent/UCD_Agent_Name=newAgentName
No
Properties String Properties to be set on the new environment, using Java property file syntax. No
Require Approvals Boolean Check this box if the environment will require approval from an approval process to
install versions or snapshots.
No

Create Environment Property

Create a property for an application environment.

Input properties for the Create Environment Property step
Name Type Description Required
Application String name/ID of the application that the environment belongs to. Not needed if you refer
to environment by ID instead of name.
No
Environment String name/ID of the environment. If you specify ID you dont need to specify the application. Yes
Property Name String name of the property to set. Yes
Property Value String value of the property to set. No
Secure Boolean check if the property should be secure. No

Create Environment from Template

Creates an environment from a template for the specified application.

Input properties for the Create Environment from Template step
Name Type Description Required
Application ID String The Application ID where the environment will be created. Yes
Description String A description of of the environment to be created. No
Environment Name String The name of the environment to be created. Yes
Environment Template ID String The ID of the environment template. The Environment Template ID or Name is required. No
Environment Template Name String The name of the environment template. The Environment Template ID or Name is required. No

Create Multiple Environments

Creates multiple environments using JSON format. Outputs a comma delimited list of
the environment UUIDs that were created (environment.ids).

Input properties for the Create Multiple Environments step
Name Type Description Required
JSON File/Text String Specify a body of JSON text or a file to define Environments. Separate multiple
JSON objects by using commas within an array, e.g. [{},{},{}].
Yes

Delete Environment

Deletes an environment.

Input properties for the Delete Environment step
Name Type Description Required
Application String name/ID of the application that the environment belongs to. Not needed if you refer
to environment by ID instead of name.
No
Environment String name/ID of the environment. If you specify ID you dont need to specify the application. Yes

Get Component Environment Properties

Get the name-value pairs of all component environment properties and sets them as
output properties for this step. Secure property values cannot be resolved.

Input properties for the Get Component Environment Properties step
Name Type Description Required
Application String name/ID of the application that the environment belongs to. Not needed if you refer
to environment by ID instead of name.
No
Component String name/ID of the component. Yes
Environment String name/ID of the environment. If you specify ID you dont need to specify the application. Yes

Get Environment Details

Retrieve basic configuration information about a environment.

Input properties for the Get Environment Details step
Name Type Description Required
Application String Application name or ID. (Required when using a name for the environment instead of
its ID)
Yes
Environment String Environment name or ID Yes

Get Environment Properties

Get the name-value pairs of all environment properties and sets them as output properties
for this step. Secure property values cannot be resolved.

Input properties for the Get Environment Properties step
Name Type Description Required
Application String name/ID of the application that the environment belongs to. Not needed if you refer
to environment by ID instead of name.
No
Environment String name/ID of the environment. If you specify ID you dont need to specify the application. Yes

Get Latest Version By Environment and Component

Gets the latest Version of a Component in a given Environment

Input properties for the Get Latest Version By Environment and Component step
Name Type Description Required
Application String Required Application Name No
Component String Required Component Name No
Environment String Required Environment Name No

Set Component Environment Property

Sets an environment-specific property value for a component. The property must already
exist.

Input properties for the Set Component Environment Property step
Name Type Description Required
Application String name/ID of the application that the environment belongs to. Not required if you specify
environment by ID instead of name.
No
Component String name/ID of the component that the environment belongs to. Yes
Environment String name/ID of the environment. If you specify ID you dont need to specify the application. Yes
Property Name String name of the property to set. Yes
Property Value String value of the property to set. No

Verify Inventory Status

Verifies that the environment has a component with a certain version in inventory.

Input properties for the Verify Inventory Status step
Name Type Description Required
Application String name/ID of the application that the environment belongs to. Not needed if you refer
to environment by ID instead of name.
No
Component String name/ID of the component to verify. Yes
Environment String name/ID of the environment. If you specify ID you dont need to specify the application. Yes
Status String The inventory entry must match this status (case sensitive). Default possible statuses
are Active or Staged, but custom statuses are also possible.
Yes
Version String name of the version to verify. Yes