# Create a rolling group

Source: https://www.jawsdeploy.net/rest-api/rolling-group-create | Section: Rolling Groups

Group a consecutive run of steps so one machine completes all of them before the next begins.

`POST /api/project/rolling-group`

Creates a rolling group from a set of member steps. The members are given here rather than added one at a time, because a group with no members cannot exist.

Read [List project steps](https://www.jawsdeploy.net/rest-api/projects-steps-list) first. Contiguity and the target-machine rule are properties of the whole ordered step list, so both are checked against it: the steps must be consecutive in `order` with no non-member between them, and every one must have a `runOn` of `TargetMachine`. If a step is in the way, reorder with [Reorder project steps](https://www.jawsdeploy.net/rest-api/project-steps-order) first.

Everything after `memberStepIds` is optional. Note the two group defaults that differ from the step equivalents: `onMachineFailure` is `StopStep`, and `windowSize` is 1 - a group exists to take machines out of service one at a time.

**Settings live in the release snapshot.** A group created after a release was cut does not apply to that release; create a new one.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | body | string | yes | The project the group belongs to. |
| `name` | body | string | no | Display name, shown in the step list, deployment preview and logs. Trimmed; maximum 500 characters. Blank or omitted becomes `Rolling group`. |
| `memberStepIds` | body | array<string> | yes | The steps to group, in step order. Must be a consecutive run, and every step must run on target machines. |
| `windowSize` | body | integer | no | How many machines work through the group at once. Defaults to 1. Capped by the organization's `maxParallelMachines`, which defaults to 8. |
| `machineOrder` | body | string | no | `MachineName` (default) or `TagPriority`. |
| `machineOrderTagIds` | body | array<string> | no | Ordered tag ids. A machine's rank is the index of the first of these tags it carries. Required when `machineOrder` is `TagPriority`. |
| `waitBetweenMachineGroups` | body | boolean | no | The barrier: finish every machine of one tag rank before the next rank starts. Requires `machineOrder` of `TagPriority`. |
| `onMachineFailure` | body | string | no | Whether the next machine starts after one fails. `StopStep` (default) or `ContinueToOtherMachines`. |
| `onMemberFailure` | body | string | no | Whether a machine runs the group's remaining steps after one fails on it. `SkipRestOnThisMachine` (default) or `ContinueMembers`. |
| `onNoTargets` | body | string | no | What happens when no machine matches any step in the group. `Skip` (default), `Warn` or `Fail`. A deployment started for other machines only always skips. |

### Enumerated values

Policy and order fields are sent and returned as names, not numbers. Parsing is case-insensitive; responses use the canonical casing. An unrecognised name is rejected rather than silently defaulted.

- `machineOrder` - `MachineName`, `TagPriority`
- `onMachineFailure` - `ContinueToOtherMachines`, `StopStep`
- `onMemberFailure` - `SkipRestOnThisMachine`, `ContinueMembers`
- `onNoTargets` - `Skip`, `Warn`, `Fail`

## Response fields

| Field | Type | Description |
|---|---|---|
| `rollingGroupId` | string | The group's id. Pass this as `rollingGroupId` when updating, dissolving, or moving a step into the group. |
| `projectId` | string | The project the group belongs to. |
| `name` | string | Display name, shown in the step list, the deployment preview and the logs. |
| `order` | integer | Where the group sits among the project's steps. **Derived** from the order of its first member and never accepted from the caller, so it cannot disagree with the step list. |
| `windowSize` | integer | How many machines work through the group at once. `1` means a strict one-at-a-time rollout. Never above the organization's `maxParallelMachines`, which defaults to 8. |
| `machineOrder` | string (enum) | The order machines enter the group. One of `MachineName` - alphabetical, case-insensitive - or `TagPriority`, where a machine's rank is the index of the first tag it carries from `machineOrderTagIds`. Within a rank machines are ordered by name; machines carrying none of the tags run last. |
| `machineOrderTagIds` | string[] | Tag ids in priority order, first tag highest. Empty array when `machineOrder` is `MachineName` - the list is not persisted for an order that does not use it. |
| `waitBetweenMachineGroups` | boolean | The barrier. `true` finishes every machine of one tag rank before the next rank starts. Only ever `true` alongside `machineOrder` of `TagPriority`. |
| `onMachineFailure` | string (enum) | Whether the next machine starts after the group fails on one. `StopStep` - the default - starts no further machine; `ContinueToOtherMachines` carries on. Neither stops the deployment; that is `onStepFailure` on the member itself. |
| `onMemberFailure` | string (enum) | Whether a machine runs the group's remaining steps after one fails on it. `SkipRestOnThisMachine` - the default - skips them; `ContinueMembers` runs them, which is what a cleanup or notification member needs. |
| `onNoTargets` | string (enum) | `Skip`, `Warn` or `Fail` - what the group does when no machine matches any of its steps. |
| `memberStepIds` | string[] | The member steps, in step order. **Projected** from the steps' own `rollingGroupId` rather than stored on the group, so this and the step list cannot disagree. Always at least one id. |

## Errors

| Status | Meaning |
|---|---|
| 400 | `memberStepIds` was empty or omitted - `a rolling group needs at least one member step`. |
| 400 | `One or more of the steps to group were not found in this project.` |
| 400 | The members are not consecutive. The message names every step sitting between them. |
| 400 | A member does not run on target machines - the message names the step and its `runOn`. |
| 400 | An unrecognised `machineOrder`, `onMachineFailure`, `onMemberFailure` or `onNoTargets` value. |
| 400 | Validation failed: a window outside 1 to the organization maximum, a missing group name, `TagPriority` with no tags, or the barrier without `TagPriority`. |
| 401 | Missing or invalid Basic auth credentials, or the service account may not edit this project. |

Example request:

```
POST /api/project/rolling-group HTTP/1.1
Authorization: Basic <base64(serviceAccountId:apiKey)>
Content-Type: application/json

{
  "projectId": "prj_42",
  "name": "web rollout",
  "memberStepIds": ["step-1", "step-2", "step-3", "step-4"],
  "windowSize": 1,
  "machineOrder": "TagPriority",
  "machineOrderTagIds": ["tag-canary"],
  "waitBetweenMachineGroups": true,
  "onMachineFailure": "StopStep",
  "onMemberFailure": "SkipRestOnThisMachine"
}
```

Example response:

```
{
  "rollingGroupId": "rg_7a1",
  "projectId": "prj_42",
  "name": "web rollout",
  "order": 3,
  "windowSize": 1,
  "machineOrder": "TagPriority",
  "machineOrderTagIds": ["tag-canary"],
  "waitBetweenMachineGroups": true,
  "onMachineFailure": "StopStep",
  "onMemberFailure": "SkipRestOnThisMachine",
  "onNoTargets": "Skip",
  "memberStepIds": ["step-1", "step-2", "step-3", "step-4"]
}
```