Deployment Scripts

A number of PowerShell scripts are provided in the Virtual Assistant Template to help deploy and configure your different resources. Please find details on each script’s purpose, parameters, and outputs below.

Resources

LU - this folder contains localized .lu files representing the basic LUIS models provided in the project.

QnA - this folder contains localized .qna files representing the basic knowledge bases provided in the project.

template.json - this file is the ARM template used to deploy the Azure Resources required by the project.

parameters.template.json - this file can be used to modify the default parameters in template.json for your specific implementation.

Scripts

deploy.ps1

This script orchestrates the deployment of all Azure Resources and Cognitive Models to get the Virtual Assistant running.

Note: QnA Maker requires three Azure resources, a QnA Maker Cognitive Service subscription, an Azure Search resource, and an Azure web app. The Cognitive Service subscription can only be deployed in West US for Azure Commercial deployments, therefore the QnA Maker endpoint will be the same for all regions unless the service is being deployed for Azure Government.

deploy_cognitive_models.ps1

This script deploys all the language models found in Deployment/Resources/LU and the knowledgebases found in Deployment/Resources/QnA. Finally it creates a Dispatch model to dispatch between all cognitive models.

update_cognitive_models.ps1

This script updates your hosted language models and knowledgebases based on local .lu files. Or, it can update your local .lu files based on your current hosted models. Finally, it refreshes your dispatch model with the latest changes.

publish.ps1

This script builds and publishes your local project to your Azure.

Frequently asked questions

What services are deployed by the script?

The Virtual Assistant Template relies on a number of Azure resources to run. The included deployment scripts and ARM template use the following services:

How do I reduce my Azure costs during development?

The default parameters.template.json file is configured to use all free service tiers to reduce the cost of testing. Provide this file in the -parametersFile parameter on the deploy.ps1 script.

There are service limits associated with free tiers (e.g. Azure Search permits only 1 free tier per subscription). Free tiers should only be used for development, not for production implementations.

How do I customize my Azure resource deployment?

Any of the following parameters in the ARM template can be overridden with your preferred values using the parameters.template.json file provided in the Deployment/Resources folder:

Simply update the parameters.template.json file with your preferred values, like so:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appInsightsLocation": {
      "value": "westus2"
    },
    "qnaMakerSearchSku": {
      "value": "basic"
    }
  }
}

Then provide the path to the file as an argument on the deploy.ps1 script:

./Deployment/Scripts/deploy.ps1 -parametersFile ./Deployment/Resources/parameters.template.json

How do I use my existing Azure resources from the same resource group?

If you want to use existing resources from the same resource group, override the parameters for the services you want in the parameters.template.json. Provide this file in the parametersFile parameter on the deploy.ps1 script.

parameters.template.json

{
    "cosmosDbName": {
      "value": "MyCosmosDbName"
    },
}

How do I use my existing Azure resources from a different resource group?

If you want to use an existing resource from a different resource group, follow these steps:

Cosmos DB

1. Provide the following parameter in the parameters.template.json file:

    "useCosmosDb": {
        "value": false
    }
   

2. Update the following properties in appsettings.json with your service configuration from the Azure Portal:

    "cosmosDb": {
        "authkey": "",
        "cosmosDBEndpoint": "",
        "containerId": "skillstate-collection",
        "databaseId": "botstate-db"
    }
   

Storage Account

1. Provide the following parameter in the parameters.template.json file:

    "useStorage": {
        "value": false
    }
   

2. Update the following properties in appsettings.json with your service configuration from the Azure Portal:

    "blobStorage": {
        "connectionString": "",
        "container": "transcripts"
    },
   

Other services

1. Remove the resource from the resources array in template.json.
2. Provide the appropriate configuration in appsettings.json from the Azure Portal.

How do I update my local deployment scripts with the latest?

Once you have created your Virtual Assistant or Skill projects using the various templates and generators, you may need to update the deployment scripts to reflect ongoing changes to these scripts over time.

Sample Project

For each of the template types we provide a sample project which is generated by the most recent template. This enables you to easily retrieve changes such as the deployment scripts. Alternatively you can clone the repro and use these sample projects as your starting point.

See the table below for a direct link to the appropriate sample project for your scenario:

Updating your deployment scripts

GitHub doesn’t provide the ability to download folders or files interactively in the Web Browser. You must therefore clone the Bot Framework Solutions repo onto your machine.

1. Clone the repo locally onto your machine
2. Browse to the appropriate deployment scripts folder using the table above as a reference to the location
3. Copy the entire contents of the Deployment folder (resources and script subdirectories) over the files in the Deployment folder of your Assistant or Skill project.

You now have the latest scripts for Assistant/Skill deployment and the latest cognitive models.

Skills

Skills are part of the Bot Framework Skills repo, so any changes to the deployment scripts will be reflected automatically when you pull the latest changes of that repository.

How do I use my existing cognitive models (LUIS and/or QnA Maker) with a Virtual Assistant project?

If you would like to use an existing LUIS app or QnA Maker knowledge base with a Virtual Assistant project, please refer to the following steps.

Use an existing QnA Maker knowledge base

