Improve docs for correlation key for message start event

docs/components/modeler/bpmn/message-events/message-events.md

@@ -14,16 +14,29 @@ A process can have one or more message start events (besides other types of star
 
 When a process is deployed, it creates a message subscription for each message start event. Message subscriptions of the previous version of the process (based on the BPMN process id) are closed.
 
+### Message correlation
+
 When the message subscription is created, a message can be correlated to the start event if the message name matches. On correlating the message, a new process instance is created and the corresponding message start event is activated.
 
 Messages are **not** correlated if they were published before the process was deployed or if a new version of the process is deployed without a proper start event.
 
-The `correlationKey` of a published message can be used to control the process instance creation. If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+The `correlationKey` of a published message can be used to control the process instance creation.
 
-When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (i.e. TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
+- If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+- When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (that is, TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
 
 If the `correlationKey` of a message is empty, it creates a new process instance and does not check if an instance is already active.
 
+:::note
+
+You do not specify a `correlationKey` for a message start event in the BPMN model when designing a process.
+
+- When an application sends a message that is caught by a message start event, the application can specify a `correlationKey` in the message.
+- If a message caught by a start event contains a `correlationKey` value, the created process is tagged with that `correlationKey` value.
+- Follow-up messages are then checked against this `correlationKey` value (that is, is there an active process instance that was started by a message with the same `correlationKey`?).
+
+:::
+
 ## Intermediate message catch events
 
 When an intermediate message catch event is entered, a corresponding message subscription is created. The process instance stops at this point and waits until the message is correlated. When a message is correlated, the catch event is completed and the process instance continues.

versioned_docs/version-1.3/components/modeler/bpmn/message-events/message-events.md

@@ -16,14 +16,29 @@ When a process is deployed, it creates a message subscription for each message s
 
 When the message subscription is created, a message can be correlated to the start event if the message name matches. On correlating the message, a new process instance is created and the corresponding message start event is activated.
 
+### Message correlation
+
+When the message subscription is created, a message can be correlated to the start event if the message name matches. On correlating the message, a new process instance is created and the corresponding message start event is activated.
+
 Messages are **not** correlated if they were published before the process was deployed or if a new version of the process is deployed without a proper start event.
 
-The `correlationKey` of a published message can be used to control the process instance creation. If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+The `correlationKey` of a published message can be used to control the process instance creation.
 
-When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (i.e. TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
+- If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+- When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (that is, TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
 
 If the `correlationKey` of a message is empty, it creates a new process instance and does not check if an instance is already active.
 
+:::note
+
+You do not specify a `correlationKey` for a message start event in the BPMN model when designing a process.
+
+- When an application sends a message that is caught by a message start event, the application can specify a `correlationKey` in the message.
+- If a message caught by a start event contains a `correlationKey` value, the created process is tagged with that `correlationKey` value.
+- Follow-up messages are then checked against this `correlationKey` value (that is, is there an active process instance that was started by a message with the same `correlationKey`?).
+
+:::
+
 ## Intermediate message catch events
 
 When an intermediate message catch event is entered, a corresponding message subscription is created. The process instance stops at this point and waits until the message is correlated. When a message is correlated, the catch event is completed and the process instance continues.

versioned_docs/version-8.2/components/modeler/bpmn/message-events/message-events.md

@@ -14,16 +14,29 @@ A process can have one or more message start events (besides other types of star
 
 When a process is deployed, it creates a message subscription for each message start event. Message subscriptions of the previous version of the process (based on the BPMN process id) are closed.
 
+### Message correlation
+
 When the message subscription is created, a message can be correlated to the start event if the message name matches. On correlating the message, a new process instance is created and the corresponding message start event is activated.
 
 Messages are **not** correlated if they were published before the process was deployed or if a new version of the process is deployed without a proper start event.
 
-The `correlationKey` of a published message can be used to control the process instance creation. If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created.
+The `correlationKey` of a published message can be used to control the process instance creation.
 
-When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (i.e. TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
+- If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+- When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (that is, TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
 
 If the `correlationKey` of a message is empty, it creates a new process instance and does not check if an instance is already active.
 
+:::note
+
+You do not specify a `correlationKey` for a message start event in the BPMN model when designing a process.
+
+- When an application sends a message that is caught by a message start event, the application can specify a `correlationKey` in the message.
+- If a message caught by a start event contains a `correlationKey` value, the created process is tagged with that `correlationKey` value.
+- Follow-up messages are then checked against this `correlationKey` value (that is, is there an active process instance that was started by a message with the same `correlationKey`?).
+
+:::
+
 ## Intermediate message catch events
 
 When an intermediate message catch event is entered, a corresponding message subscription is created. The process instance stops at this point and waits until the message is correlated. When a message is correlated, the catch event is completed and the process instance continues.

versioned_docs/version-8.3/components/modeler/bpmn/message-events/message-events.md

@@ -16,14 +16,29 @@ When a process is deployed, it creates a message subscription for each message s
 
 When the message subscription is created, a message can be correlated to the start event if the message name matches. On correlating the message, a new process instance is created and the corresponding message start event is activated.
 
+### Message correlation
+
+When the message subscription is created, a message can be correlated to the start event if the message name matches. On correlating the message, a new process instance is created and the corresponding message start event is activated.
+
 Messages are **not** correlated if they were published before the process was deployed or if a new version of the process is deployed without a proper start event.
 
-The `correlationKey` of a published message can be used to control the process instance creation. If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+The `correlationKey` of a published message can be used to control the process instance creation.
 
-When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (i.e. TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
+- If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+- When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (that is, TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
 
 If the `correlationKey` of a message is empty, it creates a new process instance and does not check if an instance is already active.
 
+:::note
+
+You do not specify a `correlationKey` for a message start event in the BPMN model when designing a process.
+
+- When an application sends a message that is caught by a message start event, the application can specify a `correlationKey` in the message.
+- If a message caught by a start event contains a `correlationKey` value, the created process is tagged with that `correlationKey` value.
+- Follow-up messages are then checked against this `correlationKey` value (that is, is there an active process instance that was started by a message with the same `correlationKey`?).
+
+:::
+
 ## Intermediate message catch events
 
 When an intermediate message catch event is entered, a corresponding message subscription is created. The process instance stops at this point and waits until the message is correlated. When a message is correlated, the catch event is completed and the process instance continues.

versioned_docs/version-8.4/components/modeler/bpmn/message-events/message-events.md

@@ -14,16 +14,29 @@ A process can have one or more message start events (besides other types of star
 
 When a process is deployed, it creates a message subscription for each message start event. Message subscriptions of the previous version of the process (based on the BPMN process id) are closed.
 
+### Message correlation
+
 When the message subscription is created, a message can be correlated to the start event if the message name matches. On correlating the message, a new process instance is created and the corresponding message start event is activated.
 
 Messages are **not** correlated if they were published before the process was deployed or if a new version of the process is deployed without a proper start event.
 
-The `correlationKey` of a published message can be used to control the process instance creation. If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+The `correlationKey` of a published message can be used to control the process instance creation.
 
-When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (i.e. TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
+- If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+- When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (that is, TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
 
 If the `correlationKey` of a message is empty, it creates a new process instance and does not check if an instance is already active.
 
+:::note
+
+You do not specify a `correlationKey` for a message start event in the BPMN model when designing a process.
+
+- When an application sends a message that is caught by a message start event, the application can specify a `correlationKey` in the message.
+- If a message caught by a start event contains a `correlationKey` value, the created process is tagged with that `correlationKey` value.
+- Follow-up messages are then checked against this `correlationKey` value (that is, is there an active process instance that was started by a message with the same `correlationKey`?).
+
+:::
+
 ## Intermediate message catch events
 
 When an intermediate message catch event is entered, a corresponding message subscription is created. The process instance stops at this point and waits until the message is correlated. When a message is correlated, the catch event is completed and the process instance continues.

versioned_docs/version-8.5/components/modeler/bpmn/message-events/message-events.md

@@ -14,16 +14,29 @@ A process can have one or more message start events (besides other types of star
 
 When a process is deployed, it creates a message subscription for each message start event. Message subscriptions of the previous version of the process (based on the BPMN process id) are closed.
 
+### Message correlation
+
 When the message subscription is created, a message can be correlated to the start event if the message name matches. On correlating the message, a new process instance is created and the corresponding message start event is activated.
 
 Messages are **not** correlated if they were published before the process was deployed or if a new version of the process is deployed without a proper start event.
 
-The `correlationKey` of a published message can be used to control the process instance creation. If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+The `correlationKey` of a published message can be used to control the process instance creation.
 
-When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (i.e. TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
+- If an instance of this process is active (independently from its version) and it was triggered by a message with the same `correlationKey`, the message is **not** correlated and no new instance is created. If the message has a time-to-live (TTL) > 0, it is buffered.
+- When the active process instance is completed or terminated and a message with the same `correlationKey` and a matching message name is buffered (that is, TTL > 0), this message is correlated and a new instance of the latest version of the process is created.
 
 If the `correlationKey` of a message is empty, it creates a new process instance and does not check if an instance is already active.
 
+:::note
+
+You do not specify a `correlationKey` for a message start event in the BPMN model when designing a process.
+
+- When an application sends a message that is caught by a message start event, the application can specify a `correlationKey` in the message.
+- If a message caught by a start event contains a `correlationKey` value, the created process is tagged with that `correlationKey` value.
+- Follow-up messages are then checked against this `correlationKey` value (that is, is there an active process instance that was started by a message with the same `correlationKey`?).
+
+:::
+
 ## Intermediate message catch events
 
 When an intermediate message catch event is entered, a corresponding message subscription is created. The process instance stops at this point and waits until the message is correlated. When a message is correlated, the catch event is completed and the process instance continues.