Skip to main content
Version: 1.3

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. Those elements can show up regularly (e.g. in your logs) and it makes things easier if you can interpret their meaning.

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.

Examine the IDs 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. You may adapt these suggestions to typical naming conventions used in your programming context.

XML AttributePrefix or SuffixResulting ID
1Tweet Approvalprocess/@idProcessTweetApprovalProcess
2New tweet writtenstartEvent/@idStartEvent_StartEvent_NewTweetWritten
3Review tweetuserTask/@idTask_Task_ReviewTweet
4Tweet approved?exclusiveGateway/@idGateway_Gateway_TweetApproved
6Tweet duplicatedboundaryEvent/@idBoundaryEvent_BoundaryEvent_TweetDuplicated
7Tweet publishedEndEvent_/@idEndEvent_EndEvent_TweetPublished

Editing IDs with Camunda Modeler

We recommend using 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:

Properties Panel

We especially do not recommend editing 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" />
<UserTask_ id="UserTask_ReviewTweet" name="Review tweet"></UserTask_> <!--3-->
<Gateway_ id="Gateway_TweetApproved" name="Tweet approved?"> <!--4-->
<SequenceFlow_ id="SequenceFlow_TweetApprovedNo" name="No"> <!--5-->
<BoundaryEvent_ id="BoundaryEvent_TweetDuplicated" name="Tweet duplicated"> <!--6-->
<Error_EventDefinition Error_Ref="Error_TweetDuplicated" />
<EndEvent_ id="EndEvent_TweetPublished" name="Tweet published"> <!--7-->

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

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.

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

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