ROOMZ Connector

Content

Overview

The ROOMZ display gets its information from a ROOMZ server. This ROOMZ server interacts with the company's booking system, such as Microsoft Exchange, IBM Domino or Google Calendar. It will read and update information using an API. Each system has its own API.  

In order to support other booking systems, ROOMZ has developed a generic connector. This connector will exchange information with any booking system providing the AP following the contract specified in the following sections:

Conventions

The following conventions have been applied for the definition of the API:

  • The API is communicating using RESTful calls

  • The returned content is in JSON format

  • The date and time are always in UTC and ISO8601 format https://www.w3.org/TR/NOTE-datetime  ("YYYY-MM-DDThh:mm:ssZ")

  • The success of the calls is identified by the HTTP status code(e.g. 200=OK, 401=Unauthorized)

  • There is no null value

Authentication and Encryption

All the requests are executed using a HTTP Basic Authentication. As the credentials are readable, it is highly recommended to provide access to the API with HTTPS only (HTTP over TLS).

Overview

The API must support the following calls:

Method

URL

Description

Method

URL

Description

GET

/rooms

Get the list of rooms

GET

/rooms/roomId/meetings

Get the list of meetings of a room

POST

/rooms/roomId/meetings

Create a new meeting

PUT

/rooms/roomId/meetings/meetingId

Update an existing meeting

Scenario:

  • When associating a ROOMZ display with a room's calendar, the list of rooms will be suggested

  • The list of meeting will be requested in order to represent the room's calendar on the display

  • The user can book a room directly on the ROOMZ display for a specified duration

  • When any meeting is finished earlier as plan, the user can directly release the room on the screen. The endDate of the current meeting will be modified

The next sections will describe each call in more details.


Get the list of rooms

Request:

Method

URL

Method

URL

GET

/rooms

Response:

Format

Structure

Format

Structure

JSON

Room [ ]

Room is composed by the following properties:

Property

Type

Description

Example

Property

Type

Description

Example

roomId

String

The identifier of the room

"r212"

name

String

The name of the room

"Weisshorn"

Example of response body:

[{"roomId":"57","name":"Weisshorn"},{"roomId":"22","name":"Moleson"}]

Possible HTTP response status codes expected:

  • OK --> 200

  • Unauthorized -> 401

Get the room's meetings

Request:

Method

URL

Method

URL

GET

/rooms/roomId/meetings?from=2010-12-31T14:00:00Z&to=2013-01-01T08:00:00Z

  • roomId refers to the room identifier

  • from is in ISO8601 UTC format ("YYYY-MM-DDThh:mm:ssZ"), is optional and corresponds to "greater or equal to" (>=)

  • to is in ISO8601 UTC format ("YYYY-MM-DDThh:mm:ssZ"), is optional and corresponds to "smaller or equal to" (<=)

Response:

Format

Structure

Format

Structure

JSON

Meeting [ ]

Meeting is composed by the following properties:

Property

Type

Description

Example

Property

Type

Description

Example

meetingId

String

The identifier of the meeting

"m1234"

subject

String

The subject of the meeting

"Product Review"

organizerId

String

The identifier of the organizer

"u567"

organizerName

String

The name of the organizer

"John Doe"

startDateUTC

String

The start date&time of the meeting

"2012-12-20T14:30:00Z"

endDateUTC

String

The end date&time of the meeting

"2012-12-20T16:30:00Z"

creationDateUTC

String

The creation date&time of the meeting

"2012-12-10T16:30:00Z"

isPrivate

Boolean

Is the meeting subject confidential

false

isCancelled

Boolean

Is the meeting cancelled

false

Remark:

  • If the information creationDateUTC is not managed by the booking system, the value must be the same as the startDateUTC

  • If the flag isPrivate is not managed by the booking system, the returned value must always be false

  • If the flag isCancelled is not managed by the booking system, the returned value must always be false

Example of response body:

[{"meetingId":"m123","subject":"Product Review", "organizerId":"u123","organizerName":"John Doe","startDateUTC": "2012-12-20T10:00:00Z","endDateUTC":"2012-12-20T12:00:00Z", "creationDateUTC": "2012-12-18T10:00:00Z", "isPrivate":false, "isCancelled":false}, {"meetingId":"m456","subject":"Strategy","organizerId":"u445,"organizerName":"Mike Horn","startDateUTC":"2012-12-21T14:00:00Z", "endDateUTC":"2012-12-21T17:00:00Z", "creationDateUTC":"2012-12-20T17:00:00Z", "isPrivate":true,"isCancelled":false}]

Possible HTTP response status codes expected:

  • OK --> 200

  • Malformed date in the request --> 400

  • Unauthorized --> 401

  • Unknown Room ID or Organizer ID --> 404


Create a new meeting

Request:

Method

URL

Method

URL

POST

/rooms/roomId/meetings

  • roomId refers to the room identifier

Request body:

Format

Structure

Format

Structure

JSON

NewMeeting

NewMeeting is composed by the following properties:

Property

Type

Description

Example

Property

Type

Description

Example

subject

String

The subject of the meeting

"Product Review"

organizerId

String

The identifier of the organizer

"u345"

startDateUTC

String

The start date&time of the meeting

"2012-12-20T14:30:00Z"

endDateUTC

String

The end date&time of the meeting

"2012-12-20T16:30:00Z"

Remark:

  • If the booking system is managing the information creationDateUTC, this value must be set by the booking system during this call

  • ROOMZ will not declare any meetings Private or Cancelled

Example of request body:

{"subject":"Product Review","organizerId":"u123", "startDateUTC":"2012-12-20T10:00:00Z","endDateUTC":"2012-12-20T12:00:00Z"}

Possible HTTP response status codes expected:

  • OK --> 200 or 201

  • Unauthorized --> 401

  • Unknown Room ID or Organizer ID --> 404

  • Conflict with existing meeting --> 409

Update an existing meeting

Request:

Method

URL

Method

URL

PUT

/rooms/roomId/meetings/meetingId

  • roomId refers to the room identifier

  • meetingId refers to the meeting identifier

Request body:

Format

Structure

Format

Structure

JSON

ModifiedMeeting

ModifiedMeeting is composed by the following properties:

Property

Type

Description

Example

Property

Type

Description

Example

startDateUTC

String

The start date&time of the meeting

"2012-12-20T14:30:00Z"

endDateUTC

String

The end date&time of the meeting

"2012-12-20T16:30:00Z"

Possible HTTP response status codes expected:

  • OK --> 200

  • Malformed information --> 400

  • Unauthorized --> 401

  • Unknown Room ID, or Meeting ID --> 404

  • Conflict with existing meeting --> 409

ROOMZ Connector configuration

On the ROOMZ portal, the following properties must be configured for communicating with the booking system's API:

Property

Example

Property

Example

URL

"https://mydomain.com/api/roomz/v1"

Username

"John"

Password

"1234"

OrganizerId

"u821"

  • The Username and Password are used for the HTTP Basic Authentication

  • The OrganizerId is used for the creation of new meeting

  • The Username and the OrganizerId could be the same value