IBM Domino 10 - integrating with Resource Reservations via Domino Data Services API

Question

We're trying to integrate with IBM Domino via REST API to pull out information about reservations/events in a specific room and also be able to create new events/reservations remotely. We already integrated with other services such as Microsoft Exchange, but IBM seems to be the toughest of them all. I studied deeply into it and read thousands of articles & stack overflow questions, and got pretty far but still can't make any real use out of it.

What I currently plan on doing is this:

• Pull information about reservations from /api/data/collections/name/($Reservations) or ($Calendar)

• Create events/reservations using the documents api, POSTing to /api/data/documents?form=Reservation, I already tried doing it and my reservation even showed in Domino Admin (not in Notes client though), but it had some errors (probably just some json problem on my side)

While it looks kinda clear and easy, it really isn't. I have a few questions:

1. How can I get reservations/calendar for a specific room? ($Calendar) returns all events in the database, not even including in which room it is, to get that information I would need to additionally query each reservation by it's unid and that would probably kill the entire app

2. Is there any way I could filter/search the /api/data/documents to return only documents whose form field has a value of Reservation or any other value? This way I could get all the reservation documents without querying each of the documents directly (/api/data/documents only returns the href to the document without any interesting data), I wouldn't also need to additionally enable DAS for each view I want to use.

3. What are the fields like $25 returned in the json, and how can I know what's their purpose if they don't have any real name? They often contain interesting data, such as the room name.

I also looked into the FreeBusy api service, and it's pretty interesting and I could easily use it to look for reservations (/busytimes) in the room I want, if it ever returned what resource/reservation is causing the busy time. It just shows the start and end time, nothing else..

I also read suggestions that one should create a 'main' user to handle the reservations and use his calendar api (/api/calendar/events), but afaik it can't be done that way. However I tried creating events in the users calendar in specified room, and kinda got it to work by adding the following attendee in the json |(PHP syntax, actually):

'organizer' => [ 'email' => 'admin/[email protected]' ],
'attendees' => [
    [
        'role' => 'req-participant',
        'userType' => 'room',
        'status' => 'accepted',
        'rsvp' => true,
        'email' => '[email protected]',
    ],
],

But it doesn't really get displayed in the room reservations, unlike normal events created in IBM Notes. It also cannot be edited or deleted in IBM Notes, and it has "Accepted: " in front of the subject, and it says "attendance is delegated for admin". To delete it, I need to delete it via API through its unid directly. x-lotus-noticetype is being set to A so I guess it's not being treated as a meeting but as an notice, no idea why though.

I'd really like some help or suggestions on how I could get this working, are there any other ways that would have any sense?

Edit: After struggling a lot and reading Dave's reply, I think it would be a good solution to have a single user that would do the reservations via calendar api, because the direct data api probably won't work. I could just only pull the list of all reservations from Rooms database ($Calendar) or ($Reservations) view, or make some sort of my own view. However! I cannot get the calendar method to work on my local IBM Domino server. Dave pointed to me that I need to specify a valid email (internet address) of the organizer, so I set my user's internet address to [email protected] (test.test is mapped to 127.0.0.1 in the hosts file). Now as soon as I try to use that address like that:

"organizer": {
    "email": "[email protected]"
}

I cannot even create the event/reservation (through /mail/admin.nsf/api/calendar/events), it's returning 500 internal error with cserror 1026, and Domino logs

[CS API]> Error | calendarapi.c(379) : There was an error sending out notices to meeting participants. (0x8E4)
Error connecting to server test/test: The remote server is not a known TCP/IP host.

So it has a problem with sending the notice, and doesn't create the event at all. I thought it may not work with localhost, so I set my users email to an external mail service, and I even received the email, but the event was still created incorrectly (x-lotus-noticetype A is being added automatically and overrides whatever I send as the value), it's not visible in the Room Reservations database.

Here's the json object of an event created via Notes client:

  "events": [
    {
      "href":"\/mail\/admin.nsf\/api\/calendar\/events\/2B35FABBC50EA4D0C12583BC002E26FA-Lotus_Notes_Generated",
      "id":"2B35FABBC50EA4D0C12583BC002E26FA-Lotus_Notes_Generated",
      "summary":"Notes client meeting",
      "location":"Test room\/Test site@test",
      "start": {
        "date":"2019-03-13",
        "time":"09:30:00",
        "tzid":"Central European Standard Time"
      },
      "end": {
        "date":"2019-03-13",
        "time":"10:30:00",
        "tzid":"Central European Standard Time"
      },
      "class":"public",
      "transparency":"opaque",
      "sequence":0,
      "last-modified":"20190313T082436Z",
      "attendees": [
                {
          "role":"chair",
          "status":"accepted",
          "rsvp":false,
          "displayName":"admin\/test",
          "email":"[email protected]"
        },
                {
          "role":"req-participant",
          "userType":"room",
          "status":"needs-action",
          "rsvp":true,
          "displayName":"Test room\/Test site",
          "email":"[email protected]"
        }
      ],
      "organizer": {
        "displayName":"admin\/test",
        "email":"[email protected]"
      },
      "x-lotus-broadcast": {
        "data":"FALSE"
      },
      "x-lotus-notesversion": {
        "data":"2"
      },
      "x-lotus-appttype": {
        "data":"3"
      }
    }
  ]

