Reservations

findReservations

Query for reservations

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
BeginTime	iCalTimeString	Find reservations from. See also Time Stamps
EndTime	iCalTimeString	Find reservations to
BeginModified	iCalTimeString	Find reservations that have been modified starting from this date and time (including this date time). Check getOffsetDateTime
EndModified	iCalTimeString	Find reservations that have been modified before this date and time (excluding this date time)
ReservationSituation	String	Reservation situations to search for. Check getReservationSituation
SearchObjects	Object[]	Objects that should be present on the reservations either directly or through membership. Info reservations, depending on the ReservationStatusList parameter, may also be included which do not contain any objects. Check findObjects
ExactSearchFields	FieldValue[]	Array of fields and search criteria. Use for category fields and boolean fields only. Check findReservationFields
GeneralSearchFields	String[]	Fields that should be used for free text search. Check findReservationFields
GeneralSearchString	String	Search string to use on GeneralSearchFields
Types	String[]	For typed reservations. Check getSpecialTypes
ReservationStatusList	String[]	List of one or more reservation status to search for. For more info, see getReservationStatus
AllReservations	Boolean	Find all reservations or only those created or modified by the authenticated user
SortOrder	String	The sorting order for the reservations matching the query. Check getReservationSortOrders
ReturnFields	String[]	The fields to include on the reservations matching the query. Check findReservationFields
ReturnTypes	TypeField[]	Array of the object types and fields for each object type to include on the matching reservations. Check getAllFields for which fields to use. Note that if info reservations are returned, depending on the ReservationStatusList parameter, these reservations will never contain objects of any type, regardless of this parameter.
BeginIndex	Int	Index of the first reservation to return (for pagination)
NumberOfReservations	Int	Maximum number of reservations to return (capped at 1000 per query, use BeginIndex to paginate over the reservations). Check getLimitations

Returns

Return	Type	Description
Reservations	Reservation[]	Array of all reservations matching the query, with the fields and objects specified in ReturnFields and ReturnTypes
TotalNumOfReservations	Int	Total number of reservations matching the query

Example

Request

<tns:begintime>20191201T000000</tns:begintime>
<tns:endtime>20191224T000000</tns:endtime>
<tns:beginmodified></tns:beginmodified>
<tns:endmodified></tns:endmodified>
<tns:reservationsituation></tns:reservationsituation>
<tns:searchobjects>
  <object>
    <extid>the_external_id_of_a_room</extid>
    <type>room</type>
  </object>
</tns:searchobjects>
<tns:exactsearchfields>
</tns:exactsearchfields>
<tns:generalsearchfields>
</tns:generalsearchfields>
<tns:generalsearchstring></tns:generalsearchstring>
<tns:types>
</tns:types>
<tns:reservationstatuslist>
  <status>B_COMPLETE</status>
  <status>B_INCOMPLETE</status>
  <status>C_CONFIRMED</status>
  <status>C_PRELIMINARY</status>
</tns:reservationstatuslist>
<tns:allreservations>true</tns:allreservations>
<tns:sortorder>ID_ASCENDING</tns:sortorder>
<tns:returnfields>
  <field>reservation.commment</field>
</tns:returnfields>
<tns:returntypes>
  <typefield>
    <type>room</type>
    <field>room.name</field>
    <field>room.seats</field>
  </typefield>
  <typefield>
    <type>course</type>
    <field>course.name</field>
    <field>course.code</field>
  </typefield>
</tns:returntypes>
<tns:beginindex>0</tns:beginindex>
<tns:numberofreservations>1000</tns:numberofreservations>

getReservations

Get reservations by reservation ids

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservations	String[]	Array of ids for the reservations to get
ReturnTypes	TypeField[]	Array of the object types and fields for each object type to include on the matching reservations
UseUTC	Boolean	Indicate whether the reservation timestamps should be in UTC or in local time

Returns

Return	Type	Description
Reservations	Reservation[]	Array of the requested reservations

Example

Request

<tns:reservations>
  <reservation>47216</reservation>
