Edit

Share via

Operation resource

  • Article

Long-running operations are represented in UCWA 2.0 as operation resources.

Applies to: Skype for Business 2015

Some operations in UCWA 2.0, such as joining an online meeting, or inviting someone into an IM session, can take a considerable amount of time, and need periodic status updates. These long-running operations are represented as a special type of resource, an operation resource.

An operation resource is created in the event channel as the result of a POST request to the URL of another kind of resource that can be thought of as an operation factory. One example of an operation factory resource is the joinOnlineMeeting resource. The response to the POST request will have the HTTP status code 201 Created, and the Location header will give the URL to the operation that was created. All subsequent updates to the operation status will arrive in the event channel, until the final "completed" event. The operation that the joinOnlineMeeting resource creates is an onlineMeetingInvitation resource. A "started", "updated", or "completed" event includes both the embedded operation resource and a link to the same resource. This way the client can associate the outcome of the operation with the operation itself. Because updates to operation resources arrive as a response to a separate HTTP request (the pending GET, or P-GET), in some cases the event can reach the client before the arrival of the 201 Created response (which contains the link to the operation resource). This makes it impossible to associate an event with the URL of the operation. To link events to their corresponding operations, all operation-starting resources in UCWA 2.0 accept an "operationId" key-value pair in either the POST body or as a query parameter. This ID is a unique identifier that is generated by the client, that is also be included in every event about the operation, which makes it possible to match the event to the operation at all times.

Example

The following is an example of a client application starting an operation, providing an operation ID, and tracking it on the event channel.

POST /ucwa/v1/applications/23/communication/onlineMeetingInvitations HTTP/1.1 
Authorization: ... 
Accept: application/json 
Content-Type: application/json 
Host: ucwapool0.contoso.com 
Content-Length: ... 

{
 "importance":"Normal",
 "operationId":"123", 
 "onlineMeetingUri":"sip:user@contoso.com;gruu;opaque=app:conf:focus:id:ABCDE"
}

The POST response includes the operation URL.

HTTP/1.1 201 Created 
Content-Length: 0 
Location: /ucwa/v1/applications/23/communication/onlineMeetingInvitations/i1

The event channel response includes the self URI for the operation and the operation ID.

HTTP/1.1 200 OK 
Content-Type: application/json; charset=utf-8 
Content-Length: ... 

{ 
 "_links": { 
 "next": { "href": "/ucwa/v1/applications/23/events?ack=2" }, 
 "self": { "href": "/ucwa/v1/applications/23/events?ack=1" }
 }, 
 "sender": [ 
 { 
 "events": [{ 
 "_embedded": { 
 "onlineMeetingInvitation": { 
 "_links": { 
 "conversation": { 
 "href": "/ucwa/v1/applications/23/communication/conversations/c1" 
 }, 
 "from": { 
 "href": "/ucwa/v1/applications/23/communication/conversations/c1/participants/user@contoso.com", 
 "title": "" 
 }, 
 "self": { 
 "href": "/ucwa/v1/applications/23/communication/onlineMeetingInvitations/i1" 
 } 
 }, 
 "direction": "Outgoing", 
 "importance": "Normal", 
 "onlineMeetingUri": "sip:user@contoso.com;gruu;opaque=app:conf:focus:id:ABCDE", 
 "operationId": "123", 
 "rel": "onlineMeetingInvitation", 
 "state": "Connecting" 
 } 
 }, 
 "link": { 
 "href": "/ucwa/v1/applications/23/communication/onlineMeetingInvitations/i1", 
 "rel": "onlineMeetingInvitation" 
 }, 
 "type": "started" 
 } 
 ], 
 "href": "/ucwa/v1/applications/23/communication", 
 "rel": "communication" 
 } 
 ] 
}