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.

dlb web architecture
Figure 1. The overall Dialogue Branch Web Architecture. The Web Service acts as a REST API wrapper around the Dialogue Branch Core, allowing Dialogue Branch Clients to render remotely executed dialogues.

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).

dlb web swagger
Figure 2. Screenshot of the provided Swagger pages for the Dialogue Branch Web Service (v1.0.0).

Dialogue Execution

A typical workflow for a client application interacting with the Web Service is a follows:

  1. Call the /auth/login end-point, providing a username and password to authenticate a user and obtain a JSON Web Token (JWT).

  2. Store the JWT, and include in the header (name: X-Auth-Token, value: <your-jwt>) for all subsequent calls.

  3. Start the execution of a dialogue, by calling the /dialogue/start end-point, providing dialogueName, language and timeZone.

  4. Render the resulting JSON object as a dialogue user interface to the user, and store the loggedDialogueId and loggedInteractionIndex.

  5. When the user selects a reply, call the /dialogue/progress end-point, providing the previously memorized loggedDialogueId and loggedInteractionIndex, as well as the selected replyId.

  6. The result is a JSON object with the same structure as received in step 4, which can again be rendered, repeating the process.

dlb web api sequence
Figure 3. Sequence diagram for a typical User to Client to Server scenario of authenticating and executing dialogues with the Dialogue Branch Web Service

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).

dlb web user vs admin authentication
Figure 4. The two modes of authentication. Left: multiple clients authenticate directly "as themselves" with the Web Service. Right: a trusted server component authenticates as an "admin" user, on behalf of multiple "delegateUsers".

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:

dlb web ext var service sequence
Figure 5. Sequence diagram for the flow of operations between a Client, the Dialogue Branch Web Service, an External Variable Service, and a 3rd Party API
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.