Stack

Manage the DeployHub Stack.

The stack is a fundamental part of DeployHub. During deployment, objects are pushed onto and popped off the stack. Objects such as Environments, Applications, and Endpoints each have their own properties. These are accessible as variables in DMScript (provided the object is currently on the stack).

Regardless of why the DMScript has been invoked (either a deployment or via it being linked to a manually invoked task), there is always a “global” scope. This contains all the Environment variables available to the deployment engine, any additional parameters specified for the invoking task and any variables set with the –g option.

The following variables are always defined in the Global scope:

Variable Description Example
ARGC Count of command line args $ARGC
ARGV Array of command line ${ARGV[1]}
DMHOME Home directory of engine $DMHOME/demo_repo
$ Process id of engine process $$
JSESSIONID The session id of the Web UI $JSESSIONID

You can use $DMHOME to reference files that are stored in directories relative to the DeployHub engine installation location.

Every invocation of the engine results in a new engine process (and therefore a new value of $$). You can use the $$ variable to create filenames that are guaranteed to be unique even if multiple engines are running simultaneously.

If the DMScript has been invoked from the DeployHub Web User Interface (i.e.: a manual deployment or a task invocation) then JSESSIONID is set to the session ID of the web session. You can use this to call the DeployHub API from inside DMScript without the need to explicitly log in to the API.

During a deployment, the Environment (and its attributes) are pushed onto the stack, followed by the Application being deployed. At this point, the stack looks like this:


Application

Environment

Global

Thus, any attributes in the Global scope can be overridden by attributes in the selected Environment. Similarly, any attributes defined in the Environment can be overridden by attributes defined in the Application.

For example, suppose the Environment “Test Environment A " has an attribute called QUEUE_NAME which is set to queue1. The Application “MyApp;2 " also has an attribute QUEUE_NAME which is set to queue2.

During a deployment of “MyApp;2 " to “Test Environment A “, a reference to $QUEUE_NAME will return queue2 – since QUEUE_NAME is defined as “queue2 " against the Application and the Application is higher in the stack.

If you want to retrieve the value of an attribute at a specific point in the stack, then you will have to reference the specific object scope. Each object scope has a specific name. Using the example above, $QUEUE_NAME will be queue2 but ${Environment.QUEUE_NAME} will be queue1.

Each scope is named as follows:

