Backend integration

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

Connection URL

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

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

Certificate

When implementing your HTTPS REST service, you must provide a standard certificate, for example, using Let’s Encrypt  . Otherwise, connecting to the web service from Dialog will not be allowed.

Custom private certificates cannot be used.

Date header

The Dialog service adds a standard HTTP Date header as part of the HTTPS request to your service.

This header contains the date and time at which the request originated, in the GMT time zone.

The header uses the following format:

Date: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT

Where:

• <day-name> is the three character day of the week, for example, “Mon”, “Tues”, “Wed”, and so on.
• <day> is the day of the month using two digits. For example, “01”, “02”, “03”, and so on.
• <month> is the three character English month abbreviation. For example, “Jan”, “Feb”, “Mar”, and so on.
• <year> is the four digit Gregorian calendar year. For example, “2020”, “2021”, and so on.
• <hour>, <minute>, and <second> give the hour (24 hour clock), minute, and second, respectively, of the GMT time, using two digits each.

For example:

Date: Mon, 27 Nov 2023 16:53:00 GMT

Supported methods

The Dialog server currently handles the following methods:

• POST
• GET

POST method

The POST method requires as input, and output, a JSON map of objects.

Input

The POST method requires as input a JSON map of objects: the variables configured in the Send Data section 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: the variables configured in the Get Data section 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:

• A returnCode of “0” indicates that the transaction was successful; the dialog flow will continue to the node specified in the Success section of the data access node.
• Any value other than “0” indicates that the transaction failed; the dialog flow will continue to the node specified in the Failure section of the data access node.

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"
}

Example

This Java example for a coffee app returns coffee prices based on coffee size and type.

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;
    }

}

GET method

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

As a best practice, use a standard GET method, that is:

• Input: You can send Mix.dialog variables as URL parameters; see Specify URL parameters for details. These variables must be configured in the Send Data section of the data access node.
• Output: As with the POST method, the GET method must return as output a JSON map of objects. See POST method output for details.

Specify URL parameters

You can pass Mix.dialog variables as URL parameters in a GET request by specifying the variable name in curly braces in the URL Extension field.

For example, to pass the values of the COFFEE_TYPE and COFFEE_SIZE variables, specify them in the URL Extension field of the data access node as follows:

/coffee/price?coffee_type={COFFEE_TYPE}&coffee_size={COFFEE_SIZE}

The dialog engine resolves the value of any variable in curly braces, so you can use variables in the endpoint path as needed. For example:

• coffee/{myVar1}/{myVar2}
• coffee/price?{myVar1}={myVar2}
• coffee/{myVar1}/price?par1={myVar3}

The variable values will be URL-encoded when used as URL query parameters. For example, the variable value 7/31/2021 5:15pm will be automatically encoded to 7%2F31%2F2021%205%3A15pm by the dialog engine.

Dialog service mTLS support

Dialog service supports mTLS with client X.509 certificates to give additional security for backend integrations. This allows you to verify that the backend data request actually comes from the expected source.

Confirm Nuance-hosted Dialog service as sender

Dialog service sends a certificate. Perform the following checks on the certificate:

• Verify the certificate CN name, which should be backend.dlgaas.nuance.partner.azure.com
• Verify that the certificate is signed by a valid Microsoft Azure issuing CA. For more details, see Azure Certificate Authority Details  . Note that the CA in the path will change regularly. See Certificate lifecycle for details.

Confirm that request comes from expected application

The request from Dialog also includes the application Mix App Id in the HTTP header as x-nuance-application-id. This allows you to verify that the request is coming from your own Dialog application and not that of another organization.

Recommended approach

By creating an integration layer consisting of a cloud function and a key-value store between Dialog and your web service, you can receive requests and authenticate the source of the request before passing it along to your web service to fetch the data.

Nuance recommends the following approach:

1. Create a cloud function, whether using an Azure function, AWS Lambda, Power Automate flow, or other similar mechanism.
2. Create an Azure Key Vault, AWS Key Management, or similar to store any authentication credentials (for example, OAuth) for your web service.
3. Configure your Dialog data access node to call the cloud function, rather than your web service directly.
4. The cloud function validates the certificate and app Id received from the Dialog service. If these are as expected, it forwards the request to your web service. The function returns the data that comes back to Dialog.

The diagram below illustrates in brief how this works.

Certificate lifecycle

Certificates are created with a validity period of three months and replaced 40 days before the end of that period.