Working with Objects

DMScript

DMScript is an object-orientated scripting language. As such, it understands each object in the DeployHub Pro model. You can access each object either by selecting it off the stack (e.g.: $Environment), by retrieving a reference to the object from some other object, or by calling a built-in Function to retrieve it. Each object has accessible properties. Some objects also have methods that can be called.

The following is a list of the objects that you can reference in DMScript.

• Application
• Change Request
• Components
• Component Items
• Credentials
• Date
• Domain
• DropZone
• DropZone File
• Environment
• Endpoint
• User
• UserGroup

Attributes

Attributes set against DeployHub Pro objects are accessible as variables in DMScript.

For example, suppose QUEUE_NAME is queue1 in “Test Environment A” and queue2 in “Test Environment B”. When deploying to “Test Environment A” the value of $QUEUE_NAME will be queue1. When deploying to “Test Environment B” the value of $QUEUE_NAME will be queue2.

You do not need to use any specific syntax to access an Object variable. Whenever a variable is accessed, DMScript will navigate up the Stack, looking for the first scope in which the variable is declared. When a variable with a matching name is found, the value at that point is returned. This means that variable values can be overwritten with other values declared higher in the stack. See the high-level section named The Stack for further discussion on this.

Application Object

The Application object represents either a Base Application, an Application Version, or a Release. In DeployHub Pro there is always an Application on the stack representing the Application/Release being deployed referenced by $Application. You can also retrieve an Application using the get_Application__Function_ or push an Application onto the Stack via using Application.

NOTE: A Release is a DeployHub Pro Object. It is of the type__Application. The release property indicates if the object represents a Release.

The following properties can be accessed for an Application object:

The following methods can be called on the Application object:

Attributes such as owner and parent return Objects. These objects have their own attributes. So, for example, one can get the owner name of an Application by writing:

set owner = ${_Application_.owner};

echo ${owner.name};

or, more simply:

echo ${_Application_.owner.name};

Get _Application_ Approval Status:

set approvals = ${_Application_.approvals};

foreach(a: $approvals) {

echo "$a : ${approvals[$a]}";

}

// e.g.:

// Test : approved

// Prod : rejected

Since the array is keyed on the domain name, you can easily check if the app is approved for a particular domain:

set approvals = ${_Application_.approvals};

if (${approvals["Test"]} = "approved") {

// _Application_ is approved for Test Domain

}

Or you can use dot notation (assuming the target domain name does not contain spaces):

set approvals = ${_Application_.approvals};

if (${approvals.Test} = "approved") {

// _Application_ is approved for Test Domain

}

To iterate through the Component_s that make up the_Application:

set Components = ${Application.Components};

echo "This Application has ${Components.length()} Components";

iterate(c: $Components) {

echo "Component ${c.name} (id ${c.id})";

}

Change Request Object

The Change Request object represents a change request record associated with either a Component or an Application. Arrays of Change Request objects are returned by accessing the requests property of an Application or Component object or the requests() method of an Application.

The following properties can be accessed for a Change Request object:

Component Object

The Component object represents either a Base Component or a Component Version. When deploying an Application, Components are pushed onto the stack after each Endpoint. They can also be pushed onto the stack by using a comploop, retrieved from an Application by using ${Application.Components} or retrieved by calling get_Component.

The following properties can be accessed for a Component object:

Attributes such as owner and parent return Objects. These objects have their own attributes. So, for example, one can get the owner name of a Component by writing:

Component Object Example

set owner = ${_Component_.owner};

echo ${owner.name};

or, more simply:

echo ${_Component_.owner.name};

Component Item

The Component Item object represents a Component item within a Component. Access to a Component item is only possible by retrieving the array of Component Item objects from the Component Object.

The following properties can be accessed for a Component item object:

Component Item Example

Iterate through the Component items for a Component:

iterate(ci: ${Component.items}) {

echo "name=${ci.name}"; // Component Item Name

echo "repository=${ci.repository}"; // Repository Name

echo "target=${ci.target}"; // Target Directory

echo "rollup=${ci.rollup}"; // rollup (true/false)

echo "rollback=${ci.rollback}"; // rollback (true/false)

set props = ${ci.properties}; // Other Properties

echo "properties:";

foreach(p: $props) { // Properties Specific

echo "$p = ${props[$p]}"; // to the Repository

} // for this Comp Item

}

Credentials

The Credential Object can be accessed with the built-in getcredential_Function_but only if the user executing the DMScript has read access to it.

If the Credential can be read, then its attributes can be accessed:

The following properties can be accessed for a Credential Object:

You can use the Credential Object to access external systems in a secure and controlled manner. The user executing the DMScript must have read access to the Credential. However, having read access does not allow the username/password to be viewed or modified using the Web UI. (The username is only displayed for the Credential owner, the username and password can only be changed if the User has update access to the Credential).

