Back up and recover your orchestration workflow models

When you create a Language resource in the Azure portal, you specify a region for it to be created in. From then on, your resource and all of the operations related to it take place in the specified Azure server region. It's rare, but not impossible, to encounter a network issue that hits an entire region. If your solution needs to always be available, then you should design it to either fail-over into another region. This requires two Azure AI Language resources in different regions and the ability to sync your orchestration workflow models across regions.

If your app or business depends on the use of an orchestration workflow model, we recommend that you create a replica of your project into another supported region. So that if a regional outage occurs, you can then access your model in the other fail-over region where you replicated your project.

Replicating a project means that you export your project metadata and assets and import them into a new project. This only makes a copy of your project settings, intents and utterances. You still need to train and deploy the models before you can query them with the runtime APIs.

In this article, you will learn to how to use the export and import APIs to replicate your project from one resource to another existing in different supported geographical regions, guidance on keeping your projects in sync and changes needed to your runtime consumption.

• Two Azure AI Language resources in different Azure regions, each of them in a different region.

Use the following steps to get the keys and endpoint of your primary and secondary resources. These will be used in the following steps.

Go to your resource overview page in the Azure portal. From the menu on the left side, select Keys and Endpoint. You will use the endpoint and key for API requests.

Start by exporting the project assets from the project in your primary resource.

Replace the placeholders in the following request with your {PRIMARY-ENDPOINT} and {PRIMARY-RESOURCE-KEY} that you obtained in the first step.

Create a POST request using the following URL, headers, and JSON body to export your project.

Use the following URL when creating your API request. Replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&api-version={API-VERSION}

Use the following header to authenticate your request.

Once you send your API request, you will receive a 202 response indicating success. In the response headers, extract the operation-location value. It will be formatted like this:

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

JOB-ID is used to identify your request, since this operation is asynchronous. Use this URL to get the exported project JSON, using the same authentication method.

Replace the placeholders in the following request with your {PRIMARY-ENDPOINT} and {PRIMARY-RESOURCE-KEY} that you obtained in the first step.

Use the following GET request to query the status of your export job. You can use the URL you received from the previous step, or replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/export/jobs/{JOB-ID}?api-version={API-VERSION}

Use the following header to authenticate your request.

{
  "resultUrl": "{Endpoint}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/export/jobs/xxxxxx-xxxxx-xxxxx-xx/result?api-version={API-VERSION}",
  "jobId": "xxxx-xxxxx-xxxxx-xxx",
  "createdDateTime": "2022-04-18T15:23:07Z",
  "lastUpdatedDateTime": "2022-04-18T15:23:08Z",
  "expirationDateTime": "2022-04-25T15:23:07Z",
  "status": "succeeded"
}

Use the URL from the resultUrl key in the body to view the exported assets from this job.

Submit a GET request using the {RESULT-URL} you received from the previous step to view the results of the export job.

Use the following header to authenticate your request.

Copy the response body as you will use it as the body for the next import job.

Now go ahead and import the exported project assets in your new project in the secondary region so you can replicate it.

Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.

Submit a POST request using the following URL, headers, and JSON body to import your project.

Use the following URL when creating your API request. Replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}

Use the following header to authenticate your request.

Use the following sample JSON as your body.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Orchestration",
    "settings": {
      "confidenceThreshold": 0
    },
    "projectName": "{PROJECT-NAME}",
    "description": "Project description",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Orchestration",
    "intents": [
      {
        "category": "string",
        "orchestration": {
          "kind": "luis",
          "luisOrchestration": {
            "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
            "appVersion": "string",
            "slotName": "string"
          },
          "cluOrchestration": {
            "projectName": "string",
            "deploymentName": "string"
          },
          "qnaOrchestration": {
            "projectName": "string"
          }
        }
      }
    ],
    "utterances": [
      {
        "text": "Trying orchestration",
        "language": "{LANGUAGE-CODE}",
        "intent": "string"
      }
    ]
  }
}

Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.

