Click on images to see them in full screen
C4BB0F5D5FBCC38480257CB800746DE5API for Domino
From Door Tablet V4.4, the Door Tablet server offers an HTTP API which allows you to manipulate calendar appointments in IBM Domino from any remote system, and have these appointment show on the Door Tablet clients. The server must be in either one of these modes:
- Stand alone Meeting Centre
- Embedded within a corporate Domino Server
Note: using the API is subject to additional license.
Why is the API needed
Many corporations use ERP or home grown systems to manage their special meeting space resources. These often specialist systems are not linked to any of the corporate messaging system such as Microsoft Exchange, IBM Domino or Google Calendar. All manner of organisations such as hospitals, local authorities, governmental institution and banks use these systems to conduct their core business, often managed entirely separately to their traditional messaging system. The ability to use a simple yet powerful API to update meeting space displays is a unique capability of the Door Tablet server.
Use cases
- A hospital can use Door Tablet to display details about an operation currently being carried out
- A police station can display the fact an interview with suspects are being carried out in a meeting space
- An accountancy firm can display the fact an audit for a particular client is taking place in a meeting space
Supported functions
Functions supported by this API:
- Create a reservation
- Delete a reservation
- Update a reservation
- Read existing reservations
- List locations and meeting spaces (to create these please use the Web UI)
Before you begin
To get the API working on your server you will need to prepare it first. If you use the Door Tablet for Windows server you can skip this section, otherwise, use the following checklist:
- Ensure the system ACL (Access Control List) is correctly set (see image 1). You do not need to do this if you use the Door Tablet Windows Server
- Sign the doorswebui.nsf database using the Domino Administrator
- Ensure that the signer name (server or user) is included in the list of authorised executors on the server, in the server profile. Note: if you upgrade Door Tablet the databases will be signed again using the server ID name so ensure that this name also appears in the list of authorised executors (see image 2)
- Update the API ID and provide it to your HTTP API developer (images 3 and 4).
Note: If you are using the API on a Door Tablet embedded Domino server you must upgrade the design of the Rooms and Resources database we provide.
Image 1: required for Domino users but not for the Door Tablet for Windows server.
ACL: change the rights for "Anonymous" to "Editor", if it has not been set yet.
Image 2
List the signer in the server document
Images 3 and 4: Update the API ID
Using the Web UI:
In the Notes UI:
API Calls
To make calls to the server you make HTTP GET calls. The server always responds with JSONP
cbk (
{
ok: true,
code: 1,
message: "Reservation posted UK, and validated",
confirmed: true,
id: "ASDHVASDJ34563456NJK3463K4563K4J5",
sourceid: "sdfgsd34567fg567dfg6574356fdg567fgh",
time: "19/06/2019 20:11:52 GDT"
}
)
General Syntax:
All calls to the http server are made using the following syntax: |
 | http://<server_address>/doortablet/doorswebui.nsf/api.xsp?cmd=<command_name>&apiid=<API_ID>¶=value¶1=value1...¶N=valueN |
