Setting up custom fields
Custom fields give you the ability to store custom data for the most important objects in your account, like Orders, Contacts and Events. In its simplest form it allows you to store extra data with a Contact. Let’s say you want to keep track of who is subscribed to your newsletter. You can easily add a checkbox that is shown whenever you add or edit a Contact.
Custom fields are treated internally exactly the same way as regular fields, so there is no performance penalty for using them. Several datatypes are available: simple string, int or date types, but also checklist or optionset types.
Custom fields for Orders and Contacts can be configured to be shown during the checkout process. This makes it possible to ask the buyer extra info during the checkout proces, either on the Order or on the Contact level. Use cases for this are for example:
As custom fields are also exposed via the Ticketmatic API it also enables you to control external systems via custom field data. An example for this is that you could list all currently published Events on your website via a (custom) CMS integration. If a custom field called “Genre” is added to “Event”, your CMS could also list the “Genre” of the “Event” on your website. This way all your “Event” related data is stored in one place.
Custom fields are managed in the Custom fields module in the Settings app. Click the button below to go there:Go to custom fields
Getting started: setting up a new custom field
Let’s add a new customfield for “Contact”. The custom field’s name will be “Newsletter” and it will indicate if the Contact is subscribed to your newsletter.
To create this custom field execute the following steps:
- Go to the “Settings app”.
- Click on “Custom fields” (in the “System” section).
- In the “Contact field” section, click on “Add”.
- Fill in the name “Newsletter”.
- Fill in the key “newsletter”. This key will be seen whenever an object is requested via the API or when the public data model is used (To define a new “Filter” for example).
- Indicate if the field is required, in this case it’s not needed to enable this.
- Set the Data type to “Boolean”.
- Set the visibility to “Backoffice”. This means that the custom field will be visible in the backoffice applications.
- Click “Save”.
If you go back to the list of custom fields you can see the new custom field in the “Contact” section.
When you add a new Contact you will see the new “Newsletter” field in the “Extra” section on the right side of the screen. The field will also appear when you edit an existing Contact.
You can define custom fields for following items:
- Delivery scenario
- Event location
- Payment method
- Payment scenario
- Price type
Custom fields visibility
For each custom field, the visibility can be defined:
Hidden: the custom field is only available through the API or the public data model. It will not be visible in the applications. This can be used to integrate with external services.
Backoffice: the custom field is available in the backoffice applications, so users can view and edit the value of the custom field
Checkout: the custom field is available during the checkout process. This visibility is only possible for custom fields of type Order or Contact.
Read-only in sales views: the custom field is read-only available for users during sales. This visibility is only possible for custom fields of type Event.
When setting the visiblity to
Checkout, you can further refine when the custom field will be shown by selecting the sales channels and optionally provide an availability script. More info on creating availability scripts
Custom fields of type
Read-only in sales views can be used to provide event information to users during sales. The event information will be available during box office sales and external sales.
Custom field types
The table below lists all the possible custom field types, the best way to use them and how they are represented in the UI. To see how they are returned via the API, check the API documentation
|String||Small amounts of text (under 255 characters).||Simple text input field.|
|Integer||Whole numeric value, for instance 0, 1, 238. But not 234.23||Number input field|
|Date||Date, for instance 2015-03-23 12:30||Date input field. Will show a datepicker with time input.|
|Text||Larger amounts of text (larger than 255 characters).||Simple text input field|
|Text (with formatting)||Larger amounts of text (larger than 255 characters). Allows basic Markdown formatting (headers, bold/italic, links)||Text input field|
|Multi-language string||Small amounts of translatable text (under 255 characters). Translations are enabled via the translations workflow.||Text input field (+translation workflow)|
|Multi-language text||Larger amounts of translatable text (larger than 255 characters)||Textarea (+translation workflow)|
|Decimal||Numeric value, for instance 2347.234||Number input field|
|Single select||Choose a single option from a list of values.||Dropdown|
|Single select (option set)||Choose a single option from a list of values.||List of radio buttons|
|Multi select||Choose one or more options from a list of values.||Dropdown with ability to select multiple values|
|Multi select (checklist)||Choose one or more options from a list of values.||List of checkboxes|
Custom field values
Some types of custom fields allow you to select one or more options from a list of possible values. These values are defined in a separate module
Custom field values. For each custom field you can specify whether the values should be ordered alphabetically or with a custom sort order that you define.
Using custom fields
From the backoffice applications
Custom fields are easy to use from the backoffice applications. Each time a Contact, Order or Event is edited the UI will show the defined custom fields in a specific section. A user will not see the difference between regular and custom fields.
From the API or the public data model
It’s also possible to fetch the data behind the custom fields via the Ticketmatic API. If you request a Contact, Order or Event via the API it will also contain a set of fields that start with
c_, these are all custom fields. The custom field are also autmatically exposed through the public data model.
For example, the previously created custom field “Newsletter” will be added to the Contact object whenever you request it via the API. The key for this customfield will be
c_newsletter because we filled in “newsletter” as key. You can find more information about custom fields in our API here.
You can query the public data model for example like this:
1select id,c_newsletter from tm.contact