In the most general form, a Yesplan query consists of three parts:
A few examples:
event:name:Othello(Search all events with ‘Othello’ in the name)
resource:role:sound engineer(Search all resources with a sound engineer role)
The scope of a query determines which type of element you will search in. If you are only looking for events, you use
event as the scope, for resources you use
resource, etc. A summary of scopes at the end of this document displays a list of all scopes supported by Yesplan. Please note that the word scope is written in English even if you set the Yesplan language to Dutch.
The keyword determines which characteristic of an element will be searched. Some examples include
label, etc. A summary of keywords at the end of this document displays a list of valid keywords that you can use in Yesplan as well as the scope in which they are applicable. Please note that the word keyword is written in English even if you set the Yesplan language to Dutch.
The last part of a query is a word . This describes the textual value that you search in within the characteristics that you have indicated based on the keyword. The query
resource:role:sound will search for all resources whose role contains the name ‘sound’. Please note that the word enter in the query (e.g. ‘sound’) only has to be part of the effective value in Yesplan. The previous query will also result in all resources with a ‘sound engineer’ role.
Please note that the word is not case-sensitive; ‘jan’ gives the same results as ‘Jan’.
We will explain the concepts above based on a few examples.
Let’s take a look at the query below:
The scope of this query is
event, the keyword is
name and the word is
The result of this query will be a list of all events whose name contains ‘othello’. The word doesn’t have to match the value of the characteristic exactly; it can be part of the value. In the example below, you see that events with the name “Othello”, “Othello 1”, “Othello 2” and “Othello 3” are displayed as results. Please note that this rule applies to most keywords in which the desired characteristic is a name or a piece of text such as
name. For keywords in which the desired characteristic is a date or a number, the match will have to be exact.
Please note that a word cannot contain spaces. If you want a search term to contain spaces, you must add double quotation marks (
"…") around the words, e.g.
group:name:"The Film Festival"
The result of this query will contain the event group with the name ‘The Film Festival’.
In addition to spaces, a word cannot contain the following symbols:
* # : ( ). These symbols are part of the syntax of the query language. This will become clear in a moment. If you want to include one of these symbols in a word, you must use double quotation marks.
If the type of element that you want to look up is not important, you can omit the scope of a query in the search. If you want to search for all elements in Yesplan that have a ‘rental’ label, you enter the following query:
The result is a list of different types of elements, e.g. an event, a resource and a contact. You’ll find a full summary of keywords that allow this under keywords with default scopes.
Finally, it is also possible to omit the keyword in a query and only enter a word. In that case, the query language will search all elements in Yesplan whose name contains the word.
The result of this query will show the events “Othello”, “Othello 1”, “Othello 2”, “Othello 3”, as well as the event group “Othello production”.
Absence of Values§
A special case that is supported within the query language is an empty word with quotation marks around it (
""). If you use this, then the absence of a value for the keyword will be checked. The query below will request all people who don’t have a label.
The absence of a value is only checked where the keyword is applicable. Under resources, for example, the keyword
team is only applicable on resources of the “Person” type because only such resources can be part of a team. The query below requests all resources in which the
team keyword is applicable, but there is no value. The result is all resources of the “Person” type that are not part of a team. Resources of other types will not appear in the results.
If you need an overview of the events that don’t have a location, you can use the following query:
Please take into account that event groups behave differently:
The first query will only return event groups where none of the events have a location. The second query will only return the event groups where at least one event takes place in the theatre.
Using a Wildcard§
To indicate that it does not matter what the value of a certain characteristic is, you can use a wildcard. The wildcard is written as an asterisk (
*). The wildcard works like the reverse of an empty word (
"") and it checks the presence of a value.
The query below requests all resources of any type:
Please note that when you use a wildcard as a word, it can only give results that have a value for the keyword that you entered.
For example, let’s take a look at the query below:
This query will request all people who have a label; people without a label will not be displayed.
If a keyword is not applicable, it cannot have a value. The query below requests all resources that are part of a team. These will always be resources of the “Person” type: the keyword
team is only applicable on such resources because only they can be part of a team.
The wildcard can also be used as a keyword. The query below will request all contacts for which any characteristic contains the value ‘jan’.
Using Dates and Periods§
The query language offers extensive functionality to ask questions in which the desired characteristic is a certain date or falls in a certain period.
For dates, you can search for an exact match with a certain date. A date is entered in the format
dd-mm-yyyy (day, month, year). The query below will request all events that take place on 28 March 2013.
For keywords where the desired characteristic is a date, different rules apply for finding a match than for textual characteristics. For textual characteristics, there is a match if the value of the characteristic contains the entered word. The match will be exact for dates.
The query language enables you to use a period as a word. A period is noted using two dates that are separated by
TO. Please note that you must separate the dates from the word
TO with a space. There is a match if the date falls within the entered period. For example, we can request all events from 15 March through 30 March 2013 using the query below:
event:date:15-03-2013 TO 30-03-2013
In addition to searching for a specific date or a specific period, the query language also offers some special words that can be used to select by date.
This query uses the word
#today to limit the request to all events that take place today. Similar special words include:
||the date matches tomorrow|
||the date matches yesterday|
||the date falls in the current calendar week; this is the week that starts on the most recent Monday and runs through the next Sunday|
||the date falls in the previous calendar week; this is the week that ends before the most recent Monday|
||the date falls in the next calendar week; this is the week that begins after the next Sunday|
||the date falls in the current calendar month|
||the date falls in the previous calendar month|
||the date falls in the next calendar month|
||the date falls within the current calendar year|
||the date falls within the previous calendar year|
||the date falls within the next calendar year|
||the date falls in the X number of calendar days after today;
||the date falls in the X number of calendar days preceding today;
||the date falls in the X number of calendar weeks following the current calendar week;
||the date falls in the X number of calendar weeks preceding the current calendar week;
||the date falls in the X number of calendar months following the current calendar month;
||the date falls in the X number of calendar months preceding the current calendar month;
||the date falls in the X number of calendar years following the current calendar year;
||the date falls in the X number of calendar years preceding the current calendar year;
Notice that for the
#previousX… keywords, the X must be replaced with a number;
event:date:#nextXdays will not work,
event:date:#next7days will work.
Requesting Custom Data§
With the query language, we can also search for Yesplan elements based on custom data fields. To do this, the custom data field keyword must be used as a keyword in the query. In Yesplan you can have the keywords for custom data fields generated automatically or set them manually.
See the section Keyword for more information about setting keywords automatically or manually in System Settings.
In the example below you see a custom data field with the label “Manager”, which automatically gets the keyword
Then you can request all resources where the “Manager” is “Sarah Peeters” with the following query:
What if you want to retrieve custom data field keywords easily in an inspector? Press the
CTRL-ALT (Windows) or
CTRL-Option (macOS) keys and the field label will change to the keyword. What if you want to copy the keyword? Click the label while holding down the keys.
The picture below shows a custom data field definition with the label “Operator” for which the administrator awarded the keyword ‘operator’.
All resource bookings for which the custom data field has the value “Jan Janssens” can be requested with the following query:
When you manually set a keyword for a custom data field, you cannot use the automatically generated keyword in the query language for that field:
- The query
resourcebooking:production_info_operator:"Jan Janssens"will no longer work if the keyword “operator” has been awarded to that field.
- You can however use
When searching for a Yes/No field, the value must be entered in English. Use the values
false. For example, if you want to request a custom data field to search for damaged resources, you can use the following query:
Finally, you can also search for the publication status of an event in the ticketing integration:
event:publicationtrigger-keyword:activeshows all Yesplan events that are linked with the integration
event:publicationtrigger-keyword:""displays all Yesplan events that are not linked with an integration
event:publicationtrigger-keyword:errorsearches for all Yesplan events where an error occurred when linking with the integration.
Requesting Numeric Fields§
For keywords where the desired characteristic is a number, different rules apply for finding a match than for textual characteristics.
For textual characteristics, there is a match if the value of the characteristic contains the entered word. For example, the query
event:name:othello will find an event named “Othello” as well as an event named “Othello 2”.
For numbers, there is a match if the value matches exactly. For example, if
free_seats is the keyword of a numeric custom data field, the result of the query
event:free_seats:23 will only find events for which the value of the custom data field is exactly ‘23’ and not events where the value of the custom data field is ‘123’ or ‘234’.
Please note that this exact match is not valid for regular input fields where you (sometimes or always) enter a number. A numeric input field is a specific type of custom data field.
Requesting Addresses of Contacts§
A contact can have one or more addresses. Each of these addresses is of a certain address type. Per contact, there is always one address marked as “default”, the default address. Address types are managed via the system settings.
country code always request the default address. The query language also foresees keywords for all the different types of addresses that a contact can have. These variants are formed by the default keyword, preceded by the name of the address type and an
For example, for the “Billing” address type the keywords are
Please note: when composing the keyword, the same rules apply as for the automatic awarding of keywords for custom data fields: spaces and special characters (such as
! ? ; etc.) are deleted and capital letters are converted to lower case letters. (An administrator can find the keyword in the system settings under the “Contacts” tab under “Address Types”.)
For example, for the “Headquarters” address type the keywords are
The variants of the keywords always request the address of a certain address type, whether this address is marked as the default address or not.
For example, with the query
contact:city:Gent you search for all contacts whose city contains “Gent” in the default address. With the query
contact:billing_city:Gent you search for all contacts whose city contains “Gent” in the “billing” type of address.