Enum metadata field

A metadata field of type enum is displayed to a user as a dropdown list. The user can select one item from the list.

Create an enum field

An enum field can be added to a metadata template either when creating a metadata template, or when updating a template with the addField operation.

The required attributes for an enum field are a type, a displayName, a key, and a list of options.

{
  "scope": "enterprise",
  "displayName": "Contract",
  "fields": [
    {
      "type": "enum",
      "key": "customer_state",
      "displayName": "Customer State",
      "description": "The US state where the customer is located",
      "hidden": false,
      "options": [
        {"key": "N/A"},
        {"key": "AL"},
        {"key": "AK"}
      ]
    }
  ]
}

Optionally, a description can be provided that is shown to a user in the UI, and the field can be set to hidden to hide it from users in the web and mobile apps.

Update an enum field

An enum template field can be updated by updating the template it belongs to. Updates to templates happen through operations to ensure that any template that is already assigned to a file or folder is updated as well.

Change basic field values

When updating an enum metadata field, one of the possible operations is the editField operation, which can be used to change the field's key, displayName, description, and hidden values.

[
  {
    "op": "editField",
    "fieldKey": "customer_state",
    "data": {
      "displayName": "Customer State (USA)",
      "key": "customer_state_usa"
    }
  }
]

Add an option

Adding an option to an enum field can be achieved through the addEnumOption operation. The operation expects the fieldKey to be set to the key of the enum field to change, and a data object with the key of the new option to add.

[
  {
    "op": "addEnumOption",
    "fieldKey": "customer_state",
    "data": {
      "key": "AR"
    }
  }
]

The list of options should now be as follows.

...
"options": [
  {"key": "N/A"},
  {"key": "AL"},
  {"key": "AK"},
  {"key": "AR"}
]
...

Reorder options

Reordering the options in an enum field can be achieved through the reorderEnumOptions operation. The operation expects the fieldKey to be set to the key of the enum field to change, and an enumOptionKeys array with the keys of the options in order.

[
  {
    "op": "reorderEnumOptions",
    "fieldKey": "customer_state",
    "enumOptionKeys": [
      "AL",
      "AK",
      "AR",
      "N/A"
    ]
  }
]

The list of options should now be as follows.

...
"options": [
  {"key": "AL"},
  {"key": "AK"},
  {"key": "AR"},
  {"key": "N/A"}
]
...

Edit an option

Editing an option of an enum field can be achieved through the editEnumOption operation. The operation expects the fieldKey to be set to the key of the enum field to change, and an enumOptionKey to be set to the key of the field option. Finally, it expects a data object with the new key of the field option.

[
  {
    "op": "editEnumOption",
    "fieldKey": "customer_state",
    "enumOptionKey": "N/A",
    "data": {
      "key": "Outside USA"
    }
  }
]

The list of options should now be as follows.

...
"options": [
  {"key": "AL"},
  {"key": "AK"},
  {"key": "AR"},
  {"key": "Outside USA"}
]
...

Remove an option

Removing an option from an enum field can be achieved through the removeEnumOption operation. The operation expects the fieldKey to be set to the key of the enum field to change, and an enumOptionKey to be set to the key of the field option to remove.

[
  {
    "op": "removeEnumOption",
    "fieldKey": "customer_state",
    "enumOptionKey": "AL"
  }
]

The list of options should now be as follows.

...
"options": [
  {"key": "AK"},
  {"key": "AR"},
  {"key": "Outside USA"}
]
...