Custom fields

Most object types in EventsAir have custom fields, which allow consumers to extend the object with additional values. A custom field definition is a template for these additional values.

Custom fields and custom field definitions

A custom field definition specifies:

1. The target type, like Event or Contact.
2. A name.
3. The type of data stored in the custom field:
   • A single line of text.
   • A boolean.
   • A number.
   • An amount.
   • A date.
   • HTML.
   • A tag.
   • A document.
4. An optional unique code.
5. A flag indicating whether a value is required.
6. A flag indicating whether the value contains personal data.

With this definition in place, custom field values can be set on the target type using the data type specified in the custom field definition.

Scope of custom field definitions

Custom field definitions have different scopes depending on which type they apply to.

Event custom field definitions are global across the system. This means that all events share the same custom field definitions. In other words, it is not possible to create a custom field definition that would apply to event A and not to event B.

note

Other types have global custom field definitions in the system, namely suppliers, offices, and users. However, at the time of writing, the GraphQL API only exposes global custom field definitions of events.

Most other types have custom field definitions that are scoped at the event level. These include definitions for contacts or registrations, for example. This means that it is possible for contacts in event A to have different custom field definitions than those in event B.

A note about contact stores

Contact stores allow sharing data across several events. For more information about contact stores, see the following articles:

1. EventsAir contact stores.
2. Marketing Tags, Notes and Custom Fields in a Contact Store.

If you're interested in knowing whether a custom field definition originates from the event or the contact store the event is associated with, you can distinguish them in different ways.

The first option is to use the __typename field which will return either EventCustomFieldDefinition or ContactStoreCustomFieldDefinition:

query CustomFieldDefinitionSourceWithTypeName {
  events {
    customFieldDefinitions {
      contacts(limit: 10) {
        __typename
        id
        name
        type
      }
    }
  }
}

Another option is to use different fragments for the different types, which carries the added possibility of selecting different fields for each type:

query CustomFieldDefinitionSourceWithFragments {
  events {
    customFieldDefinitions {
      contacts(limit: 10) {
        ... on EventCustomFieldDefinition {
          id
        }

        ... on ContactStoreCustomFieldDefinition {
          id
          name
          type
        }
      }
    }
  }
}

Query custom field definitions

Since custom field definitions have different scopes, the GraphQL API exposes them at different levels:

• Global custom field definitions are accessible through a top-level query.
• Event-scoped custom field definitions are accessible as a child field of the Event type.

query CustomFieldDefinitions {
  # Global custom field definitions
  customFieldDefinitions {
    events {
      id
      name
      type
    }
  }

  events(limit: 10) {
    # Event-scoped custom field definitions
    customFieldDefinitions {
      contacts {
        id
        name
        type
      }

      registrations {
        id
        name
        type
      }
    }
  }
}

Query custom fields

Custom fields can be queried alongside the types they apply to.

query CustomFields {
  events(limit: 2) {
    customFields(limit: 10) {
      # ID, name, and type of the custom field definition
      definitionId
      name
      type

      # Value of the custom field
      value
    }

    contacts(limit: 10) {
      customFields(limit: 10) {
        # ID, name, and type of the custom field definition
        definitionId
        name
        type

        # Value of the custom field
        value
      }
    }
  }
}

As mentioned earlier, different custom field definitions can hold different types of data, like strings, numbers, booleans, etc. It's up to the consumer of the GraphQL API to properly parse the value field based on the type.

Custom field definition type	Returned type
TEXT	A string
CHECKBOX	A boolean value, true or false
AMOUNT	A numeric value
NUMBER	A numeric value
DATE	A date represented as a string with the yyyy-MM-dd format
TAG	The value of the tag
HTML	A string representing an HTML fragment
DOCUMENT	The URL pointing to the document

Create / update custom fields

Custom fields can be created and updated while creating or updating records through the appropriate mutations.

From a consumer point of view, there is no difference between the creation and the update of a custom field. The reason for this is that the input must specify the identifier of the custom field definition. If there is no existing custom field associated with the definition, one will be created; otherwise, it will be updated.

mutation UpdateContactCustomFields {
  updateContactDetails(
    input: {
      eventId: "5f530626-7211-49dc-8b83-e64676bfbb73"
      contactId: "a51dc83f-7523-4d53-9bae-1d70c86355e3"
      customFields: [
        { definitionId: "a46cef69-2912-4d81-8ad7-fa36012ebc83", value: true }
        { definitionId: "9cc6b851-d544-4da1-87c3-5d1c0a411f3b", value: "2023-11-01" }
      ]
    }
  ) {
    contact {
      customFields {
        definitionId
        type
        value
      }
    }
  }
}

As for the query aspect, consumers must ensure that the value they provide matches the type of the custom field definition.

Custom field definition type	Expected type
TEXT	A string
CHECKBOX	A boolean value, true or false
AMOUNT	A numeric value
NUMBER	A numeric value
DATE	A date represented as a string with the yyyy-MM-dd format
TAG	The desired value of the tag
HTML	A string representing an HTML fragment

note

Document custom fields cannot currently be created or updated through the GraphQL API