Task-Publication Link Migration

This page covers migration notes for links between tasks and publications.

Use it together with Task-Publication Linking, the Elements, Element Tasks, and Element Publications migration pages.

Scope

Covered link surfaces:

Field Mapping

Root Element Writes

v1 root element payloads linked tasks and publications with a positional boolean array. Each value in publications[].assignments corresponded to the task at the same index in tasks[].

v2 removes that positional contract. Root element writes use explicit references:

v2 root element write
{
  "tasks": [
    {
      "localId": "task-reporter-1",
      "formatId": 18,
      "confirmationStatusCode": 0
    }
  ],
  "publications": [
    {
      "platformId": 101,
      "assignedTaskRefs": [
        {
          "localId": "task-reporter-1"
        }
      ]
    }
  ]
}

Migration pattern for root payloads:

1. Assign a stable request-local localId to each new task that needs to be linked.
2. Convert every true value in the old positional assignment array to an explicit assignment ref.
3. Use localId when the target task is created in the same request.
4. Use taskId when the target task already exists.
5. Send assignedTaskRefs: [] when a publication intentionally has no linked tasks.

For root POST and root PUT, each publication must declare assignedTaskRefs. For root PATCH, omitting assignedTaskRefs leaves the current links unchanged, while assignedTaskRefs: [] clears them.

Standalone Publication Writes

Standalone publication writes use persisted task IDs only:

v2 standalone publication write
{
  "assignedTaskIds": [3001, 3002]
}

Rules:

• assignedTaskIds accepts tasks that already exist under the same element.
• unknown task IDs or tasks from another element return 404 Not Found.
• on create, omitted, null, or [] creates the publication without task links.
• on patch, omitted leaves links unchanged, [] clears links, and null is invalid.
• localId is not accepted by standalone publication endpoints.

Standalone Task Writes

Standalone task create and patch do not link the task to publications.

To link a new standalone task to a publication:

Response Changes

v2 publication responses expose linked task IDs as assignedTaskIds.

Do not parse or expect assignments in v2 responses. The response IDs are persisted task IDs and are the values to use in later standalone publication writes.

Migration Checklist

• Replace positional assignments arrays with explicit assignedTaskRefs.
• Add request-local localId values for new tasks that must be linked in the same root request.
• Replace standalone assignedTasks with assignedTaskIds.
• Stop expecting task creation to assign the task to publications automatically.
• Stop parsing publications[].assignments from responses; parse assignedTaskIds.
• Verify PATCH behavior: omitted links stay unchanged, [] clears links, and null is invalid.