Generic Ticketing Introduction

Yesplan allows customers to add integrations with ticketing services:

Yesplan provides components that send API calls.
The ticketing service provides an API with endpoints for those calls.

This page provides an overview of how Yesplan works, how integrations with ticketing services are supposed to work, and some general tips.

Tip

See the Generic Ticketing API page for a detailed specification of the API.

Workflow§

Typical Workflow in Yesplan§

Yesplan is a SaaS venue management system that is used in the organization of events, both cultural (e.g. a concert) and commercial (e.g. a conference). Customers can arrange Yesplan to reflect their own internal workflows, but a typical workflow you encounter a lot is the following:

An event is booked on one or more dates and in a specific location. It is assigned the status ‘Option’, because it isn’t certain yet that the event will actually take place (or when).
There is a conversation with a representative of the artist (or with the customer for commercial events) about the final date and the conditions of the event (financial, ticket prices, technical rider, hospitality rider, shares of revenue etc.).
If an agreement is reached, the event is assigned the status ‘Confirmed’, because it will now certainly take place. Any other options that didn’t make it are removed from Yesplan.
The event is prepared: book technical equipment, technicians, catering, hotel rooms, set up schedule (soundcheck, artist dinner, doors, actual performance, breaks) etc. Additional events may be created for rehearsals, dressing rooms, reception in the foyer…
At some point, the event is made available for sale by clicking a so-called publication trigger in Yesplan. This sends information about the event with the performance to a ticketing service, where the actual sale is organized.
Often, Yesplan also retrieves information about the event from the ticketing service, such as number of sold tickets, number of available tickets etc.
The event takes place.
The event is brought to a close. It is assigned a status such as ‘To be invoiced’ or ‘To be processed’. Typical steps now are an evaluation, creating a settlement, sending information to an accounting system to pay/send invoices, logging problems encountered during the event for future reference etc.
The event is actually closed. It receives a status such as ‘Finished’, ‘Processed’ or ‘Closed’.

The crucial steps for an integration with a ticketing service are of course step 5 and step 6, so we will discuss them in more detail in the next section.

Detailed Flow for a Ticketing Integration§

Once an event is ready to go on sale, the following actions occur:

A Yesplan user clicks a so-called publication trigger, which is a button that launches a call to the API of the ticketing service. By default, this call always contains the following information (but more fields can be sent):
- Yesplan ID: Of type “ID String”. It is the unique ID for the event in Yesplan. Adding this ID to an entity in the ticketing service ensures that there is a unique link between the two systems for the event in question.
- Name: Of type “String”. This is the name of the event in Yesplan, e.g. ‘Hamlet’.
- Location: Of type “String”. This is the location of the event in Yesplan, e.g. ‘Great Hall’.
- Start Time: Of type “Date-Time String”. This is the start time of the performance in Yesplan.
- End Time: Of type “Date-Time String”. This is the end time of the performance in Yesplan.
After publication, any changes to fields in Yesplan that are linked to the ticketing service will be sent to the ticketing service automatically and updated there.
- For instance, if the location of an event is changed in Yesplan after its publication, then the new location will be sent to the ticketing service automatically and updated there.
- In other words, for fields sent from Yesplan to the ticketing service, Yesplan leads the integration with respect to the contents of these fields.
- Of course, you can limit these updates in specific cases (e.g. don’t allow an update of the location if tickets are already being sold).
Users process the entity in the ticketing service further:
- They assign a seating plan, ranks, ticket prices, subscriptions.
- They manage links with the venue’s websites, box office, ticketing module etc.
Yesplan can retrieve information from the ticketing service and display it on the event, for instance the number of sold and available tickets.

Tip

Do you already want more information about possible fields to exchange? See the following sections:

Data Model in Yesplan§

Events, Event Groups and Productions§

So far, this introduction always talked about sending information about an event. However, Yesplan also contains event groups and productions.

An event can be any of the following:
- A single event, e.g. a jazz concert ‘Branford Marsalis’.
- Part of a series of events, e.g. five performances of ‘Hamlet’ on Monday, Tuesday, Wednesday, Thursday and Friday.
- Part of a series of events on one night, e.g. the main act ‘Metallica’ and the support act ‘Weezer’ that play before the main performance.
- An event with no relation to ticketing whatsoever, such as an event that books a dressing room for the actors in ‘Othello’.
An event group can contain events or other event groups:
- The group ‘Hamlet’ can contain the five events directly.
- The group ‘Metallica’ can contain the two events for the main act and the support act.
- However, there will often be more than one subgroup: ‘Othello’ can have a subgroup ‘Dressing Rooms’ for the dressing rooms, a subgroup ‘Rehearsals’ for any rehearsals and a subgroup ‘Performances’ for the performances. Only the latter is relevant for ticketing.
An event or an event group can be marked as a production. The interpretation of a production depends on how you implement the integration:
- It could be an event group that contains a series of repeated performances, which should receive separate ticketing sales, like the ‘Hamlet’ example: one ticket sale for every event.
- It could be an event group that contains a series of events that are part of one single performance, like the ‘Metallica’ example: one ticket sale for both events together.
- Other options are possible, depending on the ticketing service’s own data model.

