NAV Navbar

Exchange data with an external system

Data access server-side integration

Data access client-side integration

You may need to exchange data with an external system in your dialog application. For example, you may want to take into account information about the user's location from the client's GPS data, a user's stored preferences or contacts, or perhaps business-specific information such as their bank account balance or their flight reservations. It all depends on the type of application you're building.

For example, consider these use cases:

Exchanging data is done through a Mix.dialog data access node. Data access nodes allow you to exchange information in two ways:

Example used in this section

To illustrate the process of exchanging data in your Mix.dialog application, this documentation uses a coffee application as an example.

This application has the following dialog:

In this example, the following information is sent by the dialog application:

And the following information is retrieved from an external system:

Server-side vs. client-side integration

Exchanging data in Mix.dialog is configured in the data access node. To specify whether data is exchanged using a server-side integration or a client-side integration, set the Enable client-side fetching integration option as follows:

Value Example Description
Enabled Enable client-side fetching Client-side integration; data is exchanged between the dialog service and the client application, using the DLGaaS API.
Disabled Disable client-side fetching Server-side integration; the dialog service interacts directly with a backend system to exchange data.

Exchanging data from the dialog application

In this option, Mix.dialog accesses a backend server through a set of REST HTTP API calls that are constructed by configuring the data access node.

For example, consider a backend web service hosted at https://coffee.app.com:443/ that supports the following HTTP calls:

Let's say that in your dialog application, after having collected the coffee type and size, you want to provide the price to the user for confirmation.

To implement this scenario, you configure the data access node to specify the following:

At runtime, the dialog engine creates an HTTP request from the data access node configuration and then executes that request, as shown in the following interaction:

Workflow

To exchange data from the dialog application:

  1. Configure the base URL of the web service.
  2. Configure the data to exchange in the data access node
  3. Build and deploy the dialog application

Configure the base URL of the web service in Mix.dashboard

Sample Data Hosts tab for coffee app

The Data Hosts tab lists the web services that are defined for a project. Server-side integration requires that the dialog runtime application has access to the backend server, so the URL of a web service may differ per environment.

The Data Hosts tab lets you specify an alias name to identify the web service, and you can set different URLs for this alias according to the environment, as appropriate.

By default, the Data Hosts tab has the following tabs:

If you have multiple environments (for example, QA, Production, etc.), a tab is available for each environment.

To add an alias and configure the base URL of the web service:

  1. In Mix.dashboard, select the project.
  2. Click the Data Hosts tab.
  3. Click the Aliases tab.
  4. For each web service:
    1. Enter the Alias name. For example, for the coffee app, you might enter COFFEE_APP.
    2. Enter the base URL for this Alias (Optional). For example, for the coffee app, this might be https://coffee.app.com:443/
  5. Click Add Alias.
  6. To specify a different URL for the Sandbox or any other environment (optional):
    1. Click the tab for the environment.
      For example, click the Sandbox tab.
    2. Click the Edit icon Edit icon for the alias.
    3. Enter the base URL and press Return.

Order of precedence for URL values

You can specify a URL for an alias in the following locations:

Configure the data to exchange in the data access node

Example: Data access node for server-side integration

To configure the data to exchange for a server-side integration, create a data access node in Mix.dialog and specify the following fields:

Field Description
Send Data Data that will be sent to the client application, for example, coffee size and type. This can be a variable or an entity.
Get Data Data that will be returned by the client application, for example, coffe price. This is a variable.
Success Node to go to if the external system returns a success code; that is, a returnCode of "0".
Failure Node to go to if the external system returns a failure code; that is, a returnCode that is not "0".
Integration Disable the Enable client-side fetching option to indicate that the dialog service interacts directly with a backend system to exchange data. See Server-side vs. client-side integration.
Copy connection settings from Lets you select default connection settings. See Configure default connection settings.
Data Host Alias Alias configured in the Mix.dashboard to define the web service. For example, COFFEE_APP might refer to https://coffee.app.com:443/. See Configure the base URL of the web service in Mix.dashboard.
URL Extention Specifies the endpoint used to access the data; for example, /coffee/price and /coffee/calories. This is defined by the backend.
Fetch Timeout Number of milliseconds allowed for fetching the data before timing out.
Connection Timeout Connection timeout in milliseconds.
Method HTTP method to use; supported values are POST and GET. This is defined by the web service.
Headers List of key-value pairs providing the headers to send to the web service.

Note: The Try pane cannot be used to test the connection to the backend. It will always trigger the Failure node.

For a detailed description of the data access node, see Set up a data access node.

Configure default connection settings

You can configure default connection settings and use them in the data access node. This is useful if you plan to reuse them in multiple data access nodes.

To configure default connection settings:

  1. On the Mix.dialog toolbar, click Data.
  2. Click the + icon next to Data connections.
  3. Type a unique name for the data connection and press Enter.
  4. Enter the following information:
Field Description
Data Preset Name Enter a name that defines this data connection.
Data Host Alias Alias configured in the Mix.dashboard to define the web service. For example, COFFEE_APP might refer to https://coffee.app.com:443/. See Configure the base URL of the web service in Mix.dashboard.
URL Extention Specifies the endpoint used to access the data; for example, /coffee/price and /coffee/calories. This is defined by the web service.
Fetch Timeout Number of milliseconds allowed for fetching the data before timing out.
Connection Timeout Connection timeout in milliseconds.
Method HTTP method to use; supported values are POST and GET. This is defined by the backend.
Headers List of key-value pairs providing the headers to send to the web service.