Scope Name Description
Global Contains all Environment variables and any “additional attributes " set by the user when the invoking task is run.
Environment Pushed during a deployment or when a manual task is invoked by right-clicking on an Environment. This scope contains the Environment Object itself and any attributes defined for that Environment.
Application Pushed during a deployment or when a manual task is invoked by right-clicking on an Application. This scope contains the Application Object itself and any attributes defined for that Application.
Endpoint Pushed during a deployment when a particular Endpoint is being targeted. Also available during a psloop (see “psloop " later in this section). This scope contains the Endpoint Object itself and any attributes defined for that Endpoint.
Component Pushed during a deployment when the Application is being deployed. The scope contains the Component Object itself and any attributes defined for that Component.

DMScript has built-in methods that allow you to iterate through Endpoint and _Component_s and these push each Component/server onto the stack at the start of the loop and pop them off again at the end of the loop. This happens automatically for each iteration through the loop. So, for example, you could print the names of all the target _Endpoint_s by writing this:

psloop {

echo  "${server.name} - ${server.hostname} ";

}

psloop stands for Physical Server Loop. It iterates through each Endpoint in the current Endpoint list (by default, this is all the _Endpoint_s associated with an Environment). Each Endpoint is pushed onto the stack at the “top " of the loop and popped off again at the end. So this loop will:

  • push the first Endpoint onto the stack;
  • the “echo " will print the name and the hostname of this Endpoint (by explicitly naming the Endpoint scope, the attributes “name " and “hostname " are pulled from the Endpoint object on the stack);
  • pop the Endpoint off again;
  • repeat (a)-(c) for Endpoint.

Stack Content During Deployment

As discussed above, the stack has different objects pushed onto it at various stages in the deployment process. Knowing the deployment process allows you to understand which objects are available to DMScript at which point.

During a Deployment, the following steps are followed:

  • The Global, Environment and Application scopes are pushed onto the stack.

  • If any Pre-Action is linked to the invoked deployment task, then the action is executed. If this action exits with an error then the process is halted.

  • If any Pre-Action is linked to the Application being deployed, then the action is executed. If this action exits with an error, then the process is halted.

  • An “Application Loop " is automatically invoked to loop between the version of the Application on the target Environment and the version being deployed.

  • If rolling forward (the Application Version being deployed is later than the version in the target Environment), the “interim " versions of the Application are checked to see if any Component contains a “Component item " with “roll-forward " option set. If so, the Component is pushed onto the stack and deployed.

  • If rolling backward (the Application Version being deployed is earlier than the version in the target Environment), the “interim " versions of the Application are checked to see if any Component contains a “Component item " with “rollback " option set. If so, the Component is pushed onto the stack and deployed.

  • When a Component is being deployed, the following steps are performed:

    • Each Component Item is executed in sequence to pull the items from the associated repository into the drop-zone.
    • The Endpoint list to which the Component is to be deployed is determined.
    • Each target Endpoint is checked to see if the version of the Component that is associated with the Endpoint is different to the version in the Application. If the Component version differs or the Component is set to “Always Deploy " then the Component is deployed:
      • Any Pre-Action on the Component is executed.
      • If the Component has a Custom Action, then the Custom Action is executed.
      • If the Component does not have a Custom Action, then the drop-zone content is pushed to the target Endpoint. If the drop-zone is empty, then no push is performed.
      • Any Post-Action on the Component is executed.

Pre Action to Task

Invocation Point Available Objects and Variables
$Component The selected Component if the task was invoked on a Component.
$Application Object The selected Application if the task was invoked on an _Application.

Post Action to Task

Invocation Point Available Objects and Variables
$? Integer The Exit Status of the task.
$Component Object The selected Component if the task was invoked on a Component.
$Application Object The selected Application if the task was invoked on an Application.

Pre Action for Application

Invocation Point Available Objects and Variables
${dep.rollforward} Boolean Set during a deployment to true or false.Indicates if the version being deployed is later than the version in the target Environment.
${dep.rollback} Boolean Set during a deployment to true or false. Indicates if the version being deployed is earlier than the version in the target Environment.
${dep.same} Boolean Set during a deployment to true or false. Indicates if the version being deployed is the same as the version in the target Environment.
$Application Object The Application being deployed.
$Environment Object The Environment being deployed to.

Post Action for Application

Invocation Point Available Objects and Variables
$? Integer The Exit Status of the deployment.
${dep.rollforward} Boolean Set during a deployment to true or false. Indicates if the version being deployed is later than the version in the target Environment.
${dep.rollback} Boolean Set during a deployment to true or false. Indicates if the version being deployed is earlier than the version in the target Environment.
${dep.same} Boolean Set during a deployment to true or false. Indicates if the version being deployed is the same as the version in the target Environment.
$Application_Object The_Application_ being deployed.
$Environment_Object. The_Environment_ being deployed to.

Custom Action for Application

Invocation Point Available Objects and Variables
${dep.rollforward} Boolean: Set during a deployment to true or false. Indicates if the version being deployed is later than the version in the target Environment.
${dep.rollback} Boolean Set during a deployment to true or false. Indicates if the version being deployed is earlier than the version in the target Environment.
${dep.same} Boolean Set during a deployment to true or false. Indicates if the version being deployed is the same as the version in the target Environment.
$Application_Object The_Application_ being deployed.
$Environment_Object The_Environment_ being deployed to.

Pre Action for Component

Invocation Point Available Objects and Variables
${dep.rollforward} Boolean Set during a deployment to true or false. Indicates if the version being deployed is later than the version in the target Environment.
${dep.rollback} Boolean Set during a deployment to true or false. Indicates if the version being deployed is earlier than the version in the target Environment.
${dep.same} Set during a deployment to true or false. Indicates if the version being deployed is the same as the version in the target Environment.
$_Component_Object The Component being deployed.
$server Object The Endpoint the Component is being deployed to.
$Application_Object The_Application_ being deployed.
$Environment_Object The_Environment_ being deployed to.
$_DropZone_Object The DropZone containing the files to be transferred to the Endpoint.

Post Action for Component

Invocation Point Available Objects and Variables
$? Integer The exit code of the Component deployment.
${dep.rollforward} Boolean Set during a deployment to true or false. Indicates if the version being deployed is later than the version in the target Environment.${dep.rollback} Boolean: Set during a deployment to true or false. Indicates if the version being deployed is earlier than the version in the target Environment.
${dep.same} Boolean Set during a deployment to true or false. Indicates if the version being deployed is the same as the version in the target Environment.
$_Component_Object The Component being deployed.
$server Object The Endpoint the Component is being deployed to.
$_Application_Object The Application being deployed.
$_Environment_Object The Environment being deployed to.
${dep.files} List The files deployed for this Component.
$_DropZone_Object The DropZone containing the files to be transferred to the Endpoint.

Custom Actions for a Component

Invocation Point Available Objects and Variables
${dep.rollforward} Boolean Set during a deployment to true or false. Indicates if the version being deployed is later than the version in the target Environment.
${dep.rollback} Boolean Set during a deployment to true or false. Indicates if the version being deployed is earlier than the version in the target Environment.
${dep.same} Boolean Set during a deployment to true or false. Indicates if the version being deployed is the same as the version in the target Environment.
$_Component_Object The Component being deployed.
$server Object The Endpoint the Component is being deployed to.
$_Application_Object The Application being deployed.
$_Environment_Object The Environment being deployed to.

DMScript can be invoked at various stages in the deployment process.

Where to Execute DMScript

Given the deployment sequence described previously, you should place DMScript here to achieve your desired results.

If you want to… DMScript goes here
Call an External Application to confirm that an Application can be deployed (e.g.: Service Desk etc). Pre-Action to Application or Deploy Task.
Modify or remove files in a Drop Zone before Deployment. Pre-Action to Component.
Modify a File on a Target Endpoint after Deployment. Post-Action to Component.
Call an external tool to deploy a Component (i.e.: Ansible). Custom Action to Component.
Notify an External Application that an Application has been deployed. Post-Action to Application or Deploy Task.
Last modified June 14, 2020: before api includes (240d0f2)