Advanced Functionality
The Health bot 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 connections
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: 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 typially 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.
Connection details
- Name: Internal identifying name for the data connection. For internal user usage.
- Description: Internal description for the connection.
- FHIR Support: Check this option if your data connection supports the FHIR protocol you can also select this option. Learn more about FHIR data connections
- Base URL: The base URL should include the
HTTPSprotocol as well as 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 will look like:https://api.mydataconnection.com/v1/ - Authentication provider: In some cases data connections are used to retrieve customer data. This will prompt end users to login via the chat thread when interacting with your bot. Learn more about end user authentication
- Headers: If required, one may add header data to be added in the HTTP call.
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.
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
FHIR data connections
Health Bot 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 will 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 is a list of FHIR servers publicly available for testing purposes.
In this examlpe, no authentication or static parameters are required, for the FHIR server we used the PyroHealth test endpoint: https://stu3.test.pyrohealth.net/fhir
Once you provide the base URL, the resource endpoints are defined automatically. To see the resources supported by your endpoint click on “Fetch Resources” at the bottom of the connection.
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 will see the resources and actions availablt 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.
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.
Global variables
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
persistent and available in all scenarios and for all users.
The global variable context value can be a predefined object (e.g., ${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 Variable
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 oprtation for perform and the value expression that will be evaluted 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
Invoke Skill
Health Bot enables you to extend your bot using Bot Framework Skills. Bot Framework Skills are re-usable 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 Health Bot using the Invoke Skill element.
Writing Action Code
Actions are snippets of JavaScript (ES5) code running in the context of the conversation session as part of a conversation dialog step. Actions offers 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 by dragging the Action icon onto the canvas. An Action object has one entry point and one exit node.
All Azure Health Bot actions are synchronous.
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 will want 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 white listed |
| Builder | Allows you to build bot messages, as well as 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.
White Listed Packages
Below is a list of useful Node JS modules you can import with require:
| Package | Description |
|---|---|
crypto |
Cryptographical functions |
path |
Path utilities |
string-decoder |
String utilities |
querystring |
Query string parsing |
url |
Url parsing |
util |
NodeJS Utilities |
jsonwebtoken |
JSON Web Token implementation (symmetric and asymmetric) |
node-sha1 |
Exports a SHA1 function that uses node's crypto module under the hood |
object-path |
Access deep object properties using a path |
soap |
A minimal node SOAP client |
strformat |
String formatting for Node.js and AngularJS |
ttl |
Simple in-memory cache for JavaScript |
underscore |
JavaScript's functional programming helper library |
xml2js |
Simple XML to JavaScript object converter |
Extending the session function
In addition to all the built-in functionality of the session function, the Health Bot 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 ${scenarioArgs} 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 very 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 will not be evaluated if there is only a literal string. The string "as-is" will be returned.