runtask allows DMScript to invoke a task associated with a domain. It allows tasks to be invoked via scripts, providing more opportunities for automation. Executing tasks via DMScript allows you to:


  • Automatically move an Application Version from one Domain to Another
  • Approve an Application Version
  • Create a New Application Version
  • Run a "Request" Task.

NOTE: runtask cannot be used to run a Deploy Task. The invoking user must have execute access to the task otherwise a runtime error occurs.


runtask takes a mandatory named parameter. Other parameters can be specified depending on the task type:


task

       Mandatory. The name of the task to execute. The task name can be qualified with as many domain names as required to uniquely identify the task.

note

       Optional String. For Move, Approve and Request Task Types. Specifies the free text "note" associated with the task execution. This note is included in the history entry and can be included in any attached notification (with the $NOTE variable).

approve

       Optional Boolean. For Approve Tasks only. If false (default) this represents a rejection. Specify true to ensure the Application is marked as approved.

predecessor

       Optional Application Object. For Create Version Tasks only. Specifies the parent Application to be used for the newly created Application.


runtask is also useful for occasions where it may be required to suspend a deployment whilst a manual operation is performed. For example, it may be required to stop the deployment whilst a backup is taken of a target Endpoint. Once the backup is performed, the deployment can be allowed to continue. To do this, runtask can be used in combination with waitfor in order to implement a "wait for manual step". In this case, runtask executes a "request" task which is linked to a stand-alone task which confirms the manual step has been performed.


Example:


Execute an automatic approval following a successful deployment:


runtask(

task: "${Application.fqdomain}.Approve",

note: "This is an automated approval",

approve: true);


Here, the deployed Application's fully qualified domain is prepended to the name of the task "Approve" in order to accurately identify the task regardless of where the Application is in the lifecycle.

NOTE: Tasks that operate on Applications require the Application to be on the stack. During a deployment operation, the Application will be on the stack and accessible via the $Application object. If you are running a task outside of the deployment process you will need to push the Application onto the stack by executing the task within a using Application block. See using Application later in this chapter for more information.



Example:

Send out a request for a manual step to be performed and suspend deployment:


runtask(task: "${Application.fqdomain}.Request Manual Step");

waitfor(task: "${Application.fqdomain}.Manual Step Performed");


Here, DMscript calls the task "Request Manual Step". This is a "request" task linked to the "Manual Step Performed" task. When this task is invoked, DeployHub will issue the notification to the users in the group who have execute access to the "Manual Step Performed" task and place the request to execute this task into those users' To Do list on their home page.


The script will then call waitfor which will suspend the script execution until the "Manual Step Performed" task is run. At which point the script will continue automatically.