Home / Guides / Step templates - Building blocks for reusable deployment logic

Step templates - Building blocks for reusable deployment logic

What are Step Templates?

Step templates are the reusable building blocks of deployment projects in Jaws Deploy. Each project step is based on a template, which defines both its purpose (e.g., run a script, deploy a package) and its UI configuration model. Templates allow you to standardize deployment logic across multiple projects, reducing duplication and ensuring consistency.

Jaws Deploy comes with a few pre-defined step templates useful in typical deployment scenarios. We are actively working on an open-source step template library, which can be used by all Jaws Deploy installations (cloud and on-prem). The library will also be open for community-authored templates. Stay tuned.

By using step templates, you can:

  • Encapsulate common deployment operations (e.g., run PowerShell script, copy files, deploy a package).
  • Parameterize project steps with custom UI input fields which are also available to other steps as context variables.
  • Extend Jaws Deploy to handle custom workflows unique to your infrastructure.

How Step Templates work?

When you add a new project step in Jaws Deploy, you select a template as its base. The template specifies:

  • UI definition (JSON): defines how configuration options are presented in the web UI.
  • Execution logic (script or code): defines what happens when the step is executed.

This separation means that templates are both user-friendly (providing configurable UI to end users) and highly extensible (thanks to JSON definition for the UI and code for logic).

When setting up steps in a project you'll notice that all steps share some common configuration - names, descriptions, filtering by Environments, Tags or Machines, is the step allowed to run in parallel (on multiple Machines at once) and others. Below the common sections there will be more options which were defined in the step JSON UI configuration.

All inputs in the step configuration support variables. This means you can wrap common deployment logic into step templates, expose some parts of the step logic as custom UI inputs, and then apply variables to them, which makes step templates one of Jaws superpowers - reusable building blocks, driven by variables, which resolve automatically depending on the deployment context.

Implementing your own step template

To get more familiar with how step templates work let's create a simple step template from scratch, create a project step based on it, run it and observe the results.

0. Prerequisites

  1. in this tutorial we will use Jaws Deploy Cloud - a fully managed installation of Jaws Deploy. If you don't have an account you can create one using this link: https://app.jawsdeploy.net/signup
  2. When your account is ready there should be a default Workspace created called "Main". You can see the current workspace in the app top bar. In this tutorial we'll use URLs that refer to the default workspace (they will contain /w/main).

1. Create a project with one pre-defined step

  1. See our Getting Started guide to find out how you can set up your workspace with machines and a sample project.
  2. Create a new project called "Step templates demo" and go into the "Steps" tab on project page details.
  3. Create a new step of type "Run script". Once the step details forms opens, click the {} icon next to step template name to view the script baked into this template. This can be helpful in future to preview the logic related with a step template.
  4. Scroll down to the bottom of the step configuration form and enter a simple script to be executed in the "Script body" textarea:

    Write-Host "Hello world!"
  5. Save the step, create a release and deploy it to a test environment, preferably just to one machine.

2. Create a new step template

  1. In the left menu choose "Step templates".
  2. Click "Add new step template".
  3. Specify name e.g. "Print a variable", choose "Machine" in the "Supported run modes" selector and insert this code into the "Script body" text area (PowerShell):

    // here we read the value from step configuration as specified in UI
    $variableNameToPrint = $Jaws.Parameters["STEP.VariableNameToPrint"].Value

    // now we read the value of a variable from deployment context, based on the variable name ...
    $variableValue = $Jaws.Parameters["VAR.$variableNameToPrint"].Value

    // ... and print the variable value to the deployment log
    Write-Host "The variable value is: $variableValue"
  4. In the "Properties" text area insert the following JSON, which defines the step UI configuration:

    [
     {
    "Id": "VariableNameToPrint",
    "Name": "Name of the variable to print",
    "Description": "Specify a name of a variable that exists in the deployment context - this step template will print it out to deployment log.",
    "ControlType": "SingleLineText"
    }
    ]
  5. Save the step template.

3. Create a step based on "Print a variable" step template

  1. Open the Projects page, select the "Step templates demo" project and go to the "Steps" tab
  2. Click "Add step", enter a name of your choice and select "Print a variable" from the "Step type" dropdown. This tells Jaws Deploy to create step based on the template we just created in previous section.
  3. Scroll down to the step configuration where you can specify "Name of the variable to print". Note that this part of UI is based on the JSON definition from previous section. The app provides a single-line text input with label and description matching the ones we configured in the step template. To the right you can see the variable name which can be used in code - in case you need to refer to the value of this field later on.
  4. Insert e.g. "MyVarToPrint" in the "Name of the variable to print" textbox.
  5. Save the step.

4. Create a variable to be printed out

  1. Go to "Variables" tab of the project and add a new project variable called "MyVarToPrint" (this is the variable name from previous section). See the Variables guide for more information on variables.
  2. Add a single variable value e.g. "My test value".

5. Create a release and deploy the project

  1. Click "Create release" button on top of the project details page.
  2. Deploy the new release to a test Environment, preferably to a single machine.
  3. Observe the deployment log. First step should print "Hello world!" and second step should print "The variable value is: My test value".

Wrapping up

In this guide we've shown some basics of step templates and we followed a very simple example showcasing how step templates can be utilized. To dive deeper into step templates refer to other existing step templates in the "Step templates" area available in the app's left menu. By examining the code you can get a deeper understanding, learn how you can wrap logic in functions, how to access variables from the deployment context and much more.

Step templates give you full control over what Jaws Deploy can do during a deployment. Since you have access to PowerShell which runs directly on the deployment target or a worker machine (which e.g. canperform deployment tasks against some cloud entities) - the possibilities of step templates are pretty much unlimited. 🚀