API Developers reference


9. Collaborating

Applications themselves will be written against the Collaboration service. This service uses Channels and Messages resource collections to model the channels on the underling system. More information about writing applications against this service can be found in the developer guide.

9.1 Authorization

Requests to the collaboration service are mapped directly to and serviced by the agent contained in the provided token. Hence, tokens used to access the collaboration service must be issued for an agent – i.e. tokens issued for the super user account will not be accepted.

Furthermore, the agent mapping to the account must be “active” – i.e. logged in to the system. Calls made with a token whose agent is not active will be failed with a Service Unavailable code. Applications must be written to deal with this error code as this will occur when the connection to the underlying chat system is dropped. Note that reconnection of the agent is automatically performed inside the MindLink API, so external application code should gracefully fail as appropriate and then retry until the agent becomes active again.

9.2 Event Streaming

Applications perform invocation and query operations on the chat system e.g. message sending, message fetching using standard HTTP verb requests - e.g. GET/POST etc. - since this paradigm is a natural mapping. To be able to subscribe to and wait for remote events e.g. receiving messages, we must use a different mechanism.

We have chosen to solve this by using a long-polling (sometimes known as “Comet”) pattern, whereby the application should continually make HTTP GET requests to the Events resource collection. If new events are available then the request will return immediately with those events, otherwise the request will be held open until events become available. If no events become available within 30 seconds an empty collection of events is returned.

Typically this logic will be implemented in an application in the form of a loop that continually makes a request, processes each event in the returned response (which may be an empty set of events), and then makes the request again.

The types of events that are returned can be configured via the querystring – this provides a pseudosubscription mechanism.

Note that when addressing the resource using instanceIDs, requests will fail if the ID does not match the API service instance. If this should occur, steps should be taken to re-synchronize the ID to continue long-polling (see section 3.8.5).


10. Walkthrough

We will conclude by examining the example requests required from both the administration and application roles to set up the API with an agent and make a request to send a message to a channel.

10.1 Pre-requisites

We assume the following:

  • The MindLink API is configured to run at https://mindlink.domain.com

  • Lync is the underlying chat system.

  • The MindLink API is configured with domain\mindlinksuperuser as the super user account

  • Active Directory user accounts domain\mindlinkadmin1 and domain\mindlinkuser1 are configured.

  • The MindLink API is configured for manual authentication. All Active Directory user accounts have “Password1” as the password.

  • Lync SIP accounts have been created with SIP addresses sip:mindlinkslave@domain.com and sip:agent1@domain.com

  • There is a Lync Persistent Chat Room called “TestChatRoom” with ID chat-room:f9a694eb3cae-4235-bcb6-b8aeefb83284 which is visible to sip:mindlinkslave@domain.com and accessible by sip:agent1@domain.com

10.2 High-Level Strategy

Our high level strategy will be as follows

  1. Provision the agents and users**

  2. a. Use the super user to create a normal admin user and slave agent

  3. b. Use the admin user to create an application user and an agent

  4. c. Search for a channel using the slave agent

  5. d. Provision the application agent with the channel

  6. Send a message**

  7. a. Use the application agent to send a message to the channel

  8. b. Verify that the message was sent to the channel

  9. By the end of the provisioning steps the system will look as follows:

Image 9

10.3. Provisioning Requests

10.3.1 Obtain a Super User Token

  • Make a POST request to https://mindlink.domain.com/Authentication/V1/Tokens with the payload: {"Username":"domain\mindlinksuperuser","Password":"Password1","AgentId":""}
  • This will return 200 OK with the token e.g. "xPq5OitUf9NIOUI8VMN314EjEEsvmatZTqZ7LHuo0AQ0Xq1VRhZ8tL6mmGSRe_xO+YGEDBDE52SOCeJphu +cGg==" If it does not then check the configured super user credentials in the MindLink Management Center and in Active Directory.
  • This token must be provided in all subsequent requests in the “Authorization” HTTP header, prefixed with “FCF ”. For example the Authorization header in this case will be: FCF xPq5OitUf9NIOUI8VMN314EjEEsvmatZTqZ7LHuo0AQ0Xq1VRhZ8tL6mmGSRe_xO+YGEDBDE52SOCeJphu+ cGg==
  • Setting this header and then making a GET request to https://mindlink.domain.com/Authentication/V1/Tokens/xPq5OitUf9NIOUI8VMN314EjEEsv matZTqZ7LHuo0AQ0Xq1VRhZ8tL6mmGSRe_xO+YGEDBDE52SOCeJphu+cGg== will return 200 OK with the token details: {"AgentId":"","ExpiresTimestamp":1370990873148,"Username":"domain\mindlinksuperuse r"}

10.3.2 Create the admin user

10.3.3 Create the admin slave agent

  • Making a GET request to https://mindlink.domain.com/Provisioning/V1/Agents will return an empty collection as there are no configured agent: []
  • Make a PUT request to https://mindlink.domain.com/Provisioning/V1/Agents/slaveagent with the payload: {"Id":"slaveagent","UserName":"sip:mindlinkslave@domain.com","Channels":[],"MetaDat a":[],"Users":[|"admin1"],"CanProvision":"true"}
  • This will return with 200 OK.
  • Making a GET request to https://mindlink.domain.com/Provisioning/V1/Agents will now return 200 OK with a collection containing the slaveagent agent: [{"CanProvision":true,"Channels":[],"Id":"slaveagent","MetaData":[],"State":2,"User Name":"sip:mindlinkslave@domain.com","Users":[|"admin1"]}]
  • Similarly, whereas a GET request to https://mindlink.domain.com/Provisioning/V1/Agents/slaveagent would have previously returned 404 Not Found, it will now return: {"CanProvision":true,"Channels":[],"Id":"slaveagent","MetaData":[],"State":2,"UserN ame":"sip:mindlinkslave@domain.com","Users":[|"admin1"]}
  • Note that the “State” property being “2” indicates that the agent has logged on successfully. If this value is 0 or 1 then check the agent user name.

