From 715418abb226b4fc24e1b44ce0161be05ef99d96 Mon Sep 17 00:00:00 2001 From: Nathanyel Sandi Date: Thu, 12 Dec 2024 09:52:51 -0300 Subject: [PATCH 1/8] feat: include the output adjustment for user task search --- .../migration-manuals/migrate-to-camunda-api.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md index a9b4bf9626c..b0fac2cacea 100644 --- a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md +++ b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md @@ -100,7 +100,22 @@ The following conventions apply to all attributes: - +- 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 in order 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. From 29ca88fadf9debc183f8898a682a292fa3e3ef8e Mon Sep 17 00:00:00 2001 From: Nathanyel Sandi Date: Thu, 12 Dec 2024 10:02:01 -0300 Subject: [PATCH 2/8] feat: add user task endpoints and variables --- .../migrate-to-camunda-api.md | 290 +++++++++++++++++- 1 file changed, 280 insertions(+), 10 deletions(-) diff --git a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md index b0fac2cacea..b0ad62d0635 100644 --- a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md +++ b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md @@ -85,16 +85,25 @@ The following conventions apply to all attributes: -- 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 +- `includeVariables` removed + - **V2:** Variables not included by default; use `GET /v2/user-tasks/{key}/variables/search` to retrieve them. @@ -121,6 +130,267 @@ The following conventions apply to all attributes: +--- + +#### Get User Task + +- **V1 endpoint**: `GET /v1/tasks/{taskId}` +- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}` + + + + + +No input adjustments. + + + + + +Same output adjustments as **Search Tasks**. + + + + +--- + +#### Assign User Task + +- **V1 endpoint**: `PATCH /v1/tasks/{taskId}/assign` +- **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/assignment` + + + + + +- `allowOverrideAssignment` renamed to `allowOverride` +- `action` attribute added (defaults to `"assign"` if not provided) + + + + + +- V1 returned `200` with the User Task body +- V2 returns `204` (No Content) + + + + +--- + +#### Unassign User Task + +- **V1 endpoint**: `PATCH /v1/tasks/{taskId}/unassign` +- **V2 endpoint**: `DELETE /v2/user-tasks/{userTaskKey}/assignee` + + + + + +No input adjustments. + + + + + +- V1 returned `200` with the User Task body +- V2 returns `204` (No Content) + + + + +--- + +#### Complete User Task + +- **V1 endpoint**: `PATCH /v1/tasks/{taskId}/complete` +- **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/completion` + + + + + +- `action` attribute added (defaults to `"complete"` if not provided) + + + + + +- V1 returned `200` with the User Task body +- V2 returns `204` (No Content) + + + + +--- + +#### Save Task Draft Variables + +- **V1 endpoint**: `POST /v1/tasks/{taskId}/variables` +- **V2 endpoint**: Not supported + + + + + +Not applicable, as this feature is not supported in V2. + + + + + +Not applicable, as this feature is not supported in V2. + + + + +--- + +#### Update User Task + +- **V1 endpoint**: No direct V1 equivalent +- **V2 endpoint**: `PATCH /v2/user-tasks/{userTaskKey}` + + + + + +This is a new endpoint in V2, no V1 adjustments. + + + + + +Refer to the documentation for which attributes can be updated: +[Update User Task Documentation](https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/update-user-task/) + + + + +--- + +#### Search Variables by a Task + +- **V1 endpoint**: `POST /v1/tasks/{taskId}/variables/search` +- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}/variables` + + + + + +- `includeVariables` removed + - **V2:** Returns all variables associated with the user task. + + + + + +- Unified response structure. +- Variables associated with both process and user task scopes returned with `scopeKey`. +- `draft` removed (no draft variables). +- `id` replaced with `variableKey`. + + + + +### Forms + +#### Get Form + +- **V1 endpoint**: `GET /v1/forms/{formId}` +- **V2 endpoints**: + - `GET /v2/user-tasks/{userTaskKey}/form` + - `GET /v2/process-definitions/{processDefinitionKey}/form` + + + + + +- No input parameters in V2; all input attributes removed. + + + + + +- Embedded forms no longer returned; only supported for user tasks. +- `isDeleted` and `processDefinitionKey` removed. +- `id` renamed to `formKey`. +- `title` renamed to `bpmnId`. + + + + +### Variables + +#### Get Variable by ID + +- **V1 endpoint**: `GET /v1/variables/{variableId}` +- **V2 endpoint**: `POST /v2/variables/search` + + + + + +- Transitioned from GET to POST with filtering options. +- Unified request structure as above. + + + + + +- Unified response structure. +- Variables associated with both process and user task scopes returned with `scopeKey`. +- `draft` removed. +- `id` replaced with `variableKey`. + + + + From eec4177be9fefeb77e5ad0fc29c52438c618df15 Mon Sep 17 00:00:00 2001 From: Nathanyel Sandi Date: Thu, 12 Dec 2024 10:22:20 -0300 Subject: [PATCH 3/8] fix: remove relative path --- docs/apis-tools/migration-manuals/migrate-to-camunda-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md index b0ad62d0635..8497908127b 100644 --- a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md +++ b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md @@ -292,7 +292,7 @@ This is a new endpoint in V2, no V1 adjustments. Refer to the documentation for which attributes can be updated: -[Update User Task Documentation](https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/update-user-task/) +[Update User Task Documentation](docs/apis-tools/camunda-api-rest/specifications/update-user-task.api.mdx) From 7491b501035f13dbdab8b4506459a9c5983ea1e4 Mon Sep 17 00:00:00 2001 From: christinaausley <84338309+christinaausley@users.noreply.github.com> Date: Fri, 13 Dec 2024 10:33:20 -0700 Subject: [PATCH 4/8] grammatical adjustments --- .../migrate-to-camunda-api.md | 33 +++++++++---------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md index 8497908127b..a6edd811671 100644 --- a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md +++ b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md @@ -109,7 +109,7 @@ The following conventions apply to all attributes: -- Response structure changes as outlined in [General changes](#general-changes). +- 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`. @@ -120,7 +120,7 @@ The following conventions apply to all attributes: - `processDefinitionVersion` - The following attributes were removed: - `isFirst` - Used to identify if the task was the first in the process. - - `variables` - Use Search Variables in order to retrieve variables from a user task. + - `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. @@ -132,7 +132,7 @@ The following conventions apply to all attributes: --- -#### Get User Task +#### Get user task - **V1 endpoint**: `GET /v1/tasks/{taskId}` - **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}` @@ -152,14 +152,14 @@ No input adjustments. -Same output adjustments as **Search Tasks**. +Same output adjustments as **Search tasks**. --- -#### Assign User Task +#### Assign user task - **V1 endpoint**: `PATCH /v1/tasks/{taskId}/assign` - **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/assignment` @@ -180,7 +180,7 @@ Same output adjustments as **Search Tasks**. -- V1 returned `200` with the User Task body +- V1 returned `200` with the user task body - V2 returns `204` (No Content) @@ -188,7 +188,7 @@ Same output adjustments as **Search Tasks**. --- -#### Unassign User Task +#### Unassign user task - **V1 endpoint**: `PATCH /v1/tasks/{taskId}/unassign` - **V2 endpoint**: `DELETE /v2/user-tasks/{userTaskKey}/assignee` @@ -208,7 +208,7 @@ No input adjustments. -- V1 returned `200` with the User Task body +- V1 returned `200` with the user task body - V2 returns `204` (No Content) @@ -216,7 +216,7 @@ No input adjustments. --- -#### Complete User Task +#### Complete user task - **V1 endpoint**: `PATCH /v1/tasks/{taskId}/complete` - **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/completion` @@ -236,7 +236,7 @@ No input adjustments. -- V1 returned `200` with the User Task body +- V1 returned `200` with the user task body - V2 returns `204` (No Content) @@ -244,7 +244,7 @@ No input adjustments. --- -#### Save Task Draft Variables +#### Save task draft variables - **V1 endpoint**: `POST /v1/tasks/{taskId}/variables` - **V2 endpoint**: Not supported @@ -271,7 +271,7 @@ Not applicable, as this feature is not supported in V2. --- -#### Update User Task +#### Update user task - **V1 endpoint**: No direct V1 equivalent - **V2 endpoint**: `PATCH /v2/user-tasks/{userTaskKey}` @@ -291,15 +291,14 @@ This is a new endpoint in V2, no V1 adjustments. -Refer to the documentation for which attributes can be updated: -[Update User Task Documentation](docs/apis-tools/camunda-api-rest/specifications/update-user-task.api.mdx) +Refer to [the documentation](docs/apis-tools/camunda-api-rest/specifications/update-user-task.api.mdx) for which attributes can be updated: --- -#### Search Variables by a Task +#### Search variables by a task - **V1 endpoint**: `POST /v1/tasks/{taskId}/variables/search` - **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}/variables` @@ -330,7 +329,7 @@ Refer to the documentation for which attributes can be updated: ### Forms -#### Get Form +#### Get form - **V1 endpoint**: `GET /v1/forms/{formId}` - **V2 endpoints**: @@ -362,7 +361,7 @@ Refer to the documentation for which attributes can be updated: ### Variables -#### Get Variable by ID +#### Get variable by ID - **V1 endpoint**: `GET /v1/variables/{variableId}` - **V2 endpoint**: `POST /v2/variables/search` From cf9eb74327287b1ad561935b66814ea544026878 Mon Sep 17 00:00:00 2001 From: Tobias Metzke-Bernstein <586643+tmetzke@users.noreply.github.com> Date: Wed, 15 Jan 2025 13:56:43 +0100 Subject: [PATCH 5/8] refactor: reorder sections to adhere to original API order --- .../migrate-to-camunda-api.md | 242 +++++++----------- 1 file changed, 93 insertions(+), 149 deletions(-) diff --git a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md index a6edd811671..0c2854676f5 100644 --- a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md +++ b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md @@ -15,13 +15,11 @@ Camunda is streamlining the developer experience by creating a unified REST API The Administration and Web Modeler APIs will not be part of the Camunda 8 REST API, as these are platform APIs outside the cluster’s scope. ::: -Overtime, there will be a deprecation process for the individual component APIs starting with the former Operate and Tasklist APIs. These will continue to be in the product for the short-term, but it is recommended to begin the adoption of the new API. In addition, we will begin to deprecate several Zeebe gPRC endpoints as well. See [the official blog announcement](https://camunda.com/blog/2024/11/camunda-8-7-releasing-february-2025/). +Over time, there will be a deprecation process for the individual component APIs starting with the former Operate and Tasklist APIs. These will continue to be in the product for the short-term, but it is recommended to begin the adoption of the new API. In addition, we will begin to deprecate several Zeebe gPRC endpoints as well. See [the official blog announcement](https://camunda.com/blog/2024/11/camunda-8-7-releasing-february-2025/). -## Migrate endpoints +This guide considers all public endpoints existing in the component REST APIs and the Camunda 8 API counterparts or required migration changes. -This section considers all public endpoints existing in the component REST APIs and the Camunda 8 API counterparts or required migration changes. - -### General changes +## General endpoint changes -### Name changes and mappings +## Name changes and mappings The following conventions apply to all attributes: - `key` and `id` fields contain the entity as a prefix, for example, `userTaskKey`, `processDefinitionId`. This applies when referencing other resources like `formKey` in the user task entity, in the respective entities themselves like `userTaskKey` in the user task entity. - The full entity is the prefix to avoid confusion, for example `processDefinitionKey` instead of `processKey` (the latter could be interpreted as process instance or process definition). - Other attributes of entities themselves have no prefix to avoid clutter, for example version in the process definition entity. In other resources, they have to be referenced with a prefix, like `processDefinitionVersion` in the process instance entity. -- The `bpmnProcessId` is now called `processDefinitionId` to be easily relatable to the entity (process definition) and the accompanying `processDefinitionKey`. -- The `decisionKey` and `dmnDecisionKey` are now aligned to `decisionDefinitionKey`, the `decisionId` and `dmnDecisionId` to `decisionDefinitionId`. Similar to the `processDefinitionId`, those attributes are now related to the entity `decisionDefinition`. +- The `bpmnProcessId` is now called `processDefinitionId` to be easily relatable to the process definition entity, like the `processDefinitionKey`. +- The `decisionKey` and `dmnDecisionKey` are now aligned to `decisionDefinitionKey`, the `decisionId` and `dmnDecisionId` to `decisionDefinitionId`. Similar to the `processDefinitionId` being related to the process definition, those attributes are now easily relatable to the decision definition entity. -### Tasklist +## Tasklist API + +### Form + +#### Get a form + +- **V1 endpoint**: `GET /v1/forms/{formId}` +- **V2 endpoints**: + - `GET /v2/user-tasks/{userTaskKey}/form` + - `GET /v2/process-definitions/{processDefinitionKey}/form` + + + + + +- Forms are not directly fetched anymore, they are fetched by user task or process definition to get the respective form data +- All input attributes removed + + + + + +- Embedded forms no longer returned; only supported for user tasks. +- `isDeleted` and `processDefinitionKey` removed. +- `id` renamed to `formKey`. +- `title` renamed to `bpmnId`. + + + + +### Task + +#### Save task draft variables + +- **V1 endpoint**: `POST /v1/tasks/{taskId}/variables` +- **V2 endpoint**: This feature is not supported in V2 anymore. Use [setting variables][] as `local` to the user task's `elementInstanceKey` as a replacement. + +#### Search task variables + +- **V1 endpoint**: `POST /v1/tasks/{taskId}/variables/search` +- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}/variables` + + + + + +- `includeVariables` removed + - **V2:** Returns all variables associated with the user task. + + + + + +- Unified response structure. +- Variables associated with both process and user task scopes returned with `scopeKey`. +- `draft` removed (no draft variables). +- `id` replaced with `variableKey`. + + + #### Search tasks @@ -85,7 +152,7 @@ The following conventions apply to all attributes: -- Request structure changes as outlined above. +- Request structure changed as outlined in [general changes](). - `assigned (boolean)` removed - **V2:** Use `assignee` with `{ "$exists": false }` - `assignees (string[])` removed @@ -130,64 +197,6 @@ The following conventions apply to all attributes: ---- - -#### Get user task - -- **V1 endpoint**: `GET /v1/tasks/{taskId}` -- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}` - - - - - -No input adjustments. - - - - - -Same output adjustments as **Search tasks**. - - - - ---- - -#### Assign user task - -- **V1 endpoint**: `PATCH /v1/tasks/{taskId}/assign` -- **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/assignment` - - - - - -- `allowOverrideAssignment` renamed to `allowOverride` -- `action` attribute added (defaults to `"assign"` if not provided) - - - - - -- V1 returned `200` with the user task body -- V2 returns `204` (No Content) - - - - ---- - #### Unassign user task - **V1 endpoint**: `PATCH /v1/tasks/{taskId}/unassign` @@ -214,8 +223,6 @@ No input adjustments. ---- - #### Complete user task - **V1 endpoint**: `PATCH /v1/tasks/{taskId}/complete` @@ -242,68 +249,12 @@ No input adjustments. ---- - -#### Save task draft variables - -- **V1 endpoint**: `POST /v1/tasks/{taskId}/variables` -- **V2 endpoint**: Not supported - - - - - -Not applicable, as this feature is not supported in V2. - - - - - -Not applicable, as this feature is not supported in V2. - - - - ---- - -#### Update user task - -- **V1 endpoint**: No direct V1 equivalent -- **V2 endpoint**: `PATCH /v2/user-tasks/{userTaskKey}` - - - - - -This is a new endpoint in V2, no V1 adjustments. - - - - - -Refer to [the documentation](docs/apis-tools/camunda-api-rest/specifications/update-user-task.api.mdx) for which attributes can be updated: - - - - ---- - -#### Search variables by a task +#### Assign user task -- **V1 endpoint**: `POST /v1/tasks/{taskId}/variables/search` -- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}/variables` +- **V1 endpoint**: `PATCH /v1/tasks/{taskId}/assign` +- **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/assignment` - -- `includeVariables` removed - - **V2:** Returns all variables associated with the user task. +- `allowOverrideAssignment` renamed to `allowOverride` +- `action` attribute added (defaults to `"assign"` if not provided) -- Unified response structure. -- Variables associated with both process and user task scopes returned with `scopeKey`. -- `draft` removed (no draft variables). -- `id` replaced with `variableKey`. +- V1 returned `200` with the user task body +- V2 returns `204` (No Content) -### Forms - -#### Get form +#### Get user task -- **V1 endpoint**: `GET /v1/forms/{formId}` -- **V2 endpoints**: - - `GET /v2/user-tasks/{userTaskKey}/form` - - `GET /v2/process-definitions/{processDefinitionKey}/form` +- **V1 endpoint**: `GET /v1/tasks/{taskId}` +- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}` - -- No input parameters in V2; all input attributes removed. +No input adjustments. -- Embedded forms no longer returned; only supported for user tasks. -- `isDeleted` and `processDefinitionKey` removed. -- `id` renamed to `formKey`. -- `title` renamed to `bpmnId`. +Same output adjustments as **Search tasks**. @@ -395,3 +337,5 @@ Refer to [the documentation](docs/apis-tools/camunda-api-rest/specifications/upd + +[setting variables]: /apis-tools/camunda-api-rest/specifications/create-element-instance-variables.mdx From b1e58c0643280732aa6cb772a4bca9c6f4a99119 Mon Sep 17 00:00:00 2001 From: Tobias Metzke-Bernstein <586643+tmetzke@users.noreply.github.com> Date: Wed, 15 Jan 2025 14:28:22 +0100 Subject: [PATCH 6/8] docs: provide reasoning to "get form" endpoint changes --- .../migration-manuals/migrate-to-camunda-api.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md index 0c2854676f5..454e1ec2d67 100644 --- a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md +++ b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md @@ -94,10 +94,15 @@ The following conventions apply to all attributes: -- Embedded forms no longer returned; only supported for user tasks. -- `isDeleted` and `processDefinitionKey` removed. -- `id` renamed to `formKey`. -- `title` renamed to `bpmnId`. +- Embedded forms are no longer returned as Camunda user tasks don't support them. +- `isDeleted` removed + - This information is not served anymore. +- `processDefinitionKey` removed + - The form content is fetched per user task or process definition, so this relational information is not necessary in the context anymore. +- `id` renamed + - Use `formKey` as this refers to the unique system identifier of the form +- `title` renamed + - Use `formId` as this aligns better with the attribute defined in the form schema From 302aaaa8bf04ab13732d799d5e8456b136866f97 Mon Sep 17 00:00:00 2001 From: Tobias Metzke-Bernstein <586643+tmetzke@users.noreply.github.com> Date: Wed, 15 Jan 2025 15:55:37 +0100 Subject: [PATCH 7/8] docs: extend user task variable search changes --- .../migrate-to-camunda-api.md | 46 +++++++++++++------ 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md index 454e1ec2d67..b61ea62b2b0 100644 --- a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md +++ b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md @@ -87,8 +87,8 @@ The following conventions apply to all attributes: -- Forms are not directly fetched anymore, they are fetched by user task or process definition to get the respective form data -- All input attributes removed +- You cannot fetch forms directly anymore. Instead, fetch them by user task or process definition to get the respective form data. +- The respective endpoint only takes the key of the resource the form is related to as input parameter. @@ -96,13 +96,13 @@ The following conventions apply to all attributes: - Embedded forms are no longer returned as Camunda user tasks don't support them. - `isDeleted` removed - - This information is not served anymore. + - The endpoint does not serve this information anymore. - `processDefinitionKey` removed - - The form content is fetched per user task or process definition, so this relational information is not necessary in the context anymore. + - You can identify the related entity from the endpoint resource and the provided key parameter, the form response does not contain it additionally anymore. - `id` renamed - - Use `formKey` as this refers to the unique system identifier of the form + - Use `formKey` as this refers to the unique system identifier of the form. - `title` renamed - - Use `formId` as this aligns better with the attribute defined in the form schema + - Use `formId` as this aligns better with the attribute defined in the form schema. @@ -117,7 +117,7 @@ The following conventions apply to all attributes: #### Search task variables - **V1 endpoint**: `POST /v1/tasks/{taskId}/variables/search` -- **V2 endpoint**: `GET /v2/user-tasks/{userTaskKey}/variables` +- **V2 endpoint**: `POST /v2/user-tasks/{userTaskKey}/variables/search` +- Request structure changes as outlined in [general changes][]. +- `variableNames` renamed and type changed + - Use the `filter` object's `name`, either with a plain string for one exact match or with `{ "$in": [ "xyz", ... ]}`. - `includeVariables` removed - - **V2:** Returns all variables associated with the user task. + - The endpoint returns all variables associated with the user task. -- Unified response structure. -- Variables associated with both process and user task scopes returned with `scopeKey`. -- `draft` removed (no draft variables). -- `id` replaced with `variableKey`. +- Response structure changes as outlined in [general changes][]. +- `id` renamed + - User `variableKey` as this refers to the unique system identifier of the variable. +- `value` renamed + - Use `fullValue` as this represents the full variable value in case the `value` is only a preview due to size constraints. If the `value` is not a preview, the `fullValue` is empty. +- `previewValue` renamed + - Use `value` as this always represents the variable value. This can be a preview value due to size constraints. In that case, the `fullValue` contains the full variable value. +- `isValueTruncated` renamed + - Use `isTruncated` as a replacement +- `draft` removed + - Draft variables are not supported in V2 anymore, see also the [Save draft variables](#save-task-draft-variables) endpoint for further details. +- `scopeKey` added + - Variables belong to a specific scope, e.g., the process instance or the element instance of a user task. This value represents the scope the variables is related to. +- `processInstanceKey` added + - A variable belongs to process instance and this value represents the unique system identifier of that instance. +- `tenantId` added + - Variables can belong to a dedicated tenant and this value represents the one it belongs to. See [multi-tenancy][] for further details. @@ -157,7 +173,7 @@ The following conventions apply to all attributes: -- Request structure changed as outlined in [general changes](). +- Request structure changed as outlined in [general changes][]. - `assigned (boolean)` removed - **V2:** Use `assignee` with `{ "$exists": false }` - `assignees (string[])` removed @@ -181,7 +197,7 @@ The following conventions apply to all attributes: -- Response structure changes as outlined in [general changes](#general-changes). +- Response structure changes as outlined in [general changes][]. - The attribute `id` renamed to `userTaskKey`. - The attribute `taskDefinitionId` renamed to `elementId`. - The attribute `taskState` renamed to `state`. @@ -344,3 +360,5 @@ Same output adjustments as **Search tasks**. [setting variables]: /apis-tools/camunda-api-rest/specifications/create-element-instance-variables.mdx +[general changes]: #general-endpoint-changes +[multi-tenancy]: /self-managed/concepts/multi-tenancy.md From da6582eafa71796cc9f549111156ffb048b7f802 Mon Sep 17 00:00:00 2001 From: Tobias Metzke-Bernstein <586643+tmetzke@users.noreply.github.com> Date: Wed, 15 Jan 2025 16:47:04 +0100 Subject: [PATCH 8/8] docs: extend user task search changes --- .../migrate-to-camunda-api.md | 89 ++++++++++++------- 1 file changed, 56 insertions(+), 33 deletions(-) diff --git a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md index b61ea62b2b0..0865a441bc3 100644 --- a/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md +++ b/docs/apis-tools/migration-manuals/migrate-to-camunda-api.md @@ -140,7 +140,7 @@ The following conventions apply to all attributes: - Response structure changes as outlined in [general changes][]. - `id` renamed - - User `variableKey` as this refers to the unique system identifier of the variable. + - Use `variableKey` as this refers to the unique system identifier of the variable. - `value` renamed - Use `fullValue` as this represents the full variable value in case the `value` is only a preview due to size constraints. If the `value` is not a preview, the `fullValue` is empty. - `previewValue` renamed @@ -173,46 +173,69 @@ The following conventions apply to all attributes: -- Request structure changed as outlined in [general changes][]. -- `assigned (boolean)` removed - - **V2:** Use `assignee` with `{ "$exists": false }` -- `assignees (string[])` removed - - **V2:** Use `assignee` with `{ "$in": [ "xyz", ... ] }` +- Request structure changes as outlined in [general changes][]. + - The `pageSize` is the `limit` in the `page` object. + - The `searchAfter` and `searchBefore` are in the `page` object. + - The `searchAfterOrEqual` and `searchBeforeOrEqual` options have been removed. +- `assigned` removed + - Use `assignee` with `{ "$exists": false }`. Multiple filters can be combined in one attribute. +- `assignees` removed + - Use `assignee` with `{ "$in": [ "xyz", ... ] }`. Multiple filters can be combined in one attribute. - `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 + - Use `elementId` as this refers to the user-provided identifier of the BPMN element that created the user task. +- `candidateGroups` removed + - Use `candidateGroup` with `{ "$in": [ "xyz", ... ] }`. +- `candidateUsers` removed + - Use `candidateUser` with `{ "$in": [ "xyz", ... ] }`. +- `followUpDate` and `dueDate` filter options renamed + - Instead of `from` and `to`, use `$gte` and `$lte`. Additionally, you can use new comparison filter options. +- `taskVariables` split up and renamed + - You can define `localVariables` and `processInstanceVariables`. + - Local variables match the defined `name` and `value` and exist in the local scope of the BPMN element instance that created the user task. + - Process instance variables match the defined `name` and `value` and exist anywhere in the process instance that the user task belongs to. +- `tenantIds` removed + - Use `tenantId` with `{ "$in": [ "xyz", ... ] }`. - `includeVariables` removed - - **V2:** Variables not included by default; use `GET /v2/user-tasks/{key}/variables/search` to retrieve them. + - The endpoint does not return variables. Use the [Search task variables](#search-task-variables) endpoint to retrieve them. +- `implementation` removed + - The V2 API supports only Camunda user tasks. +- `priority` filter options renamed + - Filter object keys need a `$` prefix. Additionally, you can use new comparison filter options like `$neq`, `$exists`, and `$in`. +- `userTaskKey` added + - Filter for specific user tasks by their unique system identifiers. - Response structure changes as outlined in [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. + - `sortValues` do not exist per result item. Instead, the `page` object contains `firstSortValues` and `lastSortValues`, referring to the `sortValues` of the first and last item of the result set. +- `id` renamed + - Use `userTaskKey` as this refers to the unique system identifier of the user task. +- `taskDefinitionId` renamed + - Use `elementId`. +- `taskState` renamed + - Use `state`. +- `processName` renamed + - Use `processDefinitionId`. +- `customHeaders` added + - TBD +- `externalFormReference` added + - TBD +- `processDefinitionVersion` added + - TBD +- `isFirst` removed + - Used to identify if the task was the first in the process. +- `variables` removed + - Use search variables to retrieve variables from a user task. +- `implementation` removed + - On V2, only user tasks are returned. +- `isFormEmbedded` removed + - User tasks do not support embedded forms. +- `formVersion` removed + - For user tasks, use the `formKey` to retrieve form data. +- `formId` removed + - For user tasks, use the `formKey` to retrieve form data.