# Task-Publication Link Migration

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

Use it together with [Task-Publication Linking](/docs/guides/editorial-workflows/task-publication-linking), the
[Elements](/docs/migration-from-v1/elements), [Element Tasks](/docs/migration-from-v1/tasks), and
[Element Publications](/docs/migration-from-v1/publications) migration pages.

## Scope

Covered link surfaces:

| Write flow | v2 link field |
|------------|---------------|
| Root element `POST`, `PUT`, `PATCH` | `publications[].assignedTaskRefs` |
| Standalone publication `POST`, `PATCH` | `assignedTaskIds` |
| Standalone task `POST`, `PATCH` | No publication-linking field |

## Field Mapping

| v1 usage pattern | v2 direction |
|------------------|--------------|
| Root `publications[].assignments` boolean array | Build `publications[].assignedTaskRefs` explicitly. |
| Standalone publication `assignedTasks` | Use `assignedTaskIds`. |
| Response `publications[].assignments` | Read `publications[].assignedTaskIds` from v2 responses. |
| Linking a new same-request task by position in `tasks[]` | Give the new task a `tasks[].localId` and reference it from `assignedTaskRefs[].localId`. |
| Linking an existing task | Use `assignedTaskRefs[].taskId` in root writes or `assignedTaskIds[]` in standalone publication writes. |

## 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:

```json title="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:

```json title="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:

<Stepper>

1. **create the task with `POST /api/v2/elements/{id}/tasks`.**

1. **read the persisted task ID from the returned parent element aggregate.**

1. **patch the publication with `assignedTaskIds`.**

</Stepper>

## 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.