Share via

Data Connections

  • Article

To integrate with external data resources, 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: This 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're 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 endpoint 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 healthcare agent service Management portal and sign in to your account as an administrator. Navigate to the Integrations section and open the Data connections page. Here you should add a new connection and you are prompted to provide the connection details.

Screen shot of a new data connection

Connection Types

There are four different data connection types available.

  • General Endpoint: A secure HTTPS connection to any of your backend endpoints.
  • FHIR Endpoint: A secure HTTPS connection to your FHIR server.
  • Azure OpenAI Endpoint: A secure connection to your Azure OpenAI instance
  • Customer Source Connection: Information to connect to your Azure Cognitive Search service to work with your data.

General Endpoint

When selecting the General Endpoint,** you can configure the following elements

  • Name: Internal identifying name for the data connection. For internal user usage.
  • Description: Internal description for the connection.
  • Type The type of data connection, such as General Endpoint, FHIR endpoint, Azure OpenAI endpoint or Customer Source endpoint.
  • Base URL: The base URL should include the HTTPS protocol and all the path parts that will be consistent across all the connection endpoints (the full path is defined at the step level). For example, a base URL looks like: https://api.mydataconnection.com/v1/
  • Authentication provider: In some cases data connections are used to retrieve customer data. This prompts end users to sign in via the chat thread when interacting with your bot. Learn more about authentication providers
  • Headers: If necessary, one may add header data to be added in the HTTP call.

A Screen shot of a general data connection

FHIR Endpoint

Healthcare agent service data connections can be used integrate with systems that support FHIR. FHIR is an HL7 standard for transferring electronic medical records (EMR). FHIR prescribes a format for accessing EMR resources and actions on the resources, which follow RESTful principals.

Different FHIR endpoints support different resources and have specific payload structure for interacting with the resource. When you define a FHIR data connection we fetch the supported resources from the endpoint and provide intelligent suggestions for building the correct FHIR payload structure.

In this article we'll connect to a dummy FHIR endpoint to demonstrate the functionality.

With FHIR connections you only need to provide the base URL and the resource endpoints are implicit. Here's a list of FHIR servers publicly available for testing purposes. In this example, no authentication or static parameters are required, for the FHIR server we used the PyroHealth test endpoint: https://stu3.test.pyrohealth.net/fhir

Screen shot of a new FHIR data connection, not fetched

Once you provide the base URL, the resource endpoints are defined automatically. To see the resources supported by your endpoint select on “Fetch Resources” at the bottom of the connection.

Screen shot of a new FHIR data connection, n fetched

To make a call to your FHIR endpoint, add the data connection object to a scenario in the visual editor. In the step level details you'll see the resources and actions available to the FHIR end point are automatically populated. Select the resource and action you would like to make and provide the payload according to the FHIR schema.

Screenshot of step level FHIR data connection settings on the scenario editor

The payload will intelligently suggest the objects according to the schema supported by the specific FHIR resource. Your scenario is now integrated with a FHIR server and can access resources in your EMR system.

Azure OpenAI Endpoint

Important

This feature is currently in Public Preview

To enable the Generative Answer step, you'll need a valid Azure OpenAI connection. When selecting the Azure OpenAI endpoint, you'll need to provide the following values

  • Name: Internal identifying name for the data connection. For internal user usage.
  • Description: Internal description for the connection.
  • Azure OpenAI endpoint: Your Azure OpenAI Endpoint
  • Azure OpenAI Key: Your Azure OpenAI Key
  • Chat Completion Deployment Name: The name of the deployed Chat Completion name
  • Maximum Tokens: The maximum number of tokens you want to use for the grounding

Important

Based on the grounding data we advice to set the maximum number of tokens between 8K and 16K depending on the grounding data. For chat with your public data via Bing Custom Search we recommend setting this to 16K due to webpage sizes.

Because we are leveraging Azure OpenAI Content filter, every customer should have Azure Content Filtering including jailbreak enabled on their Azure OpenAI Endpoint. When adding a new Azure OpenAI Endpoint, you explicitly need confirm this by checking "I confirm the Azure OpenAI endpoint has Azure Content Filtering including jailbreak enabled"

Screenshot of a new Azure OpenAI Data Connection

Customer Source Connection

Important

This feature is currently in Public Preview

To enable the Generative Answer step grounded on your data, you'll need to provide your vector database. Currently we support Azure Cognitive Search Service as a customer source.

You'll need to provide the following values:

  • Name: Internal identifying name for the data connection. For internal user usage.
  • Description: Internal description for the connection.
  • Type: Customer Source Connection
  • Customer Source Type: Azure AI Search
  • Search Service Endpoint: Your Search Service endpoint
  • Search Service Index Name: The name of your index
  • Search Service Admin Key: The Search Service Admin Key
  • Search Type: You can select either Vector, Hybrid (Vector + Keyword) or Hybrid + Semantic
  • Relevance Score: A numerical value indicating how relevant the result should be in alignment with the user's query.
  • Max Response Length: The max response length that should be returned to the end-user

Screenshot of a new Customers Source Connection Azure AI Search

To enable the Generative Answer step grounded on your public data, you'll need to provide your bing custom search key and configuration id.

You'll need to provide the following values:

  • Name: Internal identifying name for the data connection. For internal user usage.
  • Description: Internal description for the connection.
  • Type: Customer Source Connection
  • Customer Source Type: Bing Custom Search Service.
  • Custom Config ID: The custom config ID from your Bing Search service instance.
  • Bing Custom Search Key: The Bing Custom Search key to access the endpoint.
  • Max Response Length: The max response length that should be returned to the end-user

Screenshot of a new Customers Source Connection Bing Custom Search

Next steps

Authentication Providers