Enums

Enums are used for establishing a set of predefined constants, which can represent various states, types, or configurations within the library. Enums are embedded within a Runtime Entity Object and do not need any navigation through associations.

Typically, Enums are used to define the following:

• States: Enums can be used to define the state of an object, such as Active, Inactive, Pending, etc.
• Configurations: Enums can be used to define configurations, such as High, Medium, Low, etc.
• Status: Enums can be used to define the status of an object, such as Success, Failure, Pending, etc.
• Categories: Enums can be used to define categories, such as Electronics, Clothing, Furniture, etc.
• Permissions: Enums can be used to define permissions, such as Read, Write, Delete, etc.
• Priority: Enums can be used to define priority levels, such as High, Medium, Low, etc.
• Severity: Enums can be used to define severity levels, such as Critical, Major, Minor, etc.
• Frequency: Enums can be used to define frequency, such as Daily, Weekly, Monthly, etc.
• Direction: Enums can be used to define direction, such as Inbound, Outbound, Bidirectional, etc.

Creating Enums

Create a YAML file and add the following content to define an Enum:

$schema: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json
enums:
- enumId: Priority
  useFlags: false
  isExtensible: false
  values:
  - key: 1
    name: Low
    description: Low priority
  - key: 2
    name: Medium
    description: Medium priority
  - key: 3
    name: High
    description: High priority

The following table describes the fields in the Enum definition:

Field	Description	Mandatory	Default Value
enumId	The unique identifier for the Enum.	Yes
useFlags	A boolean value that indicates whether the Enum should be used as flags.	No	false
isExtensible	A boolean value that indicates whether the Enum is extensible using the API	No	false
values	An array of key-value pairs that define the values of the Enum.	Yes
key	The key for the Enum value. Must be a unique integer within the list	Yes
name	The name of the Enum value. Must be a name without special characters or whitespaces	Yes
description	The description of the Enum value.	No

Customization Extensions

Customization extensions are used to extend the values list of a predefined Enum.

warning

This feature is useful for creating master data that does not change heavily. It is not recommended to use this feature for frequently changing data, because a full reload of the tenant is required to apply the changes.

The following example demonstrates how to extend the Priority Enum with a new value:

Step 1: Update the Enum definition to make it extensible

We create a new Enum definition for the Priority Enum with the isExtensible field set to true.

$schema: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json
enums:
  - enumId: Priority
    useFlags: false
    isExtensible: true # This field is updated to true
    values:
      - key: 1
        name: Low
        description: Low priority
      - key: 2
        name: Medium
        description: Medium priority
      - key: 3
        name: High
        description: High priority

Step 2: Import the construction kit to OctoMesh

After updating the Enum definition, compile the construction kit and import it to OctoMesh. The Enum Priority is now extensible, and you can add new values to it using the API.

octo-cli -c importck -f '<path of directory for construction kit>' -w

See Importing Construction Kits for more information.

Step 3: Extend the Enum using the API

We crate a new value for the Priority Enum using the API called Urgent with the key 1. We use the INSERT operation to add the new value to the Enum.

mutation {
  constructionKit {
    enums(ckId: "ConstructionKitLibrary/Priority") {
      updateValueExtensions(
        values: [
          {
            operation: INSERT
            value: { key: 4, name: "Urgent", description: "Urgent priority" }
          }
        ]
      ) {
        ckEnumId
        isExtensible
        values {
          key
          name
          description
          isExtension
        }
      }
    }
  }
}

The result of this query is as follows

{
  "data": {
    "constructionKit": {
      "enums": {
        "updateValueExtensions": [
          {
            "ckEnumId": "ConstructionKitLibrary/Priority",
            "isExtensible": true,
            "values": [
              {
                "key": 1,
                "name": "Low",
                "description": "Low priority",
                "isExtension": false
              },
              {
                "key": 2,
                "name": "Medium",
                "description": "Medium priority",
                "isExtension": false
              },
              {
                "key": 3,
                "name": "High",
                "description": "High priority",
                "isExtension": false
              },
              {
                "key": 4,
                "name": "Urgent",
                "description": "Urgent priority",
                "isExtension": true
              }
            ]
          }
        ]
      }
    }
  }
}

Be aware of:

• The name must be unique within the Enum. If you try to insert a value with a name that already exists, the operation will fail.
• The name must not be empty, contain special characters or whitespaces. Regex pattern: ^[_a-zA-Z][_a-zA-Z0-9]*$
• The key must be unique within the Enum. If you try to insert a value with a key that already exists, the operation will fail.
• The key must be an integer and greater than 0.

It is also possible to delete or update values of an Enum. The following example demonstrates how to delete and insert a value in the Priority Enum:

mutation {
  constructionKit {
    enums(ckId: "ConstructionKitLibrary/Priority") {
      updateValueExtensions(
        values: [
         {
            operation: DELETE
            value: { key: 4, name: "Urgent", description: "Urgent priority" }
          },
          {
            operation: INSERT
            value: { key: 4, name: "Critical", description: "Critical priority" }
          }
        ]
      ) {
        ckEnumId
        isExtensible
        values {
          key
          name
          description
          isExtension
        }
      }
    }
  }
}

Behavior During Construction Kit Import

When you import or update a Construction Kit model, the system preserves custom extension values that were added via the API. This ensures that your customizations survive model updates.

Extension Values Are Preserved

When a new version of a Construction Kit is imported:

1. Extension values are automatically preserved: Any values with isExtension: true are saved before the import and restored afterward.
2. New CK-defined values are added: Values defined in the new Construction Kit model are imported normally.
3. Extension values take precedence: If an extension value has the same key as a CK-defined value, the extension value overrides the CK-defined value.

Example Scenario

Consider an enum Priority with the following initial CK-defined values:

Key	Name	IsExtension
1	Low	false
2	Medium	false
3	High	false

You add a custom extension value via the API:

Key	Name	IsExtension
4	Critical	true

Now you import a new version of the Construction Kit that adds a new value with key 4:

Key	Name	IsExtension
1	Low	false
2	Medium	false
3	High	false
4	VeryHigh	false

After the import, the result will be:

Key	Name	IsExtension
1	Low	false
2	Medium	false
3	High	false
4	Critical	true

The extension value Critical (key 4) overrides the CK-defined value VeryHigh because extension values take precedence.

Best Practice

When adding extension values, choose keys that are unlikely to conflict with future CK updates. Consider using higher key values (e.g., starting from 100 or 1000) for custom extensions.

warning

If you need to use a specific key that is defined in the Construction Kit, you can override it with an extension value. However, be aware that this may cause issues if the CK-defined value has specific meaning in the system logic.