| Basic parameters: |
| <server_address> - the address of your server, may be an IP address too. The server must be configured to accept such address.
<command_name> - defines what you want to do. For the list of actions, see below. Not required for inbound SMS submitted from a gateway
<API_ID> - is an API ID code which you must always provide. The code is inserted in the System Profile by you and must be at least 12 chars long
<return> - optional. Specify the only value "json" to return the results of your calls in JSON format instead of JSONP. For example &return=json |
| Example: | |
| http://192.168.1.10/doortablet/doorswebui.nsf/api.xsp?cmd=reserve&apiid=ABCD1234ABCD |
General Return structure:
The Door Tablet API returns response in JSONP format, as showing above. The callback routine name is always "cbk". The response has the following format: |
| "ok": true or false
"code": error number, negative means error, positive means success
"message": a descriptive message
"time": the time the action have taken place |
| Additional parameters: |
| Additional parameters are returned when a reservation is posted OK
"id": the unique ID of the reservation inside Door Tablet
"sourceid":echo of the unique ID you provided when posting the reservation |
| Example: |
cbk (
{
ok: true,
code: 1,
message: "Reservation posted UK, and validated",
confirmed: true,
id: "ASDHVASDJ34563456NJK3463K4563K4J5",
sourceid: "sdfgsd34567fg567dfg6574356fdg567fgh",
time: "19/06/2019 20:11:52 GDT"
}
)
Success and Error codes
OK_VALIDATED = 1; //Reservation posted OK and validated
OK_UNVALIDATED = 2; //Reservation posted OK but not validated
OK_REMOVED = 5; //Reservation removed OK
OK_UPDATED = 10; //Reservation updated OK
OK_UNCHANGED = 11; //Reservation not Changed
OK_HASRESRVS = 20; //Found reservations for the date
OK_NORESRVS = 21; //No reservations found for the date
//error returns
ERR_CATCH_AL = -1; //general API catch error
ERR_SYSPROF = -2; //System profile not yet setup
ERR_NO_API = -3; //API ID parameter not provided
ERR_BAD_API = -4; //API ID mismatch
ERR_BAD_IP = -5; //IP not authorised
ERR_SRV_TYPE = -6; //Server type in system profile must be Meeting Center
ERR_OWNER = -7; //Meetings owner not set in System Profile
ERR_RES_DB = -8; //Reservations Database cannot be opened
ERR_ROOMLOC = -10; //Location or meeting space name are blank
ERR_NO_ROOM = -11; //Cannot get meeting space with key
ERR_NO_ACTIVE = -12; //Cannot use inactive room
ERR_SRC_ID_IND = -13; //No source ID index in resources DB
ERR_CHECKEDIN = -14; //Cannot replace a checked-in reservation
ERR_INP_PARA = -20; //Misc parameter error
ERR_BAD_RES = -30; //Reservation Rejected
ERR_NO_ID = -40; //No sourceid or id
ERR_NO_RESERV = -41; //No reservation found
Available Calls
| Reserve - create or reservation |
| Command: | |
| reserve |
| Variables: | |
| Mandatory fields
| room | Meeting space name. Taken for the room record, for example: &room=Magnet |
| loc | Location where the room is. Taken for the room record, for example: &loc=HQ1 |
| apiid | API ID. A 12 chars string from the Door Tablet system profile, for example: &apiid=194756ABCD23 |
| start | The start time of the reservation. Format: <Hour>:<Minutes>, for example: &start=16:00 |
| end | The end time of the reservation. Format: <Hour>:<Minutes>, for example: &end=17:30 |
| purpose | The purpose of the meeting. For example: &purpose=marketing review |
| capacity | The number of people attending the meeting. Integer. For example: &capacity=8 |
Optional fields
| chair | Person chairing the meeting, default: meetings owner from System Profile. For example: &chair=James+Bond |
| nowait | Tells the API not to wait and validate the reservation, default: n. Set to y if you are setting a lot of appointments and certain that there are no booking conflicts. For example: &nowait=y |
| date | The date of the meeting, default is Today. Format: <Year>-<Month>-<day>, for example: &date=2014-7-21. Please note that invalid dates will cause the reservation to be rejected. |
| sourceid | The unique ID of the booking on the source system. Default: blank. If you provide the ID, the API will first look for a booking with this ID and delete it, then proceed to create a new one. For example:
&sourceid=slfdjsfghsdfjvasfiu236b2c2l34234b23 |
| public | Set this to Y in order to show the reservation on public welcome screens. Default: n. For example: &public=y |
| welcome | A welcome message for visitors attending the meeting. This will display on welcome screens. Default is blank. For example: &welcome=Welcome+IBM+and+Microsoft+for+the+big+collaboration+day |
| attendees | Names of Attendees |
| attendeesOpt | Names of Optional Attendees |
Notes:
1. You cannot replace a reservation that was already checked-in
2. The time zone of the reservations you post using the API are always set to the Door Tablet server time zone, and you do not need to specify it |
| Example: | |
| http://192.168.1.10/doortablet/doorswebui.nsf/ api.xsp?cmd=reserve&room=Victoria&loc=London&apiid= ABCD1234ABCD&start=16:30&purpose=hello world&chair=someone&end=16:40&capacity=7&public=y |
Returns:
cbk (
{
ok: true,
code: 1,
message: "Reservation posted UK, and validated",
confirmed: true,
id: "ASDHVASDJ34563456NJK3463K4563K4J5",
sourceid: "sdfgsd34567fg567dfg6574356fdg567fgh",
time: "19/06/2019 20:11:52 GDT"
}
)
| Remove - removes a reservation |
| Command: | |
| remove |
| Variables: | |
| Mandatory fields
| sourceid | The unique ID of the booking on the source system. For example:
&sourceid=slfdjsfghsdfjvasfiu236b2c2l34234b23 |
| id | Unique ID from the Door Tablet system, which you get when a reservation is made
Note: you have to provide one of the above only |
| apiid | API ID. A 12 chars string from the Door Tablet system profile, for example: &apiid=194756ABCD23 |
Optional fields
| room | meeting space name. Taken for the room record, for example: &room=Magnet |
| loc | Location where the meeting space is. Taken for the room record, for example: &loc=HQ1 |
Note: you have to provide the optional fields if you use the API on a Domino Server. If you use Door Tablet as a Meeting Centre and stand alone these parameters are not required. |
| Example: | |
| http://192.168.1.10/doortablet/doorswebui.nsf/api.xsp?cmd=remove&apiid=ABCD1234ABCD&id=980791475A0C804680257CAD00578329 |
| Returns: | |
cbk (
{
ok: false,
code: -14,
message: "Cannot replace a checked-in reservation",
time: "15/08/2019 18:11:52 GDT"
}
)
| Update - updates a reservation |
| Command: | |
| update |
| Variables: | |
| Mandatory fields
| sourceid | The unique ID of the booking on the source system. For example:
&sourceid=slfdjsfghsdfjvasfiu236b2c2l34234b23 |
| id | Unique ID from the Door Tablet system, which you get when a reservation is made
Note: you have to provide one of the above only |
| apiid | API ID. A 12 chars string from the Door Tablet system profile, for example: &apiid=194756ABCD23 |
| purpose | If change needed. The purpose of the meeting. For example: &purpose=marketing review |
| capacity | If change needed. The number of people attending the meeting. Integer. For example: &capacity=8 |
| chair | If change needed. Person chairing the meeting, default: meetings owner from System Profile. For example: &chair=James+Bond |
| public | If change needed. Set this to Y in order to show the reservation on public welcome screens. Default: n. For example: &public=y |
| welcome | If change needed. A welcome message for visitors attending the meeting. This will display on welcome screens. Default is blank. For example: &welcome=Welcome+IBM+and+Microsoft+for+the+big+collaboration+day |
Optional fields
| room | meeting space name. Taken for the room record, for example: &room=Magnet |
| loc | Location where the meeting space is. Taken for the room record, for example: &loc=HQ1 |
Note: you have to provide the optional fields if you use the API on a Domino Server. If you use Door Tablet as a Meeting Centre and stand alone these parameters are not required. |
| Example: | |
| http://192.168.1.10/doortablet/doorswebui.nsf/api.xsp?cmd=update&apiid=ABCD1234ABCD&id=980791475A0C804680257CAD00578329&welcome=adding%20a%20welcome%20message |
| Returns: | |
cbk (
{
ok: true,
code: 10,
message: "Reservation Updated",
confirmed: true,
id: "ASDHVASDJ34563456NJK3463K4563K4J5",
sourceid: "sdfgsd34567fg567dfg6574356fdg567fgh",
time: "14/08/2019 13:11:52 GDT"
}
)
| Read - read reservations |
| Command: | |
| read |
| Variables: | |
| Mandatory fields
| apiid | API ID. A 12 chars string from the Door Tablet system profile, for example: &apiid=194756ABCD23 |
Optional fields
| date | Optional. The date for which you wish to list meetings for, default is Today. Format: <Year>-<Month>-<day>, for example: &date=2014-7-21. Please note that invalid dates will cause the listing to be rejected |
| resdb | Optional. Note: you have to provide the optional fields if you use the API on a Domino Server. If you use Door Tablet as a Meeting Centre and stand alone these parameters are not required. For example: &resdb=roomres.nsf |
| loc | The location of the meeting space/resource. If you do not specify the room name all the rooms within the location will be listed. For example: &loc=London |
| room | Room/resource name. If you do not specify the location name, all rooms of the same name, across locations, will be listed. &room=board |
| start | Start time. Show reservations that start or end after the start time. Format: hh:mm. If you do not specify the end (below), the API assumes end=23:59. For example: &start=16:30 |
| end | End time. Show reservations that start or end before the end time. Format: hh:mm. If you do not specify the start (above), the API assumes start=00:01. For example: &end=19:30
If end time is before start time the API reverses the times automatically for you |
| logbookings | Set this to Y in order to save booking records to Door Tablet. This is required if you use the Door Tablet Google Analytics integration |
|
| Example: | |
| http://192.168.1.10/doortablet/doorswebui.nsf/api.xsp?cmd=read&apiid=ABCD1234ABCD&date=2014-04-1 |
| Returns: | |
cbk (
total: 1,
reservations: [
{
start: "14/08/2019 16:30:00 GDT",
welcome: "",
roomkey: "Elizabeth/London",
chair: "John Smith",
tablet: "Y",
public: "",
checkincd: "412",
status: "A",
sourceid: "",
capacity: 10,
end: "14/08/2019 17:30:00 GDT",
id: "985566HJi9956y7878A",
purpose: "Meeting With New York Team"
}
],
ok: true,
time: "14/08/2019 15:00:00 GDT",
code: 20
)
cbk (
{
server: "web1/pcs",
message: "read rooms ok",
api: "2.0, 27 may 2014",
ok: true,
time: "29/08/2019 14:36:36,
locations: [
{
rooms: [
{
descr: "A room with a view of the desert",
css: "",
server: "Web1/PCS",
licensed: "Y",
active: "Y",
allowQR: "Y",
facil: "",
name: "Ocean",
nameDisp: "Cool Ocean",
maxbook: "60",
resource: "resrc.nsf",
lang: "en",
Phone: "07910 22567",
authcode: "Y",
capacity: 24,
email: "sales@polymedia-europe.com"
}
],
name: "Kuwait"
}
]
}
)
Unicode
When you send text to Door Tablet which includes chars outside the ASCII range, Door Tablet would expect you to use the following JavaScript routine output to convert your text to Unicode entities. If you use other languages such as Java to post to the Door Tablet server, the routing below may be converted as long as the output is the same as the JavaScript variant.
function uni2ent(srcTxt) {
var entTxt = '';
var c, hi, lo;
var len = 0;
for (var i=0, code; code=srcTxt.charCodeAt(i); i++) {
var rawChar = srcTxt.charAt(i);
if (code > 255) {
if (0xD800 <= code && code <= 0xDBFF) {
hi = code;
lo = srcTxt.charCodeAt(i+1);
code = ((hi - 0xD800) * 0x400) + (lo - 0xDC00) + 0x10000;
i++;
}
else if (0xDC00 <= code && code <= 0xDFFF) {
hi = srcTxt.charCodeAt(i-1);
lo = code;
code = ((hi - 0xD800) * 0x400) + (lo - 0xDC00) + 0x10000;
}
c = "%u" + Right("000"+code.toString(16).toUpperCase(), 4);
} else {
c = rawChar;
}
entTxt += c;
len++;
}
return entTxt;
}