camunda-docs reformat document handling content

Description

Closes https://github.com/camunda/camunda-docs/issues/5376 and https://github.com/camunda/camunda-docs/issues/5263.

When should this change go live?

[ ] This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
[ ] This is already available but undocumented and should be released within a week. (add available & undocumented label)
[x] This is on a specific schedule and the assignee will coordinate a release with the DevEx team. (create draft PR and/or add hold label)
[ ] This is part of a scheduled alpha or minor. (add alpha or minor label)
[ ] There is no urgency with this change (add low prio label)

PR Checklist

[x] My changes are for an upcoming minor release and:
- [x] are in the /docs directory (version 8.8).
- [x] are in the /versioned_docs/version-8.7/ directory (version 8.7).
[ ] My changes are for an already released minor and are in a /versioned_docs directory.

[x] I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:
- [x] Engineering team review
- [ ] Technical writer review via @camunda/tech-writers unless working with an embedded writer.

Mar 26 '25 16:03 christinaausley

:wave: :robot: :thinking: Hello, @volodymyr-melnykc! 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/components/concepts/document-handling.md
docs/components/modeler/forms/form-element-library/forms-element-library-document-preview.md
docs/components/modeler/forms/form-element-library/forms-element-library-filepicker.md
docs/guides/document-handling.md
docs/guides/img/document-preview-in-form.png
docs/guides/img/document-preview-settings.png
docs/guides/img/document-preview.png
docs/guides/img/form-email-example.png
docs/guides/img/form-palette.png
docs/guides/img/form-with-file-picker.png
docs/guides/img/inbound-webhook-connector-example.png
docs/guides/img/inbound-webhook-document.png
docs/guides/img/rest-outbound-document.png
docs/guides/img/task-with-document-preview-tasklist.png
docs/guides/img/task-with-file-picker-tasklist.png
docs/self-managed/concepts/document-handling/configuration.md
docs/self-managed/concepts/document-handling/overview.md

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

docs/guides/img/form-email-example.png
docs/guides/img/form-palette.png

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

versioned_docs/version-8.7/components/concepts/assets/task-with-file-picker-tasklist.png
versioned_docs/version-8.7/guides/img/form-email-example copy.png
versioned_docs/version-8.7/guides/img/form-palette copy.png

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

versioned_docs/version-8.7/components/concepts/assets/task-with-file-picker-tasklist.png
versioned_docs/version-8.7/components/concepts/document-handling.md
versioned_docs/version-8.7/components/modeler/forms/form-element-library/forms-element-library-document-preview.md
versioned_docs/version-8.7/components/modeler/forms/form-element-library/forms-element-library-filepicker.md
versioned_docs/version-8.7/guides/document-handling.md
versioned_docs/version-8.7/guides/img/document-preview-in-form.png
versioned_docs/version-8.7/guides/img/document-preview-settings.png
versioned_docs/version-8.7/guides/img/document-preview.png
versioned_docs/version-8.7/guides/img/form-email-example copy.png
versioned_docs/version-8.7/guides/img/form-palette copy.png
versioned_docs/version-8.7/guides/img/form-with-file-picker.png
versioned_docs/version-8.7/guides/img/inbound-webhook-connector-example.png
versioned_docs/version-8.7/guides/img/inbound-webhook-document.png
versioned_docs/version-8.7/guides/img/rest-outbound-document.png
versioned_docs/version-8.7/guides/img/task-with-document-preview-tasklist.png
versioned_docs/version-8.7/guides/img/task-with-file-picker-tasklist.png
versioned_docs/version-8.7/self-managed/concepts/document-handling/configuration.md
versioned_docs/version-8.7/self-managed/concepts/document-handling/overview.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.

Mar 26 '25 16:03 github-actions[bot]

@christinaausley I pushed a single commit because I was confused about the lowercase "gcp" and realized it was a value that could be provided to a specific variable/config.

However, now I look closer at the content I see:

DOCUMENT_DEFAULT_STORE_ID=inmemory

This has me wondering if the value is inmemory or in-memory. Can you check on this? If the product experience is inconsistent, please challenge that. If we can't fix it for the release, let's be extra clear when you need a dash.

A few comments about this content, in general, that you may want to handle in this PR:

Has this maybe evolved from a concepts page into something more guide or config oriented?
I see two personas (maybe more) that would be interesting in this content - someone using document handling and someone configuring the ability to use document handling. Would you agree?
Can you order the storage options in lists and table formats consistently? This could be default then ABC, for example.
We mix SaaS and SM config down the page. Can you make this clearer so we have a comprehensive SaaS and SM journey for document handling? This could be tabs, separate sections, separate pages, etc. (Feel free to discuss with the Docs Team so we can support you here.)
We mix non-production and production down the page. (This might be good to consult @conceptualshark on specifically.)
- C8Run is a non-production option for locally running C8.
- Consider splitting this between prod & non-prod
:::note GCP and AWS work with SaaS, and are supported for Self-Managed in production. Camunda does not provide local or in-memory for SaaS, but Self-Managed users may configure in-memory and local storage using Camunda 8 Run. :::

Mar 28 '25 19:03 akeller

@akeller This has me wondering if the value is inmemory or in-memory. Can you check on this? If the product experience is inconsistent, please challenge that. If we can't fix it for the release, let's be extra clear when you need a dash.

In-memory is the only wonky config type, so the hyphen is what really matters when setting this up:

