Data connections

The Health bot service is a highly configurable and extensible bot building platform. One of the core capabilities is the ability to integrate third party services into your scenarios and flows.

To build such integrations we provide a data connection object which allows you to make HTTPS calls to third-party API providers or your own API endpoints.

Data connections can be defined at two levels.

  • Connection level configuration: These configuration details set the baseline for the data connection and are included in all the calls to the connection endpoints

  • Step level configuration: This configuration can extend or override the connection level details. They are used at specific scenario steps and don’t apply to every calls made to the connection.

For example, you would typically define the base URL at the connection level, and specify the path for each endpoints at the scenario step level. In this article we walk through the process of creating a new connection and adding it to your scenarios.

First you should open the Health Bot Management portal and login to your account as an administrator. Navigate to the Integrations tab and open the Data connections section. Here you should add a new connection and you will be prompted to provide the connection details.

Screen shot of connection level settings

Connection details

  • Name: Provide an internal name for identifying the data connection. The name can be anything you want.
  • Description: This is an internal description for the connection. For tenants that have many connections this can help you manage and recognize your connections.
  • Protocol: For most connections select the HTTPS option. If you are integrating with a system that supports the FHIR protocol you can also select this option. Learn more about FHIR data connections
  • Base URL: Provide the base URL for your data connection. The base URL should include the HTTPS protocol and the parts of the domain and path that will be consistent across all the connection endpoints (the full path is defined at the step level). For example, a base URL will look like: https://api.mydataconnection.com/v1/
  • Authentication provider: In some cases data connections are used to retrieve customer data. You can add an end user authentication layer to your connection. This will prompt end users to login via the chat thread when interacting with your bot. Learn more about end user authentication

Static parameters

You can also provide connection level, header and URL parameters that will be included in every call to the connection endpoints. For example, if your end point is authenticated with an API key you can add the key as a static URL parameter.

Once you have defined your connection you need to include the step in a scenario to make a call to the end point. Navigate to the scenario manager and open a new scenario in the visual editor.

Drag the data connection object onto the canvas and select the connection that you created earlier. The data connection has input nodes for sending scenario data to the connection and output nodes for receiving the response and any errors from the HTTPS call.

Screen shot of step level connection settings

The connection level information already provided should be prepopulated at the step level. In the visual editor you can define additional step level details or override the connection level parameters by simply using the same keys with different values.

  • HTTPS Method: Select the HTTP verb for the call you want to make to the connection.
  • Content type: Select the content type for the payload. This will be determined by the type of data expected by your API provider.
  • Base URL: The base URL is defined at the connection level. You can also use global variables to set the Base URL dynamically if you have different endpoints for testing and production environments.
  • Path: The path is appended to the base URL. If you are using a RESTful API the path is the resource that you are trying to access or modify.
  • Query parameters: Query parameters are added to the URL. Use string expressions in this field to set parameter values dynamically based on scenario data.
  • Header: Add header parameters if required. Header parameters defined at the connection level do not need to be displayed here and will be added dynamically. Header key value pairs are expected as a flat JSON objects or JavaScript objects.
  • Payload: Add the payload expected by the API endpoint. Payload parameters are expected as flat JSON or JavaScript objects.
  • Response: Add a variable name for the HTTP response. This variable will be available to you in the scenario conversation variables and allow you to access the response body.
  • Error: Add a variable name for error codes and messages that are returned from the endpoint. This variable will be available to you in scenario environment.

Once you have defined the details your connection is now ready. You can connect the output nodes from your data connection to the next steps in your scenario flow. There you can consume the response object or see any errors that have returned.

Custom connections

It is also possible to define the full connection details in the scenario itself. If you select the “custom” data connection all the fields will become editable and you can create a connection entirely at the step level.

In some cases authentication is required before using a data connection. Learn more about server to server authentication or end user authentication