Build and deploy the dialog application

To test your application in the runtime environment, you need to build a new version and deploy it in an environment.

When you deploy the application, you can configure a new URL for the alias if necessary, as shown in the following diagram. This URL will take precedence over all other values previously defined.

Backend integration requirements

When implementing the REST web service for a server-side integration, please follow these guidelines.

Connection URL

For security considerations, outgoing traffic is only allowed on port 443, using https.

Please contact your Nuance representative if you need a different connection option.

Certificate

You must use a standard certificate when implementing the HTTPS REST service, for example, using Let's Encrypt. Otherwise, connecting to the web service from dialog will not be allowed.

Custom, private certificates cannot be used.

Supported methods

The Dialog server currently handles the following methods:

POST method

Java example for a POST method in a coffee app; uses the Spring framework

package com.nuance.coretech.dataaccess.controller;

import io.opentracing.Tracer;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import java.util.HashMap;
import java.util.Map;

/**
 * Returns coffee prices for testing
 */
@Controller
@RequestMapping("/coffee")
public class CoffeeController {
    private final Tracer tracer;
    private final Logger log = LoggerFactory.getLogger(CoffeeController.class);

    /**
     * Default constructor that gets autowired by springboot.
     * @param tracer Tracer to use.
     */
    @Autowired
    public CoffeeController(Tracer tracer) { this.tracer = tracer; }

    /**
     * Accepts POST requests with JSON body representing the coffee contents.
     * The values used are invented and not real data. 
     *
     * @param body The request body must be a JSON map of objects
     * @return a JSON string representing a map of returned values.
     */
    @PostMapping("/price")
    @ResponseBody
    public Map<String,Object> execute(@RequestBody Map<String,Object> body)
    {
        Map<String,Object> response = new HashMap<>();

        String size = (String) body.get("COFFEE_SIZE");
        String type = (String) body.get("COFFEE_TYPE");

        if (size!=null) size = size.toLowerCase();
        if (type!=null) type = type.toLowerCase();

        // This is an example for nullpointer exceptions are not handled here
        switch (type) {
            case "cappuccino":
                switch (size) {
                    case "small":
                        response.put("coffeePrice", "1.95");
                        break;
                    case "large":
                    case "medium":
                    default:
                        response.put("coffeePrice", "2.85");
                        break;
                }
                break;

                ...more options... 

            default:
                throw new RuntimeException("Coffee type "+type+" unknown");
        }

        // returning SUCCESS
        response.put("returnCode", "0");

        // logging for debugging and testing
        log.warn("Querying Coffee type {} with size {} resulted in the price: {}",
                type,
                size,
                response.get("coffeePrice"));

        return response;
    }

}

Input

The POST method requires as input a JSON map of objects. These are the variables that will be configured in the Send Data fields of the Data Access node.

For example, for the coffee app, the request sent by the dialog application might look as follows:

 
POST /coffee/price HTTP/1.1
Host: coffee.app.com
Content-Type: application/json;charset=UTF-8

{
    "COFFEE_TYPE": "cappuccino",
    "COFFEE_SIZE": "medium"
}

Output

The POST method requires as output a JSON map of objects. These are the variables that will be configured in the Get Data fields of the Data Access node.

The returned payload must include the following variable:

returnCode

This variable indicates whether the query was successful and will be used by the dialog flow, as follows:

For example, for the coffee app, the dialog application would expect a response similar to the following:

 
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 21 May 2020 14:04:00 GMT
{
    "returnCode": "0",
    "coffeePrice": "2.85"
}

GET method

The GET method is used to retrieve information from the backend.

Nuance recommends that you use it as a standard GET method, that is:

Exchanging data with the client application

In this option, variables are exchanged between the dialog service and the client application using the DLGaaS API. The variables to send and receive are configured in Mix.dialog in the data access node. This request gets translated as a data action, which tells the client app that the dialog expects data to continue the flow.

Workflow

To exchange data with a client application:

  1. Create a data access node in Mix.dialog.
  2. Use the data access action API in the client app

Create a data access node in Mix.dialog

Example: Data access node for client-side integration

To configure the data to exchange for a client-side integration, create a data access node in Mix.dialog and specify the following fields:

Field Description
Send Data Data that will be sent to the client application, for example, coffee size and type. This can be a variable or an entity.
Get Data Data that will be returned by the client application, for example, coffe price. This is a variable.
Success Node to go to if the external system returns a success code; that is, a returnCode of "0".
Failure Node to go to if the external system returns a failure code; that is, a returnCode that is not "0".
Integration Enable Enable client-side fetching to indicate that the data is to be exchanged with a client application. See Server-side vs. client-side integration.

For a detailed description of the data access node, see Set up a data access node.

Use the data access action API in the client app

Data is exchanged between the dialog service and the client application throught the DLGaaS ExecuteRequest and ExecuteResponse gRPC API.

For details, see Data access actions in the DLGaaS API documentation.