Steps Reference 24.3.x

Introduction

This document describes the predefined, general-purpose steps that are available for use with XL Deploy rules.

Plugins such as the IBM WebSphere Application Server plugin can also provide predefined steps. For information about these steps, refer to the plugin documentation.

Step Reference

create-ci

Description

The create-ci step creates a configuration item (CI) in the XL Deploy Repository.

Note: This step cannot run on a satellite.

Examples

This is an example of a create-ci step in an XML rule. It creates a CI under Infrastructure/EC2. The CI name is determined by the name of the deployed application.

<create-ci>
    <order>63</order>
    <description>Create an SSH host</description>
    <ci>
        <overthere.SshHost>
            <id expression="true">"Infrastructure/EC2/" + deployedApplication.name</id>
                <os>UNIX</os>
                <connectionType>SUDO</connectionType>
                <address>deployed.deployable.ip</address>
                <username>ubuntu</username>
                <privateKeyFile>/tmp/key.pem</privateKeyFile>
                <sudoUsername>root</sudoUsername>
        </overthere.SshHost>
    </ci>
</create-ci>

Step Parameters

Parameter	Type	Description	Required	Calculated
ci	ConfigurationItem	Configuration item to create	Yes	No
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
order	Integer	Execution order of the step	Yes	Yes
skippable	boolean	whether a step can be skipped	No	Yes

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

delete

Description

The delete step deletes a file or directory on a remote host. When you specify a directory name, the full directory and all of its content is removed.

Examples

This is an example of the delete step created with an XML rule. It deletes a file named C:\tmp\somefile.txt from the host where the current deployed is located.

<delete>
    <target-path>C:\tmp\somefile.txt</target-path>
</delete>

This example deletes the C:\tmp\testdir and all of its content:

<delete>
    <target-path>C:\tmp\testdir</target-path>
</delete>

This is an example of a fully-specified step created with an XML rule. It combines the target file name and containing folder using a file separator that depends on the operating system of the target machine; that is, when deploying to a Windows environment, \ will be used, while on Unix and z/OS, / will be used.

<delete>
    <description expression="true">"Remove the artifact " + deployed.file.name</description>
    <order>40</order>
    <target-host expression="true">deployed.container.host</target-host>
    <target-path expression="true">deployed.container.home + deployed.container.host.os.fileSeparator + deployed.file.name</target-path>
</delete>

Step Parameters

Parameter	Type	Description	Required	Calculated
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
order	Integer	Execution order of the step	Yes	Yes
skippable	boolean	whether a step can be skipped	No	Yes
target-host	Host	A target host where the step is applied	Yes	Yes
target-path	String	Path of the file or folder to be deleted	Yes	No

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

delete-ci

Description

The delete-ci step deletes a configuration item (CI). You specify the ID of the CI, and it is deleted from the XL Deploy Repository when the step is executed.

Note: This step cannot run on a satellite.

Examples

This is an example of a delete-ci step in an XML rule. It deletes a CI under Infrastructure/Unix. The CI name is determined by the public IP address of the deployed.

<delete-ci>
    <id expression="true">"Infrastructure/Unix/" + deployed.publicIP</id>
</delete-ci>

Step Parameters

Parameter	Type	Description	Required	Calculated
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
id	String	Configuration item to create	Yes	No
order	Integer	Execution order of the step	Yes	Yes
skippable	boolean	whether a step can be skipped	No	Yes

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

jython

Description

The jython step executes a Python script locally on the XL Deploy server. The execution script receives a reference to the ExecutionContext in the context parameter. This object can be used to share data with other steps and log events.

Note that the script's context is different from the planning execution context. Be sure to understand the difference between the planning script and the jython step's <script-path> script, and the difference between the planning context and the execution context.

Note: This step does not have access to the command-line interface script API.

Note: This step cannot run on a satellite.

Examples

There is a script called script/greet_user.py in the ext/ directory with the following content:

context.logOutput("Hello " + name)

This script will print some text in the step log.

This is an example of a jython step created with an XML rule:

<jython>
    <order>60</order>
    <description>Run the 'greet_user.py' script</description>
    <script-path>script/greet_user.py</script-path>
    <jython-context>
        <user>XebiaLabs</user>
    </jython-context>
</jython>

