Fire system action by name

Fire a default system action by name on a target contentlet.

Returns a map of the resultant contentlet, with an additional AUTO_ASSIGN_WORKFLOW property, which can be referenced by delegate services that handle automatically assigning workflow schemes to content with none.

Use PUT for a single contentlet. This path also accepts POST, but that is a different operation that fires over multiple contentlets and returns a different envelope (entity.results[], a list). Sending a single-contentlet body via POST will not return the created contentlet's identifier where you expect it, even though the record may still be (half-)created by the content type's default workflow — a common silent trap. For one item, always use PUT.

Request body — wrap field values in a contentlet key:

{
  "contentlet": {
    "contentType": "<variable-or-inode>",
    "title": "My New Item",
    "...": "other field values"
  }
}

Field keys inside contentlet are the content type's field variable names (e.g., title, body, image). Unknown field names are silently dropped (a typo like titel will be ignored and may surface as a misleading 'title is required' error). Radio/Select/Checkbox values are not validated against the field's values list — out-of-range values are accepted as-is. Always verify spelling against fields[].variable from GET /api/v1/contenttype/id/{idOrVar}.

Validation error response shape:

{
  "entity": "",
  "errors": [{ "errorCode": "required", "fieldName": "image", "message": "The field Image is required." }],
  "i18nMessagesMap": {}, "messages": [], "pagination": null, "permissions": []
}

errorCode values: required, unknown. fieldName is the field variable for field-specific errors, or null for content-level errors. Note: when the content type is not found, message returns the raw translation key Workflow-does-not-exists-content-type instead of translated text.

Binary and image fields — These fields cannot receive raw file data or asset paths in the JSON body. Use one of the patterns below.

Pattern A — single-use file (works for all binary/image fields):

1. POST /api/v1/temp (multipart file part) OR POST /api/v1/temp/byUrl (JSON {"remoteUrl":"https://..."}) → use tempFiles[0].id (e.g. "temp_5311313004") as the field value.
2. Pass that ID in the contentlet body: {"contentlet": {"contentType": "ResortActivities", "image": "temp_5311313004", ...}}.

Pattern B — reusable shared asset (ImmutableImageField only):

1. Upload via /temp, create a dotAsset contentlet: PUT .../fire/PUBLISH with {"contentlet": {"contentType": "dotAsset", "asset": "temp_<id>"}}.
2. Use the returned dotAsset identifier as the field value on any ImmutableImageField.

Find a field's clazz by calling GET /api/v1/contenttype/id/{idOrVar} and reading fields[].clazz.

⚠️ Known issue: Firing PUBLISH on an archived contentlet (archived: true) does not validate the archived state and can produce an inconsistent live: true, archived: true tri-state. Always fire UNARCHIVE before PUBLISH on archived content.

⚠️ Multi-scheme content types: When a content type has multiple workflow schemes attached, firing a system action only initializes the contentlet into the scheme whose systemActionMappings entry resolved the fire. Other attached schemes will not have a task for that contentlet, and firing their actions later will fail with 'Workflow Action is not available in the Workflow Step the content is currently in.' To exercise actions in those other schemes, fire by action ID via PUT /api/v1/workflow/actions/{actionId}/fire using an action mapped to the desired scheme.

When chaining workflow actions or reading state back immediately after firing, pass indexPolicy=WAIT_FOR on each call. The default DEFER is asynchronous and can return stale index reads for several seconds, which can mimic server-side state bugs. For isolated one-off fires where nothing reads the result, leave the default.

Block Editor (Story Block) fields: send the value as a Markdown or HTML string — you do not need to hand-author the underlying ProseMirror/JSON document. dotCMS converts it to the Block Editor (ProseMirror JSON) structure automatically on save, so the field reads back as structured content with no editor round-trip required. A value that is already a valid Tiptap/ProseMirror JSON document is detected and stored unchanged. Example: "body": "## Intro\n\nHello **world**.".

Rich blocks in Markdown: blocks that plain Markdown cannot express are written as fenced code blocks whose info string is a dotcms-* label and whose body is a small JSON object. Example — embed a contentlet:

dotcms-content\n{"identifier": "<contentlet-id>", "languageId": 1}\n

Supported labels and payload fields (bold = required):

• dotcms-content → embedded contentlet: identifier, languageId (default 1). The server rebuilds the full embed data from the identifier on every read.
• dotcms-image → dotCMS-bound or decorated image: identifier or src; optional alt, title, href, target, textWrap, textAlign, languageId. Plain external images need no fence — standard  works.
• dotcms-video → video: identifier or src; optional mimeType, width, height, languageId.
• dotcms-youtube → YouTube embed: src; optional start (seconds), width, height.
• dotcms-grid → layout grid: the verbatim gridBlock node JSON ({"type":"gridBlock","attrs":{"columns":[n,n]},"content":[…two gridColumn nodes…]}).
• dotcms-node → any other node type verbatim ({"type": "<nodeType>", …}) — the fallback for custom blocks.

Rich blocks in HTML: the same labels are namespaced custom elements. Scalar payloads ride as attributes with hyphenated names (HTML lowercases attribute names, so languageId is spelled language-id, mimeType is mime-type): <dotcms-content identifier="<contentlet-id>" language-id="1"></dotcms-content>. dotcms-ai, dotcms-grid and dotcms-node take the same JSON object as the element's text body instead (HTML-escape < and & inside JSON string values). Always write an explicit closing tag — HTML parsing ignores the / in <dotcms-video … /> and would swallow the content after it. Both carriers produce identical stored documents.

Block styling (e.g. text alignment) is set by an HTML comment on its own line immediately before the block it decorates, in Markdown and HTML alike: <!-- dotcms:attrs {"textAlign":"center"} -->.

A Markdown/HTML write fully replaces the stored document; when stored rich blocks are not carried over in the submitted value, the save still succeeds and an advisory warning listing the replaced blocks is returned in the response messages field — carry the blocks over as fences or elements to preserve them. An invalid payload degrades to an ordinary code block (or is dropped when it carries no text to keep), never an error.