Remark

If the ticketing system supports productions, Yesplan can still send an individual event even if it isn’t explicitly marked as a production or part of one. In that case, Yesplan will always create a production in the ticketing system for this individual event.

When a publication trigger is clicked, the calls to the ticketing service’s API depend on the level of the trigger:

On an single event, only information about that event is sent:
- The trigger on ‘Branford Marsalis’ will only send information about ‘Branford Marsalis’.
- The trigger on the Monday performance of ‘Hamlet’ will only send information about that single event, not about the events on the other days.
On an event group, information is sent about all the separate events in the event group:
- The trigger on ‘Hamlet’ will send information for the five events in that group: Monday, Tuesday, Wednesday, Thursday and Friday. In other words, one click results in five calls. In the ticketing service, this will result in five separate ticket sales.
- The trigger on ‘Othello’ will send information about all the events in that group and its subgroups: dressing rooms, rehearsals and performances.
- The trigger on ‘Othello’ > ‘Performances’ will send information about the events in that subgroup, so only about performances.

Remark

Implementing the notion of a production is optional. Not every ticketing service uses this concept in their integrations.
Whether setting a production has any meaning in the integration can be set in the protocol. See Integration Protocol for more information.

System Data and Custom Data§

There is a strict disctinction in Yesplan between system data and custom data:

Every installation of Yesplan comes with the same system fields, such as Yesplan ID, event name, status, profile, location etc.
Yesplan customers can also add their own custom fields on top of these system fields. Examples we often see for events are title, subtitle, genre, attachments for riders, points of contact, duration etc.

Both system data and custom data can be sent from Yesplan to the ticketing service.

Exchanging Data§

Basic Fields from Yesplan to the Ticketing Software§

When clicking the publication trigger, the following system fields are sent to the ticketing service by default:

Yesplan ID: Of type “ID String”. You can identify it using event-id for events and event groups, and production-id for productions.
Name: Of type “String”. You can identify it using name.
Location: Of type “String”. You can identify it using location.
Start Time: Of type “Date-Time String”. You can identify it using starttime. This is the so-called displayed start time of the event. See Determining the Displayed Start and End Times for more information.
End Time: Of type “Date-Time String”. You can identify it using endtime. This is the so-called displayed end time of the event. See Determining the Displayed Start and End Times for more information.

However, Yesplan customers can use custom data fields instead (except for the Yesplan ID):

Field	Type of Custom Data Field
`name`	Input field
`location`	Drop-down menu
`starttime`	Date-time field
`endtime`	Date-time field

The logic is the following:

If the custom data field contains a value, then the value of the custom data field is sent.
If the custom data field doesn’t contain a value, then the value of the system field in question is sent.

Additional Fields from Yesplan to the Ticketing Software§

In many integrations, we see that additional custom data fields are sent from Yesplan to the ticketing service. However, here are some points of attention:

If values are sent for these fields, then they should be managed in Yesplan. In principle, every change to a field in Yesplan causes an update to the corresponding field in the ticketing service.
Yesplan is not a ticketing service. Ask yourself which data is useful to be exchanged and which system is best suited to manage these data.
Not every field in the list will be relevant for every ticketing service.

The additional custom data fields are:

Title
Subtitle
Genre/Category/Label
Reference/Account number/Project-ID
Intermission (yes,no)
Duration
Organizer/Agent/Impresario
Prices list
Seating plan
Template
Date presale starts
Memo/Remarks/Notes
Season
Deal / Dealtype / Deal values

Fields from the Ticketing Software to Yesplan§

Once an event has been sent to the ticketing service, Yesplan can also retrieve fields from the ticketing service and display them on the event in question, using a custom data field of type “Remote Data”. In order to make a field available for Yesplan, the ticketing service must of course add it to its API. Fields that are often sent back to Yesplan are:

Ticketing event ID
Capacity
Number of sold tickets
Number of available tickets
Number of free admissions
Number of returned tickets
Number of scanned tickets
Blocked seats
Wheelchair seat(s)
Surcharges (amount)
Turnover/Revenue Sales Price Incl. VAT (amount)
Turnover/Revenue Sales Price Excl. VAT (amount)

Yesplan uses the following scheme to retrieve the values from the ticketing service:

The data for active events is fetched from the ticketing service every night if the option “Server Supports Retrieving Events by Month” is selected in “Protocol Support”. For more information, see Integration Protocol. Yesplan fetches all active events in the future, and the active events up to one year in the past.
The data is fetched automatically if a user opens the custom tab in Yesplan containing the custom data field and if the field in question wasn’t updated in the last minute.
Users can also fetch the data manually using the “Refresh” button on a remote data field.

Tip

If an event is marked as “closed” in the API of the ticketing service, then Yesplan will no longer retrieve any data for it.

Mapping Fields§

Some fields exist in both Yesplan and the ticketing service, and you want to make sure that they contain the same values. This can be achieved by mapping them. Let us look at two examples: event type and locations.

Event Type§

In this example, you align the event types in Yesplan and the ticketing service:

