Advanced Functionality

The healthcare agent service is a highly configurable and extensible bot building platform, specifically it allows integration with third party services and resources into your scenarios and flows. Such capability has the potential to enhance conversations and provide engaging experience to the end user.

Data connection Element

To integrate 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, more information can be found on the Data Connections Page
• 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.

Connection level configuration

Once you have defined a connection you need to include the Data Connection step to the scenario. With this element you can make calls to your endpoints. 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.

The connection level information already provided should be prepopulated at the step level. In the visual editor you can define more 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.
• JSON: Sets body to JSON representation of value and adds Content-type: application/json header. Additionally, parses the response body as JSON.
• Path: The path is appended to the base URL. If you're 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.
• Headers: Add header parameters if necessary. 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 object 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.

Step level configuration

It is also possible to define the full connection details in the scenario itself. If you select the custom data connection all the fields 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 Authentication providers

Skill Element

Healthcare agent service enables you to extend your bot using Bot Framework Skills. Bot Framework Skills are reusable conversational skill building-blocks covering conversational use-cases enabling you to add extensive functionality to a Bot within minutes.

You can invoke a skill from within healthcare agent service using the Invoke Skill element.

Global Element

Using the Global variables element, you can set and get variables to use throughout your scenarios. Variables set in this way (unlike variables using the $, @, & notation) maintain their context and are available in all scenarios and for all users.

The global variable context value can be a predefined object (for example, scenario.myvar) or a JSON notation object (as in the screenshot above). It can also be a simple type of object such as a string or an integer. After setting the context, you can retrieve it with a local variable, as shown below:

Once attached to a local variable, you can use it immediately as a JavaScript object.

Assign Element

Instead of writing JavaScript code for assigning variables, you can use the Assign step, which allows the same functionality without any code.

You choose the scope of the variable, which can be: scenario, conversation or user scope, assign a variable name in the selected scope, the operation for perform and the value expression that will be evaluated in runtime Operations can be one of:

• Set: set value to variable
• incrementBy: Increments value by given expression
• multiplyBy: Multiplies value by given expression
• push: In case the value is an array, pushes new value onto this array

Action Element

Actions are snippets of JavaScript (ES5) code running in the context of the conversation session as part of a conversation dialog step.  Actions offer enormous power to the scenario composer. Basically, it allows you to take control over the Bot Framework's APIs to be able to modify and extend your bot's functionality. You can add an Action object anywhere on the designer canvas.

IMPORTANT: when defining functions in an action step, you cannot reuse that function in another action step or element in the scenario editor. If you want to create a global action, you need to use the Global Action

Actions runtime context 

Code written in an action runs in a special runtime sandbox called a NodeJS VM. When this context is created, it is empty of any objects -- a clean slate. We need to pass to this VM all the objects the author of the action might need to complete their task.  

The author wants to pass their most used objects to the action, in addition to the require object -- the one that allows you to import other node objects as long as they exist in our package.json.

Below is a list of objects we pass to the action sandbox with links to more information:

Object	Description
Session	Bot framework's current running session.
Require	Allows you to import node modules. This is a special version of require you can use to import only packages that are enabled
Builder	Allows you to build bot messages, and attachments and cards, and send them to the client.
Moment	Allows you to manipulate the date and time library.
Config	Configuration object allows access to the values of tenants’ configuration.
Underscore	Follow the link to view a useful JavaScript library.

Important

Code in Action Steps does not support asynchronous Javascript Function calls. Please use the Data Connnection object in case you want to make an API request.

Enabled JS Packages

Below is a list of useful eanbled Node JS modules you can import with require:

Package	Description
querystring	Query string parsing
moment	Parse, validate, manipulate, and display date/time in JavaScript.
jsonwebtoken	JSON Web Token implementation (symmetric and asymmetric)
underscore	Provides a whole mess of useful functional programming helpers without extending any built-in objects
xml2js	Simple XML to JavaScript object converter

Extending the session function

In addition to all the built-in functionality of the session function, the healthcare agent service has added custom programmatic functionality for you, the author.

Function	Description
session.trace(message: string, level:number)	Output trace string to the debug window level: 0-3
session.saveFeedback(message: string)	Write feedback string for this user

Writing actions best practices 

The following is a brief list of best practices to keep in mind when authoring actions:

• You can always press Ctrl + Space to get a list of variables and functions you can use in actions.
• Be careful not to write infinite loops or overly heavy code in an action. Actions can't run for more than two seconds. After two seconds, the action will fail with a timeout error.
• You can access the arguments passed to the current scenario by using the scenario variable.

Writing in-line expressions 

Everything that is available to the action author is also available in in-line expressions in some steps. These expressions should be simple -- for example, concatenating strings. If you want to write more complex code, use actions before you get to the step that needs the result from the expression. The in-line expression won't be evaluated if there's only a literal string. The string "as-is" will be returned.

Example

An example of an asynchronous action for saving feedback:

session.saveFeedback("This was a very good experience").then(function() {
    next();
}).catch(function(err) {
    session.trace("Error writing feedback " + err.message, 3 /*crtitical error*/);
});

Wait Element

If you want to delay the conversation, you can achieve this by the Wait element. Here you can configure the number of milliseconds to wait

Language Understanding Element

You can also connect to your Language Understanding Element in the scenario. This can also be configured in the Language Model Configuration section

Generative Answer on Customer Source

Important

This feature is currently in Public Preview

With Generative Answer on Customer Sources step, customers can bring their own sources through the healthcare agent service and protected through our Health Safeguards. Customers will be able to bring their own Azure AI Search endpoint or Bing Custom Search service. The healthcare agent service will use these sources in cominbation with the customer Azure OpenAI endpoint and protected with our Health Safeguards. The Customer Source Data Connection will be populated with all Azure AI Search or Bing Custom Search configured data connections, in combination with the Customer Azure OpenAI Endpoint. You can configure the Customer data sources via the data connections page

Healthcare Intelligence

The Healthcare Intelligence is a core step that contains different healthcare intelligent features. The healthcare agent service provides the different built-in features, where some of them use Generative AI. For every Healthcare Intelligence Generative AI feature, the platform is mananaging the reliable sources and the Azure OpenAI endpoint. Every answer will be protected through our Health Safeguards.

The Healthcare Intelligence features include the following items:

• Generative Answers on Built-in Sources: When selecting this option, the customer can decide to let the healthcare agent service use Generative AI and answer with one of the built-in sources such as US National Library of Medicine, The Centers for Disease Control and Prevention or The U.S. Food and Drug Administration.

• Generative Credible Fallback: Generative Credible Fallback feature is using a set of preselected built-in sources to respond with a generative answer to the user query. This allows the user to receive an answer based on any of the sources which we have curated as credible medical information that is suitable for answering user queries. Currently the sources are a combination of US National Library of Medicine, The Centers for Disease Control and Prevention and The U.S. Food and Drug Administration.

• Medical Information - Condition Symptoms, Causes, Complications, Resources: Customers can use this option to leverage the built-in medical information regarding condition symptoms, causes, complications and resources. This option is not enhanced with Generative AI

• Medical Information - Drugs, Side Effects : Customers can use this option to leverage the built-in medical information regarding drugs, side effects. This option is not enhanced with Generative AI

• Triage & Symptom Checking: Customers can use this option to leverage the built-in Triage & Symptom checking from Infermedica and Capita. This option is not enhanced with Generative AI

Next steps

Healthcare agent service instance variables