Steps Reference 10.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

    ParameterTypeDescriptionRequiredCalculated
    ciConfigurationItemConfiguration item to createYesNo
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    orderIntegerExecution order of the stepYesYes
    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

    ParameterTypeDescriptionRequiredCalculated
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    orderIntegerExecution order of the stepYesYes
    target-hostHostA target host where the step is appliedYesYes
    target-pathStringPath of the file or folder to be deletedYesNo
    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

    ParameterTypeDescriptionRequiredCalculated
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    idStringConfiguration item to createYesNo
    orderIntegerExecution order of the stepYesYes
    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

    ParameterTypeDescriptionRequiredCalculated
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    jython-contextMapDictionary with keys as variable name and values as variable that are passed to the Python scriptNoYes
    orderIntegerExecution order of the stepYesYes
    preview-scriptStringPath to the Python Preview script to execute (relative to XL Deploy's classpath)NoNo
    scriptStringPath to the Python script to execute (relative to XL Deploy's classpath)NoNo
    script-pathStringDEPRECATED: Use 'script' instead. Path to the Python script to execute (relative to XL Deploy's classpath)NoNo
    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

    ParameterTypeDescriptionRequiredCalculated
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesNo
    freemarker-contextMapDictionary that contains all values available in the templateNoYes
    mail-fromStringThe email's sender ('From:') email addressNoYes
    mail-serverSmtpServerMail server that is used to send emailsNoYes
    mail-toListThe list of email receivers to send instructions toNoNo
    message-templateStringThe path to the message template to display to the user and/or send outNoNo
    orderIntegerThe execution order of the stepYesNo
    subjectStringThe email subject lineNoYes
    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

    ParameterTypeDescriptionRequiredCalculated
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesNo
    orderIntegerExecution order of the stepYesNo
    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:

    1. Processes all FreeMarker templates with the help of freemarker-context.
    2. Creates a temporary working directory on a target host.
    3. Uploads all classpath-resources to the working directory, preserving the original folder structure.
    4. 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)
    5. 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

    ParameterTypeDescriptionRequiredCalculated
    classpath-resourcesListResources that are attached to the script and uploaded to the target hostNoNo
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    freemarker-contextMapDictionary that contains all values available in the templateNoYes
    orderIntegerExecution order of the stepYesYes
    preview-scriptStringPath to the Python Preview script to execute (relative to XL Deploy's classpath)NoNo
    scriptStringScript base name that will be executed on the target hostYesNo
    shellStringshell to be used to execute script on the target hostNoNo
    target-hostHostA target host where the step is appliedYesYes
    upload-artifactsbooleanIf true, every artifact presented in the freemarker context will be uploaded to the working directory of the scriptNoNo
    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

    ParameterTypeDescriptionRequiredCalculated
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    orderIntegerExecution order of the stepYesYes
    powershell-contextMapThe variables to pass to the Powershell stepNoYes
    scriptStringPath to the Powershell script to execute (relative to XL Deploy's classpath)YesNo
    target-hostHostContainerThe target host to run the script onYesYes
    upload-artifactsBooleanIf 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.YesNo
    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

    ParameterTypeDescriptionRequiredCalculated
    create-target-pathbooleanWhether to create the target folder structure if not present. Defaults to trueNoNo
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    freemarker-contextMapDictionary that contains all values available in the templateNoYes
    orderIntegerExecution order of the stepYesYes
    target-hostHostA target host where the step is appliedYesYes
    target-pathStringFull path on the target host where the artifact is copiedYesNo
    template-pathStringPath of the template relative to the ext/ directoryYesNo
    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

    ParameterTypeDescriptionRequiredCalculated
    artifactArtifactArtifact that is uploaded to the target hostYesYes
    create-target-pathbooleanWhether to create the target folder structure if not present. Defaults to trueNoNo
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    orderIntegerExecution order of the stepYesYes
    target-hostHostA target host where the step is appliedYesYes
    target-pathStringFull path on the target host where the artifact is copiedYesNo
    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

    ParameterTypeDescriptionRequiredCalculated
    descriptionStringDescription of this step, as it should appear in generated deployment plansYesYes
    orderIntegerExecution order of the stepYesNo
    secondsIntegerSeconds that this step pause plan executionYesNo
    Note: For information about how values are calculated, refer to Use a predefined step in a rule.