Skip to content

Generic Ticketing Module

Yesplan has built a module that external ticketing partners can use to easily build an integration so that in Yesplan you can execute the following actions:

  • Send specific data to your ticketing system.
  • Show remote data retrieved from your ticketing system, e.g. number of tickets sold.
  • Populate drop-down menus with values from the ticketing system (mapping).

Concepts§

  • Remote data: If you send event data from Yesplan to your ticketing system, it can process the data further there and additional values can be added. Thanks to custom data fields of the “Remote data” type, you can show these additional values in Yesplan (but not edit them). For example, this is useful for showing in Yesplan the number of tickets sold, the number of free tickets, or a discount. However, your ticketing system must provide this explicitly for specific fields.
  • Mapping: To exchange data, Yesplan and your ticketing system must sometimes contain the same fields and values. The disadvantage is that these values must be identical and you must maintain these values in two places. Using mapping, your ticketing system can place values in a drop-down menu in Yesplan, which allows you to keep these values up to date by synchronizing these in both systems with the push of a button. Your ticketing system determines the content of these drop-down menus. However, this must be explicitly provided for specific fields.
  • Protocol: This specifies the conventions and agreements for data exchange between Yesplan and your ticketing system. For example, this includes the fetching of data, deleting events etc.
  • Publication trigger: This button ensures that events from Yesplan are sent to your ticketing system. You have to create the button yourself.

Before You Start§

To set up your integration, you need data from the manufacturer of your ticketing system or integration. So make sure you have the following information to hand before you start. Once you have this information, you can set up the integration.

Authentication§

Yesplan supports two protocols to connect securely to external ticketing systems: “Basic Auth” and “OAuth 2.0” (Password Grant). The manufacturer of your ticketing system can tell you which one you should use and will deliver you the correct information.

For Basic Auth, you need the following information:

  • URL: The internet address Yesplan must use to exchange data with your ticketing system.
  • Username: The username to access your ticketing system via the URL.
  • Password: The password to access your ticketing system via the URL.

For OAuth 2.0, we support the Grant types”Password Credentials” and “Client Credentials”, which will create a so-called access token:

  • Grant Type: This is the type of authentication in OAuth 2.0. We support the types “Password Credentials” and “Client Credentials”.
  • URL of Resources Server: The internet address that Yesplan uses to send and fetch data about events.
  • URL of Authorization Server: The internet address of the server that creates your access token.
  • Username: The username to request an access token.
  • Password: The password to request an access token.
  • Client ID: The unique ID to identify your Yesplan installation.
  • Client Secret: A string that serves as a password of your installation when requesting an access token.

Protocol and Fields§

Additionally, you need the information below from the manufacturer of your ticketing system:

  • Protocol: Which parts of the protocol are supported. For more information, see Setting the Protocol.
  • Remote data: A list of fields in your ticketing system (with their technical name) that can be shown in Yesplan. You can then create custom data fields of the “Remote data” type for these fields.
  • Extra fields: A list of fields in your ticketing system that can be filled with values from Yesplan when an event is sent. This list includes at least:
    • The technical name of the field in your ticketing system
    • The required type for the custom data field in Yesplan (input field, text field, numeric input field, drop-down menu, or checkboxes)
    • Whether mapping is supported for that field (only relevant for drop-down menus)

Preparing for the Integration§

Before you actually create the integration, you must create the custom data fields you need:

  • The publication trigger
  • Additional fields
  • Remote data

The steps to take for each of these fields is listed below.

Tip

  • You can further adjust the visibility of custom data fields and determine where these must appear. For more information, see Visibility of Custom Data.
  • We recommend placing all the custom data fields for your ticketing system together on one tab in the event inspector, e.g. with the name ‘Ticketing’.

Creating the Publication Trigger§

You can send information from Yesplan to your ticketing system. To do so, you must first add a button to events that will execute this action:

  1. As administrator in Yesplan, go to “System Settings” > “Events” > “Custom Data”.
  2. Create a new group for your ticketing system or you can also choose to add the field to an existing group.
  3. Create the button by clicking “Add a Field”:
    • Select the type “Publication Trigger”.
    • Pick a clear label, e.g. ‘Publication tickets’.
    • Click “Add”.
    • Double-click the keyword of the field and give it an obvious name that clearly reflects what it does, e.g. ‘ticketing_publication_trigger’.

Creating Additional Fields§

