Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add migration guide for tasklist endpoints #4756

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
+294 −20
Open

docs: add migration guide for tasklist endpoints #4756

Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
715418a
feat: include the output adjustment for user task search
nathansandi Dec 12, 2024
29ca88f
feat: add user task endpoints and variables
nathansandi Dec 12, 2024
eec4177
fix: remove relative path
nathansandi Dec 12, 2024
7491b50
grammatical adjustments
christinaausley Dec 13, 2024
cf9eb74
refactor: reorder sections to adhere to original API order
tmetzke Jan 15, 2025
b1e58c0
docs: provide reasoning to "get form" endpoint changes
tmetzke Jan 15, 2025
302aaaa
docs: extend user task variable search changes
tmetzke Jan 15, 2025
da6582e
docs: extend user task search changes
tmetzke Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
306 changes: 295 additions & 11 deletions docs/apis-tools/migration-manuals/migrate-to-camunda-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,25 +85,309 @@ The following conventions apply to all attributes:

<TabItem value='input-adjustments'>

- Filter attribute `assigned (boolean)` removed
- Use filter attribute `assignee` with condition `{ "$exists": false }`
- Filter attribute `assignees (string[])` removed
- Use filter attribute `assignee` with condition `{ “$in”: [ “xyz”, ... ] }`
- Filter attribute `taskDefinitionId` renamed
- Use filter attribute `elementId`
- Filter attribute `candidateGroups (string[])` removed
- Use filter attribute `candidateGroup` with condition `{ “$in”: [ “xyz”, ... ] }`
- Filter attribute `candidateUsers (string[])` removed
- Use filter attribute `candidateUser` with condition `{ “$in”: [ “xyz”, ... ] }`
- Request structure changes as outlined above.
- `assigned (boolean)` removed
- **V2:** Use `assignee` with `{ "$exists": false }`
- `assignees (string[])` removed
- **V2:** Use `assignee` with `{ "$in": [ "xyz", ... ] }`
- `taskDefinitionId` renamed
- **V2:** Use `elementId`
- `candidateGroups (string[])` removed
- **V2:** Use `candidateGroup` with `{ "$in": [ "xyz", ... ] }`
- `taskVariables` renamed
- **V2:** Use `variables`
- `candidateUsers (string[])` removed
- **V2:** Use `candidateUser` with `{ "$in": [ "xyz", ... ] }`
- `tenantIds (string[])` removed
- **V2:** Use `tenantIds` with `{ "$in": [ "xyz", ... ] }`
- `implementation` removed
- **V2:** Only Camunda user tasks returned
tmetzke marked this conversation as resolved.
Show resolved Hide resolved
- `includeVariables` removed
- **V2:** Variables not included by default; use `GET /v2/user-tasks/{key}/variables/search` to retrieve them.

</TabItem>

<TabItem value='output-adjustments'>

<!--- TODO: insert output adjustments --->
- Response structure changes as outlined in [general changes](#general-changes).
- The attribute `id` renamed to `userTaskKey`.
- The attribute `taskDefinitionId` renamed to `elementId`.
- The attribute `taskState` renamed to `state`.
- The attribute `processName` renamed to `processDefinitionId`.
- The following attributes were added:
- `customHeaders`
- `externalFormReference`
- `processDefinitionVersion`
- The following attributes were removed:
- `isFirst` - Used to identify if the task was the first in the process.
- `variables` - Use search variables to retrieve variables from a user task.
- `implementation` - On V2, only user tasks are returned.
- `isFormEmbedded` - User tasks do not support embedded forms.
- `formVersion` - For user tasks, use the `formKey` to retrieve form data.
- `formId` - For user tasks, use the `formKey` to retrieve form data.

</TabItem>

</Tabs>

---

#### Get user task

- **V1 endpoint**: `GET /v1/tasks/{taskId}`
- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}`

<Tabs groupId="get-user-task" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

No input adjustments.

</TabItem>

<TabItem value='output-adjustments'>

Same output adjustments as **Search tasks**.

</TabItem>
</Tabs>

---

#### Assign user task

- **V1 endpoint**: `PATCH /v1/tasks/{taskId}/assign`
- **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/assignment`

