What are localCorrelationKeys and correlationKeys parameters of Correlate a Message REST API


I am trying to use REST API to correlate a message. I came across localCorrelationKeys and correlationKeys as a parameters. The description is not so clear.

Do these variables correlate to corresponding variables of the process instance receiving the message?

What happens if the corresponding variables are not present in the process instance? Is there any error thrown for this scenario?


The rest api doc for correlationkey says it correlates to ‚Äúprocess variables‚ÄĚ and localkey says it correlates with a ‚Äúlocal variables‚ÄĚ.

If the keys are not found then the correlation fails: which has a corresponding error in the API docs as response code 400

I have a process variable sub and when i pass following request data :
‚ÄúmessageName‚ÄĚ : ‚ÄúReceiveMessage‚ÄĚ,
‚ÄúbusinessKey‚ÄĚ : ‚Äútest1‚ÄĚ,
‚ÄúcorrelationKeys‚ÄĚ : {
‚Äúsub‚ÄĚ : {‚Äúvalue‚ÄĚ : ‚Äúvalue1‚ÄĚ, ‚Äútype‚ÄĚ: ‚ÄúString‚ÄĚ}


it is giving error : {
‚Äútype‚ÄĚ: ‚ÄúRestException‚ÄĚ,
‚Äúmessage‚ÄĚ: ‚Äúorg.camunda.bpm.engine.MismatchingMessageCorrelationException: Cannot correlate message ‚ÄėReceiveMessage‚Äô: No process definition or execution matches the parameters‚ÄĚ

Instead, if i send the same variable as ‚ÄúprocessVariables‚ÄĚ , it is overriding the already existing process variable.

So , why is this behavior?

if you are using processVariables as a property then you are injecting the ‚Äúsub‚ÄĚ variable into the correlated process. processVariables is not for correlation, it‚Äôs for injecting variables.

Can you show a screenshot of Cockpit showing a process that is waiting for the ‚ÄúReceiveMessage‚ÄĚ with the ‚Äúsub‚ÄĚ variable as a process variable?

Hi @StephenOTT ,

Please find screenshots below:

1.process instance waiting to receive message ‚ÄúReceiveMessage‚ÄĚ with a process variable ‚Äúsub‚ÄĚ of type string, value ‚Äúsindhu‚ÄĚ.

2.Its business key is ‚Äútest‚ÄĚ as shown below:

  1. Sending request using REST API with ‚ÄúcorrelationKeys‚ÄĚ parameter and variable as sub and with new value ‚Äúnew‚ÄĚ.

this is giving error.

  1. Sending request using ‚ÄúprocessVariables‚ÄĚ parameter and variable sub with value as ‚Äúnew‚ÄĚ

This request is success and process variable sub value is changed to ‚Äúnew‚ÄĚ

you likely have a typo somewhere.

See below a fully working flow with the same configs are you show:

test-message.bpmn (3.0 KB)

1 Like

Hi @StephenOTT,

I have tested ‚ÄúcorrelationKeys‚ÄĚ parameter by giving same value of process variable . I was previously trying with new value. It was not working. Now , its working when am using value which is available in process instance. Its working.

So , basically the behavior here is, if we use ‚ÄúcorrelationKeys‚ÄĚ parameter, the variable name and value are matched. if it is matching, it correlates message to that particular catching event.

Where as, if we use parameter ‚ÄúProcessVariables‚ÄĚ , if variable is not existing as process variable, it is injected. If existing, it is overriden.

I was trying to send new variables using correlation keys parameter.So , looks like correlationKeys parameter is to match with the catching message event, where as ‚Äúprocessvariables‚ÄĚ parameter modifies the data.