docs: add migration guide for tasklist endpoints

[nathansandi]

Description

Provide the migration guide from Tasklist endpoint

• All task endpoints / Update as well the User Task input/output attributes
• Forms
• Variables

closes camunda/camunda#23740

When should this change go live?

This can be live as soon as it is approved, as it is related to the next version and the feature is already present in alphass

PR Checklist

• My changes are for an already released minor and are in /versioned_docs directory.
• My changes are for the next minor and are in /docs directory (aka /next/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

[github-actions]

👋 🤖 🤔 Hello, @tmetzke! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.6/.

• docs/apis-tools/migration-manuals/migrate-to-camunda-api.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[tmetzke]

I am not done yet, but here is my first take on the review (there simply are a lot of things to look at and compare 😅).

General

• The headings should probably be aligned with the ones users can find in the APIs currently, i.e. „Tasklist API" > "Entity (e.g., Task, Form, Variables)" > "Endpoint (e.g., Save draft variables, Search task variables, Search tasks, ...)“
• Also the endpoint names should be identical to the old ones in V1 so they can easily be found in the guide (we can even link from the V1 endpoints to the respective guide header later maybe, @christinaausley, in a note or something, saying "Updating to V2 API? See guide here!"?)
• The endpoints could be arranged in the same order they have in the respective V1 API spec OR alphabetically (or we align both of them to be alphabetically, migration guide and V1)
• I would suggest to list the change, e.g. "attribute removed|renamed|added|type changed", followed by bullet points explaining what to do and potentially a reasoning (e.g., when something was removed without replacement)

Get form endpoint

Improvements to the endpoint itself (should go into the OpenAPI spec as a follow-up)

•  bpmnId instead of title is worse than before, maybe we should stick with title in the V2 API - Rename bpmnId to formId on REST API form responses camunda#26911
•  The description of schema can be improved to The form content - fix: update get form schema descriptions camunda#26754
•  In general, the descriptions we have in the Tasklist V1 API are a lot more elaborate, let’s reuse them in V2 more - fix: update get form schema descriptions camunda#26754

PR suggestions (this PR here)

•  We should explain why the form endpoint was split up. Previously, you could find a form by its ID but that is not possible anymore

Search task variables endpoint

Improvements to the endpoint itself (should go into the OpenAPI spec as a follow-up)

•  variableNames should be added as a filter - feat: add variable name filter for the user task variable query camunda#26798

PR suggestions (this PR here)

•  Maybe link to unified response structure details from above if possible (not sure if this works because it's inside a tab item, @christinaausley?)
•  id renamed to variableKey (you currently say it's replaced but is that correct?)
•  isValueTruncated renamed to isTruncated
•  previewValue renamed to value (is that true, can you check, @nathansandi?)
•  value renamed to fullValue (is that true, can you check, @nathansandi?)
•  scopeKey added
•  processInstanceKey added
•  tenantId added

Search tasks

Improvements to the endpoint itself (should go into the OpenAPI spec as a follow-up)

•  followUpDate and dueDate are missing as filter options - feat: add support for followUpDate and dueDate filters camunda#26751

PR suggestions (this PR here)

•  More details on request structure changes
  •  pageSize now limit inside page
  •  searchAfterOrEqual and searchBeforeOrEqual removed
  •  searchAfter and searchBefore now inside page
•  taskVariables removed
  •  Split up into processInstanceVariables and localVariables
  •  We need to explain the reasoning for this
•  priority type changed
  • Can be an integer (equals filter semantics) or advanced search (slightly different to what you can do in V1, e.g., multiple conditions are possible now, operator names are slightly different)
•  When we added followUpDate and dueDate in the endpoint filters (which we should do), they still have to be used differently (advanced search using gte and lte instead of from and to)

I will continue this review tomorrow, feel free to start with adjustments and creating follow-up issues for the OpenAPI changes we should make. Thank you for all the work here so far, @nathansandi, I know it's a lot of content but it will majorly help users migrating properly ⭐

[nathansandi]

The follow-up issues were created:

camunda/camunda#26744
camunda/camunda#26745
camunda/camunda#26746

[akeller]

@nathansandi what's the status of this PR? Will it go out with alpha3? I see conflicting info in the PR description and discussions.

[tmetzke]

That's on me, sorry, forgot to update this one. It can go out whenever, doesn't have to be in alpha3. I'll rework this week to finish this as @nathansandi needed to help out somewhere else.

[github-actions]

🚧 The preview environment for the commit 136cf37 is being built. This usually takes 15-20 minutes.