</tns:reservations>
<tns:returntypes>
  <typefield>
    <type>room</type>
    <field>room.name</field>
    <field>room.seats</field>
  </typefield>
</tns:returntypes>
<tns:useutc>false</tns:useutc>

findReservationTypes

Get valid object types on different reservation types

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Types	String[]	Search for other valid object types on reservations that include these object types
ReservationSituation	String	Reservation situations to filter for
IgnoreAlias	Boolean	Return types with or without potential alises
ActiveOnly	Boolean	Return types from active templates only. Defaults to false

Returns

Return	Type	Description
Types	Type[]	Array of valid types on reservations

Example

Request

<tns:types>
  <type>course</type>
</tns:types>
<tns:reservationsituation></tns:reservationsituation>
<tns:ignorealias>false</tns:ignorealias>
<tns:activeonly>true</tns:activeonly>

findReservationFields

Get valid fields on reservations of different types

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Types	String[]	Search for reservations including these object types
ReservationSituation	String	Reservation situations to filter for
ActiveOnly	Boolean	Return fields from active templates only. Defaults to false

Returns

Return	Type	Description
Fields	Field[]	Array of valid fields on reservations

Example

Request

<tns:types>
  <type>group</type>
</tns:types>
<tns:reservationsituation></tns:reservationsituation>
<tns:activeonly>true</tns:activeonly>

getReservationSituations

Get the available reservation situations.

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
ReservationSituationKind	String	The kind of reservation situations that are to be returned. The default kind is reservation. See also getReservationSituationKinds.

Returns

Return	Type	Description
ReservationSituations	ReservationSituation[]	Array of available reservation situations

Example

Request

getReservationSituationKinds

Get the available reservation situation kinds.

These values can be used in getReservationSituations as parameter ReservationSituationKind.

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key

Returns

Return	Type	Description
ReservationSituationKinds	ReservationSituationKind[]	Array of available reservation situation kinds to be used with getReservationSituations.

Example

Function response from July 31, 2020

<reservationsituationkinds>
    <reservationsituationkind>
        <name>RESERVATION</name>
        <description>...</description>
    </reservationsituationkind>
    <reservationsituationkind>
        <name>AVAILABILITY</name>
        <description>...</description>
    </reservationsituationkind>
</reservationsituationkinds>

getReservationSortOrders

Get available reservation sort orders

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key

Returns

Return	Type	Description
SortOrders	String[]	Array of available sort orders for reservations

Example

Request

getReservationStatus

There are currently four different groups of status; labeled A-D. If no status is given in the status list of findReservations the reservations that correspond to the first item in each group is obtained. So as default reservations with status A_RESERVATION, B_COMPLETE, C_CONFIRMED and D_TIME are returned. If we also want to obtain incomplete reservations we would have to add this to the status list parameter and also add complete reservations. So the list B_COMPLETE, B_INCOMPLETE gives us both of them. If we just send in B_INCOMPLETE we only get those reservations. If we also want the preliminary reservations and not only the confirmed reservations we will have to add C_CONFIRMED, C_PRELIMINARY to the status list parameter. If we want both complete and incomplete as well as confirmed and preliminary reservations we will need to send this list: B_COMPLETE, B_INCOMPLETE, C_CONFIRMED, C_PRELIMINARY.

If we would like to get all reservations that have a begin and end time we will use this status list: B_COMPLETE, B_INCOMPLETE, C_CONFIRMED, C_PRELIMINARY, C_PLANNED, C_REQUESTED, C_REJECTED.

The reservations returned will not contain the different default status listed above. If a reservation is B_COMPLETE this status will not be on the reservation. If on the other hand the reservation is B_INCOMPLETE this status will be in the status list of the reservation. Most reservations will have an empty status list meaning that they have the following status A_RESERVATION, B_COMPLETE, C_CONFIRMED and D_TIME.

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key

Returns

Return	Type	Description
Status	Status[]	Array of valid reservation statuses

Example

Current list of status

A_RESERVATION - Status for standard type reservations
A_AVAILABILITY - Status for availability type reservations
A_INFO - Status for info type reservations

