Naming Technically Relevant IDs

For executable flows, properly name all relevant technical element IDs in your BPMN diagrams. Focus on process, activity, message and error IDs, but also consider events as well as gateways and their sequence flows that carry conditional expressions. All of those elements will shop up in the Camunda database and you will also need to be able to interpret their meaning in the Camunda logs.
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 in Camunda’s REST communication, its history audit trail as well as its log files. Meaningful IDs will therefore help a lot for reading and easily interpreting such data later on.

Have a look on the IDs that are shown in the following example:

The following table provides you with a guideline that we would use in a context where developers are comfortable with Java and its typical camelCase naming style. Of course you may adapt these suggestions to typical naming conventions used in your programming context.

XML Attribute

Prefix or Suffix

Resulting ID

Tweet Approval

process/@id

Process

TweetApprovalProcess

New tweet written

startEvent/@id

StartEvent_

StartEvent_NewTweetWritten

message/@id

Message_

Message_NewTweetWritten

message/@name

Msg_

Msg_NewTweetWritten

Review tweet

userTask/@id

Task_

Task_ReviewTweet

Tweet approved?

exclusiveGateway/@id

Gateway_

Gateway_TweetApproved

No

sequenceFlow/@id

SequenceFlow_

SequenceFlow_TweetApprovedNo

Tweet duplicated

boundaryEvent/@id

BoundaryEvent_

BoundaryEvent_TweetDuplicated

error/@id

Error_

Error_TweetDuplicated

error/@errorCode

Err_

Err_TweetDuplicated

Tweet published

EndEvent_/@id

EndEvent_

EndEvent_TweetPublished

Editing IDs with the Camunda Modeler

We recommend to use the Camunda Modeler’s properties panel to edit technical identifiers and change them according to your naming conventions, like it is shown here for the process id:

camunda modeler properties panel

We do not recommend to edit identifiers in the XML directly, as it might accidently 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:

<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>

Element in the diagram interchange section (DI) reference identifiers from above. You have to adjust them accordingly! The 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.

Aligning the BPMN File Name With the Process ID

Note that we see it as 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.

aligning the bpmn file names

Generating ID Constants Classes

If you have lots of process, case and decision definitions with lots of IDs, consider to generate constant classes (via e.g. XSLT) directly from your BPMN or DMN XML files. This can e.g. be used for Test Cases and Data Accessors.

Bonus  Using a Modeler Plugin to Generate Meaningful IDs

You can consider creating your own modeler plugin to generate IDs that follow your naming conventions. An example of such a plugin can be found on GitHub. One could also use a similar plugin to implement checks if all relavant IDs follow certain naming conventions or if renaming was forgotten completely in some cases.

No guarantee - The statements made in this publication are recommendations based on the practical experience of the authors. They are not part of Camunda’s official product documentation. Camunda cannot accept any responsibility for the accuracy or timeliness of the statements made. If examples of source code are shown, a total absence of errors in the provided source code cannot be guaranteed. Liability for any damage resulting from the application of the recommendations presented here, is excluded.

Copyright © Camunda Services GmbH - All rights reserved. The disclosure of the information presented here is only permitted with written consent of Camunda Services GmbH.