@bpmnkit/camunda-docspack 0.0.0

package/.llms/chunks/components.best-practices.modeling.modeling-with-situation-patterns.measuring-key-performance-indicators-kpis-option-1-showing-milestones.md

@@ -0,0 +1,42 @@
+# Modeling with situation patterns — Measuring key performance indicators (KPIs) — Option 1: Showing milestones
+
+Diagram (BPMN):
+  start "Insurance application received" → business rule task "Assess application risks" → exclusive gateway "Risk level?"
+    — [Low enough: =riskLevel = "green"] intermediate throw event "Application automatically assessed" → exclusive gateway → service task "Create insurance policy" → send task "Send insurance policy" → end "Insurance application accepted"
+    — [Too high: =riskLevel = "red"] intermediate throw event "Application automatically assessed" → exclusive gateway → service task "Create letter of rejection" → send task "Send letter of rejection" → end "Insurance application rejected"
+    — [Unsure: =riskLevel = "yellow"] user task "Assess application risk" → intermediate throw event "Application manually assessed" → exclusive gateway "Risk level?"
+      — [Low enough: =riskLevel = "low"] (back to exclusive gateway)
+      — [Too high: =riskLevel = "high"] (back to exclusive gateway)
+
+**(1)**
+
+First, we assess the application risk based on a set of automatically evaluable rules.
+
+**(2)**
+
+We can then determine whether the automated rules already came to a (positive or negative) conclusion or not. If the rules led to an unsure result, a human must assess the application risk.
+
+**(3)**
+
+We use explicit intermediate events to make perfectly clear that we are interested in the applications which never see a human...
+
+**(4)**
+
+...and be able to compare that to the applications which needed to be assessed manually, because the automatic assessment failed to determine a clear result.
+
+**(5)**
+
+We also use end events, which are meaningful from a business perspective. We must know whether an application was either accepted...
+
+**(6)**
+
+...or rejected.
+
+By means of that process model, we can now let Camunda count the applications which were accepted and declined. We know how many and which instances we needed to review manually, and can therefore also narrow down our _accpeted/declined statistics_ to those manual cases.
+
+Furthermore, we will be able to measure the _handling time_ needed for the user task; for example, by measuring the time needed from claiming the task to completing it. The customer will need to wait a _cycle time_ from start to end events, and these statistics, for example, could be limited to the manually assessed applications and will then also include any idle periods in the process.
+
+*By comparing the economic _value_ of manually assessed insurance policies to the *effort\* (handling time) we invest into them, we will also be able to learn whether we focus our manual work on the meaningful cases and eventually improve upon the automatically evaluated assessment rules.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/modeling-with-situation-patterns

package/.llms/chunks/components.best-practices.modeling.modeling-with-situation-patterns.measuring-key-performance-indicators-kpis-option-2-emphasizing-process-phases.md

@@ -0,0 +1,18 @@
+# Modeling with situation patterns — Measuring key performance indicators (KPIs) — Option 2: Emphasizing process phases
+
+As an alternative or supplement to using events, you might also use subprocesses to emphasize certain phases in your process.
+
+Diagram (BPMN):
+  start "Insurance application received" → business rule task "Assess application risks" → exclusive gateway "Risk level?"
+    — [Low enough: =riskLevel = "green"] intermediate throw event "Application automatically assessed" → exclusive gateway → service task "Create insurance policy" → send task "Send insurance policy" → end "Insurance application accepted"
+    — [Too high: =riskLevel = "red"] intermediate throw event "Application automatically assessed" → exclusive gateway → service task "Create letter of rejection" → send task "Send letter of rejection" → end "Insurance application rejected"
+    — [Unsure: =riskLevel = "yellow"] subprocess "Manual application assessment" → (back to exclusive gateway)
+
+**(1)**
+
+By introducing a separate embedded subprocess, we emphasize the _phase_ of manual application assessment, which is the critical one from an economic perspective.
+
+Note that this makes even more sense if multiple tasks are contained within one phase.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/modeling-with-situation-patterns

package/.llms/chunks/components.best-practices.modeling.modeling-with-situation-patterns.measuring-key-performance-indicators-kpis.md

