AutoIncrement

AutoIncrements provide automatic value generation for attributes when entities are inserted into the repository. They ensure unique, sequential values for attributes like customer numbers, document IDs, or any other identifier that requires automatic numbering.

AutoIncrements are particularly useful for:

• Customer Numbers: Generate unique customer identifiers automatically
• Document Numbers: Create sequential document references with custom formatting
• Order Numbers: Maintain sequential order identification
• Invoice Numbers: Generate formatted invoice identifiers
• Sequence Counters: Any scenario requiring auto-generated sequential values

Defining AutoIncrements

AutoIncrements are defined as runtime entities that reference the System/AutoIncrement type. Create a YAML file with the following structure:

$schema: https://schemas.meshmakers.cloud/runtime-model.schema.json
dependencies: []
entities:
- rtId: <unique-runtime-id>
  ckTypeId: System/AutoIncrement
  rtWellKnownName: CustomerNumber
  attributes:
  - id: System/AutoIncrement.End
    value: 9999
  - id: System/AutoIncrement.CurrentValue
    value: 0
- rtId: <unique-runtime-id>
  ckTypeId: System/AutoIncrement
  rtWellKnownName: BillingDocumentDocumentNumber
  attributes:
  - id: System/AutoIncrement.End
    value: 9999
  - id: System/AutoIncrement.Format
    value: "25-{0:D4}"
  - id: System/AutoIncrement.CurrentValue
    value: 0

AutoIncrement Attributes

The following table describes the available attributes for AutoIncrement configuration:

Attribute	Description	Mandatory	Example
System/AutoIncrement.CurrentValue	The current value of the counter	Yes	0, 274
System/AutoIncrement.End	The maximum value before reset/overflow	No	9999
System/AutoIncrement.Format	Format string for value output	No	"25-{0:D4}"

Format String

The Format attribute uses .NET string formatting conventions:

• {0:D4}: Zero-padded 4-digit number (e.g., 0001, 0274, 9999)
• "25-{0:D4}": Prefix with literal text (e.g., 25-0001, 25-0274)
• If no format is specified, the raw numeric value is used

Using AutoIncrements in Types

To use an AutoIncrement in a type definition, reference it in the attribute's autoIncrementReference property:

$schema: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json
types:
- typeId: Customer
  derivedFromCkTypeId: System/Entity
  description: "Represents a customer of an energy community"
  attributes:
  - id: ${thisModel}/CustomerNumber
    name: CustomerNumber
    autoIncrementReference: "CustomerNumber"
  - id: Basic/Contact
    name: Contact
  # ... other attributes

The autoIncrementReference value must match the rtWellKnownName of the AutoIncrement entity.

Behavior

When an entity with an AutoIncrement attribute is inserted:

1. The system retrieves the current value from the referenced AutoIncrement
2. Checks if the current value has reached the End value (if specified)
3. If the end value is reached, the insertion fails and no new entities can be created
4. If within limits, increments the CurrentValue by 1
5. Applies the format string (if specified)
6. Assigns the formatted value to the attribute
7. Updates the AutoIncrement's CurrentValue in the repository

warning

AutoIncrement values are managed at the repository level and are persistent across application restarts. Ensure unique rtWellKnownName values to avoid conflicts.

Best Practices

• Use descriptive rtWellKnownName values that clearly identify the purpose
• Set appropriate End values to prevent overflow
• Test format strings to ensure they produce the desired output
• Consider the impact of concurrent insertions on sequence continuity
• Plan for scenarios where the End value is reached (entity creation will fail when limit is exceeded)