<Tabs groupId="assign-user-task" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

- `allowOverrideAssignment` renamed to `allowOverride`
- `action` attribute added (defaults to `"assign"` if not provided)

</TabItem>

<TabItem value='output-adjustments'>

- V1 returned `200` with the user task body
- V2 returns `204` (No Content)

</TabItem>
</Tabs>

---

#### Unassign user task

- **V1 endpoint**: `PATCH /v1/tasks/{taskId}/unassign`
- **V2 endpoint**: `DELETE /v2/user-tasks/{userTaskKey}/assignee`

<Tabs groupId="unassign-user-task" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

No input adjustments.

</TabItem>

<TabItem value='output-adjustments'>

- V1 returned `200` with the user task body
- V2 returns `204` (No Content)

</TabItem>
</Tabs>

---

#### Complete user task

- **V1 endpoint**: `PATCH /v1/tasks/{taskId}/complete`
- **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/completion`

<Tabs groupId="complete-user-task" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

- `action` attribute added (defaults to `"complete"` if not provided)

</TabItem>

<TabItem value='output-adjustments'>

- V1 returned `200` with the user task body
- V2 returns `204` (No Content)

</TabItem>
</Tabs>

---

#### Save task draft variables

- **V1 endpoint**: `POST /v1/tasks/{taskId}/variables`
- **V2 endpoint**: Not supported

<Tabs groupId="save-task-draft-vars" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

Not applicable, as this feature is not supported in V2.

</TabItem>

<TabItem value='output-adjustments'>

Not applicable, as this feature is not supported in V2.

</TabItem>
</Tabs>

---

#### Update user task

- **V1 endpoint**: No direct V1 equivalent
- **V2 endpoint**: `PATCH /v2/user-tasks/{userTaskKey}`

<Tabs groupId="update-user-task" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

This is a new endpoint in V2, no V1 adjustments.

</TabItem>

<TabItem value='output-adjustments'>

Refer to [the documentation](docs/apis-tools/camunda-api-rest/specifications/update-user-task.api.mdx) for which attributes can be updated:

</TabItem>
</Tabs>

---

#### Search variables by a task

- **V1 endpoint**: `POST /v1/tasks/{taskId}/variables/search`
- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}/variables`

<Tabs groupId="search-vars-by-task" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

- `includeVariables` removed
- **V2:** Returns all variables associated with the user task.

</TabItem>

<TabItem value='output-adjustments'>

- Unified response structure.
- Variables associated with both process and user task scopes returned with `scopeKey`.
- `draft` removed (no draft variables).
- `id` replaced with `variableKey`.

</TabItem>
</Tabs>

### Forms

#### Get form

- **V1 endpoint**: `GET /v1/forms/{formId}`
- **V2 endpoints**:
- `GET /v2/user-tasks/{userTaskKey}/form`
- `GET /v2/process-definitions/{processDefinitionKey}/form`

<Tabs groupId="get-form" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

- No input parameters in V2; all input attributes removed.

</TabItem>

<TabItem value='output-adjustments'>

- Embedded forms no longer returned; only supported for user tasks.
- `isDeleted` and `processDefinitionKey` removed.
- `id` renamed to `formKey`.
- `title` renamed to `bpmnId`.

</TabItem>
</Tabs>

### Variables

#### Get variable by ID

- **V1 endpoint**: `GET /v1/variables/{variableId}`
- **V2 endpoint**: `POST /v2/variables/search`

<Tabs groupId="get-variable-by-id" defaultValue="input-adjustments" queryString values={
[
{label: 'Input adjustments', value: 'input-adjustments'},
{label: 'Output adjustments', value: 'output-adjustments'},
]
}>

<TabItem value='input-adjustments'>

- Transitioned from GET to POST with filtering options.
- Unified request structure as above.

</TabItem>

<TabItem value='output-adjustments'>

- Unified response structure.
- Variables associated with both process and user task scopes returned with `scopeKey`.
- `draft` removed.
- `id` replaced with `variableKey`.

</TabItem>
</Tabs>

<!--- TODO: insert output adjustments --->
Expand Down
Loading