10.3.4 Reauthenticate as the new admin account

  • Make a POST request to https://mindlink.domain.com/Authentication/V1/Tokens with the payload: {"Username":"domain\mindlinkadmin1","Password":"Password1","AgentId":"slaveagent"}
  • This will return 200 OK with the token e.g. "fQaQrO2QgeDoOeQpnaALQMsYdQlSm75hAZDWs0CR6eL5OVzFx8ONEjia5gp1QMEc99aLsDVTaEa_FY+3dK ZuFQ=="
  • This token must be provided in all subsequent requests in the “Authorization” HTTP header, prefixed with “FCF ”
  • Setting this header and then making a GET request to https://mindlink.domain.com/Authentication/V1/Tokens/fQaQrO2QgeDoOeQpnaALQMsYd QlSm75hAZDWs0CR6eL5OVzFx8ONEjia5gp1QMEc99aLsDVTaEa_FY+3dKZuFQ== will return 200 OK with the token details: {"AgentId":"slaveagent","ExpiresTimestamp":1370990873148,"Username":"domain\mindli nkadmin1"}

10.3.5 Create the application user

10.3.6 Create the application agent

  • Make a PUT request to https://mindlink.domain.com/Provisioning/V1/Channels?query=TestChatRoom with the payload: {"Id":"agent1","UserName":"sip:agent1@domain.com","Channels":[[]],"MetaData":[[]],"User s":[["user1"]],"CanProvision":"false"}
  • This will return with 200 OK.
  • Making a GET request to https://mindlink.domain.com/Provisioning/V1/Agents/agent1 would have previously returned 404 Not Found, it will now return: {"CanProvision":false,"Channels":[[]],"Id":"agent1","MetaData":[[]],"State":2,"UserName ":"sip:agent1@domain.com","Users":[|"user1"]}
  • Note that the “State” property being “2” indicates that the agent has logged on successfully. If this value is 0 or 1 then check the agent user name.

10.3.7 Look up the channel ID for the target chat room

  • Make a GET request to https://mindlink.domain.com/Provisioning/V1/Channels?query=TestChatRoom.
  • This will return with 200 OK and the list of matching channels: {"Key":"chat-room:f9a694eb-3cae-4235-bcb6-b8aeefb83284","Value":" TestChatRoom "}
  • From this response we know that the ID of chat room TestChatRoom as recognized by the MindLink API is “chat-room:f9a694eb-3cae-4235-bcb6-b8aeefb83284”.

10.3.8 Provision the application agent with the target chat room channel

  • Make a PUT request to https://mindlink.domain.com/Provisioning/V1/Agents/agent1/Channels/chatroom:f9a694eb-3cae-4235-bcb6-b8aeefb83284
  • This will return with 200 OK.
  • Making a GET request to https://mindlink.domain.com/Provisioning/V1/Agents/agent1 will return 200 OK with: {"CanProvision":false,"Channels"[:{"Id":"chat-room:f9a694eb-3cae-4235-bcb6b8aeefb83284","State":2},"Id":"agent1","MetaData":[],"State":2,"UserName":"sip:age nt1@domain.com","Users":[|"user1"]}
  • The channel’s “State” property being “2” indicates that the agent has successfully joined the channel. If this value is 0 or 1 then check the chat room permissions for the agent’s user name.

10.4. Collaboration Requests

10.4.1 Obtain an agent Token

  • Make a POST request to https://mindlink.domain.com/Authentication/V1/Tokens with the payload: {"Username":"domain\mindlinkuser1","Password":"Password1","AgentId":"agent1"}
  • This will return 200 OK with the token e.g. "PzE4IsnjVkmLn+XnYM8LRQvWr+1xyaGkIi58qkx5mV4yBiz4kw1QAAqtGIKY4Feqdh8FtE9WKFeDZ4lADY R2xA=="
  • This token must be provided in all subsequent requests in the “Authorization” HTTP header, prefixed with “FCF ”.
  • Setting this header and then making a GET request to https://mindlink.domain.com/Authentication/V1/Tokens/PzE4IsnjVkmLn+XnYM8LRQvWr+1 xyaGkIi58qkx5mV4yBiz4kw1QAAqtGIKY4Feqdh8FtE9WKFeDZ4lADYR2xA== will return 200 OK with the token details: {"AgentId":"agent1","ExpiresTimestamp":1370990873148,"Username":"domain\mindlinkus er1"}

10.4.2 Verify the agent channels

  • For the sake of example, to verify the agent is configured correctly make a GET request to https://mindlink.domain.com/Collaboration/V1/Channels
  • This will return 200 OK with the channel collection: {"CanAcceptFiles":true,"Description":"Test Room","DisplayName":"TestChatRoom","EmailAddress":null,"Id":"chat-room:f9a694eb-3cae-4235-bcb6b8aeefb83284","IsReadOnly":false,"MaxMessageLength":500,"MaxStoryLength":4000,"Meta data":null,"Subject":"Test Room"}

10.4.3 Post a message to the channel

10.4.4 Verify the message was sent


Sample Code Repository

Sample code can be downloaded from https://github.com/mindlink/api-samples