Improve UX for HTTL mandatory for C7

[toco-cam]

Problem you would like to solve

The current user experience around ensuring HTTL is set does not suit all user profiles. Users with a HTTL set as a Global Engine Flag are confused about the default values and the error warning.

Proposed solution

• No default values are displayed in Modeler for HTTL (CMMN, DMN, BPMN):
  • Do not provide default HTTL configuration for Camunda 7 diagrams #4150
• Modeler displays an info with the suggestion to set the HTTL to 180 days as a starting point, with a link to the linting hints (in the docs) which explains why HTTL is necessary and how to set an engine HTTL
  • feat(platform): report informative message on HTTP missing bpmnlint-plugin-camunda-compat#160
  • feat(platform): make HTTL an info hint linting#100
• For Power Users (With engine configuration) the Modeler provides a disable-httl-hint flag to disable the info for users with HTTL configured on the engine)
  • feat: allow to disable HTTL hint via flag #4151
• HTTL section in properties panel provides additional context:
  • Httl user hint bpmn-io/dmn-js-properties-panel#82
  • feat(properties/HistoryCleanupProps): Add user document hint for hist… bpmn-io/bpmn-js-properties-panel#1028
• Desktop Modeler integration
  • Add BPMN properties panel Camunda 7 platform HTTL hint  #4157
  • Bump modeling dependencies #4154
• Document HTTL required in modeling guidance and link from there to other parts of the documentation
  • https://github.com/camunda/camunda-docs-modeler-screenshots/pull/81
  • https://github.com/camunda/camunda-docs-modeler-screenshots/pull/80
  • fix: correct modeling-guidance image paths camunda-docs#3385
  • Add history-time-to-live modeling guidance camunda-docs#3324
  • feat(components/modeler): document disable-httl-hint flag camunda-docs#3387
  • feat(components/modeler): document default-httl flag camunda-docs#3393
• (Optional) Users can configure a default HTTL to use for new diagrams in the modeler
  • feat(client): Ability to set a default history time to live via flags… #4147
  • feat(platform): rename flag to default-httl #4162

We use the following link to external documentation: https://docs.camunda.org/manual/latest/user-guide/process-engine/history/.

Alternatives considered

Yes

Additional context

No response

[nikku]

@toco-cam Thanks for opening this issue.

Let's get the documentation that is supposed to be linked in place. We can then go ahead to implement this fairly swiftly.

[toco-cam]

@nikku can you share the link to the docs page again please.

[nikku]

We feature modeling guidance here.

[prajwolbhandari1]

Let me work on it.

[prajwolbhandari1]

@toco-cam @nikku

Did we decide on this solution?

On the proposed solution above:

1. No default values are displayed in Modeler for HTTL (CMMN, DMN, BPMN)
   -- no default values.

2. Modeler displays an info with the suggestion to set the HTTL to 180 days as a starting point, with a link to the linting hints (in the docs) which explains why HTTL is necessary and how to set an engine HTTL
   -- what exactly does it mean by 180 days as a starting point? Since you suggested no default values in Add a stripped down menu #1.
   -- docs hints this link -> https://docs.camunda.org/manual/7.20/update/minor/719-to-720/#enforce-history-time-to-live

3. For Power Users (With engine configuration) the Modeler provides a flag to disable the info for users with HTTL configured on the engine)
   -- which flag are you referring to? Can u please elaborate on this?

Also, are we going to use flags.json file to set historyTimeToLive value in modeler or just leaving empty with a linting doc link as mentioned above.

Attached: I made historyTimeToLive textfield as an optional. I will add linting hints - a doc link.

httlNotRequired_modeler.mov

[prajwolbhandari1]

@nikku @toco-cam Once we finalize with a solution. Can you please put my name on the ticket? I can work on this.

[prajwolbhandari1]

Here is the updated history time to live lint that points to the doc on BMPM side. Please clarify on the above questions.

lint.link.to.link.doc.mov

[prajwolbhandari1]

@toco-cam @nikku any thoughts?

[nikku]

@prajwolbhandari1 Thanks for your work on this. We'll only be able to pick this up starting from next week. If you want to you can already open a PR in the mean time.

Validation for HTTL being missing must be updated via bpmnlint-plugin-camunda-compat. Thanks!

[prajwolbhandari1]

@nikku thank you for your reply.

We are able to get rid of the validation updating bpmnlint-plugin-camunda-compat (Opening a PR soon) but we have few questions on the proposed solution that I posted above. Do you mind looking at it (few posts above)?

