Copy page

Editorial Workflows

Task-Publication Linking

This page explains how tasks and publications are linked, what happens by default, and when to use localId versus persisted task IDs.

Use it as narrative guidance. The API reference remains the source of truth for exact request and response contracts. For v1 field mapping, see Element Publications.

Default Behavior

Linking Modes

Use one of these two linking styles depending on the write flow.

Write flow	Assignment field	Which task identifiers are allowed	Typical use
Root element POST, PUT, PATCH	publications[].assignedTaskRefs	taskId for existing tasks, localId for new tasks created in the same request	Create or update one element aggregate with nested tasks and publications
Standalone publication POST, PATCH	assignedTaskIds	Persisted task IDs only	Add or update one publication under an existing element
Standalone task POST, PATCH	No publication-linking field	Not applicable	Create or update a task without changing publication links

Root Element Writes

Root element writes can create or mutate tasks and publications in one payload. That is the only place where localId is relevant.

Root POST /api/v2/elements

Each nested publication must declare assignedTaskRefs.

• Send assignedTaskRefs: [] to create the publication without linked tasks.
• Use taskId when the publication should point at an existing visible task.
• Use localId when the publication should point at a new task created in the same request.

Example:

Root POST with localId ref
{
  "tasks": [
    {
      "localId": "task-reporter-1",
      "statusId": 1,
      "formatId": 18,
      "confirmationStatusCode": 0,
      "user": {
        "id": 101
      }
    }
  ],
  "publications": [
    {
      "statusId": 41,
      "platformId": 101,
      "categoryId": 401,
      "typeId": 501,
      "assignedTaskRefs": [
        {
          "localId": "task-reporter-1"
        }
      ]
    }
  ]
}

Root PUT /api/v2/elements/{id}

Root PUT is a strict replacement flow for nested publications and their task links.

• Each publication in the payload must declare assignedTaskRefs.
• assignedTaskRefs: [] clears all task links for that publication.
• If a task is omitted from the root PUT payload, it can be removed as part of the full replace.
• After the request completes, the returned element body is the new source of truth.

Root PATCH /api/v2/elements/{id}

Root PATCH is partial and presence-aware.

• If a publication patch entry includes assignedTaskRefs, that publication's links are replaced with exactly the provided refs.
• assignedTaskRefs: [] clears the links for that publication.
• If assignedTaskRefs is omitted on a publication patch entry, the current links stay unchanged.
• assignedTaskRefs: null is invalid. Use [] to clear or omit the field to keep current links.

Standalone Publication Writes

Once an element already exists, publication-task linking usually moves to the standalone publication endpoints.

POST /api/v2/elements/{elementId}/publications

Use assignedTaskIds to attach already-persisted tasks.

• assignedTaskIds accepts only persisted task IDs that belong to the same element.
• If the request contains an unknown task ID or a task from another element, the API returns 404 Not Found.
• If assignedTaskIds is omitted, the new publication starts without linked tasks.

Example:

Standalone publication POST
{
  "statusId": 41,
  "platformId": 401,
  "categoryId": 421,
  "typeId": 431,
  "assignedTaskIds": [3001, 3002]
}

PATCH /api/v2/elements/{elementId}/publications/{publicationId}

Publication patch is also presence-aware.

• Send assignedTaskIds to replace the current linked task set.
• Unknown task IDs or task IDs from another element return 404 Not Found.
• Send assignedTaskIds: [] to clear all links.
• Omit assignedTaskIds to leave the current links unchanged.
• assignedTaskIds: null is invalid. Use [] to clear or omit the field to leave links unchanged.

Example:

Standalone publication PATCH
{
  "assignedTaskIds": [3001]
}

How localId Works

localId is a request-scoped temporary identifier for new tasks inside one root element write.

What it is for:

• Connecting tasks[].localId to publications[].assignedTaskRefs[].localId before the new task has a persisted ID.
• Building the initial task-publication graph in one root write request.

What it is not:

• Not a persisted task ID.
• Not reusable across requests.
• Not valid on standalone publication writes.

Rules:

• localId is only valid for new tasks in root element POST, PUT, and PATCH.
• localId values must be unique within the request.
• Each assignment ref must contain exactly one identifier: either taskId or a non-blank localId.
• If taskId is present, do not send localId at all, even as an empty string.
• assignedTaskRefs[].localId must match a task created in the same request.
• Existing tasks should be referenced by persisted taskId, not localId.

After The Write

After a successful root write:

• Read the persisted task IDs from the returned tasks collection.
• Treat those persisted IDs as the canonical identifiers for later requests.
• For later standalone publication writes, switch to assignedTaskIds.

In other words:

• Use localId only inside one root write payload.
• Use persisted task IDs everywhere after that request completes.

Common Mistakes

• Expecting a new task to be linked to every publication automatically.
• Expecting a new publication to pick up all current tasks automatically.
• Reusing a localId from an earlier request.
• Sending localId on a task that already has persisted id.
• Sending localId together with taskId, including an empty localId.
• Sending a blank localId without taskId.
• Using assignedTaskIds in root publication payloads instead of assignedTaskRefs.
• Using localId in standalone publication writes instead of persisted task IDs.