Credential Example

set db2creds = getcredential("db2cred");

set username = ${db2creds.username};

set password = ${db2creds.password};

// username and password can now be used to access external system

b64authcan be used to generate an authorization string for Basic authentication for web- based APIs. For example:

set webcreds = getcredential("mydomain.webcred");

set auth = ${webcreds.b64auth};

set header = {

"Authorization": "Basic $auth"

};

set res = restful\_get("https://myurl",null,null,$header);

NOTE: See the description of restful_get for more information.

NOTE: If you wish to prevent the credential from being decrypted, then you ensure that the right to create DMScript is only granted to power users. Otherwise, a user could create a DMScript to decrypt a credential to which they only have read access.

Date Object

The date object represents a date/time in DMScript. Dates can be created (with the date() or now()Functions) or can be retrieved from a DropZoneFile object (which represents a file in the DropZone).

The following methods can be called on the date object:

Date Format Characters

The to_char() method returns a string which is identical to the passed fmt string with the exception of the special character sequences described below. Where these are present in the fmt string, they are replaced with the relevant Component from the date/time as described below:

Alternate Format Modifiers

Some conversion specifications can be modified by preceding the conversion specifier character by the E or O modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behavior will be as if the unmodified conversion specification were used. (SU) The Single UNIX Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect of the O modifier is to use alternative numeric symbols (say, roman numerals), and that of the E modifier is to use a locale-dependent alternative representation.

NOTE: The date is formatted by to_char using the C _Function_strftime.

Domain Object

The Domain object represents a domain in DMScript. Domain objects can be retrieved from other objects (such as Endpoints, Environments, Applications etc). The calling user’s home domain can be retrieved via ${me.domain}

The following properties can be accessed on the Domain object:

Dropzone and DropZone File Object

DropZone

The DropZone Object represents a DropZone. A DropZone is an area on disk on the DeployHub Pro Server where deployment artifacts are stored and manipulated before onward transmission to the target Endpoint(s). A DropZone is placed onto the stack during a using DropZone statement – all operations within this block have access to this DropZone via the DropZone Object. A DropZone Object is also present on the stack during pre and post action processing for a Component. In this case, the content of the DropZone are the files checked out from the repository for the associated Component Items.

The following properties can be accessed for a DropZone object:

The following methods can be called on the DropZone object:

DropZone File

The DropZone File Object represents a file in the DropZone. It can be retrieved from the DropZone object via the files property or the find method. Both of these calls return an array of DropZone File Objects, keyed on the filename. You can also call dir() on a DropZone File Object that represents a zipfile to get an array of DropZone File Objects representing the zipfile content.

The following properties can be accessed for a DropZone File Object:

The following methods can be called on the _DropZone_File object:

NOTE: See also the description for zipadd, zipget and zipdel.

Environment Object

The Environment Object represents a deployment target Environment. During a deployment, there is always an Environment Object on the stack representing the current deployment target Environment. This can be referenced by $Environment. An Environment Object can also be retrieved using the Get Environment Function.

The following properties can be accessed for an Environment object:

The following methods can be called on the Environment object:

Note, that attributes such as owner and parent return other Objects. These objects have their own attributes. So, for example, one can get the owner name of an Environment by writing:

set owner = ${_Environment_.owner};

echo ${owner.name};

or, more simply:

echo ${_Environment_.owner.name};

Here is an example of retrieving the Endpoints in the Environment:

set servers = ${_Environment_.servers};

iterate(s: $servers) {

echo "server is ${s.name}";

echo "hostname is ${s.hostname}";

}

Endpoint Object

The Endpoint (server, container, VM/Cloud Image) object represents where a deployment will be sent. An Endpoint object can be retrieved by accessing the servers array from an Environment or more typically by running a psloop. This iterates through the current Endpoint list, pushing an Endpoint object onto the stack each time through the loop. This Endpoint object can be referenced by $server.

The following properties can be accessed for an Endpoint object:

The following methods can be called on the Endpoint object:

Note, that the owner attribute returns an Object. Such objects have their own attributes.

So, for example, one can get the owner name of an Endpoint by writing:

set owner = ${server.owner};

echo ${owner.name};

or, more simply:

echo ${server.owner.name};

User Object

The User object represents a user in DMScript. User objects can be retrieved as the owner from other objects (such as Endpoints, Environments, Applications etc.). They can also be returned from a getuser call.

The following properties can be accessed on the User object:

UserGroup Object

The UserGroup object represents a UserGroup in DMScript. UserGroup objects can be retrieved as the owner from other objects (such as Endpoints, Environments, Applications etc.). They can also be returned from a getusergroup call or from a User object (as a list of groups to which the user belongs).

The following properties can be accessed on the UserGroup object: