Click on images to see them in full screen
45E29C061326607A802585F1003C479EDTSI V2.2
Introduction
The Door Tablet server interfaces with the world’s most common platforms: Microsoft 365, Exchange, Google Workspace, HCL Domino and others. Many other scheduling systems could also be integrated with Door Tablet using the interface defined here. Our software makes little demand on your system as most of Door Tablet functionality is contained within it. For the purpose of this document, your scheduling system is the "target server".
New for DTSI V2
The following changes apply to V2 of DTSI
- Choice of authentication methods
- Integration of Enterprise features, mainly covering performance
- Addition of ID source via DTSI
- New search features for use in Info Displays (a new wayfinding display), including new personal calendar
- New fields in various calls
New for DTSI V2.1
The "user" api was enhanced. A room key is now added to the call which allows the target system to decide if the user may reserve the space, check-in to the space even if the reservation is not for that user, and allow the user to open the door. The responses listed here are optional. With this version, DTSI may be used as ID Source. See more here:
.
New for DTSI V2.2
We have added resource type and class. This allows you to specify the type of room, which can then be show when showing facilities in rooms time bars. The class is used if you wish to create a graphic representation that goes along with the text, or just on its own. The class is used in CSS you create when branding Door Tablet displays.
What does Door Tablet require from your system?
- Meeting spaces - a list of meeting spaces which participate
- Meetings - the list of reservations or meetings which are confirmed for a resource on a particular day, by default today
- Create - insert a reservation for a given resource that starts now and lasts x minutes (not required for Read Only)
- Update - given a reservation, change its end time to terminate or extend it (not required for read only)
- Match IDs - given a card ID return user information
- Search meetings or reservations - provide a search criteria and return reservation for the date range
- Personal calendar - search for a reservations pertaining for a user, for example student lectures for today, professors lectures for today, meeting a user participates in
Please note the the last two features are provided in the same call, namely "search"
Why use the DTSI
If you have an in-house developed system or a facilities system that you would like to connect to Door Tablet, you do not need to engage in complicated integration challenges. Simply ask your in-house developers to implement the interface as defined here and Door Tablet will work right away. This also eliminates the need for you to make any part of your existing system available to us. Furthermore, the requirements are simple and low cost thus enabling you to deploy Door Tablet easily, and in a short time.
Read only implementations
We introduced the concept of a
Read Only interface where a DTSI does not offer the ability to create appointments, or modify them in any way. The Read Only implementation also prevents the automatic termination of appointment or the ability to extend these. One reason to have a Read Only system is that it is simpler and costs less to implement. You may also wish to use this capability as a way to phase the implementation of a full DTSI response from your server.
Configure Door Tablet
If the target system responds exactly as defined by this document, no further work will be required when deploying Door Tablet. When configuring Door Tablet select the following technology: "Door Tablet Std Interface (DTSI)" and add the parameters required by your authentication type.
Authentication
Door Tablet will authenticate with your server using a variety of methods. In all cases the authentication you enable cannot require a user intervention. In addition to the simple connection that requires no authentication you can choose one of the supported methods:
- Basic Username/Password
- OAuth 2
Should you require another form of authentication, for example using JWT, please let us know so that we can add your authentication type to DTSI.
When no authentication is required:
When OAuth 2 authentication is required:
Note: please check your connection to the server. If the implementation is correct the number rooms/spaces will show, as in the example above.
About the OAuth 2 connection
The following process will take place when a token is required. A token is required either when there is no token or the current token has expired.
- Use the Client ID and Client Secret, combined with Token URL and body variables to get an Access Token
- Use the Access Token for all subsequent calls, until the token expiry time is reached
- The Token expiry is specified in the access token response
- If the Access Token expiry was reached, a new Token will be fetched from the server
Technologies
This standard defines a common set of technologies used in the interface. Unsurprisingly, communication with your system is over HTTP/S. Requests are made using HTTP GET and responses are in JSON. Each call to the target system is made by the Door Tablet server that acts as a proxy for all the Door Tablet client applications, but for your system it is a client. The Door Tablet client applications are not aware of your scheduling system and any of its characteristics.
About your Server
As Door Tablet communicates with your server over HTTP/S, it is important to clarify some points, listed below. For the IT professionals that will be a given, but we think it is worth mentioning. So, your server:
- May be anywhere – on premise, on the cloud, hosted by you or others
- Run on any computer with any OS
- May run any other application
HTTP Calls
This interface refers to parameters, both when posting and receiving responses. In all cases parameters are written in lower case. Time arguments are in the
ISO 8601 format ("2015-05-23T18:25:43.511Z"). Date arguments are in the truncated version of time ("2015-05-23"). All returned variables are strings unless explicitly defined otherwise. For example error_cd is an integer.
Each call made to the target server is made out of two parts:
| The fix part: |
| Base HTTP: protocol, host, port, root |
 | Example: https://myserver.com:81/meetings? |
| Variables: | |
| acc (optional) |
| Example: | |
| &acc=nalhf793127y4 |
| The variable part: |
| action: the name of the action you wish to perform |
| Example: |
| &action=rooms |
| Other variables: |
| the list of parameters depends on the action you wish to perform |
| Example: | |
| &room= green_room@company.com&date=2015-06-12 |
"Read Only" Appointments
Note: for a Read Only Appointments system, the server must implement only two calls listed ahead:
rooms and
meetings.
Responses from your server
Responses to calls made to the target system are expected to be in JSON, if the server returned HTTP 200. Each action will elicit a different response from the target system. The response can be either a good or bad one. A bad response will be when the target system is not happy to communicate with the source system (Door Tablet). For example, if the credentials provided by the source system are not acceptable by the target, a bad response will be generated:
{
ok: false,
code: 3,
message: "Access Denied – please contact the administrator",
ver: "2.0",
time: "2020-10-23T18:25:43.511Z"
}
As you can see the response is in JSON format. For readability we are not showing the double quotes surrounding parameter names, for example "version".
Each response has three fixed parameters: ok, version and time. The ok parameter is a Boolean with two values, true or false. If the value returned in ok is false, Door Tablet will consider it an error response and will refer to the message. The version is, well, the version. The time parameter should be the time the JSON was generated in ISO 8601 format or Epoch format.
Calls to your server and Responses from your server
Door Tablet makes specific calls to the target system.
| rooms - get a list of rooms/resources which may be used for bookings |
| Action: | |
| rooms |
| Variables: | |
| -none- |
| Example: | |
| https://myserver.com:81/schedules?&acc=nalhf793127y4&action=rooms |
| Returns: | |
| Returns JSON:
Array of "rooms", each with the following parameters:
| room | the id of the room or resource which uniquely identifies it in the target system - this is the "room key" |
| name | the name of the room (this variable and the location below must be unique in Door tablet) - Ascii chars only |
| location | where the room is (this variable and the name above must be unique in Door tablet) - Ascii chars only |
| displayname | optional - the name of the space in your language and may include any chars |
| capacity | (integer) how many people can be accommodated in the room/resource. Integer |
groups
geolocation
description
roomtype
cssclass | a comma delimited list of group name the resource is in
the geo location of the room, latitude, semi column, longitude
description of the room
The type of resource. Any text (optional)
The CSS class used when displaying the type - must be valid CSS class name (optional) |
|
| Example Response from your server: |
{
ok: true,
ver: "2.0",
time: "2020-10-23T18:25:43.511Z",
rooms: [
{
room: "blue_room@company.com",
name: "Blue Room",
location: "London",
displayname: "নীল ঘর",
capacity: 10,
groups: "grp1,grp2,grp3",
description: "Board Room",
geolocation: "51.513764;-0.335667",
roomtype: "Class Room",
cssclass: "class-room"
}, {
room: "green_room@company.com",
name: "Green Room",
location: "London",
displayname: "",
capacity: 12,
groups: "grp1,grp5",
description: "Forest room",
geolocation: "51.513764;-0.335667",
roomtype: "Auditorium",
cssclass: "audit-room"
}
]
}
| meetings - returns an array of meetings scheduled for a particular room |
| Action: | |
| meetings |
| Variables: | |
| room
date (optional – if not listed assume today) |
| Example: | |
| https://myserver.com:81/schedules?&acc=nalhf793127y4&action=meetings&room=red_room@mycompany.com&date=2015-05-23 |
| Returns: | |
| Returns JSON:
Array of "meetings", each with the following parameters:
| id | a unique meeting ID on the target system |
| start | the start time of the meeting in ISO 8601 format |
| end | the end time of the meeting in ISO 8601 format |
| subject | the subject of the meeting |
| owner | the name of the person who own the meeting (Chair) |
| owneremail | the email address of the meeting owner |
| participants | number of all attendees, integer |
| isprivate | indicates if the meeting is private, true/false – Boolean |
|
| Example Response from your server: |
{
ok: true,
ver: "2.0",
time: "2020-10-23T18:25:43.511Z",
meetings: [
{
id: "sldjfhgwijednfv98435knsdbfvhsdfgg345tkjsdfvbsfjhdg23846tjhsf",
start: "2020-10-23T10:00:00.00Z",
end: "2020-10-23T11:00:00.00Z",
subject: "Marketing Review",
owner: "John Travolta",
owneremail: "john_travolta@company.com",
participants: 7,
isprivate: false
}, {
id: "26kjb325436h2534wsfkjhbvosedrgwebt2345b562bsjfbgsfdjbskfj",
start: "2020-10-23T12:00:00.00Z",
end: "2020-10-23T13:00:00.00Z",
subject: "Marketing Review – phase 2",
owner: "John Travolta",
owneremail: "john_travolta@company.com",
participants: 7,
isprivate: true
}
]
}
{
ok: true,
ver: "2.0",
time: "2020-10-23T10:00:00.00Z",
id: "26kjb325436h2534wsfkjhbvosedrgwebt9999b562bsjfbgsfdjbskfj"
}
{
ok: true,
ver: "2.0",
time: "2020-10-23T10:00:00.00Z",
id: "26kjb325436h2534wsfkjhbvosedrgwebt9999b562bsjfbgsfdjbskfj"
}
| user - get a user record based on a RFID tag |
| Action: | |
| user |
| Variables: | |
| tag - the RFID or UUID tag read by the front-end device and submitted to the server
room - the room where the request is made from
Note: Door Tablet will always send the room value but the responding system does not have to respond with any of the "may" variables, listed below |
| Example: | |
| https://myserver.com:81/schedules?&acc=nalhf793127y4&action=user&tag=2346236236&room=red_room@mycompany.com |
| Returns: | |
| Returns JSON:
| disabled | Is the card used by this user disabled (maybe lost etc) |
| authorised | the user is authorised to use the application |
| code | the code of the card used in tag (just for feedback) |
| user.id | the ID of the user in the form of passport number, or student number |
user.name
user.email
user.phone
user.type | the full name of the user
email address of the user in RFC821 format
phone number in any agreed format
one of the following types in abbreviated form:
User (USR)
Student (STU)
Teacher (TCH)
Nurse (NRS)
Doctor (DCT)
Systems (SYS)
Admin (ADM)
Facility (FAC)
Support (SUP)
LEVEL 1 (LV1)
LEVEL 2 (LV2)
LEVEL 3 (LV3) |
user.categs
user.authorised
user.disabled | zero or more categories the user belongs to, comma delimited
is the card authorise for use
is the card disabled (because it was lost or stolen, for example) |
mayreserve
maycheckin
mayopendoor | optional - true/false - the user may reserve this space
optional - true/false - the user may check in to meetings in this space
optional - true/false - the user may open the door to this space |
|
| Example Response from your server: |
{
ok: true,
ver: "2.0",
time: "2020-10-23T18:25:43.511Z",
disabled: false,
authorised: true,
code: "2346236236",
user: {
id: "367567",
name: "Barry Allen",
email: "BA@gmail.com",
phone: "0122744567",
type: "STU",
categs: "categ-a,categ-b,categ-c",
authorised: true,
disabled": false
},
mayreserve: true,
mayopendoor: false
}
| search - get a list of "meetings" based on a number of parameters |
| Action: | |
| search |
| Variables: | |
| tag - an RFID tag as used in the "user" call above
categ - a category of reservations
freetext - free text for use with free text search
Note: you may only use of of the parameters above at any one time. The first one containing data should be used, in the order listed here.
daysahead - optional variable. If the value is 0 or not requested then the result will be reservations for today. A value of 1 will be the next business or study day, and so on. This allows you to skip weekends and national holidays |
| Example: | |
| https://myserver.com:81/schedules?&acc=nalhf793127y4&action=search&tag=2346236236
or
https://myserver.com:81/schedules?&acc=nalhf793127y4&action=search&group=geroup-A&daysahead=2
or
https://myserver.com:81/schedules?&acc=nalhf793127y4&action=search&freetext=some+search+string&daysahead=1 |
| Returns: | |
| Returns JSON:
Please note that if a tag is used, a "user" JSON object is listed too.
Array of "meetings", each with the following parameters:
| id | a unique meeting ID on the target system |
| start | the start time of the meeting in ISO 8601 format |
| end | the end time of the meeting in ISO 8601 format |
| subject | the subject of the meeting |
| owner | the name of the person who own the meeting (Chair) |
| owneremail | the email address of the meeting owner |
| participants | number of all attendees, integer |
isprivate
room
geolocation | indicates if the meeting is private, true/false – Boolean
the room key of the resource as listed in the resource (room) key in Door Tablet, and provided in the "rooms" call above
geo location of the resource. If this is blank Door Tablet will use the resource key to lookup the geo location inside Door Tablet |
|
| Example Response from your server: |
{
ok: true,
ver: "2.0",
time: "2020-10-23T18:25:43.511Z",
user: {
id: "367567",
name: "Barry Allen",
email: "BA@gmail.com",
phone: "0122744567",
type: "STU",
categs: "categ-a,categ-b,categ-c",
authorised: true,
disabled": false
},
meetings: [
{
id: "sldjfhgwijednfv98435knsdbfvhsdfgg345tkjsdfvbsfjhdg23846tjhsf",
start: "2020-10-23T10:00:00.00Z",
end: "2020-10-23T11:00:00.00Z",
subject: "Marketing Review",
owner: "John Travolta",
owneremail: "john_travolta@company.com",
participants: 7,
isprivate: false,
room: "blue_room@company.com",
geolocation: "51.513764;-0.335667"
}, {
id: "26kjb325436h2534wsfkjhbvosedrgwebt2345b562bsjfbgsfdjbskfj",
start: "2020-10-23T12:00:00.00Z",
end: "2020-10-23T13:00:00.00Z",
subject: "Marketing Review – phase 2",
owner: "Professor Joe Briggs",
owneremail: "jbriggs@university.com",
participants: 23,
isprivate: true,
room: "green_room@company.com",
geolocation: "51.513764;-0.335667"
}
]
}