As you can see, Notes is able to create the event with [email protected] successfully.

Now here's an event created with my API, but with admin/[email protected] as the organizer's email (because normal email doesn't let me create the event):

 "events": [
    {
      "href":"\/mail\/admin.nsf\/api\/calendar\/events\/E1D1F752203FC2DFC12583BC002FCB12-Lotus_Auto_Generated",
      "id":"E1D1F752203FC2DFC12583BC002FCB12-Lotus_Auto_Generated",
      "summary":"Api reservation test",
      "location":"Test room\/Test site@test\r\nCN=Test room\/O=Test site",
      "description":"API Generated event\r\n",
      "start": {
        "date":"2019-03-20",
        "time":"11:00:00",
        "utc":true
      },
      "end": {
        "date":"2019-03-20",
        "time":"15:00:00",
        "utc":true
      },
      "class":"public",
      "transparency":"opaque",
      "sequence":0,
      "last-modified":"20190313T084201Z",
      "attendees": [
                {
          "role":"chair",
          "status":"accepted",
          "rsvp":false,
          "displayName":"admin\/test",
          "email":"[email protected]"
        },
                {
          "role":"req-participant",
          "userType":"room",
          "status":"needs-action",
          "rsvp":true,
          "displayName":"Test room\/Test site",
          "email":"[email protected]"
        }
      ],
      "organizer": {
        "displayName":"admin\/test",
        "email":"[email protected]"
      },
      "x-lotus-broadcast": {
        "data":"FALSE"
      },
      "x-lotus-notesversion": {
        "data":"2"
      },
      "x-lotus-noticetype": {
        "data":"A"
      },
      "x-lotus-appttype": {
        "data":"3"
      }
    }
  ]

As you can see, the organizer's & chair emails were automatically updated by Lotus to [email protected], and theorethically everything should work but it doesnt. In Notes, I see the event as 'Accepted: Api reservation test' and I cannot modify things like the room, or don't have the option to delete it from right click menu (I can delete it with Del keyboard button though) The only difference is that x-lotus-noticetype get's added, and I don't even know why

Edit 2: I got it to work! Dave pointed that I may have some configuration issue, so I re-installed the server & setup everything again (including the mail services), I used [email protected] and the meeting was succesfully created & added to the room reservations. Server console only showed that the message was delivered. HOWEVER! I was able to create as many identical meetings as I wanted, they weren't added to the reservations database but they were succesfully created in my calendar (with the room assigned to them) without any errors (not even in the sever console), this is obviously bad. Is there any way to check (externally, through API) if the reservation was created succesfully, and prevent it's creation if the room is busy at that moment? Notes client prompts an error when the room is busy. I could probably use FreeBusy api, however that would require another HTTP request before each reservation attempt, but if that's the only way then I'll just take it. I see that the status field of the attendeed room is set to declined, but the response from POST still contains needs-action so I'd need to do some delayed request once again to check if the status has changed to declined or not.

Also, while it works, I still don't know how I could obtain a list of reservations in a selected room? The already existing views in Reservations database don't give many details, and they need to be exclusively enabled DAS services in order to work. Is there any other way that could work properly?

Another thing is, is there any way I could get current user's email address to use for the reservations, or can I only 'hardcode' it manually? Same goes for room's email. Currently, I need to have:

• User name
• User password
• User mail database (/mail/admin.nsf/)
• User email
• Room email

and if I'd want to read some data from the Reservations database directly, then I'd also need to have the path to that database. This isn't really user-friendly, I'd like to automate some things if possible. Otherwise the integration may be impossible to make.

Answer 1

The reservation database was designed to manage reservations either (1) directly through it's own UI, or (2) indirectly by auto-processing notifications from calendar users. By using the DAS data API, you are asserting you can manage reservations (3) programmatically -- by manipulating the low-level document items. You might get this to work, but I don't think the reservation database was designed with that in mind.

That's why I think this answer is the best option. It leverages auto-processing (#2 above) and saves you from dealing with the internal design of reservation documents. If you use this approach, you should give the DAS calendar API a list of attendees like this:

  "attendees":[
    {
      "role":"req-participant",
      "userType":"room",
      "status":"needs-action",
      "rsvp":true,
      "email":"[email protected]"
    }
  ]

In other words, status must be "needs-action" -- not "accepted" as shown in your original post. Also, make sure you are using the correct email address for both the organizer and the target room. The above example shows an Internet-style address for the room, but administrators don't always give a room an Internet address.