The topic "Integration Requirements" is not available in Version 1.0.0

Integration Requirements

To integrate a custom skill bot with the Digital Assistant, when developing skill bot clients need to configure following in their skill bot.

The ManifestURL links to the skill bot's Manifest.json which contains required attributes including endpoints and activities referenced by the Digital Assistant.
The AllowedCallers array in the AppSettings.json lists the skill consumers that can access the skill. Since the Digital Assistant is a skill consumer, the MicrosoftAppId of the Digital Assistant must be specified in the AllowedCallers array. You can find the App Id of the Digital Assistant in the About window of the Customer Administration Portal.

Manifest.json

Custom skills that are integrated with the Digital Assistant require a manifest file. This is a JSON file that defines the actions a skill can take, its input and output parameters, and the skill's endpoints. The manifest contains the information needed to access the skill from the Digital Assistant.

The manifest file is part of the Azure Bot Service.

Manifest

Note: If you have localized your custom skill bot, you need to add manifest.json files for each language.

For ease of reference, use a naming convention that indicates the language and locale, e.g.,

dialogchildbot-manifest-1.0.en-us.json
dialogchildbot-manifest-1.0.en-gb.json
dialogchildbot-manifest-1.0.es-es.json
dialogchildbot-manifest-1.0.fr-fr.json

Make sure the json syntax is valid in your customized manifest.json.

The full schema for v2.2 of the Bot Framework skill manifest is described at https://docs.microsoft.com/en-us/azure/bot-service/skills-write-manifest?view=azure-bot-service-4.0&tabs=v2-2.

The following fields in the manifest.json are of particular importance:

$id — The identifier for the skill manifest. This field is required to route traffic between the skill bot and the Digital Assistant.

Example:
```
  "$id": "ReneeSampleSkillBot"
```

endpoints — The list of endpoints for the skill. At least one endpoint must be defined. Each endpoint must be unique. The Digital Assistant uses the endpointUrl to communicate with the skill. The endpointUrl is where the skill bot is listening to incoming requests.

Example:

  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV4",
      "description": "Default endpoint for the skill.",
      "endpointUrl": "https://reneeskillbot-local.azurewebsites.net/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ],

activities — The set of activities accepted by the custom skill. Each activity must have a type and name value. The activity name will be displayed as a clickable card in the Digital Assistant.

All other properties are optional and depend on the purpose of the activity.

Digital Assistant 1.1 supports only activities of "type": "event".

Example:
```
  "activities": {
    "studentInformation": {
      "description": "Student Information (multi turn).",
      "type": "event",
      "name": "StudentInformation",
      "value": {
        "$ref": "#/definitions/studentInfo"
      },
      "resultValue": {
        "$ref": "#/definitions/studentInfo"
      }
    },
```

How to Get the ManifestUrl

To determine the URL path of the manifest.json file, follow the example below:

Example:

The localized manifest file named “dialogchildbot-manifest-1.0.en-us.json” is placed in the wwwroot physical folder.
To translate the physical path to a URL path, go to the overview section of the App Service in Azure.
Copy the URL property, e.g., “https://customskillbot-sr.azurewebsites.net/”

Append the name of the manifest.json to the copied URL, e.g.,

“https://customskillbot-sr.azurewebsites.net/” + “dialogchildbot-manifest-1.0.en-us.json”

The URL path of the manifest.json file will be:

"https://customskillbot-sr.azurewebsites.net/dialogchildbot-manifest-1.0.en-us.json"

For more information, see refer to Microsoft documentation: How do I find my remote skill manifest URL?

AppSettings.json

The appsettings.json file supports the overall configuration for the skill bot. For example, it can be used to configure logging, any external connection details the skill bot requires, etc.

The following fields in the appsettings.json file are of particular importance:

"MicrosoftAppId" and "MicrosoftAppPassword" — These values are required for skill bot authentication and security. Specify your AppId and your AppPassword.
"allowedCallers" — The allowed callers array can restrict which skill consumers can access the skill. You can add a "*" element, to accept calls from any skill consumer.

For security purposes, it is recommended to specify the MicrosoftAppId of the Digital Assistant under allowedCallers. This ensures that only the Digital Assistant and no other bot can invoke the custom skill bot. You can find the App Id of the Digital Assistant in the About window of the Customer Administration Portal.

If the skill bot is configured to use QnA Maker:

The endpointKey and kbId values are required (see Create a Knowledge Base in QnA Maker).
The subscriptionKey is required. It comes from the Cognitive Service resource group (see Create QnA Maker Resources in Azure).

appsettings.json

Code for End of Conversation

A skill bot created using the Bot Framework SDK must end with the sending of an endOfConversation activity. The endOfConversation activity sends control of the dialog from the skill bot back to the root bot (Digital Assistant).

The endOfConversation activity must be placed after the EndDialogAsync as shown below.

The Code and Text values inform the Digital Assistant about the status of the activity (e.g., why/how the conversation was ended in the skill bot). The Code value is shown below. The Text value can be anything.


