General Availability of the QnA Maker was announced on May 7, 2018 at \\build\ conference. In all honesty, I was a bit surprised to see changes in the process of creation of new QnA services. But, as the new architecture is built on Azure, there are some differences between old and new portal. That also means that the data needs to get migrated from the old to the new architecture. Yes, manually.

This article wasn’t initially planned. However, the architectural changes and the migration procedure had to be addressed so I decided to write it in the middle of the series. I’ll try to shed some light on those and I hope it’ll help someone out there. Luckily, the largest part of the process is straightforward. First of all, we will need to export the knowledge base from the old portal, import the data to the new portal and then additionally take care about chat logs and alterations. Let’s crack on.

Export the knowledge base from the old portal

To access the old portal, navigate to https://www.qnamaker.ai/old and log in with your credentials. Then, under My Services, find the service you want to migrate and click / tap the Edit icon.

On the Edit page, click / tap on Download Knowledge Base.

Save the file. The Knowledge Base contents are saved in TSV (tab-separated values) format. The export file contains all question / answer pairs and information about the source of the pair.

If you are wondering where are the alterations (synonyms), they are not part of the export. More about that in a moment.

Create a new knowledge base

To create a knowledge base in the new portal, follow the procedure described in the article What the FAQ: Part 1 – QnA Maker.

Import data to the new knowledge base

Log on to the new QnA Maker portal and open the knowledge base you want to import your data to. Click the Settings link to open the knowledge base settings page, click Import knowledge base button and select the export file from your file system.

Be careful though, as the import procedure will overwrite the existing items in your knowledge base. Confirm the prompt by clicking on Replace button and hang on for a second until the questions and answer pairs are imported from the file.

Chat logs

Currently, there is no option for migrating chat logs from a knowledge base from the old portal to a knowledge base in the new portal. This is due to the architectural differences and it is not clear if this will be ever supported. However, you can download chat logs from the old portal. To do so, on the Edit page for the knowledge base in the old portal, switch to the Test tab and click Download chat logs.

The export file is in TSV format and contains questions asked, matching answers, how often the question was asked, probability score and the timestamp.

Synonyms (alterations)

You can define word synonyms to make the answers you get from the QnA service more precise. In the background, QnA Maker is also trying to mine that data. Strangely enough, they are not a part of the export. So how do you move them over to the new portal? It’s not as straightforward as it should be but it’s also not too complicated. Luckily, there are REST APIs for that.

Exporting synonyms

The old portal provides v2 APIs which provides an API for downloading alterations (synonyms). The provided link describes the API in the great detail, therefore I won’t be repeating that information here. Instead, I’m providing you with the sample script you can use (and extend if you like) to export the alterations. Let’s take a look.

$hostUrl = "https://westus.api.cognitive.microsoft.com/qnamaker/v2.0"
$kbId = "{insert your knowledge base id here (Guid)}"
$subscriptionKey = "{insert your subscription key here}"
$endpointUri = [string]::Format("{0}/knowledgebases/{1}/downloadAlterations", $hostUrl, $kbId)

$res = Invoke-WebRequest -Uri $endpointUri `
   -Method Get `
   -ContentType "application/json" `
   -Headers @{"Ocp-Apim-Subscription-Key"=$subscriptionKey}

if ($res.StatusCode -eq 200)
{
   $alterations = ConvertFrom-Json $res.Content
}

In the lines 1-4 we are initializing the variables. We are defining the host URL, providing the knowledge base ID, subscription key and finally, building the endpoint URI.

In the lines 6-9 we are making the actual call to the API. We are using the endpoint URI we just built above to make a GET request. We are setting the content type to application/json and providing the subscription key in the request header, in the Ocp-Apim-Subscription-Key field.

Assuming that everything goes well, the $res variable will contain the response with the StatusCode 200. In that case, the property Content will contain the JSON response we got from the endpoint. Let’s have a look.

Importing synonyms

The synonyms can be imported by using v4 APIs; however, you need to do a bit of data transformation first as the JSON format is different between v2 and v4 APIs.

We will start off where we left, directly after exporting synonyms. The variable $alterations contains all exported synonyms, which we need to transform first before importing with the new API.

$synonymsList = @()
foreach ($synonym in $alterations.wordAlterations)
{
   $wordSynonyms = New-Object System.Collections.Generic.List[System.String]
   $wordSynonyms.Add($synonym.word)
   foreach ($alteration in $synonym.alterations)
   {
      $wordSynonyms.Add($alteration)
   }
   $synonymsList += New-Object -Type PSObject `
          -Property @{ alterations = $wordSynonyms }
}
$allSynonyms = New-Object -Type PSObject `
      -Property @{ wordAlterations = $synonymsList }
$newSynonymsJson = ConvertTo-Json $allSynonyms -Depth 3

The code listed above will ensure that the variable $newSynonymsJson contains the JSON string in the correct format so that we can pass it as a request body to the REST API to upload the alterations to our subscription. As a key, use one of the keys found in your Cognitive Services account. Also, note that we are using an HTTP PUT method in this case.

$url = "https://westus.api.cognitive.microsoft.com/qnamaker/v4.0/alterations"
$subscriptionKey = "{insert your key here}"

$res = Invoke-WebRequest -Uri $url -Method Put -Body $newSynonymsJson -ContentType "application/json" -Headers @{"Ocp-Apim-Subscription-Key"=$subscriptionKey}

Assuming that everything went ok, $res.StatusCode will contain the HTTP status 204. For those wondering, that just means that the server processed the request successfully and returned no additional content.

More information

QnA Maker v2 APIs – https://aka.ms/qnamaker-v2-apis
QnA Maker v4 APIs – https://aka.ms/qnamaker-v4-apis