# Create a step template

Source: https://www.jawsdeploy.net/rest-api/step-templates-create | Section: Step Templates

Define a new reusable step template.

`POST /api/step-template`

Creates a step template. `propertiesRaw` is a JSON-encoded array of property definitions - the inputs a project step built from this template asks for, and the values it starts with. See below for the shape.

Step templates are the building blocks projects pick from when defining steps.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `workspaceId` | body | string | yes | ID of the workspace. |
| `name` | body | string | yes | Template name. |
| `description` | body | string | no | Optional description. |
| `supportedRunModes` | body | array<string> | no | See below. |
| `script` | body | string | yes | Body of the script. |
| `scriptLanguage` | body | string | no | `powershell` (default, PowerShell 7), `powershell5` (Windows PowerShell 5.1) or `python` (Python 3). |
| `propertiesRaw` | body | string | no | JSON-encoded array of property definitions. Defaults to `"[]"`. See below. |

### Supported run modes

Each `supportedRunModes` entry must be `TargetMachine`, `Worker`, or `WorkerToCloudTargets`. Values that cannot be parsed are ignored; if no valid entries remain, the request returns `400`.

### Property definitions

`propertiesRaw` is a string holding a JSON array, so it is JSON-encoded twice inside the request body. Each element describes one input on the form shown when the template is added to a project.

- `Id` - identifier, unique among its siblings. The script reads the value as `STEP.<Id>`, or `STEP.<GroupId>.<ChildId>` for a property nested in a group.
- `Name` - the label shown above the control.
- `Description` - optional help text under it.
- `ControlType` - one of `SingleLineText`, `MultiLineText`, `SecureString`, `Checkbox`, `Number`, `DropDownList`, `ScriptEditor`, `JsonEditor`, `PackageSelector`, `CloudAccountSelector`, `PropertyGroup`.
- `ControlTypeOptions` - settings the control needs. `ScriptEditor` takes `Language` (`powershell`, `powershell5`, `python` or `json`), `CloudAccountSelector` takes `CloudType`.
- `ControlValues` - the options offered by a `DropDownList`, as `[{"Name": "shown in the list", "Value": "read by the script"}]`.
- `DependsOn` - show this property only while another one holds a value, as `{"ControlId": "OtherProperty", "Operator": "Equals", "Value": "yes"}`. `Operator` is `Equals` or `NotEquals`, and `ControlId` is the other property's `Id`, written `<GroupId>.<ChildId>` when it sits inside a group.
- `Properties` - the nested array a `PropertyGroup` contains. Groups hold other properties and no value of their own.

### Initial property values

There is no `DefaultValue` field. A starting value goes in the typed field that matches the control.

| Control type | Field to set |
| --- | --- |
| `SingleLineText`, `MultiLineText`, `SecureString`, `ScriptEditor`, `JsonEditor`, `DropDownList`, `CloudAccountSelector` | `ValueText` |
| `Checkbox` | `ValueBoolean` |
| `Number` | `ValueNumber` |
| `PackageSelector` | `ValueObject` |

A step added from the template starts with those values, and whoever adds the step can change them afterwards. `DropDownList` is the exception - a new step always takes the first `ControlValues` entry, whatever `ValueText` says.

Setting `IsBound` to `true` replaces the control with a variable expression editor. `ValueText` then holds an expression such as `#{ServiceName}` that is resolved at deploy time, whatever the control type is.

Any other member of a property object is discarded when the template is saved. The request still returns `200`, and the discarded field is simply absent from the schema that [Get step template details](https://www.jawsdeploy.net/rest-api/step-templates-details) returns. `DefaultValue` is the one to watch for - it reads as though it should work, and a template carrying it produces steps whose inputs are empty.

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid `workspaceId`, invalid `scriptLanguage`, or validation failure. |
| 401 | Missing or invalid Basic auth credentials, or the service account lacks the required role. |

Example request:

```
POST /api/step-template

{ "workspaceId": "ws_abc", "name": "Restart Windows service", "scriptLanguage": "powershell", "script": "Restart-Service $ServiceName", "propertiesRaw": "[{\"Id\":\"ServiceName\",\"Name\":\"Service name\",\"ControlType\":\"SingleLineText\",\"ValueText\":\"Spooler\"}]" }
```

Example response:

```
{ "stepTemplateId": "st_2" }
```