The following is an example of a jython step created with a script rule. Note how in this example, context refers to the planning context - the one which allows you to add steps to the plan. This is also where you have access to e.g. the deployedApplication, the logger, the services, etc. These are not by default available during execution; but if you need them, you can add them here by letting the planning script include them in the jython_context (e.g. by saying jython_context = {"app": deployedApplication} or <jython-context><app expression="true">deployedApplication</app></jython-context>).

context.addStep(steps.jython(
    description = "Run the 'greet_user.py' script",
    order = 60,
    script_path = "script/greet_user.py",
    jython_context = {"user": "XebiaLabs"}
))

This is an example of how to return the code of a step from a jython step:

private def executeScript(executionContext: ExecutionContext): StepExitCode = {
    import scala.collection.convert.ImplicitConversions._
    implicit val scriptContext = createJythonContext(executionContext, Bindings.xlDeployApiServices ++ (jythonContext + ("context" -> executionContext)).toMap)
    val scriptResult: AnyRef = jython.executeScript(byResource(scriptPath), resultProcessor = extractJythonResult)
    scriptResult match {
      case "PAUSE" => StepExitCode.PAUSE
      case "RETRY" => StepExitCode.RETRY
      case x: Integer if x > 0 =>
        executionContext.logError(s"Python script exited with exit code '$x'")
        StepExitCode.FAIL
      case x: StepExitCode => x
      case _ => StepExitCode.SUCCESS
    }
  }

Step Parameters

