Custom Skill with Knowledge Base

Log in to your subscription in the Azure Portal and select Cognitive Services on the home page.

In the menu on the left, select All Cognitive Services, click Add, and select QnA Maker.  

— OR —

Select Create a resource on the Home page and enter QnA Maker in the search field.

Click Create to create a resource for QnA Maker.  

Populate the fields on the Create QnA Maker page and click Review + create.  

On successful creation of the QnA Maker resource, the following Azure services are made available:

• App service
• QnA Maker (Cognitive service)
• Search service

You can locate these services under the Resource group provided on the Create page above.  

Select the QnA Maker service type, select Keys and Endpoint under Resource Management in the left menu, and click Show Keys.  

Open Bot Framework Composer and click Create new.

Select the Core Bot with QnA Maker template and click Next.  

The template is the starting point for your bot dialog; once created, you can customize and extend the dialog as needed. For more information, see https://docs.microsoft.com/en-us/composer/concept-templates.

Assign a Name to the project.

Note: The project name is the label for the conversation flow and will be displayed as a, activity (clickable option) in Anthology Digital Assistant. Choose a name that is meaningful to a bot user.

Use Runtime type Azure Web App (default) and click Create.

It takes a few minutes for Composer to download the template, create the project, build the runtime, and merge packages.

When prompted, specify a Knowledge base name and click Next.

The "Select a source for your knowledge base's content" modal provides options to create a new knowledge base or import an existing knowledge base from the QnA Maker portal. For a new knowledge base, you can specify the Source URL for content that is hosted online such as an FAQ or document link (.csv, .xls or .doc format). If you do not have online source content available, select Skip & Create blank knowledge base.  

The next screen prompts you to set up QnA Maker.  

Click the Set up QnA Maker link shown above (or click the hamburger icon to expand the navigation menu on the left and select Configure).

In the Set up QnA Maker modal, select Use existing resources since you've already created the QnA Maker App Service and Cognitive Service in your subscription and click Next.  

If you did not create the QnA Maker App Service and Cognitive Service, select "Create and configure new Azure resources". Choose "Generate instructions for Azure administrator" if you need an administrator to create Azure resources for you.

Sign in to your Azure subscription.  

Select your Azure directory (if applicable), Azure subscription, and QnA Maker resource name and click Next.  

The QnA Maker Key and your selected Region are displayed. Click Done.  

On the configuration page, the QnA Maker Subscription key field is populated with the value displayed in the previous step. The Subscription key is automatically added to the appsettings.json file for the custom skill bot.

Select Knowledge base in the navigation menu at the left.

Click the Add QnA Pair link and enter a question and answer.

Click the Add alternate phrasing link in a Question field to enter additional utterances that might be applicable for an answer. To remove a question and answer pair, click the delete icon on the right.  

Click the ellipsis next to the project name and select Add new trigger.  

• In the "What is the type of this trigger?" field, select Activities.  

• In the "Which activity type?" field, select Event received (Event activity) and click Submit. This trigger is added to handle and manage the activity that the skill bot is going to consume. 

  

The "Create a trigger" modal is closed and the "Event received" activity is added to the project.

Click the + icon on the canvas to add an activity to the flow.  

• Select Send a response in the Add activity drop-down.  

  

• In the properties pane for the Send a response activity, specify the response Text that will be displayed when the custom skill selected in the Digital Assistant.  

  

If your custom skill bot supports multiple activities, you need to route each activity to a separate dialog flow. You can do this using a branch component.

• Click the + icon on the canvas, select Create a condition > Branch: If/Else.

• In the Properties pane, click the drop-down in the Condition field and select Write an expression.  

  

• In the Condition field, specify or select the following expression: =turn.activity.name  

  

• Append the name of the activity as defined in the manifest to the expression in the Condition field.

  Example:

  If your manifest includes an activity named "studentInformation", specify =="studentInformation" as the value for the turn.activity.name variable.

  

• Click the + icon in the "true" branch, and select Dialog Management > Begin a new dialog, and assign a name to the dialog.

• Click the + icon in the "false" branch, and insert a Branch: If/Else flow for another activity as described above.

  In our example, the manifest includes a second activity named "campusInformation". So the value of the turn.activity.name variable is =="campusInformation". Another "Begin new dialog" section follows.  

  

• Continue building the new dialogs for each branch.

