Introduction
Sequence codes generate persisted, tenant-scoped counter values that can be used to create unique, human-readable identifiers. They are commonly combined with type codes, dates, department codes, or other business values.
For example, a sequence value can be formatted as REQ-24-03-007 or SVC-REQ-ENG-2024-Mar-42.
When to use sequence codes
- Generate a unique reference number when an instance is created.
- Assign a formal identifier during a lifecycle transition, such as Submit.
- Add a running number to an identifier that also includes a year, month, type, or department.
Configure a sequence code
- In the Admin application, open Schema and select Sequence Codes.
- Select Create.
- Enter a unique Code Name.
- Configure the sequence:
- Prefix — optional text or Protrak expression placed before the number.
- Suffix — optional text or Protrak expression placed after the number.
- Start From — the first numeric value to issue.
- Digits — the width of the numeric portion when padding is enabled.
- Padding Required — adds leading zeroes to make the numeric portion match the configured digit count.
- Save the sequence code.
- To generate a Type's name or tracking ID automatically, open the Type configuration, enable Auto Generate Instance Name or Auto Generate Tracking Id, and select the sequence code in the corresponding field.
For example, configure prefix REQ-, start value 1, digits 3, and enable padding to generate values such as REQ-001, REQ-002, and REQ-003.
Prefix and suffix fields can use Protrak expressions to include instance attributes, related values, or dates. Select the information icon beside the code-name field in the editor for expression examples. A sequence code that uses @Relation navigation cannot be assigned as a Type's create-time name or tracking sequence code; use it from a program after the relationship is available instead.
Using sequence codes in programs
Inject ISequenceCodeService into the program and call GetNextValue with the configured sequence-code name:
public ISequenceCodeService SequenceCodeService { get; set; }
var sequence = SequenceCodeService.GetNextValue("REQUEST_SEQ");
var reference = $"REQ-{DateTime.Now:yy-MM}-{sequence.PadLeft(3, '0')}";
instance.SetTextAttributeValue("Name", reference);
The service returns the next counter value as a string. The counter is persisted and maintained separately for each tenant. Use PadLeft when the identifier requires a fixed-width numeric portion.
Applicable program types
| Program type | Typical use |
|---|---|
| Pre Create Trigger | Generate an instance name or custom ID before the instance is saved. |
| Promote Action Command | Generate a formal ID when an instance reaches a lifecycle state. |
Idempotency
Guard sequence generation when a program can run more than once. Check whether the target attribute already contains a generated identifier before requesting another value:
if (!string.IsNullOrEmpty(trackingId))
return new ProgramResult { IsSuccess = true };
This prevents duplicate identifiers when a transition or program is retried.
Common formats
| Format | Example | Parts |
|---|---|---|
TYPE-YY-MM-NNN | REQ-24-03-007 | Type prefix, two-digit year, two-digit month, padded sequence. |
PREFIX-TYPE-DEPT-YYYY-Mon-N | SVC-REQ-ENG-2024-Mar-42 | Prefixes, department code, year, month, and sequence. |
ID-YYYY-ORG-USER | ID-001-2024-ORGNAME-JOHN | Base ID, year, organization, and user components. |
Related guidance
- Sequence number program pattern — complete Pre Create and Promote Action examples.
- Rules — configure conditions that can control when related actions are available.