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:

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

imageUrl

String

Image to diplay during the meeting

https://someurl.com/images/someCoolImageToDisplay.jpg”

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

  • The image for the imageUrl field is optional and should be behind an HTTPS resource, and it should be public (no authentication), to use the Image shown you have to toggle on the following switch:

    image-20240312-073654.png

We strongly recommend the use of an image with a 1024x768 resolution, as this is the native resolution of the ROOMZ Displays
Before a publication, it is recommended to convert your image using our ROOMZ Image Converter. The Displays have their own greyscale threshold. Using the tool guarantees that the rendering on the Display will be the very same as on your image

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,     "imageUrl": null   },   {     "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,     "imageUrl": "https://someurl.com/images/someCoolImageToDisplay.jpg"   } ]

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

 

As alternative for the authentication, you can use:

Property

Example

Property

Example

URL

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

Access token

“123456789”

Custom authorization header

“Security: MyHeader”

OrganizerId

"u821"