The query API is accessible over HTTP/HTTPS (although HTTP would usually be disabled) and provides read-only access to the database using queries where you can specify arbitrarily complicated conditions to select the right data and also choose which data paths should be included in the response. It can serve data in JSON, XML and HTML formats. It is available on your own system by appending "/webdav/q" to your normal login URL. This means it will look like:

 

https://yourcalpendo/webdav/q

 

Conditional Queries

URLs are of the form:

 

webdav/q/TYPE[?paths=PATHS]

 

or

 

webdav/q/TYPE/EXPR[?paths=PATHS]

 

where

 

Note that any CLOSE items at the end of the URL can be omitted.

 

The relations EQ | NE | LT | LE | GT | GE stand for:

 

- equal

- not equal

- less than

- less than or equal

- greater than

- greater then or equal

 

For example:

 

webdav/q/Workflow/updated/GT/20140526T1200

 

returns the contents of all Workflows that have been modified since noon on May 26, 2014.

 

webdav/q/Workflow/AND/updated/GT/20140526T1200/name/CONTAINS/Thing

 

returns the contents of all Workflows that have been modified since noon on May 26, 2014 and whose name contains the text "Thing".

 

Also, note that if a query is made to ask for data for a repeatable Biskit, then those Biskits with a repeat will be expanded into each instance of the repeat provided the query specifies a range within which the results should be returned. This is necessary to avoid expanding an infinite set of results. The server will attempt to identify the minimum value of the start date/time and the maximum value of the finish date/time. If it can work out both of those from the conditions set on the query, then all Biskits with a repeat will be expanded.

 

For example, in Calpendo if you search for bookings like this:

 

/webdav/q/Booking/AND/id/eq/88/dateRange.finish/gt/20140501-00:00/dateRange.start/lt/20140701-00:00

 

then the bookings will be expanded.

Applicability Of Relations

 

•CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, DOES_NOT_START_WITH, ENDS_WITH and DOES_NOT_END_WITH all apply to String-valued properties and apply case insensitive comparisons.

•INCLUDES_ALL, DOES_NOT_INCLUDE_ALL, INCLUDES_ANY, DOES_NOT_INCLUDE_ANY, GAINED_VALUES, NOT_GAINED_VALUES, LOST_VALUES and NOT_LOST_VALUES only apply to integer properties that are defined as a bit set.

•MEMBER_OF and NOT_MEMBER_OF applies toapplies to two sorts of paths:

1.A path that leads to a group.
 
For Calpendo, this means it applies to Calpendo.CalpendoUser, Calpendo.Project and Calpendo.Resource, and the value compared against would be UserGroup, Calpendo.ProjectGroup and Calpendo.ResourceGroup respectively.
 
For other Exprodo applications, this would apply only to ExprodoUser and the value compared against would be a UserGroup.
 
For example:
 
webdav/q/ExprodoUser/self/MEMBER_OF/UserGroup-7

2.A path that leads to a collection, or through a collection of biskits.
 
For example:
 
webdav/q/ExprodoUser/self/MEMBER_OF/UserGroup-7.users
webdav/q/Calpendo.CalpendoUser/self/MEMBER_OF/Calpendo.Project-4.users
webdav/q/Calpendo.CalpendoUser/self/MEMBER_OF/Calpendo.ProjectGroup-7.projects.owner
webdav/q/Calpendo.CalpendoUser/self/MEMBER_OF/Calpendo.ProjectGroup-7.projects.users

•CONTAINS_MEMBER and DOES_NOT_CONTAIN_MEMBER apply only to groups. For Calpendo, this means it applies to UserGroup, ProjectGroup and ResourceGroup and the value being tested is a CalpendoUser, Project or Resource. For other Exprodo applications, it applies only to UserGroup and the value being tested is an ExprodoUser.

Note that MEMBER_OF, NOT_MEMBER_OF, CONTAINS_MEMBER and DOES_NOT_CONTAIN_MEMBER all require that a value that is a Biskit is provided. This can be done by specifying a string of the form "biskitType-PK" where biskitType is the Biskit's Type, and PK as its primary key.

Time Zones

The dates are formatted like this:

 

  2017-06-12T17:00Z

 

The "Z" is short for "Zulu" and is the standard indication that a time is in UTC. This is close to UK time, but not the same thing.

If the UK is on summer time, they are at UTC+1. There's an inconsistency - the output is all in UTC, but the dates put into the query are interpreted as local time.

 

When asking for "all booking entries for Sunday (06/11) starting from midnight to 11:59 pm"

 

This would be:

 

AND/dateRange.start/ge/20170611-00:00/dateRange.start/lt/20170612-00:00/

Refining Searches

Choosing bookings for particular resources such as MRI1 and MRI2, can be done either by the name of the resources, or by their ID.

 

To do this by name (pseudo code format):

  start >= 20170611-00:00 and start < 20170612-00:00 and (resource.name = MRI1 or resource.name = MRI2)

 

and by resource id (pseudo code format):

  start >= 20170611-00:00 and start < 20170612-00:00 and (resource.id = 1 or resource.id = 2)

 

if MRI1 and MRI2 have IDs 1 and 2.

 

Therefore, the full query line for these are:

 

webdav/q/Calpendo.Booking/AND/dateRange.start/GE/2017061100:00/dateRange.start/LT/2017061200:00/OR/resource.name/EQ/3TW/resource.name/EQ/3TE

 

or

 

webdav/q/Calpendo.Booking/AND/dateRange.start/GE/2017061100:00/dateRange.start/LT/2017061200:00/OR/resource.id/EQ/1/resource.id/EQ/2

Query Data Through Collections

•In a single API call, the user can ask for all the users that own a project in a particular Project Group, or all the users associated with projects in a particular Project Group.

•For example, to find all the users that belong to projects in project group number 7:

webdav/q/Calpendo.CalpendoUser/self/MEMBER_OF/Calpendo.ProjectGroup-7.projects.users

 

•and to find all the owners of projects in project group 9:

webdav/q/Calpendo.CalpendoUser/self/MEMBER_OF/Calpendo.ProjectGroup-9.projects.owner