Updating docs and adding a BPMN doc

docs/BPMN.adoc

@@ -0,0 +1,54 @@
+:figure-caption!:
+:source-highlighter: highlight.js
+:source-language: java
+:imagesdir: res
+:toc2:
+
+= BPMN
+
+== Models
+
+[cols="1, 3a, 3a", headers]
+|===
+||Strategic |Operational
+
+| Target | Business | Engine
+| Goal | Communicate | Execute
+
+| Type
+| Abstract:
+
+* This is a bird's eye view of the process
+* Compact, easy to read and understand
+* No complicated constructs footnote:[e.g. no need to close gateways]
+* Tasks are undefined
+* Lanes can be used to show responsibilities
+
+| Concrete:
+
+* This is an executable process
+* Every task is defined and bound to code if required
+* No Lanes
+
+|===
+
+Use both type of processes: strategic first to validate understanding and then operational for execution.
+
+== Events
+
+* Use the https://docs.camunda.io/docs/components/modeler/bpmn/error-events/[BPMN Error event] for business errors
+
+* Use None Intermediate events to model KPIs or milestones that can be tracked
+
+* Use multiple None End events to illustrate different outcomes to help with metrics collection
+
+* Use gateways to clarify the flow, a.k.a. explicit modeling footnote:[avoid implicit input XOR; avoid implicit output AND; use explicit OR gateway instead of conditional flow]
+* Use merging gateways to make the process more readable
+* Use synchronizing parallel gateways to avoid repeating tasks footnote:[or keeping the processing alive when it should be done]
+
+* Use separate gateways for merging and splitting
+
+== Resources
+
+. https://docs.camunda.io/docs/components/best-practices/best-practices-overview/[Camunda 8 Docs - Modeling Best Practices]
+. https://academy.camunda.com/page/bpmn[Camunda Academy: BPMN]

docs/Camunda.adoc

@@ -47,6 +47,10 @@ It is based on https://www.keycloak.org/[Keycloak].
 
 * In the Self-Managed deployment option, the Web Modeler is available for Enterprise customers
 
+=== Connectors
+
+* https://docs.camunda.io/docs/components/connectors/use-connectors/[Connectors] use https://docs.camunda.io/docs/components/console/manage-clusters/manage-secrets/[secrets] to avoid exposing sensitive information
+
 == Best Practices
 
 === Development
@@ -72,13 +76,15 @@ Access to Operate and Optimize is not needed for the workers.
 
 It should therefore have no dependency on any Camunda classes.
 
+* We will use the https://docs.camunda.io/docs/components/connectors/protocol/rest/[REST Connector] and Camunda https://docs.camunda.io/docs/components/console/manage-clusters/manage-secrets/[secrets] to communicate with our micro-services
+
 === Deployment
 
 === Modeler
 
 * Use the https://docs.camunda.io/docs/components/modeler/web-modeler/new-web-modeler/[Web Modeler] to take advantage of its collaboration features
 
-* Use the https://docs.camunda.io/docs/components/modeler/bpmn/error-events/[BPMN Error event] for business errors and https://docs.camunda.io/docs/components/concepts/incidents/[Camunda Incidents] for technical errors
+* Use https://docs.camunda.io/docs/components/concepts/incidents/[Camunda Incidents] for technical errors
 
 Do not model the retries of service tasks into the BPMN model as mentioned in https://camunda.com/blog/2021/04/where-is-the-retry-in-bpmn-20/[Where is the “retry” in BPMN 2.0?].
 
@@ -94,6 +100,8 @@ This helps in communicating with other stakeholders.
 
 * Use camel case for service tasks' task definition
 
+* Use the https://github.com/camunda/camunda-modeler-token-simulation-plugin[Token Simulation] plugin to make sure the process is correct
+
 === Tasklist
 
 * Use the Tasklist https://docs.camunda.io/docs/apis-tools/tasklist-api-rest/tasklist-api-rest-overview/[REST API] over the https://docs.camunda.io/docs/apis-tools/tasklist-api/tasklist-api-overview/[GraphQL API]