Go to respective dialog to create a conversation flow. Click on the + icon.

• Select Ask a question > Multi-choice in the Add activity drop-down. Placeholders for the "Prompt with multi-choice" and "User input (Choice)" activities are added to the canvas.

• Select Prompt with multi-choice in the canvas.

• In the properties pane on the Bot response tab, specify the prompt Text, e.g., "Please select ...".  

  

• Select User input (Choice) in the canvas.

• In the properties pane on the User input tab, scroll down to Array of choices.

• Click Add new and specify the label for the first choice. Repeat this step for each choice. The bot will display the choices on clickable cards.  

  

• On the User input tab, scroll up to Property and specify user.<variable>. Name the variable as appropriate for your multi-choice option. The user’s choice will be stored in user state variable. The variable will be re-used during the conversation flow.    

  

• Scroll down to List style and select heroCard. This list style enables users to click on a card that displays a question from the knowledge base.

Click the + icon below the previous activity.

• Select Send a response.

• In the properties pane, specify some Text to echo the selected choice using the variable, e.g., You have selected $(user.<variable>).  

Click the + icon below the previous activity.

• Select Create a condition > Branch: Switch (multiple options).  

  

• Select the Branch activity on the canvas.

• In the properties pane in the Condition field, specify user.<variable>.  

  

• In the properties pane for the Branch activity, specify the values for the Cases.  

  

Click the + icon below the first case.

• Select the Send a response activity.

• Specify the response Text for the case, e.g., "The $(user.<variable>) is...."    

Repeat this step for all cases.

If you categorized your knowledge base questions and there are multiple questions in each category, create Multi-choice prompts in each category.

Each Multi-choice prompt will be followed by User input with a variable that stores the category selection.

In the Array of choices fields, copy and paste the questions and alternate phrasing from the knowledge base.

Click the + icon below the User input (Choice) (i.e., the questions created in the previous step) and switch to the QnA Intent recognized trigger flow. You will need to add every single activity from the QnA Intent recognized flow to the main path of the Event received flow.  

In the QnA Intent recognized flow, select Branch: If/else activity and copy the Condition value to the clipboard.  

In the Event received flow, add a Branch: If/else activity.

In the Condition field, select Write an expression and paste the value from the clipboard into the field. Delete the = sign at the beginning of the field.  

As illustrated in the previous two steps, one by one, re-create the activities and code from the QnA Intent recognized trigger in the Event received trigger flow.

As the last step, click the + icon below the last activity and select Dialog management > End this dialog.  

(Optional) After you have transferred all the activities and code from QnA Intent recognized to Event received, you can remove the QnA Intent recognized trigger. Click the ellipsis next to QnA Intent recognized and select Remove this trigger.  

In the left menu of Bot Framework Composer, select Publish.

If you have previously created a publishing profile and want to republish your project after some edits, select your project on the Publish tab and select your Publish target.  

If you are publishing the first time, select the Publishing profile tab and click the Add new link. Continue with the steps below.  

Specify a Name for your profile. In the Publishing target field, select Publish bot to Azure, and click Next.  

Select Create new resources and click Next.  

You will be prompted to sign into your Azure account.

On the Configure resources modal, specify your subscription, resource group, operating system, and resource details. Click Next to continue.  

On the Add resources modal, the Required resources are automatically selected. The QnA Maker resources will be created. 

Select from the Optional resources as applicable and click Next.   

Select Next and review the list of resources to be created. To proceed, click Create. The resources will be provisioned and deployed in Azure. This may take a few minutes.  

The following services are created for QnA Maker:

• App Service
• Cognitive Service
• Search Service

The AppServiceRegistration is created implicitly.

You can locate the QnA Maker services under Resource groups.  

You need to get the MicrosoftAppIds/Keys for the resources you intend to use.

For QnA Maker, select the Cognitive Service, select Keys and Endpoint under Resource Management in the left menu, and click Show Keys.  

Copy and save the MicrosoftAppId and/or Key so that you have it available later to paste it into the AppSettings.json file.

The MicrosoftAppId also needs to be specified in the Customer Administration Portal > Skills > Custom Skills.

Log in to your Azure subscription, select the App Service that was created for the skill bot, and open the App Service Editor under Development Tools.