private async Task<DialogTurnResult> FinalStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var student = (Student)stepContext.Options;
    if (!(bool)stepContext.Result)
        return await stepContext.ReplaceDialogAsync(InitialDialogId, new Student(), cancellationToken);

    
    var random = new Random();
    var marks = random.Next(20, 100);

    var message = $"The mark of student {student.Id} in {student.AcademicYear} year participating in program {student.Program} is {marks}%";
    await stepContext.Context.SendActivityAsync(message, null, InputHints.IgnoringInput, cancellationToken);

    var endOfConversation = Activity.CreateEndOfConversationActivity();
    endOfConversation.Code = EndOfConversationCodes.CompletedSuccessfully;
    endOfConversation.Text = "Ending the conversation";

    await stepContext.EndDialogAsync(null, cancellationToken);
    await stepContext.Context.SendActivityAsync(endOfConversation, cancellationToken);
    return EndOfTurn;

    public override Task<DialogTurnResult> ContinueDialogAsync(DialogContext outerDc, CancellationToken cancellationToken = default)
    {
        return base.ContinueDialogAsync(outerDc, cancellationToken);
    }

To integrate a custom skill bot with the Digital Assistant, clients need to provide a skill name, a MicrosoftAppId, a ManifestURL, and an AllowedCallers array.

The ManifestURL links to the skill bot's Manifest.json which contains required attributes including endpoints and activities referenced by the Digital Assistant.
The AllowedCallers array in the AppSettings.json lists the skill consumers that can access the skill. Since the Digital Assistant is a skill consumer, the MicrosoftAppId of the Digital Assistant must be specified in the AllowedCallers array.
The MicrosoftAppId is used to register the extension to the Digital Assistant with the Azure Bot Service. You can find the App Id of the Digital Assistant in the About window of the Customer Administration Portal.

Manifest.json

The manifest file is part of the Azure Bot Service.

Manifest

The full schema for v2.2 of the Bot Framework skill manifest is described at https://docs.microsoft.com/en-us/azure/bot-service/skills-write-manifest?view=azure-bot-service-4.0&tabs=v2-2.

The following fields in the manifest.json are of particular importance:

$id — The identifier for the skill manifest. This field is required to route traffic between the skill bot and the Digital Assistant.

Example:
```
  "$id": "ReneeSampleSkillBot"
```

endpoints — The list of endpoints for the skill. At least one endpoint must be defined. Each endpoint must be unique. The Digital Assistant uses the endpointUrl to communicate with the skill.

Example:

  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV4",
      "description": "Default endpoint for the skill.",
      "endpointUrl": "https://reneeskillbot-local.azurewebsites.net/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ],

activities — The set of activities accepted by the custom skill. Each activity must have a type and name value. The activity name will be displayed as a clickable card in the Digital Assistant.

All other properties are optional and depend on the purpose of the activity.

Digital Assistant 1.1 supports only activities of "type": "event".

Example:
```
  "activities": {
    "studentInformation": {
      "description": "Student Information (multi turn).",
      "type": "event",
      "name": "StudentInformation",
      "value": {
        "$ref": "#/definitions/studentInfo"
      },
      "resultValue": {
        "$ref": "#/definitions/studentInfo"
      }
    },
```

For more information, see Microsoft documentation: How do I find my remote skill manifest URL?

AppSettings.json

The appsettings.json file supports the overall configuration for the skill bot. For example, it can be used to configure logging, any external connection details the skill bot requires, etc.

The following fields in the appsettings.json file are of particular importance:

"MicrosoftAppId" and "MicrosoftAppPassword" — These values are required for skill bot authentication and security. Specify your AppId and your AppPassword.
"allowedCallers" — The allowed callers array can restrict which skill consumers can access the skill. You can add a "*" element, to accept calls from any skill consumer.

For security purposes, it is recommended to specify the MicrosoftAppId of the Digital Assistant under allowedCallers. This ensures that only the Digital Assistant and no other bot can invoke the custom skill bot. You can find the App Id of the Digital Assistant in the About window of the Customer Administration Portal.

If the skill bot is configured to use QnA Maker:

The endpointKey and kbId values are required (see Create a Knowledge Base in QnA Maker).
The subscriptionKey is required. It comes from the Cognitive Service resource group (see Create QnA Maker Resources in Azure).

appsettings.json

Code for End of Conversation

The endOfConversation activity must be placed after the EndDialogAsync as shown below.


private async Task<DialogTurnResult> FinalStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var student = (Student)stepContext.Options;
    if (!(bool)stepContext.Result)
        return await stepContext.ReplaceDialogAsync(InitialDialogId, new Student(), cancellationToken);

    
    var random = new Random();
    var marks = random.Next(20, 100);

    var message = $"The mark of student {student.Id} in {student.AcademicYear} year participating in program {student.Program} is {marks}%";
    await stepContext.Context.SendActivityAsync(message, null, InputHints.IgnoringInput, cancellationToken);

    var endOfConversation = Activity.CreateEndOfConversationActivity();
    endOfConversation.Code = EndOfConversationCodes.CompletedSuccessfully;
    endOfConversation.Text = "Ending the conversation";

    await stepContext.EndDialogAsync(null, cancellationToken);
    await stepContext.Context.SendActivityAsync(endOfConversation, cancellationToken);
    return EndOfTurn;

    public override Task<DialogTurnResult> ContinueDialogAsync(DialogContext outerDc, CancellationToken cancellationToken = default)
    {
        return base.ContinueDialogAsync(outerDc, cancellationToken);
    }