Subscriptions using SOAP RESTful EWS Gateway

[Adam_Summers]

Hi,

Could anyone provide some assistance on the correct process for setting up a subscription to data using the SOAP REST Api Endpoint?

I have successfully registered a subscription and notification request and can get initial values but I am an unsure what the correct workflow is beyond that. It looks like I need to create a new notification on the subscription after each successful read but I'm not sure if that's right. I'm looking for a simple explanation as to how this works. Would also be good to know the correct decisions to make about cleaning up (removing notifications and subscriptions etc after use)

Thanks,

Adam.

[sesa180908_brid]

Adam,

Here is the process in detail.  Most of this you are probably already doing but I figured I'd document it here for others.

1. Create a Subscription.  A Subscription defines what data will be monitored by the underlying server.  Data is returned in the form of NotificationItems for a particular Notification.
2. Create a Notification.  A Notification is a session of shorts or a snapshot in time of all data changes.  This allows the server to manage paging of the NotificationItems for an arbitrary long number of data points.
3. Read the NotificationItems.  A NotificationItem is the actual data that has changed for a Notification of a Subscription.

Remember the RESTful Gateway API (and data constructs) it uses was defined to support the full EWS specification, In the case of the SoapEwsRestProvider (at least when SBO is the server) you can ignore anything not related to "ValueItemChanged" subscriptions.

The above steps in more detail...

1. Create a Subscription.  Issue a POST to Subscriptions/Create with the new subscription definition in the body.  Using Swagger, you will see the format of this body parameter:

{
  "DurationInMinutes": 0,
  "SubscriptionType": "ValueItemChanged",
  "Ids": [
    "string"
  ],
  "PriorityFrom": 0,
  "PriorityTo": 0,
  "Types": [
    "string"
  ]
}

Ignoring what you don't need for the SoapEwsRestProvider brings us to...

{
  "DurationInMinutes": 30,
  "SubscriptionType": "ValueItemChanged",
  "Ids": [
    "<< One or more unescaped EWS ValueItem IDs go here>>"
  ]
}

NOTE: Even though you can supply a DurationInMinutes value, SBO will always make subscriptions 30 minutes in length.

The POST result is the Subscription which you will need to create Notifications.

2. Create a Notification.  Issue a POST to Notifications/Create with new Notification definition in the body.  Using Swagger, you will see the format of this body parameter:

{
  "SubscriptionId": "<< ID of the subscription returned from step 1 >>",
  "ChangesOnly": true
}

ChangesOnly indicates that you only want what has changed since the last time you called created a Notification for a specific Subscription.  The first time you call Notifications/Create for a Subscription this is ignored and all data will be returned.  Subsequent calls can either return all data (ChangesOnly=false) or only changes (ChangesOnly=true).  In most cases you can always leave this as "true" and get what you probably want.

The POST result is the Notification which you will use to retrieve the actual data.

3. Read the NotificationItems.  Issue a GET to Notifications/{ID}/Items.

The ID supplied is the ID of the Notification returned in step 2.

The GET results are the NotificationItems you requested.  Paging is expected for the API.

As for data management and cleanup.... 

In the SoapEwsRestProvider world, SmartConnector has to manage data that is not supported by EWS in order to create a client experience that is conducive to the REST paradigm.  In other words, SmartConnector caches a lot of data.  This data is automatically cleaned up for you as it "ages away".  There is nothing that clients need to do. 

If I didn't answer all of your questions/concerns please let me know.

[Adam_Summers]

Thanks as always Mark, I think I was doing it right then.

Just for clarity it is a case of creating subscription then creating a notification and calling the results in a loop. So for every “poll” I would need to create a new notification, even if the notification result is empty (no changes)?

[sesa180908_brid]

Exactly.  Each call to Notification/Create creates the "session" and caches the actual data so that you can retrieve it as needed later.  In retrospect, it would have been useful to return an indication that the Notification has actual data (or perhaps the number of items) so that you wouldn't have to make a subsequent call if there were no items to retrieve.  Perhaps I'll look to add that for 2.3.