Parameter	Type	Description	Required	Calculated
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
jython-context	Map	Dictionary with keys as variable name and values as variable that are passed to the Python script	No	Yes
order	Integer	Execution order of the step	Yes	Yes
preview-script	String	Path to the Python Preview script to execute (relative to XL Deploy's classpath)	No	No
script	String	Path to the Python script to execute (relative to XL Deploy's classpath)	No	No
script-path	String	DEPRECATED: Use 'script' instead. Path to the Python script to execute (relative to XL Deploy's classpath)	No	No
skippable	boolean	whether a step can be skipped	No	Yes

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

manual

Description

The manual step allows you to incorporate a manual process as part of a deployment. The step can reference a text file that contains instructions for the manual execution. The content of the text file will appear in the logging output when the step is executed. You can use FreeMarker for the template.

When the step is executed, the deployment is put into a PAUSE state. To resume the deployment, the user must carry out the instructions and click Continue in the XL Deploy interface. Alternatively, the "continue" action can be triggered by the command-line interface or the REST API.

XL Deploy can automatically send the instructions in the step to one or more email addresses, which you specify in the mail-to parameter. This feature requires that there is either:

An SMTP server associated with the mail-server that you are deploying to, or
A default SMTP server defined in the XL Deploy repositoryService (which XL Deploy will then use)

Note: This step cannot run on a satellite.

Examples

This is an example of a manual step created with an XML rule:

<manual>
    <description>Send mails</description>
    <order>50</order>
    <message-template>templates/email.txt.ftl</message-template>
    <mail-server expression="true">deployedApplication.environment.smtpServer</mail-server>
    <mail-to>
        <value>jdoe@operations.example.com</value>
        <value>manager@operations.example.com</value>
    </mail-to>
    <mail-from>noreply@deployment.example.com</mail-from>
    <subject>Deploying...</subject>
    <freemarker-context>
        <buttonColour>green</buttonColour>
    </freemarker-context>
</manual>

Same example of manual of step but with calculated parameters omitted.

<manual>
    <description>Send mails</description>
    <order>50</order>
    <message-template>templates/email.txt.ftl</message-template>
    <mail-to>
        <value>jdoe@operations.example.com</value>
        <value>manager@operations.example.com</value>
    </mail-to>
    <mail-from>noreply@deployment.example.com</mail-from>
    <freemarker-context>
        <buttonColour>green</buttonColour>
    </freemarker-context>
</manual>

This is an example of a manual step created with a script rule:

context.addStep(steps.manual(
    description = "Send mails",
    order = 50,
    message_template = "templates/email.txt.ftl",
    mail_server = deployedApplication.environment.smtpServer,
    mail_to = ["jdoe@operations.example.com","manager@operations.example.com"],
    mail_from = "noreply@deployment.example.com",
    subject = "Deploying...",
    freemarker_context = {"buttonColour": "green"}
))

Both examples refer to a template, <XL_DEPLOY_HOME>/ext/templates/email.txt.ftl, which contains:

Hi!

We're deploying ${deployed.name}.

Please press the $buttonColour button so we can proceed!

Don't forget to push the Continue button in XL Deploy afterward to resume the deployment :-)

Calculated Step Parameters

Mail Server

mail-server is set to the one of the following:

environment property of type mail.SmtpServer and name smtpServer.
mail.SmtpServer that has a name defaultSmtpServer in the repositoryService.
If nothing of above is available, the parameter must be specified manually.

Mail From

mail-from is set to the default sender address specified in the mail server configuration.

Step Parameters

Parameter	Type	Description	Required	Calculated
description	String	Description of this step, as it should appear in generated deployment plans	Yes	No
freemarker-context	Map	Dictionary that contains all values available in the template	No	Yes
mail-from	String	The email's sender ('From:') email address	No	Yes
mail-server	SmtpServer	Mail server that is used to send emails	No	Yes
mail-to	List	The list of email receivers to send instructions to	No	No
message-template	String	The path to the message template to display to the user and/or send out	No	No
order	Integer	The execution order of the step	Yes	No
subject	String	The email subject line	No	Yes

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

noop

Description

The <noop> step is a step that does not perform any actions; a kind of 'dummy' step. One can use it as a marker to indicate that a plan defined by means of rules is correct.

Note: This step cannot run on a satellite.

Example

<noop>
    <description>This is a dummy step that performs no actions</description>
    <order>60</order>
</noop>

Step Parameters

Parameter	Type	Description	Required	Calculated
description	String	Description of this step, as it should appear in generated deployment plans	Yes	No
order	Integer	Execution order of the step	Yes	No

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

os-script

Description

The os-script step executes a script on a remote host. The required script parameter refers to the script in classpath or the ext/ directory.

The step has the following features:

Operating system independence: The step will select the script based on the host of the operating system (OS) of the host where the script will be executed, so you do not need to include the script extension in the script parameter.
- In the case of Unix, XL Deploy searches for a script with an .sh extension.
- In the case of Microsoft Windows, it searches for a .bat or .cmd extension.
FreeMarker template support: If the script has an .ftl extension, XL Deploy processes it with FreeMarker before uploading it and removes the .ftl extension from the uploaded file. The input that you define in the freemarker-context parameter is used to resolve the FreeMarker template.
Classpath resources: In classpath-resources, you can specify additional resources that are located in the classpath or the ext/ directory. XL Deploy uploads these resources with the script. If a resource has an .ftl extension, XL Deploy processes it with FreeMarker before uploading it and removes .ftl from the uploaded file.
Attach artifacts to your step: You can attach an artifact (which is a deployed that implements udm.Artifact) to the script. XL Deploy will upload the artifact to the working directory on the target host.

Attachment is done through the FreeMarker context. Any artifact in the FreeMarker context will be uploaded (the deployed itself is added to the FreeMarker context by default). The artifact can only be resolved after it is uploaded. For each artifact in the FreeMarker context, artifact.file resolves to an OverthereFile that points to the final destination of the uploaded artifact.

Examples

The following example shows how to use os-script to deploy a deployed of type udm.Artifact to a remote host. This example focuses on defining the step and omits other required preconditions such as packaging, deployment plan, and so on.

This example deploys a WAR file to a container and copies company-logo.jpg and index.html to the www folder of an HTTP server.

Assume that the following files are created in the ext/ directory.

os-script-example
├── images
│   └── company-logo.jpg
├── html
│   └── index.html.ftl
└── scripts
    ├── deploy.bat.ftl
    └── deploy.sh.ftl

The WAR file (sample-artifact.war) is provided in a configuration item (CI) that was created in the XL Deploy repositoryService.

index.html is a FreeMarker template with the following content:

<!DOCTYPE html>
<html>
<head lang="en">
    <meta charset="UTF-8">
    <title>Welcome to ${deployedApplicationName}</title>
</head>
<body>
    <img src="images/company-logo.jpg">
</body>
</html>

The FreeMarker expression ${deployedApplicationName} is a way of accessing the name of the deployed application; it must be provided in the step definition.

deploy.sh.ftl is a FreeMarker template with the following content:

cp ${deployed.file.path} /opt/container/wars/
cp os-script-example/images/company-logo.jpg /var/www/company-site/image/
cp os-script-example/html/index.html /var/www/company-site/

${deployed.file.path} will resolve to the final destination of the uploaded artifact.

deploy.bat.ftl is a script that executes same commands as deploy.sh.ftl, but on a Windows host.

The step definition is:

<os-script>
    <description>Deploying War file to servlet container and static content to an HTTP server</description>
    <order>70</order>
    <target-host expression="true">deployed.container.host</target-host>
    <script>os-script-example/scripts/deploy</script>
    <shell>/bin/sh</shell>
    <freemarker-context>
        <deployedApplicationName expression="true">deployedApplication.name</deployedApplicationName>
    </freemarker-context>
    <classpath-resources>
        <value>os-script-example/images/company-logo.jpg</value>
        <value>os-script-example/html/index.html</value>
    </classpath-resources>
</os-script>

The os-script parameters are defined as follows:

target-host is a Jython expression that points to a host (deployed.container.host) where the script is executed.
script points to a script that is executed on the target host. Note that it does not specify the extension bat.ftl or sh.ftl, because the os-script step chooses the correct file, based on the operating system of the target host.
shell specifies the optional Unix shell needed to execute the shell script (.sh file). This is an optional property with no default value. In it's absence the script is run as an executable. Note that it is only valid for Unix/Linux operating systems.
freemarker-context specifies inputs for the index.html.ftl, deploy.bat.ftl, and deploy.sh.ftl FreeMarker templates. Note that there is no definition of the deployed FreeMarker input that is used in deploy.sh.ftl; XL Deploy will automatically calculate it.
classpath-resources specifies dependencies of the script. These dependencies are uploaded to the target host.

An os-script step defined in this way does following:

Processes all FreeMarker templates with the help of freemarker-context.
Creates a temporary working directory on a target host.
Uploads all classpath-resources to the working directory, preserving the original folder structure.
Uploads all udm.Artifacts available in the freemarker-context to the working directory. The resulting file names are available in the FreeMarker template as ${artifactName.file.path} (in our example, the artifact has name deployed, thus the expression ${deployed.file.path} must be used)
Executes the script in the working directory.

Files are created in the working directory on the target host as follows:

os-script-example
├── images
│   └── company-logo.jpg
├── html
│   └── index.html
├── scripts
│   └── deploy.sh        
└── sample-artifact.war

Note that all files generated with FreeMarker templates lose the ftl extension.

The content of deploy.sh is:

cp sample-artifact.war /opt/container/wars/
cp os-script-example/images/company-logo.jpg /var/www/company-site/image/
cp os-script-example/html/index.html /var/www/company-site/

Step Parameters

Parameter	Type	Description	Required	Calculated
classpath-resources	List	Resources that are attached to the script and uploaded to the target host	No	No
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
freemarker-context	Map	Dictionary that contains all values available in the template	No	Yes
order	Integer	Execution order of the step	Yes	Yes
preview-script	String	Path to the Python Preview script to execute (relative to XL Deploy's classpath)	No	No
script	String	Script base name that will be executed on the target host	Yes	No
shell	String	shell to be used to execute script on the target host	No	No
skippable	boolean	whether a step can be skipped	No	Yes
target-host	Host	A target host where the step is applied	Yes	Yes
upload-artifacts	boolean	If true, every artifact presented in the freemarker context will be uploaded to the working directory of the script	No	No

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

powershell

Description

The powershell step executes a PowerShell script on the remote (Windows) host.

Examples

The script Hello.ps1 in the ext/ directory contains this script:

Write-Host "Hello" $who

This is an example of a powershell step created with an XML rule:

<powershell>
    <order>60</order>
    <description>Run the 'Hello.ps1' test script</description>
    <script>Hello.ps1</script>
    <target-host expression="true">deployed.container</target-host>
    <powershell-context>
        <who>World</who>
    </powershell-context>
</powershell>

The order, description and target-host, if not specified, are calculated by XL Deploy.

<powershell>
    <script>Hello.ps1</script>
    <powershell-context>
        <who>World</who>
    </powershell-context>
</powershell>

This is an example of a powershell step created with a script rule:

context.addStep(steps.powershell(
    description = "Greeting the world",
    order = 80,
    script = "Hello.ps1",
    powershell_context = {"who": "World"},
    target_host = deployed.container
))

The syntax used for powershell_vars is also available directly in the XML variant above. That is, you can write:

<powershell-context expression="true">{"who":"XebiaLabs"}</powershell-context>

Calculated Step Parameters

The target-host parameter of a step is calculated as follows:

If the scope is deployed:
- deployed.container is of type overthere.HostContainer, the target-host is set to deployed.container
In other cases, target-host cannot be calculated automatically and must be specified manually.

Step Parameters

Parameter	Type	Description	Required	Calculated
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
order	Integer	Execution order of the step	Yes	Yes
powershell-context	Map	The variables to pass to the Powershell step	No	Yes
script	String	Path to the Powershell script to execute (relative to XL Deploy's classpath)	Yes	No
skippable	boolean	whether a step can be skipped	No	Yes
target-host	HostContainer	The target host to run the script on	Yes	Yes
upload-artifacts	Boolean	If true, the artifacts from the powershell context will be uploaded to the target host and available to the script as $bindingName.file. Defaults to true.	Yes	No

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

template

Description

The template step generates a file based on a FreeMarker template and uploads the file to a remote host.

Examples

This is an example of the template step.

These examples resolve a template from the file datasource.ftl and copies the resulting file to a directory on the target host. The file contains:

<datasource>
    <name>${deployed.datasourceName}</name>
    <property>${prop}</property>
</datasource>

${prop} is provided to the template with freemarker-context. Also, deployed is added to the freemarker-context. Refer to Define rule behavior for more information.

This is an example of a template step created with an XML rule:

<template>
    <target-path>/somewhere/there/datasource.xml</target-path>
    <template-path>templates/datasource.ftl</template-path>
    <freemarker-context>
        <prop>myProp</prop>
    </freemarker-context>
</template>

This is an example of a template step created with a script rule:

context.addStep(steps.template(
    target_path = "/somewhere/there/datasource.xml",
    template_path = "templates/datasource.ftl",
    freemarker_context = {"prop": "myProp"})
    )

Step Parameters

Parameter	Type	Description	Required	Calculated
create-target-path	boolean	Whether to create the target folder structure if not present. Defaults to true	No	No
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
freemarker-context	Map	Dictionary that contains all values available in the template	No	Yes
order	Integer	Execution order of the step	Yes	Yes
skippable	boolean	whether a step can be skipped	No	Yes
target-host	Host	A target host where the step is applied	Yes	Yes
target-path	String	Full path on the target host where the artifact is copied	Yes	No
template-path	String	Path of the template relative to the ext/ directory	Yes	No

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

upload

Description

The upload step copies a udm.Artifact to an overthere.Host.

Examples

This is an example of a upload step created with an XML rule:

<upload>
    <artifact expression="true">deployed</artifact>
    <target-host expression="true">deployed.container.host</target-host>
    <target-path>/tmp/somewhere/there/file</target-path>
    <create-target-path>true</create-target-path>
    <order>50</order>
    <description>Rule based copy artifact step</description>
</upload>

This is an example of a upload step created with a script rule:

context.addStep(steps.upload(
    artifact = deployed,
    target_host = deployed.container.host,
    target_path = "/tmp/somewhere/there/file",
    create_target_path = True,
    order = 50,
    description = "Rule based copy artifact step"))

This is an example of a upload step with parameters calculated by XL Deploy:

<upload>
    <target-path>/tmp/somewhere/there/file</target-path>
</upload>

Step Parameters

Parameter	Type	Description	Required	Calculated
artifact	Artifact	Artifact that is uploaded to the target host	Yes	Yes
create-target-path	boolean	Whether to create the target folder structure if not present. Defaults to true	No	No
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
order	Integer	Execution order of the step	Yes	Yes
skippable	boolean	whether a step can be skipped	No	Yes
target-host	Host	A target host where the step is applied	Yes	Yes
target-path	String	Full path on the target host where the artifact is copied	Yes	No

Note: For information about how values are calculated, refer to Use a predefined step in a rule.

wait

Description

The wait step freezes the deployment plan execution for a specified number of seconds.

The description parameter is optional and defaults to "Waiting for xx seconds".

Note: This step cannot run on a satellite.

Examples

This is an example of a wait step created with an XML rule:

<wait>
    <order>60</order>
    <description>Let us have a 10 seconds pause</description>
    <seconds>10</seconds>
</wait>

This is an example of a wait step created with a script rule:

context.addStep(steps.wait(
    description = "Delay the rest of the execution plan for 10 seconds",
    order = 80,
    seconds = 10
))

Step Parameters

Parameter	Type	Description	Required	Calculated
description	String	Description of this step, as it should appear in generated deployment plans	Yes	Yes
order	Integer	Execution order of the step	Yes	No
seconds	Integer	Seconds that this step pause plan execution	Yes	No

Note: For information about how values are calculated, refer to Use a predefined step in a rule.