Skip to content

Latest commit

 

History

History
98 lines (64 loc) · 7.05 KB

integration-guide.adoc

File metadata and controls

98 lines (64 loc) · 7.05 KB
Raw

Smarti Integration Guide

The development of Smarti follows an API-driven approach (API-first).

Whenever new features will be released for Smarti, the first step is to develop the corresponding API. This means that before developing any Apps or other graphical user interfaces, the API already exists: No feature without an API. This makes it very easy to integrate Smarti into third party applications.

Smarti’s web services are basically divided into the following five components:

Note
 the Chat Adapter was removed with v0.7.0. Most of its functionality was integrated in the Conversational Analyzing Webservice.

In the following sections each web service is introduced briefly.

The aim of this documentation is to explain every web service at a high level. It is not the aim of this documentation to learn how the individual API calls work in detail, but rather to understand what the goal of the individual web services is and why they are built as they are.

Swagger documentation

Smarti’s web services are designed and documented using Swagger. Who is interested in implementing against the RESTful-API should move to Smarti’s Swagger API documentation. If Swagger is new to you, follow this link to familiarize yourself with Swagger: Getting started with Swagger

At runtime Smarti provides a generated Swagger JSON file that can easily accessed by opening the following URLs within your web browser:

You can copy & past the raw JSON from http://${smarti-host}:${smarti-port}/v2/api-docs into any Swagger editor of your choice. Alternatively Smarti provides a Swagger user interface to browse the API without using external tools:

Integration tasks

  1. Preconditions

    1. Setup Smarti

    2. Create a client

    3. Create a client configuration

    4. Create a client auth token

  2. Chat Integration

    1. Store the auth token

    2. Authenticate each request

    3. Adapt Smarti into Chat (onMessage, callback, onClose)

    4. Implement a backend for the integration widget/bot

  3. User Interface

    1. Implement a widget

RESTful-Integration Sequence

The /conversation service supports CRUD functionality for Conversation. In Smarti Conversational data are represented by Conversations that contain messages. Data of the chat server need to mapped to this model.

The simplest model is to map a channel/room of the chat to a single conversation in Smarti. All messages in that channel/room can be added as messages to the conversation. However integrators may also choose different mappings. In any way, the mapping between channel/rooms and conversations in in the responsibility of the integrator. While it is possible to store channel/room IDs with the conversation it is the responsibility of the integrator to provide this mapping.

RESTful-Integration Sequence

  1. Create a Conversation: The payload for this operation is optional. If no payload is present Smarti will create an empty conversation and assign an unique ID to it. If a payload is present the provided data are stored. The provided conversation can contain any data (such as existing messages). The ID is always assigned by Smarti.

  2. Append a Message: Messages are assigned to conversations therefore all CRUD operations on Messages are in the context of an existing conversation. Smarti allows to set IDs of messages (assumed to be unique within the conversation). Integrators can therefore use message IDs of their chat system. If no message IDs is provided Smarti will assign an unique ID.

  3. Analysis results for the current state of the conversation. This is an expensive operation. So expect longer response times (possible in the seconds). To mitigate this Smarti per-processes analysis on changes to conversations. So retrieving an analysis for a conversation that has not changed recently is typically fast. When called immediately after an update pre-processing will not have finished and response times will be longer. The following section provides more information retrieving analysis results asynchronous via a callback.

  4. Update conversation fields: Smarti allows to store meta infomation for conversation and messages. Those can be updated and deleted. The key of the field is part of the request path. The value is represented by the JSON playload. A similar possibility exists for messages.

  5. Complete Conversation: by setting the meta.staus field to "completed". Completion of a Conversation does NOT prevent from future modifications, but as an indicator that the conversation is in a state so that it can be used as an information source. Several components allow to exclude none completed conversations from results and suggestions.

As the analysis of conversation is an expensive opertation the /conversation service supports asynchronous callbacks for analysis results. This mode is activated by including the callback parameter in requests to the conversation service. All CRUD operations that result in modifications of the conversation do support this parameter (see the Swagger documentation for details).

The callback needs to be a valid URL supporting POST requests with a application/json payload with the Analysis results.

The following figure shows how this works.

RESTful-Integration Sequence

  1. Create a Conversation: As described above the conversation is created assigned an unique ID and returned to the caller (sync). If a callback is given the results of the analysis is POST to this URL as soon as it is available.

    1. The callback receives an Analysis object that referes the conversation (by id) and the analysed version of the conversation (by modified date).

  2. Append a Message: As with the sync workflow the added message is sent back synchronously. The analysis results of the updated conversation are POST to the provided callback when processing finishes.

    1. The callback receives an Analysis object that referes the conversation (by id) and the analysed version of the conversation (by modified date).

  3. On Analysis requests providing a callback the request is confrimed by a 202 Accepted. The actual analysis is sent to the callback URL (even if it is already pre-processed and available)