Key Entity Concepts

Here we introduce the main concepts involved with working with the MindLink API.

7.1 Agents

You can think of an Agent as representing an application on the chat system. Agents live constantly in-memory inside the MindLink web service node, and maintain the online endpoint on the chat system.

Typically there will be one agent per application, and hence the MindLink web service node will have many agents running simultaneously, all logged on and listening for messages from the underlying chat system. When an application makes calls to use the agent, under-the hood the MindLink web service simply looks up the appropriate agent instance and uses that to process the requests.

Figure 2 : Collaboration service mapping requests to agents To configure a new application, an administrator will create a new agent and configure it with the credentials that the application will be seen to use by other users. He will do this by making a request to the Provisioning service. Note that the administrator must simply provide a single sip: address – since the connection made by the agent on the MindLink web service node to the chat system is via trusted connection, no user name/password credentials are required.

Figure 3 : Provisioning Service As soon as an agent is created it will log on and show its presence as available, until it is deleted. If an incorrect sip-address is provided and as such log-on cannot occur, it will continue re-trying to connect until such time that the administrator modifies the agent’s sip-address. Similarly, if the agent becomes unexpectedly disconnected due to network connectivity loss etc. the agent will continue re-trying to connect.

Figure 4 : Agent state The agent reports its state via the web service to the administrator via a State property. If an application makes calls to the collaboration service e.g. to send a message when an agent is not active then the request will be returned with a 503 service unavailable error. Note: When using a Microsoft Skype or Office Communications Server backend, agents connect as a trusted autonomous application. Microsoft Persistent/Group Chat only supports trusted endpoints that are backed by an object in Active Directory. This implies that an Active Directory User object must be used to provide the SIP address for an agent, otherwise the agent will be refused connection by Microsoft Persistent/Group Chat. This means that the agent can have a SIP URI of a regular user, but not that a trusted application endpoint configured by the NewCsTrustedApplicationendpoint cmdlet.

7.2 Channels

A “Channel” represents a source and destination of message data. This is a generalisation over both instant-messaging and chat room communication – i.e. a channel can either be a chat room or a remote user.

Agents are configured with channels by the administrator. Adding a channel to an agent will immediately join the agent to the chat room or subscribe the agent to a user’s presence. This will make the channel “active” and allow messages to be sent and received on the channel.

Figure 5 : Channels and agent relationship Unlike with agent state, there is no reconnection logic for failed channel joins or subscribes. An administrator must remove and re-add a channel to an agent if the initial join or subscribe fails.

Figure 6 : Channel state Channels report their state to both the administrator and the application via a State property. If an application tries to send a message to a channel that is not active or not provisioned, a 403 forbidden error is returned.

7.3 Users

The final entity in the MindLink API model is the “User”. You will notice that while an agent is provisioned with the user name with which it will appear on the chat system (the sip address), this is not the same as the credentials with which applications will authenticate with the web services to obtain access to make collaboration and provisioning web service calls.

This is the role that the “User” covers – i.e. it represents a set of credentials with which an application can authenticate itself against the web service. We have chosen this pattern so that application credentials and authorization at the web-service layer are decoupled from the underlying chat-system credentials (sip-address), used to post messages from an application.

There is therefore an explicit mapping between “Users” created to specify web-service credentials, and the “Agent” that authenticated applications can use to post messages. This mapping is such that an Agent is configured with the users that can make web service calls to it.

Figure 7 : User and agent relationship Note that the difference between the mapping of an agent to its channels and an agent to its users is that the channels can be considered an agent-specific sub-collection whereas users are a globally defined collection that the agent maintains a mapping to.

For clarity, consider the provisioning of a new application that will appear on the chat system as sip:app-1@domain.com. The application itself will make calls to the collaboration service to send messages which will appear as coming from that SIP address. However, the application itself will not authenticate against the MindLink API services using that SIP address or any related account, it will instead authenticate itself with the domain\bot1 Active Directory account.

The administrator would provision the following (note that IDs are arbitrary strings specified on creation by the administrator):

• A User with user name domain\bot1 and ID user1

• An agent with user name sip:app-1@domain.com, ID agent1, and a users collection that contains “user1”.

The application would then be configured to authenticate with the domain\bot1 credentials, and specify that it wishes to use agent1 to service its calls.

Figure 8 : Example configuration

7.4 Super User

The “super user” is a single special kind of user that is configured not via the provisioning web services but on installation in the MindLink Management Tool configuration. This user has default provisioning rights, and should be used to create the initial agent and user accounts.

---

Sample Code Repository

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