Yesplan always sends four fields to the ticketing system and these also receive default values from Yesplan. However, you can set up the integration in such a way that you send the value of a custom data field instead of the default value. The table below gives an overview of the value in the ticketing system and the default value sent by Yesplan:

Ticketing System Value Default Value in Yesplan
name The name of the event.
location The location of the event.
starttime The start time of the event.
endtime The end time of the event.

The table below shows which type of custom data field to use if you don’t want to send a default value:

Ticketing System Value Type of Custom Data Field
name Input field
location Drop-down menu
starttime Time field
endtime Time field

Tip

If a custom data field does not contain a value, Yesplan will revert to the default value for that field.

For example:

  • Create a custom data field of type “Drop-down menu”.
  • Add the value ‘Cinema’ to the field.
  • Link that field to the “location” field (see Linking the Data).

If the value ‘Cinema’ is selected in the drop-down menu, this value will be sent to the ticketing system. If nothing is selected in the drop-down menu, the default value will be sent (e.g. ‘Theater’ or ‘Dance Hall’). This allows you to decide in Yesplan which location name you send for certain events.

Besides these four fields, Yesplan can send many more fields to your ticketing system. However, this depends on the options in that system and on your own needs:

  • Ask the manufacturer of your ticketing system or integration for a list of additional fields that are supported (see Before You Start. You also need to know what type these custom data fields must be in Yesplan.
  • Ask yourself which information you want to manage in which system (prices, capacity, genre etc.). Please note that you overwrite the field values in your ticketing system when sending new values from Yesplan. So make a thorough analysis beforehand.
  • Custom data fields of type “Drop-down menu” support mapping, but your ticketing system must support this for those fields.

Once you have decided which custom data fields you would like to use, you can actually create them:

  1. As administrator in Yesplan, go to “System Settings” > “Events” > “Custom Data”.
  2. Create a new group for your ticketing system or you can also choose to add the field to an existing group.
  3. Create the button by clicking “Add a Field”:
    • The type depends on the field. Look for default values in the table above and request a list of additional fields from the manufacturer of your ticketing system or integration.
    • Pick a clear label, e.g. ‘Ticketing capacity’.
    • Click “Add”.
    • Double-click the keyword of the field and give it an obvious name that clearly reflects what it does, e.g. ‘ticketing_capacity’.

Remark

Additional fields can only have one of the following types:

  • Input Field
  • Text Field
  • Numeric Input Field
  • Drop-down Menu
  • Checkboxes

You will link these fields to the appropriate fields in your ticketing system in the step Linking the Data.

Creating Fields for Remote Data§

Not only can you send fields to your ticketing system, you can also show (but not edit) fields from your ticketing system in Yesplan. Which fields you show in Yesplan depends on your own needs and the features of your ticketing system:

  • Ask the manufacturer of your ticketing system or integration for a list of data that can be shown in Yesplan.
  • Ask yourself which information you need to help you work efficiently. If you show more information, you must also read more information in Yesplan.

Once you have decided which remote data you would like to show, you can also create custom data fields for it:

  1. As administrator in Yesplan, go to “System Settings” > “Events” > “Custom Data”.
  2. Create a new group for your ticketing system or you can also choose to add the field to an existing group.
  3. Create the button by clicking “Add a Field”:
    • Choose the type “Remote Data”.
    • Select the correct data type for the data in question.
    • Choose a clear label, e.g. ‘Number sold’.
    • Click “Add”.
    • Double-click the keyword of the field and give it an obvious name that clearly reflects what it does, e.g. ‘ticketing_external_sold’.

You will link these fields to the appropriate fields in your ticketing system in the step Linking the Data.

Tip

See Remote Data for more information on the available data types.

Creating the Integration§

Once you have created the custom data fields, you can create the integration:

  1. Go to “System Settings” > “Integrations”.
  2. Click the ‘+’ icon to add an integration. Give the link a name, for example ‘Ticketing’ or your ticketing system’s brand.
  3. Click “Add” and select “Generic Ticketing” under “Integration”.

Next, you can enter the details of your ticketing system. To do so, select the correct type of authentication for your ticketing system: “Basic Auth” or “OAuth 2.0”:

  • Basic Auth:
    • You receive the values for “URL”, “Username” and “Password” from the manufacturer of your ticketing system. For more information, see Before You Start.
    • Click the “Update” button to link Yesplan to your ticketing system.
  • OAuth 2.0:
    • Select the correct value for the field “Grant Type”: “Password Credentials” or “Client Credentials”.
    • You receive the values for “URL of Resources Server”, “URL of Authorization Server”, “Username”, “Password”, “Client ID” and “Client Secret” from the manufacturer of your ticketing system. For more information, see Before You Start.
    • Click “Verify” to request your access token from the ticketing system.
    • Next, click the “Update” button to link Yesplan to your ticketing system.

Do you get an error message? Please contact the manufacturer of your ticketing system or integration. When the systems are properly linked, you can continue to set up the integration.

Setting the Protocol§

For integrations, it is important that the two systems know what they support and what they do not. You can specify this in the “Protocol Support” section. Ask the manufacturer of your ticketing system or integration what to select here:

  • Server Supports Productions: In Yesplan, you can set an event group as “Production”. If the ticketing system supports productions, the events in this group are converted to performances in a series, multiple performances of one event etc. This depends on the workflow and concepts of your ticketing system.
  • Server Supports Deletion: If you click the publication trigger in Yesplan, you can then click the same button to revoke that publication. If you select this option, your ticketing system supports this action. What exactly happens depends on the individual system: deleting the event, just breaking the link between Yesplan and the event in the ticketing system etc.
  • Server Supports Retrieving Events by Month: If you select this option, Yesplan can retrieve the latest information every night for all future events linked between Yesplan and the ticketing system. For this, Yesplan retrieves the data of all active events in the future, and of all active events in the past, going back one year.

Setting Up the Publication Trigger§

In this step you determine which publication trigger must be used for sending events in this integration. Select in the drop-down menu the keyword of the publication trigger you created earlier. In our example, it was ‘ticketing_publication_button’.

Linking the Data§

In this step, you determine which data will be exchanged during the:

  • Publication of an event
  • Publication of a production
  • Retrieval of remote data

Mapping Data for Event Publish Action§

Under “Mapping data for event publish action”, you will first find the four fields that Yesplan always sends: “name”, “location”, “starttime” and “endtime”. If you want to send a value other than the default value, you can select the keyword for the appropriate custom data field from the drop-down menu.

If you want to send additional fields, you can add these as follows:

  1. At the bottom of the “Ticketing System Value” column, type the technical name of the field in the ticketing system, e.g. ‘tickets_capacity’.
  2. In the drop-down menu of the “Yesplan Value” column, select the keyword of the custom data field whose value you want to send for that field, e.g. ‘ticketing_capacity’. These are the fields you created in the step Creating Additional Fields. Make sure this custom data field has the right type.
  3. If the custom data field in question is a drop-down menu, the drop-down menu becomes active in the “Mapping” column:
    • Does the ticketing system support mapping for specific fields? Then you can select such a field from the drop-down menu.
    • If mapping is not supported, you can only select the value “Default”.
  4. Click “Add”.

Remark

If mapping is set for a drop-down menu, the content of this drop-down menu is managed in your ticketing system. See Managing Mapping for more information.

Mapping Data for Production Publish Action§

The section “Mapping Data for Production Publish Action” only appears if you selected the option “Server Supports Productions” in “Support Protocol”. One field is always sent by Yesplan: “name”, with the name of the event or the event group in question as a value. If you want to send a different value for this field, you can select the keyword for the appropriate custom data field from the drop-down menu.

If you want to send additional fields, you can add these as follows:

  1. At the bottom of the “Ticketing System Value” column, type the technical name of the field in the ticketing system, e.g. ‘capacity’. These are the fields you created in the step Creating Additional Fields.
  2. In the drop-down menu of the “Yesplan Value” column, select the keyword of the custom data field whose value you want to send for that field, e.g. ‘ticketing_capacity’.
  3. If the custom data field in question is a drop-down menu, the drop-down menu becomes active in the “Mapping” column:
    • Does the ticketing system support mapping for specific fields? Then you can select such a field from the drop-down menu.
    • If mapping is not supported, you can only select the value “Default”.
  4. Click “Add”.

Remark

If mapping is set for a drop-down menu, the content of this drop-down menu is managed in your ticketing system. See Managing Mapping for more information.

Remote Data§

In the “Remote Data” section, you can link fields from the ticketing system to custom data fields in Yesplan, so that you can see the values of the fields from your ticketing system in Yesplan:

  1. At the bottom of the “Ticketing System Value” column, type the technical name of the field in the ticketing system, e.g. ‘sold’.
  2. In the drop-down menu of the “Custom Data Element” column, select the keyword of the custom data field whose value you want to send for that field, e.g. ‘ticketing_external_sold’. These are the fields you created in step Creating Fields for Remote Data.
  3. Click “Add”.

Using the Integration§

Once everything is set up correctly, you can use the integration to send event data to your ticketing system. We give some general guidelines below, which may be different for the ticketing system you use.

Publication of a Single Event§

If you want to publish a single event to your ticketing system, we recommend that you fill out at least the information below:

  • Event name
  • Schedules

Tip

If you use the default fields for the times, Yesplan follows the logic below:

  • If the event has a schedule with a displayed start and end time (the red dots), then Yesplan sends the displayed start and end time. We recommend you work this way.
  • If the event contains a schedule with a single schedule item, containing only the displayed start time (red dot), Yesplan sends the displayed start time and the time of the next shifted day line.
  • If the event has a schedule with multiple schedule items and only the displayed start time (red dot), Yesplan sends the displayed start time and the last time in the schedule. If the displayed start time is itself the last time, it will also be selected as the end time and you will not be able to send the times, as the start and end times must be different.
  • If the event does not include a schedule, Yesplan sends the times of the shifted day line.

If Yesplan sends the times of the shifted day line, the times depend on the setting of the shifted day line in Yesplan. With a day line at 07:00, the start time will be 07:00 in the morning and the end time 07:00 in the morning of the next day.

If you send additional fields to your ticketing system, you must fill them out in the ticketing tab. Once that is done, you can click the publication trigger.

Tip

Once the publication succeeds, all fields are automatically sent to your ticketing system when you change a linked field: Yesplan then takes the lead in the integration. This means that the existing values in your ticketing system are overwritten. So only change linked additional fields in Yesplan.

Publication of Multiple Events at Once§

You can also publish multiple events at once by grouping them together in an event group. They then appear in your ticketing system as separate events:

  1. First create the different events. We recommend that you fill out at least the information below:
    • Event name
    • Schedules
  2. If you send additional fields to your ticketing system, you must fill them out in the ticketing tab.
  3. Then group the events or add them to an existing group. For more information, see the section Grouping Events.
  4. Publish the events by clicking the publication trigger:
    • Do this at the level of the event group with the “Publish All Events” button to send all events together.
    • Do this at the level of the event with the “Publish Event” button to send them separately.

Tip

If you use the default fields for the times, Yesplan follows the logic below:

  • If the event has a schedule with a displayed start and end time (the red dots), then Yesplan sends the displayed start and end time. We recommend you work this way.
  • If the event contains a schedule with a single schedule item, containing only the displayed start time (red dot), Yesplan sends the displayed start time and the time of the next shifted day line.
  • If the event has a schedule with multiple schedule items and only the displayed start time (red dot), Yesplan sends the displayed start time and the last time in the schedule. If the displayed start time is itself the last time, it will also be selected as the end time and you will not be able to send the times, as the start and end times must be different.
  • If the event does not include a schedule, Yesplan sends the times of the shifted day line.

If Yesplan sends the times of the shifted day line, the times depend on the setting of the shifted day line in Yesplan. With a day line at 07:00, the start time will be 07:00 in the morning and the end time 07:00 in the morning of the next day.

Publication of a Production§

You can group multiple events under one production, to make them appear in your ticketing system as performances in a series, multiple performances of one event etc. The exact interpretation of a production depends entirely on your ticketing system and we have no control over it in Yesplan. We will only describe below how to mark an event group as a production and send it out:

  1. First create the different events. We recommend that you fill out at least the information below:

    • Event name
    • Schedules
  2. Then group the events or add them to an existing group. For more information, see section Grouping Events.

  3. Click “Set Production” in the bottom left of the event inspector and select the checkbox next to the event group.
  4. Click “Set Production” again to save your changes.
  5. If necessary, fill out additional fields on the ‘Ticketing’ tab.
  6. Publish the production by clicking the publication trigger (at the event group level).

Attention

  • To send productions, the option “Server Supports Productions” must be selected in “Protocol Support”. For more information, see Setting the Protocol.
  • You must specify the production before sending data.
  • You cannot shift productions after you have transferred data.
  • Ticketing systems may impose additional requirements on events that you send as a production. So be sure to ask the manufacturer of your ticketing system or integration what the correct workflow is.

Changing Events§

If you want to change linked fields, this must be done in Yesplan. If a field is changed, Yesplan sends all the fields back to your ticketing system.

Attention

Do not change linked events in your ticketing system. If you do so, these values will be overwritten after the next change in Yesplan.

Copying Events§

In Yesplan, you can copy events that are already linked to your ticketing system. However, these new events are not automatically linked:

  • After copying, click the publication trigger to send them to your ticketing system.
  • Then follow the instructions in your ticketing system.

Tip

Adjust any changed playing times as well.

Deleting Events§

We do not recommend deleting linked events in Yesplan. It is better to give them a certain status, for example, ‘Cancelled’. Depending on your work method, you can also break the link between Yesplan and your ticketing system for the event in question.

Warning

Did you delete a linked event in Yesplan after all? Then you still have to manually delete the corresponding entry in your ticketing system.

Viewing Data from Your Ticketing System§

If you created custom data fields, Yesplan can also show data from your ticketing system (e.g. number of tickets sold). For more information, see Creating Fields for Remote Data.

  • The data is fetched automatically if more than one hour has passed since the relevant tab containing the custom data fields was opened.
  • You can also fetch the data manually using the “Refresh” button to the right of the field.
  • The data for all active events is retrieved automatically from your ticketing system every night if the option “Server Supports Retrieving Events by Month” is selected in “Protocol Support”. For more information, see Setting the Protocol. For this, Yesplan retrieves the data of all active events in the future, and of all active events in the past, going back one year.

Frequently Asked Questions§

Managing Mapping§

How do you manage fields with values that are entered via mapping?

Attention

Your ticketing system must of course support mapping in order to use it in Yesplan.

Creating Mapping§

For example, you want Yesplan to retrieve the options in the selection list for the hall set-up from your ticketing system. Then carry out the steps below in Yesplan:

  1. Create a custom data field of type “Drop-down menu” in “System Settings” > “Events” > “Custom Data” with the keyword ‘ticketing_hall_set_up’.
  2. Navigate to your integration settings in “System Settings” > “Integrations”.
  3. Do the following under “Mapping data for event publish action”:
    • At the bottom of the “Ticketing System value” column, type the technical name of the field in the ticketing system, e.g. ‘Hall_Setup’.
    • In the column “Yesplan value”, select the field ‘ticketing_hall_set_up’ from the drop-down menu.
    • In the “Mapping” column, enter the desired field from your ticketing system in the drop-down menu. This is the field in your ticketing system that contains the options, e.g. the field ‘Hall_Setup’ with the values ‘Standing’, ‘Small Stand’, ‘Large Stand’.
    • Click “Add”.
  4. Do you publish events as productions to your ticketing system? Then repeat these steps in the table under “Mapping data for production publish action”.
  5. Click the “Click to update” button at the top of the page, under “Settings”.

The drop-down menu in Yesplan will now contain the values ‘Standing’, ‘Small Stand’ and ‘Large Stand’.

Editing a Mapped Field§

You have already set up the mapping for a drop-down menu in Yesplan, but you want to change the options in this drop-down menu.

For example, you have a drop-down menu ‘ticketing_hall_set_up’ in Yesplan, which contains the values ‘Standing’, ‘Small Stand’ and ‘Large Stand’. These are defined in the ‘Hall_Setup’ field of your ticketing system. Now you want to add the value ‘Club’:

  1. Add the option ‘Club’ to the ‘Hall_Setup’ field in your ticketing system.
  2. In Yesplan, navigate to your integration settings in “System Settings” > “Integrations”.
  3. Click the “Click to update” button at the top of the page, under “Settings”.

The drop-down menu in Yesplan will now contain the values ‘Standing’, ‘Small Stand’, ‘Large Stand’ and ‘Club’.

Overview of (Un)published Events§

In Yesplan, you can create an overview of events with their publication status in your ticketing system in two ways: via dataviews and via the search language.

Via Dataviews§

The process is described in the dataview examples: see Ticket Publication for more information.

For your ticketing system, you must then do the following:

  • Add the publication trigger for your ticketing system as a column.
  • Filter on “{Publication Trigger} contains off” for all events that are not linked to your ticketing system.
  • Filter on “{Publication Trigger} contains active” for all events that are linked to your ticketing system.

Tip

Also use the date filter in your dataview. If you request many events, it may take some time for all the data to be shown.

Via the Search Language§

You can use the following searches to get an overview in the general search or event search:

  • event:{keyword-of-the-publication-trigger}: active: Display all the events that are linked to your ticketing system.
  • event:{keyword-of-the-publication-trigger}:"": Return all the events that are not linked to your ticketing system.
  • event:{keyword-of-the-publication-trigger}:error: Search all the events where something goes wrong with the link to your ticketing system.