Business Key


Can someone clarify or point me to documentation on what a Business Key is and why you would use one? Thank you for any assistance.

Garth Gerstein


Hi Garth,

I like to think of the businessKey as the business user’s unique identifier for a process instance. Whilst the engine internals use processInstanceId, this is meaningless to the business user who can thus use something more meaningful.

For example, the businessKey could be the reference number on an application form, the policy number on an insurance policy, the customer number from a CRM record, a shipping tracking number.

I tend to think of a businessKey as a lot like a process variable with extra privileges. It tends to behave a lot like a process variable. It is part of the BPMN specification and hence it is provided for in the engine. It can enable some convenient and efficient functions, for example find by business key. Imagine a scenario where a customer rings a company to find where something is at, they quote their reference number (eg the business key), which enables easy retrieval of a process instance or instances associated with that key.

The value of the key can be anything you choose, eg from a 1 character code to a large string. Often the form of the key is determined by business context. Usually the business key tends to enable uniqueness.

In terms of usage, the most common usage with be using the business key value in a start process. Hence you will see reference to businessKey in the start process API and in the forms reference. Once set, the businesskey value is immutable for the life of the process. Hence you won’t find any update methods…




Very useful indeed! Up till now I stored it as a plain process variable.
However I use a database sequence while generating the key and as it looks like it can only be set in the start-form it will be quite a hassle to set it (I’ll need to create a REST service only to get a seq nr…)