Dialogue Branch Web Services Documentation
Overview
The Dialogue Branch Web Service is a JAVA Spring Boot Application that can be deployed as a web service. It acts as a wrapper around the Dialogue Branch Core Library, offering an API that allows you to create client-server dialogue applications. A typical, simple architecture is shown in the Figure below.
The components described in the Architecture above are described as follows (from left to right):
-
Dialogue Branch Client - Your client application that connects to the web service in order to render remotely executed Dialogue Branch dialogues.
-
Dialogue Branch Web Service - the Java Spring Boot Application that can be deployed in a web server. It provides simple user management, and a REST API.
-
REST API - a set of REST end-points for Authentication, Executing DLB dialogues, and managing DLB Variables.
-
Dialogue Branch Core - the "core" Java Library that contains the software for parsing and executing .dlb scripts. This is a collection of POJO’s (Plain Old Java Objects) that can be embedded into any Java or Android application.
-
-
External Variable Service - Your (optional) web service that may be used to provide just-in-time updates to DLB Variables.
Given the architecture above, a typical scenario for using Dialogue Branch in a client-server deployment is as follows. You deploy a DLB Web Service that has a collection of .dlb scripts embedded. You then write a client application that connects to the DLB Web Service, allowing users to login, start-, and progress dialogues. If your .dlb dialogues include Variables that need to be updated from an external source, implement and deploy your own External Variable Service and connect this to your web service deployment.
Dialogue Branch Web Service Component
The Dialogue Branch Web Service source code is part of the "dlb-web" repository at github.com/dialoguebranch/dlb-web. Specifically, it may be found in the /dlb-web-service/ folder of the repository.
The provided build.gradle
file may be used to build and deploy the Web Service to a running Tomcat 10 instance. A detailed installation tutorial is provided here: Dialogue Branch Web Service - Installation.
After having successfully deployed the web service, you can start exploring its functionalities through the provided Swagger pages (see image below).
Dialogue Execution
A typical workflow for a client application interacting with the Web Service is a follows:
-
Call the
/auth/login
end-point, providing a username and password to authenticate a user and obtain a JSON Web Token (JWT). -
Store the JWT, and include in the header (
name
:X-Auth-Token
,value
:<your-jwt>
) for all subsequent calls. -
Start the execution of a dialogue, by calling the
/dialogue/start
end-point, providingdialogueName
,language
andtimeZone
. -
Render the resulting JSON object as a dialogue user interface to the user, and store the
loggedDialogueId
andloggedInteractionIndex
. -
When the user selects a reply, call the
/dialogue/progress
end-point, providing the previously memorizedloggedDialogueId
andloggedInteractionIndex
, as well as the selectedreplyId
. -
The result is a JSON object with the same structure as received in step 4, which can again be rendered, repeating the process.
Working with Variables
Variables are used in .dlb scripts to create dynamic dialogue flow, and include flavourful personalisations. These Variables can be set and used inside the dialogue scripts themselves, as in the example below:
<<set $playerName = "Bob">>
Hello $playerName, how are you doing?
[[I'm fine.|PlayerIsFine]]
[[I'm sad.|PlayerIsSad]]
However, as in the example, it doesn’t always make sense to set the values for Variables in the dialogue scripts themselves. Instead, these values might originate from another part of your client application. Imagine that your client application is a game that includes a user interface where players can insert their name. When a player does this, the value should be communicated to DialogueBranch, so that the $playerName variable may be used in dialogues.
The Web Service offers the following 2 end-points for sending Variable-values to the service:
-
/variables/set-variable
- allowing you to set the value for a single Variable by providing a `name' and a `value'. -
/variables/set-variables
- allowing you to set the value for a number of Variables simultaneously by including a JSON payload in the body.
Using these, you can inform DialogueBranch about Variables whose values are generated through any part of your client application. The other way around, your client application can also ask the Web Service about Variable values, using the following end-point:
-
/variables/get-variables
- allows you to ask for all known Variables for a user, or a list of specific Variables (by providing a comma-separated list of variable names).
Another way of making sure that DialogueBranch has up-to-date values for Variables, is by using an External Variable Service, as explained below.
Authentication
As explained in the Dialogue Execution step, the first thing you need to do before working with the Web Service is to authenticate.
The Web Service supports two different "modes" of authenticating. Users that are defined in the users.xml configuration file can be given a role which can either be "user" or "admin" (if you don’t specify, the role "user" will be assumed).
When you authenticate with the Web Service (using the /auth/login end-point) as a regular "user", you can perform actions (start dialogues, set variables, etc) on behalf of that authenticated user. However, when you authenticate as a user that has the "admin" role, you can control dialogues (start, progress, cancel, etc) and data (set and retrieve variables) for any "dlb user" you specify using the optional delegateUser
parameters that are a part of all API end-points.
This method of authentication may be used e.g. in a scenario where "clients" don’t directly interact with the Dialogue Branch Web Service, but instead connect through a trusted web component that manages a single connection (see Figure below).
External Variable Service
An External Variable Service is a web service that may be used by a Dialogue Branch Web Service deployment to act as an external source of information for Variable data. The Web Service itself keeps track of all Variables that are set for every individual user. For example, if a Variable is set in a dialogue using <<set $variableName = "value">>
that value is stored. If your .dlb scripts only uses Variables that are set within the dialogue itself, the Web Service alone will handle everything.
However, if your dialogue contains a statement such as The temperature outside is $temperatureAtUserLocation
degrees., the value for $temperatureAtUserLocation
is something that would likely need to be fetched from an external component - that is where the External Variable Service comes in.
Every time the Web Service starts executing a dialogue script, it collects a list of all the Variables used within that dialogue. The Web Service may (or may not) already have known values for these variables, but in any case, it will send a request to the External Variable Service to check whether any of the variables require updating. Your specific implementation of the External Variable Service needs to take care of these variable updates. For example, your variable service could in turn call a 3rd party weather API to retrieve the temperature at the user’s location, and return this value to the Dialogue Branch Web Service.
This flow is outlined in the sequence diagram below:
It is worthwhile to make sure that the External Variable Service answers the request for variable updates quickly, because any delay will delay the starting of dialogue execution in the Dialogue Branch Web Service - which will negatively impact your end-user’s experience. Apply caching, and make use of the provided updatedTime parameter that is passed along with each Variable, to make quick judgements whether a variable needs to be updated at all.
|
If you found errors or have questions about this page, please consider reporting an issue at https://github.com/dialoguebranch/dlb-documentation or sending an email to info@dialoguebranch.com. |