Create room reservations using Domino data services REST API

Question

I've been attempting to create room bookings using the Domino data services REST API but I seem to be missing a trick.

Sending a POST request to the document endpoint I am able to submit and create a reservation document which appears in the Rooms and resource view but the underlying room still shows as available in the notes client.

Here is a sample of the request body:

   {
  "@authors": [
    "CN=Andrew Jones/O=MyCorp",
    ""
  ],
  "@form": "Reservation",
  "From": "CN=Andrew Jones/O=MyCorp",
  "Chair": "CN=Andrew Jones/O=MyCorp",
  "AltChair": "CN=Andrew Jones/O=MyCorp",
  "Principal": "CN=Andrew Jones/O=MyCorp",
  "SequenceNum": 1,
  "OrgState": "5",
  "ResourceType": "1",
  "ResourceName": "Room/Office",
  "ROOM": "Room/Office@MyCorp",
  "Capacity": 1,
  "AppointmentType": "3",
  "StartTimeZone": "Z=0$DO=1$DL=3 -1 1 10 -1 1$ZX=47$ZN=GMT",
  "EndTimeZone": "Z=0$DO=1$DL=3 -1 1 10 -1 1$ZX=47$ZN=GMT",
  "TOPIC": "Test",
  "SendTo": "CN=Room/O=Office",
  "SelectedRR": "CN=Room/O=Office",
  "$BusyName":"CN=Room/O=Office",
  "Encrypt": "0",
  "Categories": "",
  "RouteServers": "CN=dominonode/O=MyCorp",
  "DeliveredDate": { "data":"2017-03-09T12:38:34Z","type":"datetime"},
  "StartDate": {"data":"2017-03-09T20:00:00Z","type":"datetime"},
  "StartTime": {"data":"2017-03-09T20:00:00Z","type":"datetime"},
  "StartDateTime": {"data":"2017-03-09T20:00:00Z","type":"datetime"},
  "EndDate": {"data":"2017-03-09T21:00:00Z","type":"datetime"},
  "EndTime": {"data":"2017-09-03T21:00:00Z","type":"datetime"},
  "EndDateTime": {"data":"2017-03-09T21:00:00Z","type":"datetime"},
  "CalendarDateTime": {"data":"2017-03-09T20:00:00Z","type":"datetime"},
  "UpdateSeq": 1,
  "Author": "CN=Andrew Jones/O=MyCorp",
  "ResourceOwner": "",
  "ReservedFor": "CN=Andrew Jones/O=MyCorp",
  "ReservedBy": "CN=Andrew Jones/O=MyCorp",
  "RQStatus": "A",
  "Purpose": "API Test",
  "NoticeType": "A",
  "Step": 3,
  "Site": "Office",
  "ReserveDate": {"data":"2017-03-09T20:00:00Z","type":"datetime"}
}

This question suggests I should instead be trying to create a Calendar event but everything I send seems to get rejected with bad request, including the sample

I've also looked at another question which suggests I need to create an appointment and then a notice document for the room, but whilst I can create these documents, it doesn't seem to create a reservation.

Has anyone tried this and got it to work or am I just joining the elephant's graveyard?

Answer 1

I recommend registering a special "user" to act as the booking agent. Then you can use the calendar API to book any room. I think this approach will work better than the data API.

Details:

• Register a new "user" to act as the booking agent. Let's call the user "Room Agent/MyCorp". The user's mail file is "mail/ragent.nsf".

• Make sure the calendar API is enabled on a mail server with a replica of "mail/ragent.nsf".

• When someone uses your tablet app to book a room, the app sends a request to create an event on the room agent's calendar (POST /mail/ragent.nsf/api/calendar/events). The new event should include the room in the list of attendees.

• The calendar API sends an invitation to the room (actually the resource database). As long as the room is not already booked, the resource database accepts the invitation and the room becomes busy for that time slot.

This saves you from having to deal with the data API and the intricacies of the resource database. Your tablet app just needs to know the mail server host name, the name of the mail file, and the room agent's credentials. I also like the idea of being able to "audit" all bookings originating from your tablet app. You'll be able to find all the events and notices (accept or decline) in the room agent's mail file.

One disadvantage is booking will not be instantaneous, but the resource database should be able to accept an invitation in a matter of seconds.

By the way, here is some sample JSON input for your POST request:

{
  "events":[
    {
      "summary":"Calendar API test",
      "location":"test",
      "description":"test",
      "start":{"date":"2018-01-01","time":"13:00:00","utc":true},
      "end":{"date":"2018-01-01","time":"14:00:00","utc":true},
      "organizer":{"email":"ragent@mycorp.com"},
      "attendees":[
        {
          "role":"req-participant",
          "userType":"room",
          "status":"needs-action",
          "rsvp":true,
          "email":"room@mycorp.com"
        }
      ]
    }
  ]
}

It's important to specify "userType":"room" for the attendee. Otherwise, the resource database won't accept the invitation.