Create room reservations using Domino data services REST API

2
votes

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?

1
lotus-noteslotus-domino
I need to better understand your use case. The calendar API makes sense if you are trying to create an event on a user's calendar. You can book a room as a side effect of creating such an event, but the request would be "POST /{database}/api/calendar/events" where {database} is the user's mail file. I don't think {database} can be the reservation database itself. When you say everything gets "rejected with bad request", what {database} are you using? – Dave Delay
The intent is to have tablet devices outside each of the rooms in our office. The tablet will show the schedule for the room for the day. If there is room is not booked, the user should be able to instantly book the room for the next 30mins, 1 hr etc. So I'm expecting to do this by sending a POST request(s) to some endpoint. I was using resource.nsf, so instead I should use the database corresponding to the room's mail file? – Andrew Jones
A room doesn't have a mail file per se, but I think have an answer that will work for you. Stay tuned. I'll post the answer in a moment. – Dave Delay
You cannot create a booked reservation (RQStatus": "A") directly. You can only create a reservation request (RQStatus": "T"). The Rooms and Resource Manager (RnRMgr) task is responsible for making the final decision. When your doc is saved to the R&R dB, Domino will notify the RnRMgr to look at your request. RnRMgr will process it based on the room settings and make a final determination. If it decides the rest is good and the room is free, it will change the RQStatus to "A" and make sure busytime is updated. If not it may Decline it ("R") or notify any room owners to make a choice. – Bruce Kahn

1 Answers

4
votes

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":"[email protected]"},
      "attendees":[
        {
          "role":"req-participant",
          "userType":"room",
          "status":"needs-action",
          "rsvp":true,
          "email":"[email protected]"
        }
      ]
    }
  ]
}

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