## Create or replace a blueprint (tenant:settings:write)

`PUT /api/workflow/v1/blueprints/{blueprintId}`

Module: Workflow · operationId: `saveBlueprint` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores the blueprint under the `id` **of the body** (the path segment is not used). The blueprint
needs an `id`, at least one step, a name for every step and, for `transaction` triggers, at
least one transaction type and status (`400`); the full check of `POST /blueprints/validate` must
find no problems (`422`). `version` defaults to 1 and is not incremented by the server.
A step's legacy `teamsWebhookUrl` is moved into a comms webhook channel (`teamsChannel`); if comms
fails the save answers `502`. Running instances keep the blueprint they started with.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `blueprintId` | path | string | yes | Blueprint id |

### Request body

`application/json` (required)

- `id` (string, required): Free identifier, unique per tenant
- `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
  - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
  - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
  - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
  - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
  - `fields` (array of Field): Fields shown in a user step
    - `name` (string, required): Trade field (`GET /blueprints/fields`), `typeData.<key>`, `lines.<field>`, or a workflow-local input field
    - `editable` (boolean): The user may change it; trade fields only if listed as editable
    - `label` (string): Label shown in the step
    - `required` (boolean): The user must fill it in to complete the step
    - `visible` (boolean, nullable): Whether the field is shown; null means visible
  - `group` (string): HR group UUID the user step is assigned to (required for user steps)
  - `lines` (LineActions): Line actions of a user step besides editing line fields
    - `allowDelete` (boolean): The user may delete lines
    - `allowDuplicate` (boolean): The user may duplicate lines
  - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `notificationEmail` (string): E-mail address notified about this step
  - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
  - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
  - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
  - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
  - `user` (string): E-mail of a person the user step is additionally assigned to
- `trigger` (Trigger, required)
  - `objectType` (string, required): The only supported object type (one of `transaction`)
  - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
  - `nextStep` (NextStep)
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `statuses` (array of string): Trade statuses that start the workflow
  - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
- `active` (boolean): Only active blueprints start workflows; missing means active
- `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
- `overviewField1` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `overviewField2` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
- `version` (integer (int64)): Informational; set to 1 when 0 on save

Example:

```json
{
  "active": true,
  "id": "angebot-pruefung",
  "overviewField1": {
    "label": "Kunde",
    "name": "partnerCompany"
  },
  "overviewField2": {
    "label": "Brutto",
    "name": "grossTotal"
  },
  "steps": [
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Angebotsnummer",
          "name": "transactionNumber"
        },
        {
          "editable": true,
          "label": "Gültig bis",
          "name": "typeData.validUntil"
        },
        {
          "editable": true,
          "label": "Menge",
          "name": "lines.quantity"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "lines": {
        "allowDelete": false,
        "allowDuplicate": true
      },
      "name": "pruefung",
      "nextSteps": [
        {
          "color": "primary",
          "icon": "i-lucide-arrow-right",
          "label": "Weiter",
          "step": "betrag_pruefen"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "notifyAssigneesByEmail": true,
      "stepType": "UserStep"
    },
    {
      "action": "route",
      "name": "betrag_pruefen",
      "nextSteps": [
        {
          "condition": "grossTotal \u003e 1000",
          "step": "freigabe_gf"
        },
        {
          "condition": "default",
          "step": "freigegeben"
        }
      ],
      "stepType": "SystemStep"
    },
    {
      "fields": [
        {
          "label": "Brutto",
          "name": "grossTotal"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "name": "freigabe_gf",
      "nextSteps": [
        {
          "color": "success",
          "label": "Freigeben",
          "step": "freigegeben"
        },
        {
          "color": "error",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "stepType": "UserStep"
    },
    {
      "action": "approve",
      "name": "freigegeben",
      "stepType": "SystemStep"
    },
    {
      "action": "reject",
      "name": "abgelehnt",
      "stepType": "SystemStep"
    }
  ],
  "trigger": {
    "nextStep": {
      "step": "pruefung"
    },
    "objectType": "transaction",
    "statuses": [
      "DRAFT"
    ],
    "transactionTypes": [
      "OFFER"
    ]
  }
}
```

### Responses

- **200** Saved (no body)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **422** The blueprint has problems and was not saved or switched on (`invalid_blueprint`, the problems in `details.problems`) (`application/json`)
- **500** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/workflow/v1/blueprints/angebot-pruefung' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"id":"angebot-pruefung","overviewField1":{"label":"Kunde","name":"partnerCompany"},"overviewField2":{"label":"Brutto","name":"grossTotal"},"steps":[{"allowInquiry":true,"fields":[{"label":"Angebotsnummer","name":"transactionNumber"},{"editable":true,"label":"Gültig bis","name":"typeData.validUntil"},{"editable":true,"label":"Menge","name":"lines.quantity"}],"group":"4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71","lines":{"allowDelete":false,"allowDuplicate":true},"name":"pruefung","nextSteps":[{"color":"primary","icon":"i-lucide-arrow-right","label":"Weiter","step":"betrag_pruefen"},{"color":"error","icon":"i-lucide-x-circle","label":"Ablehnen","step":"abgelehnt"}],"notifyAssigneesByEmail":true,"stepType":"UserStep"},{"action":"route","name":"betrag_pruefen","nextSteps":[{"condition":"grossTotal \u003e 1000","step":"freigabe_gf"},{"condition":"default","step":"freigegeben"}],"stepType":"SystemStep"},{"fields":[{"label":"Brutto","name":"grossTotal"}],"group":"4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71","name":"freigabe_gf","nextSteps":[{"color":"success","label":"Freigeben","step":"freigegeben"},{"color":"error","label":"Ablehnen","step":"abgelehnt"}],"stepType":"UserStep"},{"action":"approve","name":"freigegeben","stepType":"SystemStep"},{"action":"reject","name":"abgelehnt","stepType":"SystemStep"}],"trigger":{"nextStep":{"step":"pruefung"},"objectType":"transaction","statuses":["DRAFT"],"transactionTypes":["OFFER"]}}'
```
