Skip to main content

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​

  1. In the Admin application, open Schema and select Sequence Codes.
  2. Select Create.
  3. Enter a unique Code Name.
  4. 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.
  5. Save the sequence code.
  6. 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 typeTypical use
Pre Create TriggerGenerate an instance name or custom ID before the instance is saved.
Promote Action CommandGenerate 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​

FormatExampleParts
TYPE-YY-MM-NNNREQ-24-03-007Type prefix, two-digit year, two-digit month, padded sequence.
PREFIX-TYPE-DEPT-YYYY-Mon-NSVC-REQ-ENG-2024-Mar-42Prefixes, department code, year, month, and sequence.
ID-YYYY-ORG-USERID-001-2024-ORGNAME-JOHNBase ID, year, organization, and user components.