API Developers reference
Provisioning is the term used to describe the process of configuring the MindLink API entities such that applications can communicate with the chat system. This is done by making calls to the Provisioning service, which uses typical REST resource collections to describe the various configurable entities.
Calls to the Provisioning service must be made with a token obtained from the Authentication service. A token will be considered valid if:
The token was obtained for the super user.
The token maps to an agent that is authorized to perform the requested operation.
This means that typically all initial set up will be performed by the super user, and then subsequent configuration will be performed using a token obtained for a special “provisioning slave” agent. In addition, it also means that special applications may be granted permission to perform provisioning operations themselves – either on behalf of other agents or on behalf of themselves. This essentially allows applications to be written using the traditional “bot” paradigm where the application itself decides which channels it is joined to.
The Provisioning service exposes REST resource collections for the User, Agent and Throttle resources. These resource collections are examined and manipulated using standard REST verbs requests.
Users - define the credentials used by applications and administrators to access the MindLink API.
Agents – represent the application on the chat system. Creating an agent resource will immediately spin up an agent instance and log the agent in. Querying the “State” property of an agent will determine whether the agent is Active (logged in) or Inactive – log on failed or waiting to reconnect.
Throttles – these can be applied to agents to limit the rate of actions that an application can perform.
The channels that an agent is joined to are configured via the Agent resource’s “Channels” sub-resource collection. Adding a channel – which is represented via an ID – to this collection will immediately make the agent join the channel. Querying a Channel’s “State” property will indicate whether the channel is Active (joined) or Inactive – the join failed.
As mentioned previously, each application running against the MindLink API should map to a single Agent. If that Agent resource is configured that has been given permissions to provision, then an application holding a token that maps to that agent may make calls to the Provisioning service. This means that it is possible for the application to provision its own channels – i.e. decide which channels to join and leave – or to provision channels of other agents.
In this way an application can be written in a traditional autonomous “bot” style, in which the application itself controls its own actions. We would recommend however that typically this permission is not granted to agents used by applications, and applications are written such that the channels to which they are joined is driven entirely by the actions of a central administrator.
9.2.1 Provisioning Modes (v18.6+)
If the MindLink server is version 18.6 or later, agents can be given a ProvisioningMode instead of setting the CanProvision property. This gives admins more granular control over what agents are able to do. The possible values are as follows:
1: None : The agent cannot access any functionality of the provisioning API. This is functionally equivalent to CanProvision=false.
2: System : The agent has full access and can make all requests to the provisioning API. This is functionally equivalent to CanProvision=true.
3: Self : The agent can access the provisioning API only for their own data. Self-provisioning agents can make requests to access and modify their own channels list and metadata, and can also search for channels. However they cannot access or modify data of other agents, users or throttles.
Note that CanProvision will still function as before and is used if the ProvisioningMode is not specified.
9.3 Obtaining Channel IDs
Channels – chat rooms and users – are referenced by ID. The ID of a channel is typically not a well known value, since the ID of a chat room does not map or depend on its name. Therefore, for convenience, the Provisioning service provides a mechanism to search for and obtain the IDs of available channels – the Channels resource collection.
These available channels are fetched by directly searching the underlying chat system and as such fulfilling such requests to the Channels resource collection requires a connection to the underlying chat system to be available. For this reason, requests to this collection can only be serviced using a token that maps to an agent – that agent is used to perform the query of the underlying chat system.
It is suggested therefore that to configure the MindLink API for the first time, a master “provisioning slave” agent is created that can then be used to perform channel search queries. This agent would typically:
Be given a chat-system account that has access to all available channels – i.e. it must be able to “see” the channels on the chat system for them to be returned in the search queries. In Skype terms, this means it must be have rights to view chat rooms in every category.
Have its “CanProvision” property set to “true” (or "ProvisioningMode" set to "2"). This is because all requests made to the Provisioning service must be made with a token that maps to an agent that can provision (unless the token is for the super user).
Have all administrator users in its Users collection. This means that all administrators will be able to have access to and obtain a token to use this agent.
All Agent resources have a “MetaData” sub-resource collection. This metadata can be used to store arbitrary key/value configuration that an application using that agent can understand. The purpose of this is to facilitate the “inversion of control” design principals whereby all application configuration is driven from the administration of the central MindLink API server.
Via the Collaboration service, applications can subscribe to notifications of their metadata being changed by the administrator and be coded to take action accordingly.
9.5 Initial Set Up
The typical workflow for initial set up of the MindLink API via the provisioning service would be as follows:
In the MindLink Management Center, set the super user as “domain\mindlinksuperadmin”.
From the Authentication service, obtain a token for user “domain\mindlinksuperadmin”.
Using this token, make a request to create the normal admin users e.g. “admin1” with user name “domain\mindlinkadmin1”.
Make a request to create a provisioning slave agent e.g. “adminagent1” with user name “sip:email@example.com”, and “CanProvision” to true.
Assign the “admin1” agent to the users collection of “adminagent1”.
Re-authenticate by obtaining a token using the standard admin account – “admin1” with agent “adminagent1”. This will be the standard way of authenticating to provision in future.
Create and configure the agents and users for your applications using the new token.
Obtain the Channel IDs for each agent by searching the Channels resource collection – an operation which will be mapped to and serviced by the “adminagent1” agent.
Sample Code Repository
Sample code can be downloaded from https://github.com/mindlink/api-samples