Tip

Communicate with External Systems

You can use Bot Framework Composer to call the API of another system, retrieve data through an HTTP request, and then show the data in the bot responses. This approach eliminates the need to create and maintain hard-coded values for the bot responses.

The example described below can be downloaded from GitHub at https://github.com/anthology-inc/renee-integration-samples/tree/main/skillbot/src/botFrameworkComposer/3.calling%20external%20api

Retrieve Data from Anthology Student

Our example is an extension of the conversation flow described in the Custom Skill topic, where the bot visitor selects a campus from a predefined (hard-coded) list. In this example we are using the Anthology Student API to populate the list of campuses. Based on the bot visitor's campus selection, we are then retrieving the names of high schools for the selected campus from the Anthology Student database.

We are also showing how to display bot responses in the Live Assist variant of Digital Assistant as text with markdown and in the web chat variant as UI cards.

• The bot displays a greeting and prompts the visitor to select a campus. The campuses are displayed on a hero card. (We used markdown syntax (**) to apply bold text to "Campus Information System".)

• After the visitor selects a campus, the bot displays the campus code and location (city, state) on a thumbnail card and asks whether the visitor wants to see the list of schools for the campus.

• After the visitor answers "Yes", the bot displays the names of high schools associated with the selected campus. The list is formatted as a numbered list using markdown syntax.

   

Limitations:

• Currently, the Digital Assistant does not support authentication of students registered in the student information system, hence it will not be able to pass the token to the skill bot for retrieving student related data. Therefore, we cannot retrieve transactional data for a specific student. The option is to design a UI flow in the skill bot in the form of questions to identify the correct student based on the user input data. In this example, we are retrieving is reference data that is configured in the Anthology Student system and not dependent on authenticating a student.

• The example described in this topic is not a complete custom skill bot. It just demonstrates how to use specific Bot Framework Composer activities and properties to retrieve data from an external system. You can use pieces of this example to enhance a skill bot that requires similar interactions.

Send an HTTP Request to Retrieve Campuses

The HTTP request activity is the main tool to retrieve data from an external system.

To add the HTTP request activity in the Bot Framework Composer canvas, click the + icon and select Access external resources > Send an HTTP request.  

HTTP Request - Details

Field	Value
HTTP method	GET
Url	https://<domain>:<port>/ds/campusnexus/Campuses?$top=5 This is an ODATA query where: /ds/campusnexus/Campuses? retrieves the Campuses entity from the CampusNexus data model. $top=5 requests the top 5 items in the collection of Campuses to be included in the result. The domain and port values represent the system where bot visitors are registered as a students.
Headers:
Key	Content-Type
Value	application/json
Key	apiKey The apiKey secures APIs in the Anthology Student system. An API key is a secret token that is submitted with a web service request to identify the origin of the request. The API key is unique for each client.
Value	<encrypted string of 64 characters>
Result property	dialog.api_response The results of the query are stored in a property we named "dialog.api_response". The name must consist of two parts, the scope of the property and the name of the property. See Notes.
Content type	application/json
Response type	json

For more information, see Make an HTTP request from Bot Framework Composer at https://docs.microsoft.com/en-us/composer/how-to-send-http-request?tabs=v2x

Send a Response

The results of a Send HTTP request activity are displayed to the bot visitor using a Send response activity. The formatting of data in a Send response activity depends on whether you are using web chat or Live Assist.

• Live Assist bots support only plain text displays. See Send a Response in Live Assist.

• Web chat bots can use either text or cards. We are generating the hero cards dynamically using a Bot Responses function. See Dynamically Create Hero Cards.

Set a Property to Hold the URL for an HTTP Request

We are using a Set a Property activity to define a Bot Framework Composer property that holds the OData query for a Campus Name/ID.

To set the property, in the Bot Framework Composer canvas, click the + icon and select Manage properties > Set a property.  

Set Property - Details

Field	Value
Property	Specify a name for the property, i.e., dialog.url. The name must consist of two parts, the scope of the property and the name of the property. See Notes.
Value	https://<domain>:<port>/ds/campusnexus/Campuses?$filter=Name eq '${turn.activity.text}' This is an ODATA query where: /ds/campusnexus/Campuses? retrieves the Campuses entity from the CampusNexus data model. $filter=Name eq '${turn.activity.text}' returns the Name of a campus using the visitor's campus selection as a filter. The turn.activity.text object is a standard Bot Framework Composer object. It holds the user message within the current turn. In our example, it will be the campus selection. See Notes. The domain and port values represent the URL of the student information system Anthology Student where bot visitors are registered as a students.

Send an HTTP Request Using a Set Property

Another HTTP request retrieves data based on the bot visitor's campus selection.  

HTTP Request - Details