CC @georgios-goulos and @conceptualshark, as we recently discussed this here.

Has this maybe evolved from a concepts page into something more guide or config oriented? We mix SaaS and SM config down the page. Can you make this clearer so we have a comprehensive SaaS and SM journey for document handling?

Summary incoming, but I have adjusted the structure according to this 👍

We mix non-production and production down the page. (This might be good to consult @conceptualshark on specifically.) C8Run is a non-production option for locally running C8. Consider splitting this between prod & non-prod

Still to-do on new config page.

Can you order the storage options in lists and table formats consistently? This could be default then ABC, for example.

Still to-do on new config page.

Mar 31 '25 18:03 christinaausley

@akeller @marcosgvieira @volodymyr-melnykc @georgios-goulos

You can preview these recent changes via the deploy label, but a few updates based on the feedback above:

I have create a space for a document handling guide, split into SaaS and SM versions.
We still have the document handling overview in the Concepts section, but this is now SaaS-specific. I have created another document handling section in the Self-Managed docs, within its Concepts section.
The SM document handling content now has an overview, and a separate config page.

I need help with the following:

The new guide needs to be updated -- can someone please review the content we have in the SaaS portion, and incorporate the empty fields (user task forms, start forms)? We will also need to create the SM portion of the guide.

Who is best to work with on this so we can tidy this content prior to the minor next week? I am also happy to work with a SaaS and SM delegate together, but will leave it up to you. Copying this into the team Slack channel as well.

Note that this is currently only in the 8.8 docs. Once this PR is complete, I will backport to 8.7.

Mar 31 '25 19:03 christinaausley

Hi folks -- as I am sure you have seen, we have a large quantity of docs feedback to sift through and act on. Not all of this can be resolved prior to the minor next week, but can be immediately acted on to provide a deliverable before the minor, with additional deliverables in the upcoming alphas. Here is my documentation update:

Docs update

Referencing this PR, and as mentioned above:

I have create a space for a document handling guide, split into SaaS and SM versions. @volodymyr-melnykc is going to provide details in this guide on the file[] format, start forms, user task forms, and displaying a document in a user task.
We still have the document handling overview in the Concepts section, but this is now SaaS-specific. I have created another document handling section in the Self-Managed docs, within its Concepts section.
The SM document handling content now has an overview, and a separate config page. I am going to update this PR today with the following config details:

I still need to loop IDP links into the existing docs -- to do before the minor.

Lingering issues for upcoming alphas (to create separate issues):

[x] Restructure guide to step through the following for SaaS and SM:

[x] Clearly document where storage settings should be configured for different environments (e.g., by deep-linking) and detail which components require this configuration and where to apply it.
[ ] Enhance editor UX and tooltips: Where possible, provide additional user interface guidance to highlight and clarify the data type being returned. Link to API definition or add a documentation space outlining the JSON format we use to represent documents.
[x] Tasklist and Zeebe config is needed and must be the same. See related comment below:

[x] (potentially) Create three separate pages for the config/storage section -- pages for Helm, C8Run, and Docker.
[ ] Provide further details on how clients for Connectors and Forms may specify a custom expiration date when uploading documents.

I will create separate issues for all of these today. With the current changes taking place in the docs update section above, I do not see the lingering issues as completable before the minor, but are still high priority and should take place over the next alpha or two.

This same update has been provided in the doc handling epic.

Apr 02 '25 14:04 christinaausley

Pushed the updates for the File picker and Document preview form components:

Updated the File picker form component with a description of how to reference uploaded files.
Described that the Document preview form component only accepts arrays.
Added a reference to the Document handling concept page.

Apr 02 '25 15:04 volodymyr-melnykc

@georgios-goulos Mind having a final look over the config additions to the Self-Managed section of the docs?

Apr 03 '25 19:04 christinaausley

@volodymyr-melnykc Really nice documentation 🎉

@marcosgvieira I think @volodymyr-melnykc and I are pretty much out of this PR -- we can either merge upon @georgios-goulos approval and you can create a follow up PR for any non-urgent deliverables we discussed in our meeting this week, or if you want to get additional changes in before the end of this week you can work in this PR. Whatever you prefer.

Apr 03 '25 21:04 christinaausley

The latest pushed updates include more guidance for Self-Managed storage configuration with more clarity on production vs non-production use. https://preview.docs.camunda.cloud/pr-5382/docs/8.7/self-managed/concepts/document-handling/document-handling-configuration/

Apr 04 '25 09:04 volodymyr-melnykc

@volodymyr-melnykc @marcosgvieira @esraagamal6 @georgios-goulos

We have accomplished all of the 8.7 deliverables I outlined in the docs update, plus some from @volodymyr-melnykc. Let's get this PR merged and launch any additional changes in a separate PR.

Ready for final review here. I will create a backlog issue for the remaining items outlined in lingering issues for upcoming alphas above.

Three final comments:

Per @mathieu-stennier, add a section around the known limitations around in-memory not working well when zeebe is used in combinaison with task list in SM. I will add a note for this in this PR.
Are there additional storage options we anticipate users asking for? If we have plans to add storage options, I may note that in the docs.
Not sure if anyone here can answer this, but if a user wants to use this with IDP, do they only need access to amazon textract, or additional config requirements?

Apr 04 '25 13:04 christinaausley

:broom: Preview environment for this PR has been torn down.

Apr 07 '25 12:04 github-actions[bot]