Set up a data access node

Use data access nodes to exchange information with a backend system. For example:

• In a coffee shop application, look up the price for the specified coffee type and size
• In a coffee shop application, look up special coffee types that might only be available on specific occasions, to complement the regular menu
• In a banking application, look up all payees registered for the specified user
• In a pharmacy application that allows users to refill their medication, check whether the specified medication is valid for the current user and whether it’s available at their preferred location
• In an IoT application, trigger an action such as turning on the water heater, for the user
• Send a message into a messaging bus system

Remember that the client application or a dedicated backend are often better suited than the dialog model to perform conditional logic, such as iterating through lists to verify, for example, whether a medication is listed in the user’s file and that the maximum number of refills hasn’t yet been reached.

Click a data access node on the design canvas, to see its properties in the Node properties pane.

  Data access node properties example  

To set up a data access node:

1. Specify a latency message if desired.
2. Specify data to send to the backend, if any.
3. Specify data to get from the backend, if any.
4. Specify where to go with the returned data.
5. Configure backend connection details, if required.

Specify a latency message

1. Click + Latency message.
   The fields that appears let you set a message, formatting parameters (for text output), and properties to determine when to show or play the message, and for how long (for audio output).
2. If the latency message must be limited to a specific channel, choose the desired channel.
   
3. Click the message placeholder.
   This opens the message editor.
4. Use the message editor to create your message.
   Tip: In the message editor, you can click the Library icon to open the Messages resource panel and add variations to your latency message, for other channels and output modalities.
5. (Optional) Use the View messages as selectors to review any message variations, by channel and output modality, directly on the compact message.
   Once you have selected a modality, your selection persists as long as the current channel supports it. If you switch to a context where the applicable channel doesn’t support the selected modality, the modality selector falls back to the first modality available for the current channel.
6. (Optional) If the latency message is meant to appear in a text form, in the View area, specify formatting information to pass to the client application.
   Type and Class or CSS are freeform parameters—the client application is responsible for interpreting them.
   
7. (Optional) If you wish to override the global fetching properties for you project, set the desired Fetch delay and Fetch minimum values.
   

Remove the latency message

Click the Delete icon in the upper-right corner of the Latency message section.

Specify data to send to the backend

Self-hosted environments: Sending Last Message Object requires engine pack 2.3 (or later) for Speech Suite deployments; engine pack 3.11 (or later) for self-hosted Mix deployments.

1. Under Send data, click + Variable/Entity.
   
   A compact Send placeholder appears.
   
2. Click the placeholder.
   An editor appears.
3. Use the selector to choose an element you want to send to the backend system.
   You can send a variable, an entity, the messages from the last visited message node or from the latest step of the last visited question and answer node (Last Message Object), the active intent’s value, confidence score, and literal, or the interpretation results from the last collection and confirmation steps (see Predefined variables for more details).
   
   Tip: Use the search fields to narrow down the lists if needed. If a variable you want to send is missing, you can create it on the fly, and then use it immediately.
4. Click outside the editor to close it.
   The Node properties pane shows the compact Send parameter.
   
5. If you want to send more elements:
   1. Click the Add icon , below or above a Send parameter, and then click Variable/Entity.
      A compact Send placeholder appears.
   2. Click the placeholder and use the selector in the editor that appears, as described above.
   3. Proceed in the same fashion until you have added all the variables, entities, or other elements you want to send to the backend system.
      

You can reorder and remove Send parameters, if desired.

Specify data to get from the backend

Under Get data specify the variables you want the backend system to return, if any. The Dialog service expects backend systems to always set these two predefined variables: returnCode, and returnMessage. You do not need to specify them in the Get data section of your data access nodes. However, if you want to validate your data access node’s failure path in preview mode, add returnCode to the Get data section, momentarily. This will allow you to enter a non-zero value when the data access node prompts for stub values, in the chat pane.

To add Get data parameters:

1. Under Get data, click + Variable.
   
   A compact Get placeholder appears.
   
2. Click the placeholder.
   An editor appears.
3. Use the selector to choose a variable you want to get from the backend system.
   
   Tip: Use the search field to narrow down the list if needed. If a variable you want to get is missing, you can create it on the fly, and then use it immediately.
4. Click outside the editor to close it.
   The Node properties pane shows the compact Get parameter.
   
5. If you want to get more variables:
   1. Click the Add icon , below or above a Get parameter, and then click Variable.
      A compact Get placeholder appears.
   2. Click the placeholder and use the selector in the editor that appears, as described above.
   3. Proceed in the same fashion until you have added all the variables you want to get from the backend system.

You can reorder and remove Get parameters, if desired.

Remove a Send or Get parameter

1. Bring your pointer to the right-hand side of the parameter you want to remove.
2. Click the More options icon that appears and choose Remove Variable/Entity (for a Send parameter), or Remove Variable (for a Get parameter).
   

Move a Send or Get parameter

1. Bring your pointer to the right-hand side of the parameter you want to move.
   
2. Use the handle that appears, to drag the selected element up or down.
3. Drop the selected element at the desired position.

Create an input variable on the fly

In the Send data section of data access nodes and external actions nodes, you can create input variables directly from the search field at the top of the Variables list. This feature is also available from the Send data section of question and answer nodes.

1. Navigate to the Variables list, and click the search field.
   
2. Enter a name for the new variable (see Naming guidelines).
3. Click the Add icon .
   The new variable appears in the list, with an indication that its type is string.

You can now choose the new variable. Unless the variable is meant to be of type string (default), remember to use the Variables resource panel to complete its definition. See Manage variables.

Create a return variable on the fly

In the Get data section of data access nodes and external actions nodes, you can create return variables directly from the search field at the top of the variables list.

1. Click the search field.
   
2. Enter a name for the new variable (see Naming guidelines).
3. Click the Add icon .
   The new variable appears in the list, with an indication that its type is string.
   

You can now choose the new variable. Unless the variable is meant to be of type string (default), remember to use the Variables resource panel to complete its definition. See Manage variables.

Specify where to go with the returned data

1. Set the GoTo transition to perform when the external system returns a success code.
   A success return code means that the dialog was able to communicate with the backend. It doesn’t mean that the backend actually returned the desired data.
2. Set the GoTo transition to perform when the external system returns a failure code.

Set up backend connection details

By default data access nodes support client-side integration—that is, data is to be exchanged between the dialog runtime service and the client application. In such a case, the client application itself is set up to access any required backend system and no further configuration is required for your data access node.

Otherwise, if your data access node must communicate directly with an external data host, turn off Enable client-side fetching, under Integration, and use the fields that appear to configure server-side integration.

Refer to Exchange data with an external system for more information on setting up server-side integration (as opposed to client-side integration).

See also: Configure default connection settings for information on creating connection profiles you can apply to multiple data access nodes.