B_COMPLETE - Status for complete reservations
B_INCOMPLETE - Status for incomplete reservations

C_CONFIRMED - Status for accepted reservations that are definitive
C_PRELIMINARY - Status for preliminary reservations
C_PLANNED - Status for planned reservations
C_REQUESTED - Status for reservation requests
C_REJECTED - Status for rejected reservation requests

D_TIME - Status for reservations with begin and end time
D_WAITING_LIST - Status for reservations that don't have begin or end time

validateReservations

Validate new reservations without importing them

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservations	Reservation[]	Array of reservations to validate
AllowIncomplete	Boolean	Allow incomplete reservations in validation
ReservationSituation	String	Reservation situation to use in validation

Returns

Return	Type	Description
Status	Status[]	Array of validation status per reservation. A status of 0 indicates the reservation was successfully validated

Example

Request

<tns:reservations>
    <reservation>
        <begin>20190605T103000</begin>
        <end>20190605T120000</end>
        <objects>
            <object>
                <type>staff</type>
                <value>d7ae3d30-6510-4cf3-8f5f-f4fb238e488d</value>
            </object>
            <object>
                <type>staff</type>
                <value>2ff60334-86ee-4834-867a-8b9c4de072e0</value>
            </object>
            <object>
                <type>activity</type>
                <value>fe1835f8-97c8-400b-9440-19e07e216c5e</value>
            </object>
            <object>
                <type>company</type>
                <value>be7a66d4-7ba2-4e86-b3ea-1f436b7adc63</value>
            </object>
            <object>
                <type>project</type>
                <value>45e7140c-a38c-410b-9fa0-c1708af1b390</value>
            </object>
            <object>
                <type>contact</type>
                <value>4d10f5a3-7b4d-4716-99ab-e84de13efbfe</value>
            </object>
            <object>
                <type>place</type>
                <value>3becbee1-d3b8-4998-8af2-21aa34f06f89</value>
            </object>
        </objects>
        <fields>
            <field>
                <extid>reservation.comment</extid>
                <value>Bring pencil</value>
            </field>
        </fields>
        <organizations>
            <organization></organization>
        </organizations>
    </reservation>
</tns:reservations>
<tns:allowincomplete>true</tns:allowincomplete>
<tns:reservationsituation></tns:reservationsituation>

importReservations

Import reservations

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservations	Reservation[]	Array of reservations to import
AllowIncomplete	Boolean	Allow incomplete reservations in import
ReservationSituation	String	Reservation situation to use for the import

Returns

Return	Type	Description
Status	Status[]	Array of import status per reservation. A status of 0 indicates the reservation was successfully imported

Example

Request

<tns:reservations>
    <reservation>
        <begin>20190605T103000</begin>
        <end>20190605T120000</end>
        <objects>
            <object double="true">
                <type>staff</type>
                <value>d7ae3d30-6510-4cf3-8f5f-f4fb238e488d</value>
            </object>
            <object double="true">
                <type>staff</type>
                <value>2ff60334-86ee-4834-867a-8b9c4de072e0</value>
            </object>
            <object>
                <type>activity</type>
                <value>fe1835f8-97c8-400b-9440-19e07e216c5e</value>
            </object>
            <object>
                <type>company</type>
                <value>be7a66d4-7ba2-4e86-b3ea-1f436b7adc63</value>
            </object>
            <object>
                <type>project</type>
                <value>45e7140c-a38c-410b-9fa0-c1708af1b390</value>
            </object>
            <object>
                <type>contact</type>
                <value>4d10f5a3-7b4d-4716-99ab-e84de13efbfe</value>
            </object>
            <object>
                <type>place</type>
                <value>3becbee1-d3b8-4998-8af2-21aa34f06f89</value>
            </object>
        </objects>
        <fields>
            <field>
                <extid>reservation.comment</extid>
                <value>Bring pencil</value>
            </field>
        </fields>
        <organizations>
            <organization>SomeOrg</organization>
        </organizations>
    </reservation>
</tns:reservations>
<tns:allowincomplete>true</tns:allowincomplete>
<tns:reservationsituation></tns:reservationsituation>