Use the following GET request to query the status of your import job. You can use the URL you received from the previous step, or replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

Use the following header to authenticate your request.

Once you send the request, you will get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".

{
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx",
  "createdDateTime": "2022-04-18T15:17:20Z",
  "lastUpdatedDateTime": "2022-04-18T15:17:22Z",
  "expirationDateTime": "2022-04-25T15:17:20Z",
  "status": "succeeded"
}

After importing your project, you only have copied the project's assets and metadata and assets. You still need to train your model, which will incur usage on your account.

Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.

Create a POST request using the following URL, headers, and JSON body to submit a training job.

Use the following URL when creating your API request. Replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}

Use the following header to authenticate your request.

Use the following object in your request. The model will be named MyModel once training is complete.

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "standard",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}

Once you send your API request, you will receive a 202 response indicating success. In the response headers, extract the operation-location value. It will be formatted like this:

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

You can use this URL to get the training job status.

Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.

Use the following GET request to get the status of your model's training progress. Replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

Use the following header to authenticate your request.

Once you send the request, you will get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "xxxxxx-xxxxx-xxxxxx-xxxxxx",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

This is the step where you make your trained model available form consumption via the runtime prediction API.

Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.

Create a PUT request using the following URL, headers, and JSON body to start deploying an orchestration workflow model.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}

Use the following header to authenticate your request.

{
  "trainedModelLabel": "{MODEL-NAME}",
}

Once you send your API request, you will receive a 202 response indicating success. In the response headers, extract the operation-location value. It will be formatted like this:

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

You can use this URL to get the deployment job status.

Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.

Use the following GET request to get the status of your deployment job. Replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

Use the following header to authenticate your request.

Once you send the request, you will get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Within your system, at the step where you call runtime API check for the response code returned from the submit task API. If you observe a consistent failure in submitting the request, this could indicate an outage in your primary region. Failure once doesn't mean an outage, it may be transient issue. Retry submitting the job through the secondary resource you have created. For the second request use your {YOUR-SECONDARY-ENDPOINT} and secondary key, if you have followed the steps above, {PROJECT-NAME} and {DEPLOYMENT-NAME} would be the same so no changes are required to the request body.

In case you revert to using your secondary resource you will observe slight increase in latency because of the difference in regions where your model is deployed.

Maintaining the freshness of both projects is an important part of process. You need to frequently check if any updates were made to your primary project so that you move them over to your secondary project. This way if your primary region fail and you move into the secondary region you should expect similar model performance since it already contains the latest updates. Setting the frequency of checking if your projects are in sync is an important choice, we recommend that you do this check daily in order to guarantee the freshness of data in your secondary model.

Use the following url to get your project details, one of the keys returned in the body indicates the last modified date of the project. Repeat the following step twice, one for your primary project and another for your secondary project and compare the timestamp returned for both of them to check if they are out of sync.

Use the following GET request to get your project details. You can use the URL you received from the previous step, or replace the placeholder values below with your own values.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}

Use the following header to authenticate your request.

{
  "createdDateTime": "2022-04-18T13:53:03Z",
  "lastModifiedDateTime": "2022-04-18T13:53:03Z",
  "lastTrainedDateTime": "2022-04-18T14:14:28Z",
  "lastDeployedDateTime": "2022-04-18T14:49:01Z",
  "projectKind": "Orchestration",
  "projectName": "{PROJECT-NAME}",
  "description": "This is a sample Orchestration project.",
  "language": "{LANGUAGE-CODE}"
}

Repeat the same steps for your replicated project using {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY}. Compare the returned lastModifiedDateTime from both projects. If your primary project was modified sooner than your secondary one, you need to repeat the steps of exporting, importing, training and deploying your model.

In this article, you have learned how to use the export and import APIs to replicate your project to a secondary Language resource in other region. Next, explore the API reference docs to see what else you can do with authoring APIs.

• Authoring REST API reference

• Runtime prediction REST API reference