Data access actions

A data access action tells the client app that the dialog needs data from the client to continue the flow.

Use case

Consider the following use cases:

  • In a coffee application, after asking the user for the type and size of coffee to order, the dialog must provide the price of the order before completing the transaction. In this use case, the dialog sends a data access action to the client application, providing the type and size of coffee and requesting the price.
  • In a banking application, after having collected all the information necessary to make a payment (that is, the user’s account, the payee, and the payment amount), the dialog is ready to complete the payment. In this use case, the dialog sends a data access action to the client application, providing all the transaction details so that the client application can process the payment and provide a return code back to the dialog.

Configuration

Data access actions are configured in Mix.dialog in data access nodes. The configurations in these nodes specify:

  • Variables or entities sent by the Dialog service to the client application
  • Variables the Dialog service expects to be sent back by the client application
  • A message to play to the user while waiting for the data to be retrieved and transferred
  • Settings for playing the message

Data access actions are sent only when the data access node has enabled client-side fetching.

Data access nodes can also be configured in Mix.dialog for server-side fetching directly from a backend server without going through the DLGaaS API. In that case a Continue action is sent instead.

See Exchange data with an external system for additional details.

Using the data access API in the client app

When a data access node is configured for client-side fetching, data access information is sent and received as follows:

For example, in the coffee app use case, if a user says “I want a double espresso,” the dialog will send data access action information to the client application in the ExecuteResponsePayload:

{
  "payload": {
    "messages": [
     {
      "nlg": [],
      "visual": [
       {
        "text": "Great! A large espresso coming right up.",
        "mask": false,
        "barge_in_disabled": false
       }
      ],
      "audio": [],
      "view": {
       "id": "",
       "name": ""
      }
     }
    ],
    "da_action": {
      "id": "get_coffee_price",
      "message": {
        "nlg": [],
        "visual": [
         {
          "text": "Hold on a moment while we ring that up.",
          "mask": false,
          "barge_in_disabled": false
         }
        ],
        "audio": []
      },
      "view": {
       "id": "sample class",
       "name": "sample type"
      },
      "data": {
        "COFFEE_TYPE": "espresso",
        "COFFEE_SIZE": "lg"
      },
      "message_settings": {
       "delay": "500ms",
       "minimum": "0ms"
      }
    }
  }
}

Where:

  • id in da_action uniquely identifies the data access action node. This lets the client application know what process is required. For example, when the client app parses the ExecuteResponse and sees a data access action id of get_coffee_price, it can call a function that retrieves the coffee price.
  • data provides the values of the sent data that were configured in the Data Access node. In this case, it is entity values that were collected in Dialog. These tell the client app which coffee price it needs to look up.
  • message provides details for a message the client can play to the user while waiting on the data exchange.
  • message_settings provides settings to be used along with the message played to the user.

The client application uses that information to perform the action required by the dialog, in this case fetching the price of the coffee based on the user’s choice. While retrieving the data it plays the message to the user using the specified message settings.

When the client gets the coffee price from the data source, it then returns the value in the coffee_price variable as part of the ExecuteRequestPayload data field. Note that data also includes a returnCode.

{
  "selector": {
    "channel": "ivr",
    "language": "en-US",
    "library": "default"
  },
  "payload": {
    "requested_data": {
      "id": "get_coffee_price",
      "data": {
        "coffee_price": "4.25",
        "returnCode": "0"
      }
    }
  }
}

The returnCode is required, otherwise the Execute request will fail. A returnCode of “0” indicates a successful interaction.

Data access action sequence flow

This sequence diagram here shows a data access action exchange. For simplicity, only the payload of the requests and responses related to the data access feature are shown.

data access flow