Working with Objects

Working with Objects using DMScript.

DMScript is an object-orientated scripting language. As such, it understands each object in the DeployHub 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 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:

Property Type Description
id Integer Application id, as used in the database.
name String Application name.
fqdomain String Fully qualified domain name.
summary String Summary text.
domain Object Domain in which the Application is contained.
owner Object User or UserGroup that owns the Application.
parent Object The Base Application.
predecessor Object Predecessor Application Version (the version on which this version is based).
Release Boolean true if object is a Release, false otherwise.
Applications Array Array of Application objects if the object is a Release a list of the consituent Applications. If the object is not a Release, this returns null.
Components Array Array of Component objects (keyed by Component name) which make up this Application.
approvals Array Array of strings (approved/rejected) keyed by domain name for which the Application is approved/rejected.
requests Array Array of Change Request objects associated with this Application.
creator User User Object representing the user who created this Application.
modifier User User Object representing the user who last modified this Application.
ctime Date Date Object representing the date/time the Application was created.
mtime Date Date Object representing the date/time the Application was last modified.
attributes Array Array of Strings, keyed by Attribute Name

The following methods can be called on the Application object:

Method Return Type Description
children(all) Array Returns an array of Application objects representing the descendants of this Application. If the parameter all is passed as true then the returned array includes all the descendants of the immediate descendants recursively. If the parameter all is omitted or passed as false then the return array only includes the immedate descendants.
versions(all) Array Synonym for children. Works identically.
getatt(attname) String Returns the value of the specified attribute held against the Application. Parameter is the attribute name.
requests(onlyForApp) Array Returns an Array of Change Request objects. If onlyForApp is not specifed or passed as false then this is identical to accessing the requests attribute. If onlyForApp is specfied as true then only the change request records associated with the Application itself are returned Note: No change request which is only associated with a consituent Component is returned. This allows you to differentiate between change requests associated with the Application and any of its Components.
latest(branchname) Object Returns the latest Application Version of this Application. If branchname is specified then the returned Application Object is the latest version on the specified branch.

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:

id String The change request id.
name String The change request description.
status String The change request status.
api_url String A URL which - if passed to restful_get - will return an array containing the full details of the change request from the external change tracking system. Useful for getting more information than the id / description / status combination which is stored in DeployHub.
html_url String A URL which will direct a browser to the page describing the change request in the external change tracking system.

The Component and Component Item Objects

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:

Property Type Description
id Integer Component id, as used in the database.
name String Component name.
fqdomain String Fully qualified domain name.
summary String Summary text.
domain Object Domain in which the Component is contained.
owner Object User or UserGroup that owns the Component.
parent Object The Base Component.
predecessor Object Predecessor Component Version (the version on which this version is based).
items Array An array of Component Item objects. These represent the items that make up this Component.
servers Array An array of Endpoint objects. These are the Endpoints to which this Component has been deployed.
requests Array Array of Change Request objects – the change requests associated with this Component.
lastbuild Integer The last build number for this Component. 0 if never built.
creator User User Object representing the user who created this Component.
modifier User User Object representing the user who last modified this Component.
ctime Date Date Object representing the date/time the Component was created.
mtime Date Date Object representing the date/time the Component was last modified.
attributes Array Array of Strings, keyed by Attribute Name

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:

Examples:

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:

Property Type Description
id Integer Component Item id, as used in the database.
name String Component Item name.
summary String Summary text.
parent Object The Component to which this Item belongs.
repository String The Name of the Repository from which this Component Item pulls files.
target String The target directory to which the files should be deployed.
rollup Boolean Whether this Component Item should be deployed during a roll forward operation.
rollback Boolean Whether this Component Item should be deployed during a roll back operation.
properties Array An array of Strings representing the values for the Repository Attributes

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:

Property Type Description
id Integer Credential id, as used in the database.
name String Credential name.
fqdomain String Fully qualified Domain name.
summary String Summary text.
domain Object Domain in which the Credential is associated.
owner Object User or UserGroup that owns the Credential
username String Decrypted username.
password String Decrypted password.
b64auth String A string representing the decrypted username and password together, with a : separator and then base64 encoded. Used for Basic Authorization for web-based APIs. See the description of restful_post, restful_get and soap in the high level section named Built-In Functions for more information.
creator User User Object representing the user who created this Credential.
modifier User User Object representing the user who last modified this Credential.
ctime Date Date Object representing the date/time the Credential was created.
mtime Date Date Object representing the date/time the Credential was last modified.
kind String Credential use.

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).

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:

