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:

Try Me

mutation SetupEventCustomField {
  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:

Try Me

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

Locations also support Custom Fields: use objectType: Location when creating a definition and customFieldTemplate(type: Location) to retrieve it. See Locations for create and update examples.

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:

Try Me

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

Choice IDs

The options of a choice or multichoice field carry an id: a stable identifier for that option within the field. It does not change when the option is renamed. A field’s own identifier is its definitionKey.

Update mutations accept optionInputs, a list of { id, value }, as an alternative to options, a list of strings. Send one or the other, never both: sending both is rejected with “Supply options or optionInputs, not both”, and optionInputs on a field that is not a choice is rejected with “Only choice fields accept option inputs”. The value is the option’s text, which is also the label shown to users.

Send the id of every option you want to keep, exactly as the API returned it. An option sent with its id keeps that identity when it is renamed, so anything referring to it by id still refers to the same option:

Try Me

mutation renameChoice {
  customFields {
    updateGlobalCustomDefinition(input: {
      definitionKey: "Q3VzdG9tRmllbGREZWZpbml0aW9uOjIx",
      optionInputs: [
        { id: "Q3VzdG9tRmllbGRPcHRpb246NDI=", value: "Crimson" }
      ],
    }) {
      customFieldDefinition {
        key
        options { id value label }
      }
      errors {
        label
        message
        value
      }
    }
  }
}

An option sent without an id is matched by its value, so a plain list of strings matches the existing options by their text. Renaming an option that way gives the renamed option a new id, as does removing an option and adding the same text back later.

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:

Try Me

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