Create a new manifest file in the wwwroot folder of your subscription. Refer to the instructions provided at https://docs.microsoft.com/en-us/azure/bot-service/skills-write-manifest?view=azure-bot-service-4.0&tabs=v2-2.

— OR —

Retrieve a manifest.json sample file from https://github.com/anthology-inc/renee-integration-samples/tree/main/skillbot/src/botFrameworkSdkV4_C%23/wwwroot/manifest, copy it to wwwroot in your subscription, and modify its content.

In your manifest.json file, locate the endpoints section and provide the msAppId and endpointUrl values.  

• Populate the msAppId field with the Microsoft AppId of your custom skill bot. At least one endpoint must be defined. Each endpoint must be unique.

• Populate the endpointUrl field with the URL of your skill bot followed by /api/messages. Anthology Digital Assistant uses the endpoint Url to communicate with the skill bot.

  To get the endpoint Url, go to the App Service details page of your custom skill bot in Azure and copy the URL value. 

  

  Provide the endpoint URL value to Anthology. Anthology staff will configure the URL in the Customer App Portal (see Custom Skill with Knowledge Base

In the activities section of the manifest, specify appropriate name and type values for the activities in your custom skill bot. All other properties are optional and depend on the purpose of the activity. 

Save your manifest.json file(s).

In your Azure subscription, navigate to the appsettings.json file in the wwwroot folder and edit it using the App Service Editor.

In the allowedCallers field, specify the MicrosoftAppId of Anthology Digital Assistant. This is required to ensure that only the Digital Assistant (and no other bot) can invoke your custom skill bot. The MicrosoftAppId of Anthology Digital Assistant is displayed in the About window of the Customer Admin Portal.  

The appsettings.json is automatically populated with the MicrosoftAppId for the custom skill bot. Copy and paste this key into the manifest.json.  

Log in to the Customer Administration Portal and select the Skills tile (see Configure Skills).

In the Settings pane, select Custom Skills and click the Add Skill button.

In the Add Skill dialog, specify the following values:

• Skill Name

• Microsoft AppId

• Manifest Url

If your custom skill is available in multiple languages, click the Add Locale button, select the Locale value and specify the Locale Name.

Click the Save button.

Go to your Azure portal.

Test the published bot by selecting Test in Web Chat.

Log in to your subscription in the Azure Portal and select Cognitive Services on the home page.

In the menu on the left, select All Cognitive Services, click Add, and select QnA Maker.  

— OR —

Select Create a resource on the Home page and enter QnA Maker in the search field.

Click Create to create a resource for QnA Maker.  

Populate the fields on the Create QnA Maker page and click Review + create.  

On successful creation of the QnA Maker resource, the following Azure services are made available:

• App service
• QnA Maker (Cognitive service)
• Search service

You can locate these services under the Resource group provided on the Create page above.  

Select the QnA Maker service type, select Keys and Endpoint under Resource Management in the left menu, and click Show Keys.  

Open Bot Framework Composer and click Create new.

Select the Core Bot with QnA Maker template and click Next.  

The template is the starting point for your bot dialog; once created, you can customize and extend the dialog as needed. For more information, see https://docs.microsoft.com/en-us/composer/concept-templates.

Assign a Name to the project.

Note: The project name is the label for the conversation flow and will be displayed as a, activity (clickable option) in Anthology Digital Assistant. Choose a name that is meaningful to a bot user.

Use Runtime type Azure Web App (default) and click Create.

It takes a few minutes for Composer to download the template, create the project, build the runtime, and merge packages.

When prompted, specify a Knowledge base name and click Next.

The "Select a source for your knowledge base's content" modal provides options to create a new knowledge base or import an existing knowledge base from the QnA Maker portal. For a new knowledge base, you can specify the Source URL for content that is hosted online such as an FAQ or document link (.csv, .xls or .doc format). If you do not have online source content available, select Skip & Create blank knowledge base.  

The next screen prompts you to set up QnA Maker.  

Click the Set up QnA Maker link shown above (or click the hamburger icon to expand the navigation menu on the left and select Configure).

In the Set up QnA Maker modal, select Use existing resources since you've already created the QnA Maker App Service and Cognitive Service in your subscription and click Next.  

If you did not create the QnA Maker App Service and Cognitive Service, select "Create and configure new Azure resources". Choose "Generate instructions for Azure administrator" if you need an administrator to create Azure resources for you.

Sign in to your Azure subscription.  

Select your Azure directory (if applicable), Azure subscription, and QnA Maker resource name and click Next.  

The QnA Maker Key and your selected Region are displayed. Click Done.  

On the configuration page, the QnA Maker Subscription key field is populated with the value displayed in the previous step. The Subscription key is automatically added to the appsettings.json file for the custom skill bot.

Select Knowledge base in the navigation menu at the left.

Click the Add QnA Pair link and enter a question and answer.

Click the Add alternate phrasing link in a Question field to enter additional utterances that might be applicable for an answer. To remove a question and answer pair, click the delete icon on the right.  

Click the ellipsis next to the project name and select Add new trigger.  

• In the "What is the type of this trigger?" field, select Activities.  

• In the "Which activity type?" field, select Event received (Event activity) and click Submit. This trigger is added to handle and manage the activity that the skill bot is going to consume. 

  

The "Create a trigger" modal is closed and the "Event received" activity is added to the project.

If your custom skill bot supports multiple activities, you need to route each activity to a separate dialog flow. You can do this using a branch component.

• Click the + icon on the canvas, select Create a condition > Branch: If/Else.

• In the Properties pane, click the drop-down in the Condition field and select Write an expression.  

  

• In the Condition field, specify or select the following expression: =turn.activity.name  

  

• Append the name of the activity as defined in the manifest to the expression in the Condition field.

  Example:

  If your manifest includes an activity named "studentInformation", specify =="studentInformation" as the value for the turn.activity.name variable.

  

• Click the + icon in the "true" branch, and select Dialog Management > Begin a new dialog, and assign a name to the dialog.

• Click the + icon in the "false" branch, and insert a Branch: If/Else flow for another activity as described above.

  In our example, the manifest includes a second activity named "campusInformation". So the value of the turn.activity.name variable is =="campusInformation". Another "Begin new dialog" section follows.  

  

• Continue building the new dialogs for each branch.

Click the + icon on the canvas to add an activity to the flow.  

• Select Send a response in the Add activity drop-down.  

  

• In the properties pane for the Send a response activity, specify the response Text that will be displayed when the custom skill selected in the Digital Assistant.  

  

Go to respective dialog to create a conversation flow. Click on the + icon.

• Select Ask a question > Multi-choice in the Add activity drop-down. Placeholders for the "Prompt with multi-choice" and "User input (Choice)" activities are added to the canvas.

• Select Prompt with multi-choice in the canvas.

• In the properties pane on the Bot response tab, specify the prompt Text, e.g., "Please select ...".  

  

• Select User input (Choice) in the canvas.

• In the properties pane on the User input tab, scroll down to Array of choices.

• Click Add new and specify the label for the first choice. Repeat this step for each choice. The bot will display the choices on clickable cards.  

  

• On the User input tab, scroll up to Property and specify user.<variable>. Name the variable as appropriate for your multi-choice option. The user’s choice will be stored in user state variable. The variable will be re-used during the conversation flow.    

  

• Scroll down to List style and select heroCard. This list style enables users to click on a card that displays a question from the knowledge base.

Click the + icon below the previous activity.

• Select Send a response.

• In the properties pane, specify some Text to echo the selected choice using the variable, e.g., You have selected $(user.<variable>).  

Click the + icon below the previous activity.

• Select Create a condition > Branch: Switch (multiple options).  

  

• Select the Branch activity on the canvas.

• In the properties pane in the Condition field, specify user.<variable>.  

  

• In the properties pane for the Branch activity, specify the values for the Cases.  

  

Click the + icon below the first case.

• Select the Send a response activity.

• Specify the response Text for the case, e.g., "The $(user.<variable>) is...."    

Repeat this step for all cases.

If you categorized your knowledge base questions and there are multiple questions in each category, create Multi-choice prompts in each category.

Each Multi-choice prompt will be followed by User input with a variable that stores the category selection.

In the Array of choices fields, copy and paste the questions and alternate phrasing from the knowledge base.

Click the + icon below the User input (Choice) (i.e., the questions created in the previous step) and switch to the QnA Intent recognized trigger flow. You will need to add every single activity from the QnA Intent recognized flow to the main path of the Event received flow.  

In the QnA Intent recognized flow, select Branch: If/else activity and copy the Condition value to the clipboard.  

In the Event received flow, add a Branch: If/else activity.

In the Condition field, select Write an expression and paste the value from the clipboard into the field. Delete the = sign at the beginning of the field.  

As illustrated in the previous two steps, one by one, re-create the activities and code from the QnA Intent recognized trigger in the Event received trigger flow.

As the last step, click the + icon below the last activity and select Dialog management > End this dialog.  

(Optional) After you have transferred all the activities and code from QnA Intent recognized to Event received, you can remove the QnA Intent recognized trigger. Click the ellipsis next to QnA Intent recognized and select Remove this trigger.  

In the left menu of Bot Framework Composer, select Publish.

If you have previously created a publishing profile and want to republish your project after some edits, select your project on the Publish tab and select your Publish target.  

If you are publishing the first time, select the Publishing profile tab and click the Add new link. Continue with the steps below.  

Specify a Name for your profile. In the Publishing target field, select Publish bot to Azure, and click Next.  

Select Create new resources and click Next.  

You will be prompted to sign into your Azure account.

On the Configure resources modal, specify your subscription, resource group, operating system, and resource details. Click Next to continue.  

On the Add resources modal, the Required resources are automatically selected. The QnA Maker resources will be created. 

Select from the Optional resources as applicable and click Next.   

Select Next and review the list of resources to be created. To proceed, click Create. The resources will be provisioned and deployed in Azure. This may take a few minutes.  

The following services are created for QnA Maker:

• App Service
• Cognitive Service
• Search Service

The AppServiceRegistration is created implicitly.

You can locate the QnA Maker services under Resource groups.  

You need to get the MicrosoftAppIds/Keys for the resources you intend to use.

For QnA Maker, select the Cognitive Service, select Keys and Endpoint under Resource Management in the left menu, and click Show Keys.  

Copy and save the MicrosoftAppId and/or Key so that you have it available later to paste it into the AppSettings.json file.

The MicrosoftAppId also needs to be specified in the Customer Administration Portal > Skills > Custom Skills.

Log in to your Azure subscription, select the App Service that was created for the skill bot, and open the App Service Editor under Development Tools.

Create a new manifest file in the wwwroot folder of your subscription. Refer to the instructions provided at https://docs.microsoft.com/en-us/azure/bot-service/skills-write-manifest?view=azure-bot-service-4.0&tabs=v2-2.

— OR —

Retrieve a manifest.json sample file from https://github.com/anthology-inc/renee-integration-samples/tree/main/skillbot/src/botFrameworkSdkV4_C%23/wwwroot/manifest, copy it to wwwroot in your subscription, and modify its content.

In your manifest.json file, locate the endpoints section and provide the msAppId and endpointUrl values.  

• Populate the msAppId field with the Microsoft AppId of your custom skill bot. At least one endpoint must be defined. Each endpoint must be unique.

• Populate the endpointUrl field with the URL of your skill bot followed by /api/messages. Anthology Digital Assistant uses the endpoint Url to communicate with the skill bot.

  To get the endpoint Url, go to the App Service details page of your custom skill bot in Azure and copy the URL value. 

  

  Provide the endpoint URL value to Anthology. Anthology staff will configure the URL in the Customer App Portal (see Custom Skill with Knowledge Base

In the activities section of the manifest, specify appropriate name and type values for the activities in your custom skill bot. All other properties are optional and depend on the purpose of the activity. 

Save your manifest.json file(s).

In your Azure subscription, navigate to the appsettings.json file in the wwwroot folder and edit it using the App Service Editor.

In the allowedCallers field, specify the MicrosoftAppId of Anthology Digital Assistant. This is required to ensure that only the Digital Assistant (and no other bot) can invoke your custom skill bot. The MicrosoftAppId of Anthology Digital Assistant is displayed in the About window of the Customer Admin Portal.  

The appsettings.json is automatically populated with the MicrosoftAppId for the custom skill bot. Copy and paste this key into the manifest.json.  

Log in to the Customer Administration Portal and select the Skills tile (see Configure Skills).

In the Settings pane, select Custom Skills and click the Add Skill button.

In the Add Skill dialog, specify the following values:

• Skill Name

• Microsoft AppId

• Manifest Url

If your custom skill is available in multiple languages, click the Add Locale button, select the Locale value and specify the Locale Name.

Click the Save button.

Go to your Azure portal.

Test the published bot by selecting Test in Web Chat.