@@ -0,0 +1,12 @@
+# Modeling with situation patterns — Measuring key performance indicators (KPIs)
+
+You want to measure specific aspects of your process execution performance along some indicators.
+
+**Example:** A software developer involved in introducing Camunda gets curious about the business: "How many applications do we accept or decline per month, and how many do we need to review manually? How many are later accepted and declined? How much time do we spend for those manual work cases, and how long does the customer have to wait for an answer? I mean...do we focus on the meaningful cases...?"
+
+When modeling a process, we should actually always add some information about important key performance indicators (KPIs) implicitly. For example, specifically [naming start and end events](https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements#naming-events) with the process state reached from a business perspective. Additionally, we might explicitly add additional business milestones or phases.
+
+While the following section concentrates on the aspects of modeling KPIs, you might want to learn more about using them for [reporting about processes](https://docs.camunda.io/docs/next/components/best-practices/operations/reporting-about-processes) from a more technical perspective. For example, when being faced with the task to actually retrieve and present Camunda's historical data collected on the way of execution.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/modeling-with-situation-patterns

package/.llms/chunks/components.best-practices.modeling.modeling-with-situation-patterns.processing-a-batch-of-objects.md

@@ -0,0 +1,51 @@
+# Modeling with situation patterns — Processing a batch of objects
+
+You need to process many objects at once, which were already created before one by one, or which were updated one by one to reach a certain status.
+
+We sometimes also call that pattern simply the **1-to-n problem**.
+
+**Example:** A lawyer explains to a new client the way he intends to bill him: "Of course, if you need advice, you can call me whenever you want! We will agree about any work that needs to be done and my assistant will track those services which are subject to a charge. Once a month mostly you will receive a neatly-structured invoice providing you with all the details!"
+
+### Using data stores and multi instance activities
+
+Diagram (BPMN):
+  start "Advice needed" → "Provide advice" → "Record billable hours" → end "Advice provided"
+
+Diagram (BPMN):
+  start "Monthly" → "Determine billable clients" → subprocess "Client Invoicing" → end "Billable Clients invoiced"
+  note: For every billable client
+
+**(1)**
+
+The client asks for advice whenever they need it. Note that we create one process instance per request for advice.
+
+**(2)**
+
+The lawyer makes sure to record the billable hours needed for the client.
+
+**(3)**
+
+As he does not directly inform anybody by doing this, but rather collects data, we show this with a data store representing the time sheet and a data association pointing in its direction - representing the write operation.
+
+**(4)**
+
+The assistant starts their invoicing process on a monthly basis. In other words, we create one process instance per monthly billing cycle.
+
+**(5)**
+
+As a first step, the assistant determines all the billable clients. This are the clients for which time sheet entries exist in the respective month. Note that we have _many_ legal advice instances who have a relationship to _one_ billing instance and that the connection is implicitly shown by the read operation on the current status of data in the time sheet.
+
+**(6)**
+
+Now that the assistant knows the billable clients, they can iterate through them and invoice all of them. We use a sequential multi-instance subprocess to illustrate that we need to do this for every billable client.
+
+**(7)**
+
+On the way, the assistant is also in charge of checking and correcting time sheet entries, illustrated with a parallel multi-instance task. Note that these time sheet entries (and hence task instances) relate here 1:1 to the instances of the lawyer's "legal consulting" process. In real life, the lawyer might have created several time sheet entries per legal advice process, but this does not change the logic of the assistant's process.
+
+**(8)**
+
+Once the client is invoiced, the assistant starts a "payment processing" instance per invoice, the details of which are not shown in this diagram. We can imagine that the assistant needs to be prepared to follow up with reminders until the client eventually pays the bill.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/modeling-with-situation-patterns

package/.llms/chunks/components.best-practices.modeling.modeling-with-situation-patterns.requiring-a-second-set-of-eyes-option-1-using-separate-tasks.md

@@ -0,0 +1,43 @@
+# Modeling with situation patterns — Requiring a second set of eyes — Option 1: Using separate tasks
+
+Diagram (BPMN):
+  start "Loan requested" → user task "Approve loan" → exclusive gateway "Loan approved?"
+    — [No: =not(approved)] exclusive gateway → end "Loan not approved"
+    — [Yes: =approved] user task "Approve loan" → exclusive gateway "Loan approved?"
+      — [Yes: =approved] end "Loan approved"
+      — [=not(approved)] (back to exclusive gateway)
+  note: Second set of eyes
+
+**(1)**
+
+A first approver looks at the loan and decides whether they approve. If they decide not to approve, we are done, but if the loan is approved...
+
+**(2)**
+
+...a second approver looks at the loan. If they also decide to approve, the loan is ultimately approved.
+
+**Evaluation:**
+
+- This solution _explicitly_ shows how the two steps of this approval are performed. Tasks are modeled separately, followed by gateways visualizing the decision making process.
+
+- Note that the approvers work in a _strictly sequential_ mode, which might be exactly what we need in case we want _minimization of effort_ and, for example, display the reasonings of the first approver for the second one. However, we also might prefer _maximization of speed_. If this is the case, observe solution [option 3 (multi-instance)](#option-3-using-a-multi-instance-task) further below.
+
+- The usage of separate tasks leads to _duplication_ and makes the model _larger_, even more so in case multiple steps of approvals need to be modeled.
+
+You might want to use that pattern when modeling the need for a _second set_ of eyes needed in _sequential_ order, therefore _minimizing effort_ needed by the participating approvers.
+
+While it is theoretically possible to model separate, explicit approval tasks in parallel, we do not recommend such patterns due to readability concerns.
+
+Diagram (BPMN):
+  start "Loan requested" → parallel gateway
+    — user task "Approve loan" → exclusive gateway "Loan approved?"
+      — [Yes: =approved] parallel gateway → end "Loan approved"
+      — [No: =not(approved)] exclusive gateway → end "Loan not approved"
+    — user task "Approve loan" → exclusive gateway "Loan approved?"
+      — [No: =not(approved)] (back to exclusive gateway)
+      — [Yes: =approved] (back to parallel gateway)
+
+As a better alternative when looking for _maximization of speed_, observe [option 3 (multi-instance)](#option-3-using-a-multi-instance-task) below.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/modeling-with-situation-patterns

package/.llms/chunks/components.best-practices.modeling.modeling-with-situation-patterns.requiring-a-second-set-of-eyes-option-2-using-a-loop.md

@@ -0,0 +1,29 @@
+# Modeling with situation patterns — Requiring a second set of eyes — Option 2: Using a loop
+
+Diagram (BPMN):
+  start "Loan requested" → user task "Approve loan" → exclusive gateway "Loan approved?"
+    — [No: =not(approved)] end "Loan not approved"
+    — [Yes: =approved] exclusive gateway "Another set of eyes necessary?"
+      — [No: =not(eyesNecessary)] end "Loan approved"
+      — [Yes: =eyesNecessary] (back to user task "Approve loan")
+
+**(1)**
+
+A first approver looks at the loan and decides if they approve. If they decide not to approve, we are done, but...
+
+**(2)**
+
+...if the loan is approved, we turn to a second approver to look at the loan. If they also decide to approve, the loan is ultimately approved.
+
+**Evaluation:**
+
+- This model is a more _compact_ modeling solution to the situation. If it comes to multiple sets of eyes needed, you will probably prefer such an approach to avoid huge diagrams.
+
+- Note that the approvers work in a _strictly sequential_ mode, which might be exactly what we need if we want _minimization of effort_ and, for example, display the reasonings of the first approver for the second one. However, we also might prefer _maximization of speed_. If this is the case, observe [option 3 (multi-instance)](#option-3-using-a-multi-instance-task) below.
+
+- The solution is _less explicit_. We could not choose to label the tasks with explicit references to a first and a second step of approval, as a single task is used for both approvals. The solution is _less readable_ for a less experienced reading public. For a fast understanding of the two steps needed for ultimate approval, this method of modeling is less suitable.
+
+You might want to use that pattern when modeling the need for _multiple sets_ of eyes needed in _sequential_ order, therefore _minimizing effort_ needed by the participating approvers.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/modeling-with-situation-patterns

package/.llms/chunks/components.best-practices.modeling.modeling-with-situation-patterns.requiring-a-second-set-of-eyes-option-3-using-a-multi-instance-task.md

@@ -0,0 +1,26 @@
+# Modeling with situation patterns — Requiring a second set of eyes — Option 3: Using a multi-instance task
+
+Diagram (BPMN):
+  start "Loan requested" → user task "Approve loan" → end "Loan approved"
+  note: For every approver
+
+**(1)**
+
+All the necessary approvers are immediately asked to look at the loan and decide by means of a multi-instance task. The tasks are completed with a positive approval. Once all positive approvals for all necessary approvers are made, the loan is ultimately approved.
+
+**(2)**
+
+If the loan is not approved by one of the approvers, a boundary message event is triggered, interrupting the multi-instance task and therefore removing all the tasks of all approvers who did not yet decide. The loan is then not approved.
+
+**Evaluation:**
+
+- This model is a very _compact_ modeling solution to the situation. It can also easily deal with multiple sets of eyes needed.
+
+- Note that the approvers work in a _parallel_ mode, which might be exactly what we need in case we want _maximization of speed_ and want the approvers to do their work independent from each other and uninfluenced by each other. However, we also might prefer _minimization of effort_. If this is the case, refer to [option 1 (separate tasks)](#option-1-using-separate-tasks) or [option 2 (loop)](#option-2-using-a-loop) above.
+
+- The solution is much _less explicit_ and _less readable_ for a less experienced reading public, because the way the boundary event interacts with a multi-instance task requires a profound understanding of BPMN. For communication purposes, this method of modeling is therefore typically less suitable.
+
+You might want to use that pattern when modeling the need for _two_ or _multiple sets_ of eyes needed in _parallel_ order, therefore _maximising speed_ for the overall approval process.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/modeling-with-situation-patterns

package/.llms/chunks/components.best-practices.modeling.modeling-with-situation-patterns.requiring-a-second-set-of-eyes.md

@@ -0,0 +1,14 @@
+# Modeling with situation patterns — Requiring a second set of eyes
+
+For a certain task - typically a critical one in terms of your business - you need the opinion, review, or approval of two different people.
+
+We sometimes also call that pattern the **four eyes principle**.
+
+**Example:** The manager of a small sized bank's lending department has a problem: "Over the last quarter, we lost €100,000 in unrecoverable medium-sized loans. Controlling now tells me that could probably have been easily avoided by more responsible decisions of our lending department staff! I want that every such decision is signed off by two people from now on."
+
+Modeling a process dealing with that requirement can be achieved easily, but the better solution also depends on whether you prefer overall speed over total effort.
+
+All of the following modeling patterns assume that the two or more tasks needed to ultimately approve the loan must not be completed by one and the same person. When executing such patterns, you must enforce that with the workflow engine.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/modeling-with-situation-patterns

package/.llms/chunks/components.best-practices.modeling.naming-bpmn-elements.helpful-practices.md

@@ -0,0 +1,10 @@
+# Naming BPMN elements — Helpful practices
+
+### Avoiding abbreviations
+
+Avoid using _abbreviations_ as they are not always clear to every reader. This is especially true for abbreviations which are specific to companies or departments. Try to avoid them completely.
+
+If you want to use an abbreviation in your model (to save space or sometimes even to improve understandability) make sure you explain the abbreviation in the model in brackets, by text annotations, or use an accessible glossary.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements

package/.llms/chunks/components.best-practices.modeling.naming-bpmn-elements.md

@@ -0,0 +1,11 @@
+# Naming BPMN elements
+
+Name all elements in your BPMN diagrams, like activities, events, and gateways, by focusing on the business perspective.
+
+Name all elements in your BPMN diagrams by focusing on the business perspective. For activities, use a verb to describe what to do. For events, describe in which (business) state the process or domain object is currently in. For (data-based) gateways, pose a question and describe the conditions under which the process moves on along the outgoing flows.
+
+
+## Essential practices
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements

package/.llms/chunks/components.best-practices.modeling.naming-bpmn-elements.naming-activities.md

@@ -0,0 +1,21 @@
+# Naming BPMN elements — Naming activities
+
+Name a _task_ using an object and a verb in the infinitive. By doing this, you consistently describe _what you do with an object_.
+
+Diagram (BPMN):
+  "Check invoice"
+  "Review draft"
+  "Announce job"
+
+Name a _subprocess_ (or _call activity_) by using an object and a (by convention _nominalized_) verb. Similar to tasks, you should always describe _what you do with an object_.
+
+Diagram (BPMN):
+  subprocess "Draft review"
+  subprocess "Invoice check"
+  subprocess "Job announcement"
+
+**Note**
+Avoid very broad and general verbs like "Handle invoice" or "Process order." Try to be more specific about what you do in your activity from a business perspective.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements

package/.llms/chunks/components.best-practices.modeling.naming-bpmn-elements.naming-events.md

@@ -0,0 +1,32 @@
+# Naming BPMN elements — Naming events
+
+Wherever possible, name an _event_ using an object and a verb reflecting a state. Always try to describe _which state an object is in_ when the process is about to leave the event.
+
+Diagram (BPMN):
+  start "Draft reviewed"
+
+This naming approach does not always work perfectly. In those cases, precisely describe the business semantics when the process is about to leave the event. The following names are also valid:
+
+Diagram (BPMN):
+  start "Draft to be reviewed"
+
+Be specific about the state you reached with your event from a business perspective. Often, you will reach "success" and "failure" like events from a business perspective:
+
+Diagram (BPMN):
+  start "Invoice to be checked" → "Check invoice" → exclusive gateway "Invoice correct?"
+    — [Yes: =correct] "Pay invoice" → end "Invoice paid"
+    — [No: =not(correct)] "Reject payment of invoice" → end "Invoice rejected"
+
+**(1)**
+
+"Invoice paid" better qualifies the "successful" business state than "Invoice processed" would...
+
+**(2)**
+
+...because in principle, you can call the failed state "Invoice processed", too, but the reader of the diagram is much better informed by calling it "Invoice rejected".
+
+**Note**
+Avoid very broad and general verbs like "Invoice processed" or "Order handled"!
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements

package/.llms/chunks/components.best-practices.modeling.naming-bpmn-elements.naming-gateways.md

@@ -0,0 +1,29 @@
+# Naming BPMN elements — Naming gateways
+
+Label a data-based _exclusive gateway_ with a question. Label the outgoing sequence flows with the conditions they are executed under. Formulate the conditions as answers to the question posed at the gateway.
+
+Diagram (BPMN):
+  start "Invoice to be checked" → "Check invoice" → exclusive gateway "Invoice correct?"
+    — [Yes: =correct] "Pay invoice" → end "Invoice paid"
+    — [No: =not(correct)] "Reject payment of invoice" → end "Invoice rejected"
+
+This naming approach does not always work for _inclusive gateways_, because the outgoing flows' conditions can be completely independent from each other. Still, use a question whenever possible.
+
+Diagram (BPMN):
+  start "11 am" → "Choose menu" → inclusive gateway "Selected courses?"
+    — [Starter: =starter] "Prepare starter" → inclusive gateway → "Have lunch" → end "Lunch finished"
+    — [Dessert: =dessert] "Prepare dessert" → (back to inclusive gateway)
+    — [Main: =main] "Prepare main course" → (back to inclusive gateway)
+
+If this is not possible, leave out the question completely but describe the conditions under which the outgoing paths are executed.
+
+Diagram (BPMN):
+  start "Order received" → "Check order" → inclusive gateway
+    — [Always: =true] "Package goods" → inclusive gateway → end "Shipment prepared"
+    — [Heavy good: =heavy_good] "Order pick-up service" → (back to inclusive gateway)
+    — [Insurance necessary: =insurance_necessary] "Effect an insurance" → (back to inclusive gateway)
+
+_Avoid naming event-based gateways_, but ensure you name their subsequent events. Also, avoid naming _parallel gateways_ and all forms of _joining gateways_. You don't need to specify anything about those gateways, as the flow semantics are always the same.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements

package/.llms/chunks/components.best-practices.modeling.naming-bpmn-elements.naming-processes.md

@@ -0,0 +1,18 @@
+# Naming BPMN elements — Naming processes
+
+A _pool_ should be given the same name as the process the pool contains using an object and a nominalized verb. Optionally, add the organizational role responsible for the process shown in the pool as a whole.
+
+Diagram (BPMN):
+  start "Dinner time" → "Prepare dinner" → end "Dinner prepared"
+
+If you have more than one lane in a pool, name each _lane_ using the organizational role or technical system responsible for carrying out the activities shown in the lane.
+
+Diagram (BPMN): Dinner preparation and intake
+  start "Dinner time" → "Prepare dinner" → "Have dinner" → end "Dinner finished"
+  lanes: Family member, Chef
+  note: Every family member
+
+Name a _diagram_ (file) with same name as the process shown in the diagram. In case of a collaboration diagram, use a name reflecting the end-to-end perspective shown in that diagram.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements

package/.llms/chunks/components.best-practices.modeling.naming-bpmn-elements.recommended-practices.md

@@ -0,0 +1,17 @@
+# Naming BPMN elements — Recommended practices
+
+### Using sentence case
+
+Use [sentence case](https://en.wiktionary.org/wiki/sentence_case) when naming BPMN symbols. This is standard capitalization of an English sentence, with the first letter uppercase and subsequent letters lowercase, with exceptions such as proper nouns or acronyms.
+
+Diagram (BPMN): Dinner preparation and intake
+  start "Dinner time" → "Prepare dinner" → "Have dinner" → end "Dinner finished"
+  lanes: Family member, Chef
+  note: Every family member
+
+### Avoiding technical terms
+
+Avoid using purely _technical terms_ when naming activities or other BPMN symbols, for example. These are not always clear to every reader. Completely avoid using names of coding artifacts like classes, methods, technical services, or purely technical systems.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-bpmn-elements

package/.llms/chunks/components.best-practices.modeling.naming-technically-relevant-ids.generating-id-constants-classes.md

@@ -0,0 +1,11 @@
+# Naming technically relevant IDs — Generating ID constants classes
+
+If you have lots of process, case, and decision definitions with lots of IDs, consider generating constant classes (e.g. via XSLT) directly from your BPMN or DMN XML files. For example, this can be used for testing.
+
+
+## Using a Camunda Modeler plugin to generate meaningful ids
+
+You can use [this modeler plugin community extension](https://github.com/camunda-community-hub/camunda-modeler-plugin-rename-technical-ids) to automatically convert your IDs to comply with our best practices. Of course, you could also use this as a basis to create your own modeler plugin to generate IDs that follow your custom naming conventions. Or, you could implement a similar plugin to implement checks if all relavant IDs follow your naming conventions.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-technically-relevant-ids

package/.llms/chunks/components.best-practices.modeling.naming-technically-relevant-ids.md

@@ -0,0 +1,13 @@
+# Naming technically relevant IDs
+
+For executable flows, properly name all relevant technical element IDs, like BPMN IDs, in your BPMN diagrams.
+
+For executable flows, properly name all relevant technical element IDs in your BPMN diagrams.
+
+**Note**
+Keep technical IDs and names short enough for the target environment. Most user-defined BPMN and DMN IDs, names, deployed resource names, and form IDs support up to 32,768 characters with Elasticsearch/OpenSearch-backed storage and 256 characters with RDBMS-backed storage. If you use RDBMS, or might migrate to it later, keep these values comfortably within the 256-character limit.
+
+Focus on process, activity, message, and error IDs, but also consider events as well as gateways and their sequence flows that carry conditional expressions. Those elements can show up regularly (e.g. in your logs) and it makes things easier if you can interpret their meaning.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-technically-relevant-ids

package/.llms/chunks/components.best-practices.modeling.naming-technically-relevant-ids.using-naming-conventions-for-bpmn-ids-aligning-the-bpmn-file-name-with-the-process-id.md

@@ -0,0 +1,8 @@
+# Naming technically relevant IDs — Using naming conventions for BPMN IDs — Aligning the BPMN file name with the process ID
+
+It is a good practice to _align_ the _file name_ of your BPMN models with the _process id_ of the executable process that is inside the file.
+
+![BPMN file name](naming-technically-relevant-ids-assets/aligning-the-bpmn-file-names.png)
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-technically-relevant-ids

package/.llms/chunks/components.best-practices.modeling.naming-technically-relevant-ids.using-naming-conventions-for-bpmn-ids-editing-ids-with-camunda-modeler.md

@@ -0,0 +1,45 @@
+# Naming technically relevant IDs — Using naming conventions for BPMN IDs — Editing IDs with Camunda Modeler
+
+We recommend using Camunda Modeler's properties panel on the right side of the screen to edit technical identifiers and change them according to your naming conventions, like it is shown here for the process ID:
+
+![Properties Panel](naming-technically-relevant-ids-assets/camunda-modeler-properties-panel.png)
+
+We especially do not recommend editing identifiers in the XML directly, as it might accidentally corrupt your BPMN file. You have to keep the identifiers in the section about the graphical layout (so called "DI" for diagram interchange) further down in sync with the execution semantics at the top of the XML.
+
+However, we include an XML example of all those identifiers mentioned for illustration:
+
+```xml
+<process id="TweetApprovalProcess" name="Tweet Approval"> <!--1-->
+  <StartEvent_ id="StartEvent_NewTweetWritten" name="New tweet written"> <!--2-->
+    <Message_EventDefinition Message_Ref="Message_NewTweetWritten" />
+  </StartEvent_>
+  <UserTask_ id="UserTask_ReviewTweet" name="Review tweet"></UserTask_> <!--3-->
+  <Gateway_ id="Gateway_TweetApproved" name="Tweet approved?"> <!--4-->
+  </Gateway_>
+  <SequenceFlow_ id="SequenceFlow_TweetApprovedNo" name="No"> <!--5-->
+  </SequenceFlow_>
+  <BoundaryEvent_ id="BoundaryEvent_TweetDuplicated" name="Tweet duplicated"> <!--6-->
+    <Error_EventDefinition Error_Ref="Error_TweetDuplicated" />
+  </BoundaryEvent_>
+  <EndEvent_ id="EndEvent_TweetPublished" name="Tweet published"> <!--7-->
+  </EndEvent_>
+</process>
+
+<Message_ id="Message_NewTweetWritten" name="Msg_NewTweetWritten" /> <!--2-->
+<Error_ id="Error_TweetDuplicated" name="Tweet duplicated" Error_Code="Err_TweetDuplicated" /> <!--6-->
+...
+ <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="TweetApprovalProcess">
+      <bpmndi:BPMNShape id="_BPMNShape_StartEvent__1" bpmnElement="StartEvent_NewTweetWritten"> <!--8-->
+        <dc:Bounds x="100" y="50" width="36" height="36" />
+      </bpmndi:BPMNShape>
+```
+
+**(8)**
+
+Elements in the diagram interchange section (DI) reference identifiers from above; you have to adjust them accordingly! Camunda Modeler takes care of this automatically.
+
+Changing IDs can potentially break your tests or even process logic if done at a late stage of development. Therefore, consider using meaningful IDs right from the beginning and perform the renaming as part of the modeling.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-technically-relevant-ids

package/.llms/chunks/components.best-practices.modeling.naming-technically-relevant-ids.using-naming-conventions-for-bpmn-ids.md

@@ -0,0 +1,31 @@
+# Naming technically relevant IDs — Using naming conventions for BPMN IDs
+
+Define developer-friendly and business-relevant IDs for the process itself, as well as all activities, messages, and errors. Also consider events, gateways, and the sequence flows that carry conditional expressions. Even though IDs are just identifiers, keep in mind that they will show up regularly on the technical level. Meaningful IDs will help a lot.
+
+One case where an ID is more than an identifier is an element inside an [ad-hoc sub-process](https://docs.camunda.io/docs/next/reference/glossary#ad-hoc-sub-process) that an [AI agent](https://docs.camunda.io/docs/next/reference/glossary#ai-agent) uses as a tool. There, the ID is the tool name passed to the model, and it directly affects which tool the model selects, so describe what the tool does rather than applying the type prefixes below. See [write a tool name and description](https://docs.camunda.io/docs/next/components/agentic-orchestration/add-tool-to-ai-agent#write-a-tool-name-and-description) for more details.
+
+Examine the IDs shown in the following example:
+
+Diagram (BPMN): Tweet Approval
+  start "New Tweet written" → user task "Review tweet" → exclusive gateway "Tweet approved?"
+    — [No: =not(approved)] service task "Send rejection notification" → end "Tweet rejected"
+    — [Yes: =approved] service task "Publish on Twitter" → end "Tweet published"
+
+The following table provides you with a guideline that we would use in a context where developers are comfortable with _Java_ and _PascalCase_ naming style. You may adapt these suggestions to typical naming conventions used in your programming context.
+
+|       |                   | XML Attribute        | Prefix or Suffix | Resulting ID                  |
+| ----- | ----------------- | -------------------- | ---------------- | ----------------------------- |
+| **1** | Tweet Approval    | process/@id          | Process          | TweetApprovalProcess          |
+| **2** | New tweet written | startEvent/@id       | StartEvent\_     | StartEvent_NewTweetWritten    |
+|       |                   | message/@id          | Message\_        | Message_NewTweetWritten       |
+|       |                   | message/@name        | Msg\_            | Msg_NewTweetWritten           |
+| **3** | Review tweet      | userTask/@id         | Task\_           | Task_ReviewTweet              |
+| **4** | Tweet approved?   | exclusiveGateway/@id | Gateway\_        | Gateway_TweetApproved         |
+| **5** | No                | sequenceFlow/@id     | SequenceFlow\_   | SequenceFlow_TweetApprovedNo  |
+| **6** | Tweet duplicated  | boundaryEvent/@id    | BoundaryEvent\_  | BoundaryEvent_TweetDuplicated |
+|       |                   | error/@id            | Error\_          | Error_TweetDuplicated         |
+|       |                   | error/@errorCode     | Err\_            | Err_TweetDuplicated           |
+| **7** | Tweet published   | EndEvent\_/@id       | EndEvent\_       | EndEvent_TweetPublished       |
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/modeling/naming-technically-relevant-ids

package/.llms/chunks/components.best-practices.operations.reporting-about-processes.connecting-custom-business-intelligence-systems-bi-data-warehouses-dwh-or-monitoring-solutions.md

@@ -0,0 +1,12 @@
+# Reporting about processes — Connecting custom business intelligence systems (BI), data warehouses (DWH), or monitoring solutions
+
+You might move data from the Camunda History to a decoupled system like a Business Intelligence (BI) solution, a Data Warehouse (DWH), some Data Lake, or an own monitoring solution, for example based on Prometheus.
+
+Leveraging typical BI system's **ETL** (extract, transform, and load) features allows you to optimize data structure for your reporting purposes (to _speed up_ report generation) or to combine generic process engine data with business entities (to allow for _more in-depth analysis_).
+
+To get the data into the BI system, leverage one of the mechanisms described above. Our recommendation generally is:
+
+- In SaaS, leverage the history API to regularly pull data, as custom exporters are not supported there.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/operations/reporting-about-processes

package/.llms/chunks/components.best-practices.operations.reporting-about-processes.history-architecture.md

@@ -0,0 +1,21 @@
+# Reporting about processes — History architecture
+
+It is useful to understand the architecture around history data in Camunda 8.
+
+**Caution: Camunda 7**
+Note that the history architecture is very different in Camunda 7.x, refer to [Camunda 7 User Guide](https://docs.camunda.org/manual/latest/user-guide/process-engine/history/).
+
+![History architecture](reporting-about-processes-assets/history-architecture.png)
+
+Camunda saves historical data not just when a process instance finishes, but on the go, while a process instance is active. By doing this, Camunda separates runtime data from history data. A growing history will not influence the runtime behavior, and you should never need to access runtime data for reporting purposes.
+
+Historical data can be leveraged via three possible mechanisms:
+
+- **Camunda tools**: Leverage Camunda Operate or Camunda Optimize. This is a very simple approach that works out-of-the-box and should satisfy many requirements already. Camunda Operate focuses on operational use cases ("Where is my process? Why did this fail?") whereas Camunda Optimize provides business intelligence about your processes. Optimize allows you to build reports and dashboards including setting alerts for thresholds. For processes containing AI agents, the [agentic control plane](https://docs.camunda.io/docs/next/components/optimize/userguide/agentic-control-plane) in Optimize adds agent-specific metrics such as token usage, reliability, and tool calls without additional setup.
+
+- **Query API**: Using the public API (currently under development), this has the advantage that you can make use of the history data within your own applications.
+
+- Pushing **events**: Pushing Camunda events by using [exporters](https://docs.camunda.io/docs/next/components/zeebe/technical-concepts/architecture#exporters). Note that you can only add own exporters in a Self-Managed setting, not in Camunda 8 SaaS. Exporters have the advantage that you can push the data into any infrastructure you have, and possibly even filter or enrich the data in that step.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/operations/reporting-about-processes

package/.llms/chunks/components.best-practices.operations.reporting-about-processes.md

@@ -0,0 +1,58 @@
+# Reporting about processes
+
+The Camunda engine automatically collects audit information about historical process or instances for users to leverage and generate relevant reports.
+
+The Camunda engine automatically collects audit information about historical process or decision instances. Leverage this data by generating and displaying business relevant reports. Add business relevant phases and milestones to your process models serving as a basis for key performance indicators (KPIs).
+
+
+## Modeling key performance indicators (KPIs)
+
+When modeling a process, you always add information about important key performance indicators implicitly; for example, by introducing **start and end events**.
+
+Additionally, you can explicitly add the following:
+
+- Meaningful additional business **milestones** by modeling **intermediate events**, for example. This might not have any execution semantics other than leaving a trace in the history of the workflow engine. The milestone is met as soon as the process has passed the event. Its status can therefore be **passed** or **not passed**.
+
+- Meaningful business **phases** by modeling things like (embedded) **subprocesses**. In contrast to a milestone, a phase's state can be **not entered**, currently **active**, or **passed**.
+
+Consider the following example - a "Tweet Approval Process" shows start and end events as well as **milestones**:
+
+Diagram (BPMN): TwitterReportingDemoProcess
+  start "New Tweet written" → user task "Review tweet" → exclusive gateway "Tweet approved?"
+    — [No: =not(approved)] exclusive gateway → service task "Send rejection notification" → end "Tweet not published"
+    — [Yes: =approved] intermediate throw event "Tweet approved" → service task "Publish on Twitter" → end "Tweet published"
+
+**(3)**
+
+After one business day, the reviewer is reminded to speed up - and such reviews are internally _marked_ by passing the end event 'Review done slowly'.
+
+**(4)**
+
+**Approved tweets** will pass the additional **intermediate event**. The **cycle time** up until that point is automatically captured too.
+
+**(5)**
+
+Furthermore, when tweets are successfully published, we are interested in the **ratio** of those tweets...
+
+**(6)**
+
+...when compared to tweets that do not get published. Therefore, we model _two different end events_ representing those two business end states of the process.
+
+**Note**
+Duplicate tweets will _not be published_ even though they have been _approved_ before. The more precisely we describe and _name_ the business semantics of events, the better our KPI's will reflect the reality we want to measure!
+
+When you do not (only) want to concentrate on milestones, but _phases_ in your process, model the phases as subprocesses:
+
+Diagram (BPMN): TwitterReportingDemoProcess
+  start "New Tweet written" → subprocess "Review" → subprocess "Publication" → end "Tweet processed"
+
+**(1)**
+
+The phase _Review_—modeled with a subprocess—will be active, while the human reviewer will need to find time to complete the task...
+
+**(2)**
+
+...whereas the phase _Publication_ will be completed automatically - hence process instances "remaining" there for longer than a few seconds will probably indicate ongoing problems with the uptime and reachability of the used services.
+
+---
+Source: https://docs.camunda.io/docs/next/components/best-practices/operations/reporting-about-processes