[prajwolbhandari1]

@nikku @toco-cam can you guys please help me understand the proposed solution? My question is above.

Also, are you sure we don't want #3869 as an option? It will help to set default value in modeler. I can see it will solve few use cases.

[nikku]

@prajwolbhandari1 Not sure which question you refer to. The only one I found was this one:

For Power Users (With engine configuration) the Modeler provides a flag to disable the info for users with HTTL configured on the engine)

-- which flag are you referring to? Can u please elaborate on this?

We are going to introduce a flag, controlled via flags.json or command line to opt-out of the HTTL hint. I propose the name of the flag shall be disable-httl-hint. We'll not provide a default value via that flag, as either the user shall explicitly set the HTTL or the engine mandates the HTTL to be used.

[prajwolbhandari1]

@nikku appreciate it!

Does it make sense to put user hint as 'Set Time to Live as 180. <Link for docs>' ?
<Link for docs> -> https://docs.camunda.org/manual/7.20/update/minor/719-to-720/#enforce-history-time-to-live

[prajwolbhandari1]

I am working on with the team to raise a PR that we worked on so far. Raising the PR soon tomorrow or day after.

[nikku]

@toco-cam We could consider to address this along with #4120.

[prajwolbhandari1]

@nikku @toco-cam I also see the similar message in cmmn deployments if I try to deploy a CMMN Diagram without filling "History cleanup".

[toco-cam]

@prajwolbhandari1 Thanks for your support!

No default values are displayed in Modeler for HTTL (CMMN, DMN, BPMN)
The target is to handle all HTTL models similarly.

The idea was not to add a link directly to the toolbar - but instead add a "Model guideline" to https://docs.camunda.io/docs/next/components/modeler/reference/modeling-guidance/ and add a link into the linking text.

[nikku]

We have an initial draft for the modeling guidance: camunda/camunda-docs#3324.

[nikku]

As a start we want to tackle BPMN. Later DMN and (unlikely but possible) CMMN would follow suite.

[nikku]

Documentation update is ready for review: camunda/camunda-docs#3324

[nikku]

Final batch of documentation updates incoming 🎉.

[prajwolbhandari1]

@prajwolbhandari1 Thanks again. You PRs helped a ton to drive this forward.

We're still in the process of clarifying two things:

• Improve UX for HTTL mandatory for C7 #4062 (comment)
• Link to documentation page, documenting HTTL and user options => Likely is going to be https://docs.camunda.org/manual/latest/user-guide/process-engine/history/ (to be created page).

Only then we'll be able to move forward.

@nikku @toco-cam what did we decide on this, are we going ahead and merge it? This will help us in our use case. #4147

[nikku]

@prajwolbhandari1 Why do you favor diagram configuration over engine configuration?

If you want to go ahead with this, then please updated it on top of the latest develop branch (were we added the disable-httl-hint flag). Your PR could be a cherry on top if we see that it could be valueable for a use case.

[prajwolbhandari1]

@nikku will do that and let you know.

[nikku]

@prajwolbhandari1 Why do you favor diagram configuration over engine configuration?

Please also allow us to learn about why you think this is a better approach, in your environment. This helps us evaluate how we further proceed.

[HarishMalavade]

@nikku in our organization our camunda set up is shared process engine and we have multiple product lines that have different requirements based on process they build. and each product line can have hundreds of process model include parent and call activities.
For Example our trade processes have requirement to retain history only for 30 days
Where as our Defined contribution processes have requirements to retain history for 180 days and some others beyond 80 days
Since all these processes are deployed to same engine(shared) and we cannot leverage one httl value on the engine side and at the same time we cannot have history retained forever for performance concerns.

We do give different version of desktop modelers to BPM developers across product lines with our custom elements template and settings like disabling cmmn, httl etc in a package that we give them.

the changes @prajwolbhandari1 made will allow us to enforce httl on the modeler side during design time (Catch on left)
We work for Fintech. Please request you if it does not impact anything else to merge code from @prajwolbhandari1 so we can benefit from this contribution.

[prajwolbhandari1]

@nikku just pushed the change #4147

[nikku]

default-httl flag is going to be available to customized the default history time to live value to be used for new diagrams.

[nikku]

Thanks @prajwolbhandari1, @HarishMalavade and anyone else who contributed to this discussion issue in a meaningful way ❤️.

This is scheduled for release with the next Desktop Modeler. I'm super happy how this turned out.

[prajwolbhandari1]

Thanks @nikku for all your help.