Let’s assume that the ticketing service contains a field for the event type, containing the values ‘Pop’, ‘Rock’, ‘Blues’, ‘Jazz’ and ‘Flamenco’.
The ticketing service provides an endpoint in the API with this field name, the five values, and for every value a unique string.
In Yesplan, you create a custom data field of the type “Drop-down menu” for the event type.
In the settings for the integration, you map the Yesplan event field to the field in the ticketing service. Yesplan retrieves the field values and unique strings using the endpoint in the API.
End users in Yesplan will see a drop-down menu for the event type containing the values ‘Pop’, ‘Rock’, ‘Blues’, ‘Jazz’ and ‘Flamenco’.
When the event is sent to the ticketing service, Yesplan will send the unique string for the selected value.
If the list of values is edited in the ticketing service, it also changes in its API and it can be updated in Yesplan. In other words, the ticketing service leads in the integration with respect to mapped fields.

Location§

Both Yesplan and the ticketing service often contain a location. However, their values may differ:

Yesplan may have a location ‘Great Hall’, with three setups: ‘Box’ (900 standing places), ‘Flex’ (840 standing places and 300 seats) and ‘Theater’ (700 seats).
However, in the ticketing service, these are three separate locations: ‘Great Hall – Box’, ‘Great Hall – Flex’ and ‘Great Hall – Theater’.
Yesplan should send the correct values to the ticketing service, because these are the names that will appear on the tickets.

This can be achieved by mapping a custom data field in Yesplan onto a field in the ticketing service:

The ticketing service contains a field for the location, containing the values ‘Great Hall – Box’, ‘Great Hall – Flex’ and ‘Great Hall – Theater’.
The ticketing service provides an endpoint in the API with this field name, the three values, and for every value a unique ID.
In Yesplan, you create a custom data field of the type “Drop-down menu” for the location.
Do the following in the settings for the integration:
- Map the Yesplan custom data field for the location to the field in the ticketing service. Yesplan retieves the field values and IDs using the endpoint in the API.
- Specify that the ‘Location’ custom data field has to be sent instead of the “Location” system field if the former contains a value. See Basic Fields from Yesplan to the Ticketing Software for more information.
End users in Yesplan will see a drop-down menu for the location containing the values ‘Great Hall – Box’, ‘Great Hall – Flex’ and ‘Great Hall – Theater’.
When the event is sent to the ticketing service, Yesplan will send the ID for the selected value in the drop-down menu. If no value is selected there, Yesplan will send the value of the system field for the location: ‘Great Hall’. See Basic Fields from Yesplan to the Ticketing Software for more information about this logic.
If the list of values is edited in the ticketing service, it also changes in their API and it can be updated in Yesplan. In other words, the ticketing service leads in the integration with respect to mapped fields.

Tip

Do you want to know the specific steps to update the values of a mapped field? Then read Editing a Mapped Field.

Division of Work§

In a ticketing integration, how is the work divided between Yesplan and the ticketing service?

Yesplan§

Yesplan provides the following:

The publication trigger, which can make an API call using the methods GET, PUT and DELETE.
Custom data fields of type “Remote Data”, which can make an API call using the method GET, to retrieve data from the ticketing service.
Custom data fields of type “Drop-down menu”, which can make an API call using the method GET, to populate these fields with options from the ticketing service.

Ticketing Service§

The ticketing service provides an API with the following:

Endpoints for the calls from Yesplan
Correct responses for these calls
Pairs of fields and values in the correct data format

The specific requirements can be found in the Generic Ticketing API page.

Integration Protocol§

Not every ticketing service needs to implement all features when integrating with Yesplan. The integration can be limited in three ways:

Productions: a ticketing service can decide not to implement any logic for this concept from Yesplan.
Deletion: a ticketing service can decide not to add any logic to the DELETE method of the publication trigger.
Nightly retrieval: a ticketing service can decide not to allow the nightly retrieval of data for active events.

These limitations are set in the section “Protocol Support” of the settings page of the integration in Yesplan. See Setting the Protocol for more information.

Tips§

Field for Yesplan ID§

We strongly advise to add a field on events in the ticketing service where users can manually add the Yesplan ID of the corresponding event in Yesplan.

Strictly speaking, you can only link events from Yesplan to events in a ticketing service by publishing the event from the former to the latter.
However, this is problematic if both systems already contain events for the same performance when setting up the integration (which is often the case). Publishing the event in Yesplan will create a duplicate in the ticketing service.
In practice, this is often circumvented by setting up the integration at the beginning of a season or planning cycle. But this creates bottlenecks.
The field for the Yesplan ID allows customers to link events that already exist in both systems, which will remove any bottlenecks to start up an integration.

Delete§

Yesplan offers the method DELETE via the publication trigger. What this method actually triggers in the ticketing service is up to the developers of the ticketing service. However, two points of advice:

Bear in mind that the DELETE method is optional. See Integration Protocol for more information.
If the ticketing service does implement the DELETE method, we strongly advise against letting it actually delete an event in the ticketing service. The behavior we often see is that the DELETE method breaks the link between the events in the two systems, and that the actual events remain.