Steps Reference

    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
    Note: For information about how values are calcuated, 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
    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 calcuated, 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
    Note: For information about how values are calcuated, 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"}
    ))
    

    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
    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
    Note: For information about how values are calcuated, 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 repository (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 repository.
    • 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 calcuated, 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 calcuated, 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 repository.

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

    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
    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
    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 calcuated, 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
    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 calcuated, 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
    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 calcuated, 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
    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 calcuated, 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 calcuated, refer to Use a predefined step in a rule.