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
        }
      }
    }
  }
}