importReservationsOtherUser

Import reservations impersonating another user with the permissions of that user. Also uses thenewmodifiedby import tag

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservations	Reservation[]	Array of reservations to import including newmodifiedby tag
AllowIncomplete	Boolean	Allow incomplete reservations in import
ReservationSituation	String	Reservation situation to use for the import
User	User	The user that is impersonated by this import, the same user as in newmodifiedby tag

Returns

Return	Type	Description
Status	Status[]	Array of import status per reservation. A status of 0 indicates the reservation was successfully imported

Example

Request

<tns:reservations>
    <reservation>
        <begin>20190605T103000</begin>
        <end>20190605T120000</end>
        <objects>
            <object>
                <type>room</type>
                <value>room_SomeGroupRoom</value>
            </object>
            <object>
                <type>student</type>
                <value>StudentObject</value>
            </object>
        </objects>
        <fields>
            <field>
                <extid>reservation.comment</extid>
                <value>This is very we study stuff</value>
            </field>
        </fields>
        <organizations>
            <organization>SomeOrg</organization>
        </organizations>
        <newmodifiedby>
            <loginname>StudentUserName</loginname>
            <authserver>Students_SAML2</authserver>
        </newmodifiedby>
    </reservation>
</tns:reservations>
<tns:allowincomplete>true</tns:allowincomplete>
<tns:reservationsituation>StudentGroupRoomBooking</tns:reservationsituation>
<tns:user>
    <loginname>StudentUserName</loginname>
    <authserver>Students_SAML2</authserver>
</tns:user>

exportReservations

Export reservations

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservations	String[]	Array of ids for the reservations to export
ExcludeId	Boolean	Flag to exclude ids in the export
UseUTC	Boolean	Indicates whether the reservation timestamps should be in UTC or in local time

Returns

Return	Type	Description
Reservations	Reservation[]	Array of reservations requested

Example

Request

<tns:reservations>
  <reservation>2</reservation>
</tns:reservations>
<tns:excludeid>true</tns:excludeid>
<tns:useutc>false</tns:useutc>

deleteReservations

Delete reservations

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservations	String[]	Array of ids for the reservations to delete

Returns

Return	Type	Description
Status	Status[]	Array of statuses for the deletion request

Example

Request

<tns:reservations>
  <reservation>427</reservation>
</tns:reservations>

deleteReservationsOtherUser

Delete reservations using the permissions of an impersonated user

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservations	String[]	Array of ids for the reservations to delete
User	User	The user that is impersonated by this delete reservation

Returns

Return	Type	Description
Status	Status[]	Array of statuses for the deletion request

Example

Request

getModifiableReservationFields

Get the reservation fields the currently authenticated user has permissions to modify

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservation	String	Id of the reservation to get modifable fields for

Returns

Return	Type	Description
Fields	FieldValue[]	Array of the fields the authenticated user has permissions to modify

Example

Request

<tns:reservation>6559</tns:reservation>

setModifiableReservationFields

Set values of modifable reservation fields

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservation	String	Id of the reservation to set modifable fields of
Fields	FieldValue[]	Array of fields and values to set for the given reservation

Returns

Return	Type	Description
Status	Status	Status of the requested operation

Example

Request

<tns:reservation>5698</tns:reservation>
<tns:fields>
  <field>
    <extid>reservation.comment</extid>
    <value>Bring a pen</value>
  </field>
</tns:fields>

getReservationsHistory

Get audit trail for reservations

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Reservations	String[]	Array of ids for the reservations to get audit trails for
ReturnTypes	TypeField[]	Array of the object types and fields for each object type to include on the matching cancelled reservations
UseUTC	Boolean	Indicate whether the reservation timestamps should be in UTC or in local time

Returns

Return	Type	Description
Reservations	Reservation[]	Array of array of reservation history

Example

Request

<tns:reservations>
  <reservation>234774</reservation>
</tns:reservations>
<tns:returntypes>
</tns:returntypes>
<tns:useutc>false</tns:useutc>