---
title: Field definitions
slug: ref/field-definitions
docTags: 
createdAt: 2023-12-06T14:02:45.219Z
---

Field definitions provide a way to expose low level information about the main entities in the Ticketmatic applications. This allows setup experts and regular users to configure views, ticket layouts and documents without technical knowledge of the public data model:

- views are simply composed by selecting a set of field definitions
- in ticket layouts all field definitions related to the ticket and order are available
- in documents all field definitions related to the order are available

:::hint{type="info"}
Field definitions always belong to one of the main entities in Ticketmatic:

- contact
- event
- ticket
- payment
:::



Field definitions are managed in the Field definitions module in the Settings app. Click the button below to go there:

:::CtaButton{label="Go to field definitions" externalHref="https://apps.ticketmatic.com/#!/settings/fielddefinitions" openInNewTab="true"}

:::



***

## Basic example

Let's try a basic example. Press `Add` in the Contact tab to create a new field definition

![Field definition](https://api.archbee.com/api/optimize/zGnEynQy6cgPdn1J1kZsn/PBaPQw0rSVWqCUZ0jaIjs_image.png "Field definition")

Enter this configuration:

- **Name**: the visible name for the field, use 'First name'
- **Key**: the key to reference the field in ticket layouts or documents, use 'firstname'
- **Display**: select how the field should be displayed. Use 'String'
- **Width**: default width of this field in views, use 40
- **Variable width**: whether the field should be resized in views when necessary, check it.
- **Alignment**: the field alignment

The `definition` field should contain the actual sql-clause.

::::hint{type="success"}
For example, to display the first name of the contact:

:::BlockQuote
contact.firstname
:::
::::

The preview result section will display a few sample results in real-time.

Save the field definition. This definition is now ready to be used in [views](docId\:kfyzMnbMfvgYj6X0PkhcX), [ticket layouts](docId\:w9n-qRlGQo5QXo-mEY7_d) and [documents](docId\:gCzf4OHu7oMFvRiqXRAEF).

***

## Definition

You use the [public data model](https://www.ticketmatic.com/docs/db) to define field definitions. A field definition is actually an sql select clause. Depending on the entity the field definition belongs to, the main sql table will be different. For example, for field definitions of type `contact`, the main table is [tm.contact](https://www.ticketmatic.com/docs/db/contact).

You can use any supported sql function in the definition. 

::::hint{type="success"}
For example, to put the first name in upper case:

:::BlockQuote
UPPER(contact.firstname)
:::
::::



You can use subqueries as well. 

::::hint{type="success"}
For example to create a field definition for the number of orders for a contact:

:::BlockQuote
(select count(\*) from tm.order where tm.order.contactid=contact.id) as nbroforders
:::
::::

### Joins

Depending on the field definition type, certain joins can be activated. 

::::hint{type="success"}
For example, if you want to create a field definition for the address for a contact, you can use following definition:

:::BlockQuote
\<NEEDED TAG="address"/>contactaddress.city
:::
::::



Bij specifying the `NEEDED` tag, you activate the join. Below is the list of joins that can be activated:

*Contact*

| Join          | Table that becomes available |
| ------------- | ---------------------------- |
| address       | tm.contactaddress            |
| phone1        | tm.contactphonenumber        |
| phone2        | tm.contactphonenumber        |
| phone3        | tm.contactphonenumber        |
| customertitle | tm.contacttitle              |

*Order*

| Join             | Table that becomes available                            |
| ---------------- | ------------------------------------------------------- |
| saleschannel     | tm.saleschannel                                         |
| customer         | tm.contact, tm.contactaddress and tm.contactphonenumber |
| paymentscenario  | tm.paymentscenario                                      |
| deliveryscenario | tm.deliveryscenario                                     |

*Event*

No optional joins are available, but eventlocation and production are always available automatically

*Ticket*

| Join             | Table that becomes available        |
| ---------------- | ----------------------------------- |
| basket           | tm.order                            |
| event            | tm.tickettype and tm.event          |
| pricetype        | tm.tickettypeprice and tm.pricetype |
| buyer            | tm.contact (as buyer)               |
| ticketholder     | tm.contact (as ticketholder)        |
| seat             | tm.seatrank                         |
| deliverystatus   | deliverystatus                      |
| deliveryscenario | tm.deliveryscenario                 |
| locktype         | tm.locktype                         |

*Payment*

| Join          | Table that becomes available |
| ------------- | ---------------------------- |
| basket        | tm.order                     |
| paymentmethod | tm.paymentmethod             |
| user          | tm.user                      |

:::hint{type="success"}
For more examples, take a look at the field definitions that by default are available in your account.
:::