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 tenantsteps(array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names anothername(string, required): Unique within the blueprint; referenced bynextSteps[].stepstepType(string, required):UserStep(a person decides) orSystemStep(the engine decides) (one ofUserStep,SystemStep)action(string): Outcome when the workflow ends after this step:approve→ APPROVED,reject→ REJECTED (German synonyms accepted), else COMPLETEDallowInquiry(boolean): The assignee may ask another person (inquiry)fields(array of Field): Fields shown in a user stepname(string, required): Trade field (GET /blueprints/fields),typeData.<key>,lines.<field>, or a workflow-local input fieldeditable(boolean): The user may change it; trade fields only if listed as editablelabel(string): Label shown in the steprequired(boolean): The user must fill it in to complete the stepvisible(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 fieldsallowDelete(boolean): The user may delete linesallowDuplicate(boolean): The user may duplicate lines
nextSteps(array of NextStep): Transitions: buttons of a user step, conditions of a system stepcolor(string): Button color of a user step transitioncondition(string): System steps: expr condition, ordefaulticon(string): Button icon of a user step transitionlabel(string): Button label of a user step transitionstep(string): Name of the target step
notificationEmail(string): E-mail address notified about this stepnotifyAssigneesByEmail(boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps onlynotifyAssigneesByTeams(boolean): Notify the assignees in their personal Teams chat; user steps onlyteamsChannel(string): Comms webhook channel id notified about this step (seeGET /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 oftransaction)condition(string): Optional expr condition over the transaction data; false ends the start asTRIGGER_NOT_MATCHEDnextStep(NextStep)color(string): Button color of a user step transitioncondition(string): System steps: expr condition, ordefaulticon(string): Button icon of a user step transitionlabel(string): Button label of a user step transitionstep(string): Name of the target step
statuses(array of string): Trade statuses that start the workflowtransactionTypes(array of string): Trade transaction type codes (active in trade)
active(boolean): Only active blueprints start workflows; missing means activeinquiryWebhookUrl(string): Webhook (JSON) notified about inquiries and their answers;********keeps the stored URLoverviewField1(OverviewField)label(string): Column labelname(string): Transaction field shown in task lists
overviewField2(OverviewField)label(string): Column labelname(string): Transaction field shown in task lists
updatedAt(string (date-time), read-only): Last modification of the stored blueprintversion(integer (int64)): Informational; set to 1 when 0 on save
Example:
{
"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 indetails.problems) (application/json) - 500 Error (
application/json) - 503 Error (
application/json)
Example request
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"]}}'