Skip to main content

Sequences

Introduction​

The Sequence editor allows you to create and manage sequence definitions. Sequences are used to generate sequential, formatted numbers that can be used in process instance names, case instance names, task names, and other places where unique, incrementing identifiers are needed.

A typical use case is generating business-friendly reference numbers such as INV-00001, CASE-00042, or TICKET-001234.

important

When using sequence generation, the generated sequence value is persisted across transactions. This means that if an exception occurs, the value that was used is lost and can no longer be generated again.

Creating a Sequence​

To create a new sequence model, navigate to the Other tab in Flowable Design and select the Sequence filter. Click the Create button to open the creation dialog.

Provide:

  • The display name of the sequence.
  • The sequence's unique key.
  • An optional description of the sequence.

After clicking Create new model, you are redirected to the sequence editor where you can configure the sequence properties.

Sequence Editor​

The Sequence editor is a form-based editor where you configure how the sequence generates values.

A sequence definition has the following properties:

PropertyDescription
Minimum digitsThe minimum number of digits that should be used for the sequence number. If the generated number has fewer digits, it will be left-padded with zeros. For example, if minimum digits is 5 and the generated number is 1, the sequence returns 00001.
PrefixA prefix that is prepended to the generated number. For example, setting the prefix to INV- produces values like INV-00001.
SuffixA suffix that is appended to the generated number. For example, setting the suffix to -EU produces values like 00001-EU.
StartThe first sequence number to be generated.
IncrementThe step by which the sequence is incremented. Must be a non-zero value. A positive value produces an ascending sequence, a negative value produces a descending sequence.
Max valueThe maximum value the sequence can reach. Must be larger than the start and min values.
Min valueThe minimum value the sequence can reach. Must be less than the start and max values.
Allow cycleWhether the sequence is allowed to cycle when its boundary is reached. An ascending sequence that reaches its maximum will restart from its minimum value. A descending sequence that reaches its minimum will restart from its maximum value. If cycling is not allowed and the sequence can no longer be incremented, an exception will be thrown.

Using Sequences​

Once a sequence definition is created and included in an app, there are several ways to use it:

Process and Case Sequences​

In the BPMN and CMMN editors, you can link a sequence model to a process or case. This generates a sequence value when a new process or case instance is started. The generated value is stored in a variable that can be referenced in instance name expressions or business key expressions.

Generate Sequence Task​

The BPMN and CMMN palettes include a Generate Sequence Task that can generate sequence values on demand during process or case execution. See the BPMN Generate Sequence Task and CMMN Generate Sequence Task for more details.

Sequence Expressions​

Sequence values can also be generated using expressions:

  • ${seq:next('mySequence')} - generates a sequence value using the sequence definition with the key mySequence
  • ${seq:next(mySequenceKey)} - generates a sequence value using the key stored in the variable mySequenceKey

Further Reading​