Custom Fields configuration

Custom Fields allow to collect information specific to your business processes and are available to users in the TMS. We recommend custom field creation is carefully considered, and stock fields be used when possible, as the latter have enhanced visibility and functionality within the TMS.

Configuring a new custom field will require the following information:

1. label: this will be visible to end users and shown in the UI.
2. type: such as string, number, choice ... (full list available in our CustomFieldType API Reference)
3. options (required for choice or multichoice types): the list of seletable values for the field
4. description (optional): this should instruct users about how to use the field and will be shown as a tooltip.
5. isRequired (optional, default false): whether setting a value for the field is required to save the entity
6. roles (optional): whether to restrict visibility of the field only to users assigned the specified roles

For a full list of options, see our CustomFieldDefinitionInput API Reference

Create

The following mutation sets up an Event Custom Field and returns its key:

mutation {
  customFields {
    createGlobalCustomDefinition(
      input: {
        objectType: Event,
        definition: {
          label: "Attire",
          description: "Note any venue restrictions on dress, e.g. no shorts or flip flops",
          isRequired: false,
          type: html,
        }
      }
    ) {
      customFieldDefinition{
         key
      }
    }
  }
}

The key returned in the response is needed to set values for the new field:

{
  "data": {
    "customFields": {
      "createGlobalCustomDefinition": {
        "customFieldDefinition": {
          "key": "Q3VzdG9tRmllbGREZWZpbml0aW9uOjI2"
        }
      }
    }
  }
}

Retrieve configuration

The following query returns all Custom Fields configured for the Event entity:

query {
  customFieldTemplate(type:Event) {
    customFieldDefinitions {
      key
      label
      description
      type
      options { value }
      isRequired
    }
  }
}

For a full list of entities that support custom fields, see our SupportsCustomField API Reference.

Update

A Custom Field may have to be updated after its creation for reasons such as:

• Fixing typos in the field label or description.
• Revising the permissions or required state on the field.
• Changing the available options for a choice or multichoice value.

The type of a custom field cannot be changed after creation.

Please note the following quirks around choice and multichoice fields:

• Adding and changing options does not retroactively update existing data
• Any edits made, either via the GraphQL API or by users in the TMS will require to update any entities set to a removed / changed option for the field to a new, valid option

To following mutation updates a field's label and description and makes it required:

mutation updateField {
  customFields {
    updateGlobalCustomDefinition(input: {
      definitionKey: "Q3VzdG9tRmllbGREZWZpbml0aW9uOjIx",
      label: "New Label",
      description: "New Description",
      isRequired: true,
    }) {
      customFieldDefinition {
        key
      }
      errors {
        label
        message
        value
      }
    }
  }
}

Delete

A Custom Field may have to be deleted if:

• Business processes have changed and it's no longer used.
• It was created in error.
• It needs to be removed for compliance reasons (e.g. GDPR).

BEWARE: Deleting a custom field will remove it from the instance and purge all data.. The change is irreversible and all existing data will be permanently lost. Take care when using this mutation, as the field will cease to return in all Reports, GraphQL API queries, and REST API calls (if applicable).

The following mutation removes a custom field:

mutation removeField {
  customFields {
    removeGlobalCustomDefinition(input: {
      definitionKey: "GLOBAL_CUSTOM_FIELD_DEFINITION_ID"
    }) {
      key
      errors {
        label
        message
        value
      }
    }
  }
}