If you have an existing QnA Maker knowledge base that you want to use in your Virtual Assistant project, follow these steps:

1. Add your knowledge base configuration in cognitivemodels.json

    "knowledgebases": [
      {
        "id": "mykb",
        "name": "<your-knowledge-base-name>",
        "kbId": "<your-knowledge-base-id>",
        "endpointKey": "<your-endpoint-key>",
        "hostname": "https://<your-qna-host>.azurewebsites.net/qnamaker",
        "subscriptionKey": ""
      }
    ]
   

   kbId, endpointKey, and hostname can be found in the Publish tab of the QnA Maker portal:

    POST /knowledgebases/<kbId>/generateAnswer
    Host: <hostname>
    Authorization: EndpointKey <endpointKey>
    Content-Type: application/json
    {"question":"<Your question>"}
   

2. Run the following command from your project directory to import the .qna schema of your hosted knowledge base and update your local Dispatch model and DispatchLuis.cs file:

    .\Deployment\Scripts\update_cognitive_model.ps1 -RemoteToLocal
   

3. Access your knowledge base in a Dialog using the following code (where “knowledgebase-id” is the id property from your cognitivemodels.json file):

    var qnaDialog = TryCreateQnADialog("knowledgebase-id", localizedServices);
    if (qnaDialog != null)
    {
        Dialogs.Add(qnaDialog);
    }
   
    return await stepContext.BeginDialogAsync(knowledgebaseId, cancellationToken: cancellationToken);
   

Use an existing LUIS model

If you have an existing LUIS application that you want to use in your Virtual Assistant project, follow these steps:

1. Add your LUIS app configuration in cognitivemodels.json:

    "languageModels": [
        {
          "id": "MyLuisApp",
          "name": "<your-luis-app-name>",
          "appId": "<your-luis-app-id>",
          "endpoint": "<your-luis-endpoint>",
          "authoringkey": "<your-luis-authoring-key>",
          "subscriptionKey": "<your-luis-subscription-key>",
          "region": "<your-luis-region>",
          "version": "0.1"
        }
      ],
   

   Each of the above properties can be found in the following locations:

   • Luis application name
     • Navigate to the LUIS portal for your region (e.g. www.luis.ai for West US region)
     • Open the Manage > Settings tab
     • Copy the App name property
   • Luis application ID
     • Navigate to the LUIS portal for your region (e.g. www.luis.ai for West US region)
     • Open the Manage > Settings tab
     • Copy the App ID property
   • Luis endpoint
     • Navigate to the LUIS portal for your region (e.g. www.luis.ai for West US region)
     • Open the Manage > Azure Resources > Authoring Resource tab
     • For the assigned prediction resource, copy the Endpoint URL property
   • Luis authoring key
     • Navigate to the LUIS portal for your region (e.g. www.luis.ai for West US region)
     • Open the Manage > Azure Resources > Authoring Resource tab
     • For the assigned authoring resource, copy the Primary Key property
   • Luis subscription key
     • Navigate to the LUIS portal for your region (e.g. www.luis.ai for West US region)
     • Open the Manage > Azure Resources > Authoring Resource tab
     • For the assigned prediction resource, copy the Primary Key property
   • Luis region
     • Navigate to the LUIS portal for your region (e.g. www.luis.ai for West US region)
     • Open the Manage > Azure Resources > Authoring Resource tab
     • For the assigned authoring resource, copy the Location property
2. Run the following command from your project directory to import the .lu schema of your hosted LUIS model and update your local Dispatch model and DispatchLuis.cs file:

    .\Deployment\Scripts\update_cognitive_model.ps1 -RemoteToLocal
   

3. Access your LUIS model in a Dialog using the following code (where “luis-app-id” is the id property from your cognitivemodels.json file and YourLUIS.cs is the LUIS generation class created for your application):

    // Get cognitive models for the current locale.
    var localizedServices = _services.GetCognitiveModels();
   
    // Run LUIS recognition on General model and store result in turn state.
    var luisResult = await localizedServices.LuisServices["luis-app-id"].RecognizeAsync<YourLUIS.cs>(innerDc.Context, cancellationToken);
   

How do I add support for additional languages to my existing Virtual Assistant?

If you would like to add support for additional languages to your existing Virtual Assistant, please refer to the following steps.

1. Run the following command from your project directory. Replace “locale” with one or more of the supported language codes (en-us, it-it, de-de, es-es, fr-fr, or zh-cn). The values for the remaining parameters can be found in appsettings.json after Virtual Assistant deployment.

      .\Deployment\Scripts\deploy_cognitive_models.ps1 `
        -languages "locale" `
        -name 'base-name-of-luis-model' `
        -resourceGroup 'resouce-group-for-luis-resource' `
        -luisAuthoringRegion 'luis-authoring-region' `
        -luisAuthoringKey 'luis-authoring-key' `
        -luisAccountName 'luis-account-name' `
        -luisAccountRegion 'luis-account-region' `
        -luisSubscriptionKey 'luis-subscription-key' `
        -luisEndpoint 'luis-endpoint' `
        -qnaSubscriptionKey 'qna-subscription-key'