Custom Data
It is possible to define extra fields in Yesplan on top of the default data that can be entered for events, resources and contacts. We call this custom data. This makes it possible to configure Yesplan freely. In fact, you can add extra fields yourself that are specific to a certain workflow or a certain organization.
Custom data fields can be added to:
- Events
- Resources
- Resource bookings
- Contacts
- Contact bookings
They are displayed in their respective inspectors, on the tab of your choosing. You can create extra tabs for this.
Remark
For every element to which custom data can be added, there is a separate screen for managing that custom data. These screens can be found in the system settings, under the tabs “Events”, “Resources” and “Contacts”, in the sections “Custom Data” or “Custom Data for Bookings”.
Since the configuration of custom data fields is quite similar for the different elements, we will not discuss every separate screen in detail. Instead, we will explain the general set-up of the configuration screen for custom data.
Custom Data Structure§
You can define multiple custom data fields for a certain type of element (such as events, resources and contacts). Instead of presenting these fields in one single long list, Yesplan offers two possibilities for dividing custom data fields. When displaying the values of custom data fields on inspectors, this division will be respected.
-
Groups: Groups are the highest level for dividing custom data fields in Yesplan:
- A group has a name and is displayed above the table in the configuration screen.
- The configuration screen only displays the details of one group at the time. To see the details of another group, click the “Open” button next to the group name.
- You can also change the order of the groups (to determine the order in which they will be displayed in the inspectors). In order to do this, you can use the up and down arrows next to the group name.
- Double-click the name of a group to edit it.
- Click “Delete this Group” on the right side of the screen to delete a group entirely.
-
Blocks: Within a group, custom data fields can be further divided into blocks:
- For example, in the image above we see that the group “Production” contains one block: “Info”.
- Just like groups, blocks can be moved by clicking “Up” or “Down” (in the right-hand column).
- Double-click the name of a block to edit it.
- Click “Delete” in the right-hand column to delete a block entirely.
To add a custom data field to a block, you slide the field into the block using “Up” and “Down”.
Tip
A custom data field or a block can be moved to another group by moving it completely to the top or bottom of the group and then clicking “Up” or “Down” one more time.
Label, Keyword and Description§
When editing custom data fields you can change the label, keyword and description.
Tip
Do you want to retrieve the keyword of a custom data field easily in an inspector? Press Ctrl+Alt (Windows) or Ctrl+Option (macOS): the field’s label changes to the keyword. Do you want to copy the keyword? Then click the label while holding down the same keys.
Label§
The label of a custom data field assigns a (short) name to the field. This label is displayed in the inspector, to the left of or directly above the input fields. Double-click a label to edit it.
Keyword§
The keyword is the internal technical name for the custom data field, and it will be used to refer to this field, for example in the query language, in reports and for integrations that use the API. The keyword can be generated automatically or you can set it yourself manually.
The custom data field with the label ‘Designer’ in the image below is automatically assigned the keyword ‘production_info_designer’, while the custom data field with the label ‘Operator’ was manually awarded the keyword ‘operator’. A keyword chosen manually is displayed in black text, whereas an automatically generated keyword is displayed in gray italic text.
All automatically generated keywords are constructed in the same way:
- They are a combination of the group, the block and the label of the custom data field, always separated by an
_(underscore). All spaces and special characters (such as! ? ;etc.) are deleted and capital letters are converted to lowercase letters. - When you move a custom data field (to another group for example), the automatically generated keyword does not change along with it automatically.
It is often clearer if you set the custom data field keywords yourself. To edit the keyword, double-click it:
- The keyword must be unique in Yesplan, as it is used to identify the field. If you enter a keyword that already exists, Yesplan will alert you and automatically assign the field a different name that is unique.
- If you want to delete a manually chosen keyword and replace it with an automatically generated keyword, double-click the keyword, remove the manually chosen value and click “OK”. A new keyword is then created based on the custom data field’s current position in the hierarchy.
- When you choose a keyword manually, the automatically generated keyword will no longer work in the query language, integrations or reports.
Attention
If you change the keyword for custom data fields that are used in reports or for an integration, the fields will no longer work in those places. After all, keywords are used to query custom data fields in reports and integrations.
Always be very careful when changing keywords, and think of a system in advance to name your keywords.
Description§
The description is an optional field in which you can describe the use or the aim of the custom data field. This description is displayed in the inspectors under the custom data field.
Types of Custom Data Fields§
Yesplan supports different types of custom data. The custom data type determines which values can be entered. You can only use certain types under certain conditions. The list below is an overview of the different types, when they can be used and their aim.
Input Field§
An input field is a short bit of text, for free input.
Text Field§
A text field is a longer bit of text, for free input.
Numeric Input Field§
A numeric input field is an input field for a numeric value. Once created, you can indicate in the “Values” column whether a field should be displayed as a percentage or not.
Attachment Field§
An attachment field can be used to add a file as an attachment or a link to a file. The maximum file size for uploads in Yesplan is 15 MB.
Changed Functionality
The URL of a link in an attachment field appears in the API exactly as it has been entered, without additional encoding. See URLs in the Links of Attachment Fields for more information.
Yes/No Field§
A yes/no field is a field with three options: “Yes”, “No” or blank.
Drop-down Menu§
A drop-down menu is a list with a number of predefined choices, one of which the user can select from a menu.
Checkboxes§
This custom data field is displayed as a list of one or more checkboxes, each with its label, from which the user can select one or more.
Date Input§
The date input field allows the user to select or enter a date.
Time Input§
The time input field allows the user to enter a time (hours and minutes).
Date and Time Input§
The date and time input field allows the user to select or enter a combination of date and time.
Comment Field§
The comment field does not allow input, but it enables you to show a bit of text as a comment between other fields, for instance a guideline related to filling out a certain field. These comment fields appear in the inspectors as green text between the custom data fields.
Resource Field§
A resource field allows you to book a resource:
- You can book existing resources.
- You can create and book new resources.
Remark
This field is available for events only. If a resource is booked via this custom data field, it also appears in the list of booked resources for that event.
Contact Field§
A contact field is a field that allows you to book a contact:
- You can book existing contacts.
- You can create and book new contacts.
Unique Sequence Field§
A unique sequence field generates a unique value and can be added to an event, resource (booking) and contact (booking). Let’s assume for a moment that a unique sequence field is added to an event:
- The field is empty by default and will be assigned a unique value when a user clicks the button next to the field.
- When the button is clicked, Yesplan generates the value of the unique sequence field for that event: e.g. the value ‘1’.
- The next time the button of this custom data field is clicked, the event will receive the next value that is applicable at that moment: the value ‘2’.
- The sequence value within the unique series is increased by one at the time. It is never decreased, because the value may no longer be unique then.
- A unique sequence field can also be emptied again. However, the deleted sequence value will not be used again in the future. A sequence value within a series is always unique, but the series is not necessarily consecutive.
Tip
- You can create as many unique sequence fields as you want. Multiple series can exist alongside each other. The value of a field is always unique within its own series in a specific field.
- You can see the current value of the sequence value in the system settings and—if required—increase it.
When creating the custom data field, you can set the starting value of the sequence value, but you can also compose a pattern with the following building blocks:
- The sequence value
- Bits of fixed text
- The Yesplan ID of the element that the field appears on
- (Parts of) the date where and/or time when the button was clicked
You can put together a pattern with these building blocks. In this pattern, the sequence value is represented by {sequence} and the Yesplan ID by {id}:
- If you want to make a unique sequence field from the text ‘event’ followed by a space and a sequence value, then you enter the pattern as:
event {sequence}. - If you want a unique sequence field of booking number 123 with Yesplan ID 12438-028283, in the format ‘booking-123/12438-028283’, then you enter the pattern as:
booking-{sequence}/{id}.
To express the date and/or time notation, use {datetime:…} and a fixed date and time, namely Saturday, 3 February 2001 at 16:05:06. It is important that you always use this exact date and time to express the date and/or time format:
- If the button was clicked on 21 February 2014 and you want to see this in the unique sequence field as ‘2014-02-21’ then you enter the following pattern:
{datetime:2001-02-03}. - If the button was clicked on 23 January 2014 and you want to see this in the unique sequence field as ‘Thu 23 Jan 2014 at 20:22’ then you enter the following pattern:
{datetime:Sat 3 feb 2001 at 16:05}.
Remark
- You must always write the date and time elements in English when defining the unique sequence field. However, the result is displayed in the system language of the Yesplan installation.
- You can also use free text in the
{datetime:…}parameter (e.g. ‘at’ in the example above), but this is copied literally so it’s not translated into the installation language.
Of course, you can also combine all of these elements: if you want a unique sequence field such as ‘event-123-jan-2014’, then you enter the following pattern: event-{sequence}-{datetime:feb-2001}.
Below you can find a complete summary of the capabilities of {datetime:…}. The reference date is ‘Saturday February 3 2001 16:05:06’:
| Description | Use in the pattern |
|---|---|
| Year | 2001 |
| Year with leading zeros | 01 |
| Month | 2 |
| Month with leading zeros | 02 |
| Name of month | february |
| Name of month capitalized | February |
| Name of month in capitals | FEBRUARY |
| Name of month abbreviated | feb |
| Name of month abbreviated and capitalized | Feb |
| Name of month abbreviated and in capitals | FEB |
| Day | 3 |
| Day with space | _3 |
| Day with leading zeros | 03 |
| Weekday | saturday |
| Weekday capitalized | Saturday |
| Weekday in capitals | SATURDAY |
| Weekday abbreviated | sat |
| Weekday abbreviated and capitalized | Sat |
| Weekday abbreviated and in capitals | SAT |
| Time in 12 h format | 4 |
| Time in 12 h format with leading zeros | 04 |
| Time in 24 h format with leading zeros | 16 |
| Day part | pm |
| Day part in capitals | PM |
| Minute | 5 |
| Minute with leading zeros | 05 |
| Second | 6 |
| Second with leading zeros | 06 |
| Timezone Z | Z |
| Timezone | +00:00 |
| Timezone abbreviated | UTC |
Event Labels§
This field displays the labels of the event. Via this field, labels can be added to and deleted from an event (or event group).
This field is only applicable to events. At the level of an event group, this field displays all labels that appear on the underlying events.
Attention
- There is only one set of labels for an event. If you define this custom data field multiple times, for example to show it in different groups or on different tabs, then they are always exactly the same labels.
- In other words, adding or deleting a label in one place will add or delete it in all other places where the labels of the event are displayed.
- Labels are always displayed in alphabetical order.
Publication Trigger§
A publication trigger is used to send Yesplan data to an external system:
- For example, you can add a publication trigger to events if a ticketing system is linked to Yesplan. You can then click the button to send an event to the ticketing system.
- You can add a publication trigger for a webhook. After clicking the button, it retrieves information from another system or it starts a process there. Since Yesplan 28, this is not only possible for events, but also for contacts, resources and their bookings.
Remark
If you open the inspector for multiple elements (e.g. multiple contacts), the publication trigger will summarize the status of the button on each of these elements. For example, if you inspect three contacts at once and the button is activated on only one of them, then “OFF (2x), ACTIVE (1x)” will appear as text on the button.
Remote Data§
This field is used to display data in Yesplan that comes from a linked ticketing system you have sent an event to. For example, for a forwarded event you can use a remote data field to display the number of sold tickets from your ticketing system in Yesplan. These fields also contain a “Refresh” button to retrieve current data from your ticketing system.
When creating a field for remote data you can choose the data type:
- Single-Line Text: A short piece of text. Free input of one line.
- Multi-Line Text: A longer piece of text. Free input where several lines are permitted.
- Number: A numeric value.
- Date: A date.
- Time: A time of day.
- Date and Time: A combination of date and time.
- Single Option: A single value, for example as the result of a selection made in a drop-down menu.
- Multiple Options: A list containing one or more values, for example as the result of a selection made in a series of checkboxes.
Integration Data§
Custom data fields for integration data can be used by webhooks. This field cannot be filled out by users in Yesplan itself and can only be assigned a value via a webhook.
When creating a field for integration data you can choose the data type:
- Single-Line Text: A short piece of text. Free input of one line.
- Multi-Line Text: A longer piece of text. Free input where several lines are permitted.
- Number: A numeric value.
- Date: A date.
- Time: A time of day.
- Date and Time: A combination of date and time.
- Single Option: A single value, for example as the result of a selection made in a drop-down menu.
- Multiple Options: A list containing one or more values, for example as the result of a selection made in a series of checkboxes.
Remark
- You need an API key to use webhooks.
- Do you also want to use a webhook to write information back to an integration data field? Then you must first explicitly link an API key to the webhook in question.
See Managing API Keys and the Webhooks API for more information.
Visibility of Custom Data§
It’s often not desirable to display a custom data field everywhere and at all times. Sometimes you only want to display the custom data field on certain inspector tabs, or you only want to show it under certain conditions. For example, the number of tickets sold of an event are only important once the event has the status ‘Planned’, or a field that keeps track of the sizes of a resource is only useful for resources of type “Material”.
You can set the visibility of a custom data field by clicking “Add” in the “Where or When to Show” column. You will then see a drop-down menu with all the possible conditions. When you choose a condition, it will be displayed in one of the columns to its left. In the image above (for events) we see the columns “Inspector Tabs”, “Profile”, “Status” and “Location”. If you choose the “Info” tab from the list of conditions, then “Info” will appear in the column “Inspector Tabs”; this condition is now active. You can remove the active condition again by clicking the “Delete” button next to it.
The tables below are arranged per element type, and they offer an overview of the conditions that can be used to determine the visibility of a custom data field and the accompanying rules.
Events§
| Condition | Description |
|---|---|
| Tab | The custom data field is only visible on the selected tabs. If no tabs are selected for this field, then it will not be visible anywhere. |
| Location | The custom data field is only visible if the event takes place in the selected locations. If no locations are selected for this field, then the custom data field is visible irrespective of the location where the event takes place. |
| Event Profile | The custom data field is only visible if the event has a certain profile. If no profiles were selected for this field, then the custom data field is visible irrespective of the event’s profile. |
| Event Status | The custom data field is only visible if the event has a certain status. If no statuses were selected for this field, then the custom data field is visible irrespective of the event’s status. |
Resources and Resource Bookings§
| Condition | Description |
|---|---|
| Tab | The custom data field is only visible on the selected tabs. If no tabs were selected for this field, then the custom data field will not be visible anywhere. |
| Resource Role | The custom data field is only visible for resources with a certain role. If no roles were selected for this field, then the custom data field is visible irrespective of the resource’s role. |
| Resource Type | The custom data field is only visible for resources of a certain type. If no types were selected for this field, then the custom data field is visible irrespective of the resource’s type. |
Contacts and Contact Bookings§
| Condition | Description |
|---|---|
| Tab | The custom data field is only visible on the selected tabs. If no tabs were selected for this field, then the custom data field will not be visible anywhere. |
| Label | The custom data field is only visible for contacts that have a certain label. If no labels were selected for this field, then the custom data field is visible irrespective of which labels the contact has. |
Management§
You will find several tips for managing custom data below.
Creating Custom Data§
A group can be added by clicking “Add a Group” at the bottom of the screen. To add a block or a custom data field, make sure that the group to which you want to add them is open. Click “Add a Field”. Now choose the correct type from the drop-down menu (or the option “New Block”), enter the label and, if required, options separated by a comma. You finish the process by clicking the “Add” button.
The configuration screen for custom data shows the type for every field. If the type requires additional parameters, they will be displayed in the “Values” column. These parameters can be changed by double-clicking them. For custom data fields that expect a list of options (like a drop-down menu or a checkbox), the values entered must be separated by commas.
Attention
It is not possible to change the type of a custom data field once it has been set.
Editing Checkboxes and Drop-down Menus§
Once custom data fields of the type “Checkbox” or “Dropdown” have been created, you can edit the list of predefined values by double-clicking it. However, it’s possible that these values have already been selected, for example on an event. In that case, Yesplan does the following:
- After you edit the value in the system settings, the old value will be followed by a red prohibition sign. This indicates that the value has indeed been selected, but no longer exists in the system settings.
- If a user selects a different value from the list than the edited one with a prohibition sign, the latter will disappear automatically from the list of checkboxes or options.
For example:
- You create a drop-down menu with the values ‘menu 1’, ‘menu 2’ and ‘menu 3’.
- A user selects the value ‘menu 2’ in that drop-down menu on the event ‘Hamlet’.
- You remove ‘menu 2’ from the drop-down menu in the system settings:
- In ‘Hamlet’, the option ‘menu 2’ will be followed by a red prohibition sign for that drop-down menu.
- ‘Menu 2’ will disappear as an option when another value (e.g. ‘menu 1’) is selected.
Restoring Deleted Custom Data Fields§
Groups, blocks and custom data fields that are deleted do not disappear from the system completely. They can be restored. If there are deleted custom data fields, the option “Show Deleted Fields” will appear at the bottom, under the list of custom data groups. Clicking this will display a list of deleted fields.
Besides the details of the fields, you can also see the option to “Restore” items in the “Edit” column. If the block or group to which the custom data field belonged still exists, the field will be restored within that block or group. If it no longer exists, you will see a drop-down menu with all existing blocks and groups, allowing you to indicate where the field should be added. Clicking “Delete Permanently” will remove the field from Yesplan permanently. Therefore, you should think twice before doing this.