Field	Value
HTTP method	GET
Url	${dialog.url} OData query using the dialog.url property defined in the preceding Set Properties activity as https://<domain>:<port>/ds/campusnexus/Campuses?$filter=Name eq '${turn.activity.text}'
Body (string)	N/A
Headers:
Key	Content-Type
Value	application/json
Key	apiKey The apiKey secures APIs in the Anthology Student system. An API key is a secret token that is submitted with a web service request to identify the origin of the request. The API key is unique for each client.
Value	<encrypted string of 64 characters>
Result property	turn.results The results of the query are stored in a property we named "turn.results". The turn.results object includes the following information: Status code — HTTP status code. Our example only handles the happy path. However, you could filter based on status code and design the flow accordingly. For example if the code is 200, proceed with the flow. If the code is not 200, handle exceptions as needed. Content — The content of the query. In our example, the content is an array of values. We will use content turn.results.content.value in another activity. See Send a Response on a Thumbnail Card. Reason Header
Content type	application/json
Response type	json

Send a Response on a Thumbnail Card

Based on the bot visitor's campus selection (turn.results), the bot displays location details about the selected campus on a thumbnail card.  

The thumbnail card is designed using a Send response activity with the following code.

Note: The image property is optional.

[ThumbnailCard
    title = Campus Code is ${turn.results.content.value[0].Code}
    text = The Campus *"${turn.activity.text}"* City is **${turn.results.content.value[0].City}** & State is  **${turn.results.content.value[0].State}**
    image = https://<domain>:<port>/src/dataservices/other/images/Anthology_Student.svg
]

Set a Property

The Set Properties activity stores the turn.activity.text object in the user.campus property.

Prompt and User Input

The Prompt for Confirmation activity displays the following to the bot visitor:

Do you want to view the list of schools for ${turn.activity.text}?

Where ${turn.activity.text} is the campus selected by the bot visitor.  

Set a Property

If the bot visitor confirms the question Do you want to view the list of schools for ${turn.activity.text}?, the flow continues to another Set Properties activity.

The Set Properties activity stores the following OData query in the dialog.url property. See Notes.

https://<domain>:<port>/ds/campusnexus/HighSchools?$select=Name&$filter=CampusGroup/CampusList/any(p: p/Campus/Name eq '${user.campus}')

The query retrieves the HighSchools entity and filters it based on the campus selected by the user.  

Send a Response in Live Assist

In the Live Assist variant of Digital Assistant hero cards are not supported. To display a list of values retrieved from an external system, the bot response is formatted using an expression. 

${join(foreach(turn.results.content.value, x, `1. ` + x.Name),`
` )}

You can construct the expression by inserting pre-built functions.

1. In the Properties pane, select the Text field, click the fx drop-down, and choose Collection > join.  

   

   The pre-built join expression appears in the Text field as follows:

   ${join(collection, delimiter)}

2. Select the word collection in the pre-built join expression, click the fx drop-down, and choose Collection > foreach. This will insert a foreach statement inside the join expression.

   ${join(foreach(collection, iteratorName, function), delimiter)}

3. In the pre-built foreach expression:

   • Select the word collection and replace it with turn.results.content.value. This the value of the visitor's campus selection.

   • Select the word iteratorName and replace it with an index for iterating through the list of returned value. We're using a variable called x.

   • Select the word function and replace it with a variable called x.Name. This is the high school name retrieved from Anthology Student.

     Where in x.Name, Name is the property that is retrieved from the following OData query:

     https://<domain>:<port>/ds/campusnexus/HighSchools?$select=Name&$filter=CampusGroup/CampusList/any(p: p/Campus/Name eq '${user.campus}')

   • Select the word delimiter and replace it with `1. ` +. This is the markdown syntax for a numbered list.

Dynamically Create Hero Cards

The Bot Responses file in Bot Framework Composer can be used to create functions for the bot's response activities. You can use these functions in any project or conversation flow as needed.

To view the file, select Bot Responses in the menu at the left and then select your project. The Bot Responses page lists the existing responses by name, indicates whether the responses have been used, and enables you to edit, delete, or copy responses. You can access the code view using the Show Code toggle button.  

We created the following functions in the Bot Responses file. In the web chat variant of Digital Assistant, these functions enable us to display data retrieved from external systems on dynamically generated hero cards.

# heroCards(dataList)
- ${herocardTemplate(datalist, datalist, datalist, datalist)}

# herocardTemplate(title, subTitle, text, buttons)
[HeroCard
    title = List of Campuses
    buttons = ${foreach(buttons, x, x.Name)}

• The heroCards function takes a dataList as input. The results retrieved from an external system will be passed to the dataList. The heroCards function calls the herocardTemplate function.

• The herocardTemplate is defined to include a title, subtitle, text, and button. The buttons are built dynamically for each item in the dataList.

To use the hero cards function in responses, define the Attachments property in the Send a response activity. By default, any Send response activity creates an Activity value, however, the Attachments value will not be present. Whenever you want to create a response using a hero card, a thumbnail card, or other UI element for the response, you need to define the Attachments value.  

Click Show Code in the Properties pane to view the code for the Activity property. The code for the Activity and the Text is created by default.

We added the Attachments and AttachmentLayout lines.

• Attachments invokes the heroCards function. The content and value of the retrieved dialog.api_response are passed to the function.

• AttachmentLayout is defined as list.

For more information, see Respond with cards using Bot Framework Composer at https://docs.microsoft.com/en-us/composer/how-to-send-cards?tabs=v2x