Method Return Type Description
to_int(secs) Integer Returns an integer representing the date as the number of seconds since midnight on January 1st 1970 (epoch). The secs parameter is optional. If specified, the specified number of seconds is added to the date/time before the new value is returned.
to_char(fmt) String Formats the date into a string given by the passed fmt string. The fmt string should contain characters as specified below.

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:

Sequence Description
%a The abbreviated name of the day of the week according to the current locale.
%A The full name of the day of the week according to the current locale.
%b The abbreviated month name according to the current locale.
%B The full month name according to the current locale.
%c The preferred date and time representation for the current locale.
%C The century number (year/100) as a 2-digit integer.
%d The day of the month as a decimal number (range 01 to 31).
%e Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space.
%E Modifier: use alternative format, see below.
%F Equivalent to %Y-%m-%d (the ISO 8601 date format).
%G The ISO 8601 week-based year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead.
%g Like %G, but without century, that is, with a 2-digit year (00-99).
%h Equivalent to %b.
%H The hour as a decimal number using a 24-hour clock (range 00 to 23).
%I The hour as a decimal number using a 12-hour clock (range 01 to 12).
%j The day of the year as a decimal number (range 001 to 366).
%k The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also %H.)
%l The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also %I.)
%m The month as a decimal number (range 01 to 12).
%M The minute as a decimal number (range 00 to 59).
%n A newline character.
%O Modifier: use alternative format, see below.
%p Either “AM” or “PM” according to the given time value, or the corresponding strings for the current locale. Noon is treated as “PM” and midnight as “AM”.
%P Like %p but in lowercase: “am” or “pm” or a corresponding string for the current locale.
%r The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to %I:%M:%S %p.
%R The time in 24-hour notation (%H:%M). For a version including the seconds, see %T below.
%s The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
%S The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds).
%t A tab character.
%T The time in 24-hour notation (%H:%M:%S).
%u The day of the week as a decimal, range 1 to 7, Monday being 1. (See also %w.)
%U The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day ofweek 01. (See also %V and %W.)
%V The ISO 8601 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. (See also %U and %W. (Calculated from tm_year, tm_yday, and tm_wday.)
%w The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
%W The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01.
%x The preferred date representation for the current locale without the time.
%X The preferred time representation for the current locale without the date.
%y The year as a decimal number without a century (range 00 to 99).
%Y The year as a decimal number including the century.
%z The +hhmm or -hhmm numeric timezone (that is, the hour and minute offset from UTC).
%Z The timezone name or abbreviation.
%% A literal '%' character.

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:

Property Return Type Description
id Integer Domain id, as used in the database.
name String Domain name.
fqdomain String Fully qualified domain name.
summary String Summary text.
domain Object Domain in which the Domain is contained
subdomains Array List of Domain objects which are contained within this Domain.
Life Cycle Boolean true if the Domain contains a Life Cycle, false otherwise.
Applications Array List of Application objects which are contained within this domain.
Environments Array List of Environment objects which are contained within this domain.
creator User User Object representing the user who created this domain.
modifier User User Object representing the user who last modified this domain.
ctime Date Date Object representing the date/time the domain was created.
mtime Date Date Object representing the date/time the domain was last modified.
owner Object User or UserGroup that owns the Domain.

Dropzone and DropZone File Object

DropZone

The DropZone Object represents a DropZone. A DropZone is an area on disk on the DeployHub 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:

Property Type Description
name String DropZone name.
path String The full path of the location on disk where the DropZone is located. Useful for passing to external scripts that may need to manipulate files in the DropZone.
files Array An Array of DropZone Objects, each one of which represents a file in the DropZone. The array is keyed by the full path name of the file.

The following methods can be called on the DropZone object:

Method Return Type Description
find(pattern) Array Returns an Array of DropZone Object, each one of which represents a file in the DropZone. The Array is restricted to files whose file name matches the specified pattern. The array is keyed by the full path name of the file.
dir() String The full path of the location on disk where the DropZone is located. Equivalent to the path attribute.

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:

Property Type Description
dzpath String The relative path of the file in the DropZone.
repopath String The relative path of the file as located in the Repository (this path is relative to the base directory of the repository).
size Integer The size of the file in bytes.
ctime Date The creation time of the file.
mtime Date The modified time of the file.

The following methods can be called on the _DropZone_File object:

Method Return Type Description
delete() Integer Removes the file represented by the DropZone File Object from the DropZone. After this operation the file will no longer be transferred to the target server in any subsequent transfer operation. Returns 1 (true) if the file was successfully removed, 0 otherwise.
dir() Array If the DropZone File Object refers to a zipfile (including web archive files such as WAR, JAR, EAR) then dir() will return an array of DropZone File Objects which represent the content of the zipfile. The array is keyed by the filename and can be used as input to the zipget and zipdel statements.

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:

Property Type Description
id Integer Environment id, as used in the database.
name String Environment name.
fqdomain String Fully qualified domain name.
summary String Summary text.
domain Object Domain in which the Environment is contained.
owner Object User or UserGroup that owns the Environment.
basedir String Base directory for deployments.
Endpoints Array Array of Endpoint objects keyed by name.
Applications Array Array of Application Objects (_Application_s present in this Environment).
creator User User Object representing the user who created this Environment.
modifier User User Object representing the user who last modified this Environment.
ctime Date Date Object representing the date/time the Environment was created.
mtime Date Date Object representing the date/time the Environment was last modified.
parent Object Parent domain.

The following methods can be called on the Environment object:

Method Return Type Description
getatt(attname) String Returns the value of the specified attribute held against the Environment. Parameter is the attribute name.
deptime(Application) Date Returns a Date object representing the last time the specified Application was deployed to the Environment. Returns null if the specified Application is not currently on the Endpoint.

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:

Property Type Description
id Integer Endpoint id, as used in the database.
name String Endpoints name.
fqdomain String Fully qualified Domain name.
summary String Summary text.
domain Object Domain in which the Endpoint is contained.
owner Object User or UserGroup that owns the Endpoint.
hostname String Hostname (if set) or name otherwise.
basedir String Base Directory for Deployments.
type String Endpoint Type, ie: windows, unix, cluster, etc.
credential Object The Credential Object used to access this Endpoint.
Components Array An Array of Component Objects – the Components currently installed on this_Endpoint.
creator User User Object representing the user who created this Endpoint.
modifier User User Object representing the user who last modified this Endpoint.
ctime Date Date Object representing the date/time the Endpoint was created.
mtime Date Date Object representing the date/time the Endpoint was last modified.
attributes Array Array of Strings, keyed by Attribute Name.

The following methods can be called on the Endpoint object:

Method Return Type Description
append(path1,path2) String Appends path2 to path1, returning the combined path formatted according to the Endpoint type. See append in the previous section for more information.
appendstd(path1,path2) String Appends path2 to path1, returning the combined path formatted according to the Endpoint type. See appendstd in the previous section for more information.
basename(path) String Returns the filename Component of the specified path. The structure of the path is based on the Endpoint type.
dirname(path) String Returns the directory path Component of the specified path. The structure of the path (and the returned String) is based on the Endpoint type.
getatt(attname) String Returns the value of the specified attribute held against the Endpoint. Parameter is the attribute name.
deptime(Component) Date Returns a Date object representing the last time the specified Component was deployed to the Endpoint. Returns null if the Component is not currently on the Endpoint.

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:

Property Return Type Description
id Integer User id, as used in the database.
name String User Name.
kind String Returns “user”. Used to differentiate between users and groups where retrieving an owner object.
fqdomain String Fully qualified domain name.
realname String The User's full name.
email String The User's email address.
phone String The User's telephone number.
groups Array Array of UserGroup Objects – the UserGroups to which this user belongs.
lastlogin Date The date/time the user last logged into DeployHub.
creator User User Object representing the user who created this user.
modifier User User Object representing the user who last modified this user.
ctime Date Date Object representing the date/time the user was created.
mtime Date Date Object representing the date/time the user was last modified.
owner Object User or UserGroup that owns the User

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:

Property Return Type Description
id Integer UserGroup id, as used in the database.
name String UserGroup Name.
kind String Returns “group”. Used to differentiate between users and groups where retrieving an owner object.
fqdomain String Fully qualified Domain name.
email String The UserGroup’s email address.
creator User User Object representing the user who created this UserGroup.
modifier User User Object representing the user who last modified this UserGroup.
ctime Date Date Object representing the date/time the UserGroup was created.
mtime Date Date Object representing the date/time the UserGroup was last modified.
owner Object User or UserGroup that owns the UserGroup.
Last modified July 9, 2020: small cleanup (b45ee8f)