How to create projects in orchestration workflow

Orchestration workflow allows you to create projects that connect your applications to:

• Custom Language Understanding
• Question Answering
• LUIS

Prerequisites

Before you start using orchestration workflow, you will need several things:

• An Azure subscription - Create one for free.
• An Azure AI Language resource

Create a Language resource

Before you start using orchestration workflow, you will need an Azure AI Language resource.

Note

• You need to have an owner role assigned on the resource group to create a Language resource.
• If you are planning to use question answering, you have to enable question answering in resource creation

Create a new resource from the Azure portal

1. Go to the Azure portal to create a new Azure AI Language resource.

2. Select Continue to create your resource

3. Create a Language resource with following details.

   Instance detail	Required value
   Region	One of the supported regions.
   Name	A name for your Language resource.
   Pricing tier	One of the supported pricing tiers.

Create a new Language resource from Language Studio

If it's your first time logging in, you'll see a window in Language Studio that will let you choose an existing Language resource or create a new one. You can also create a resource by clicking the settings icon in the top-right corner, selecting Resources, then clicking Create a new resource.

Create a Language resource with following details.

Instance detail	Required value
Azure subscription	Your Azure subscription
Azure resource group	Your Azure resource group
Azure resource name	Your Azure resource name
Location	Learn more about supported regions.
Pricing tier	Learn more about supported pricing tiers.

Important

• Make sure to enable Managed Identity when you create a Language resource.
• Read and confirm Responsible AI notice

Sign in to Language Studio

To create a new intent, select +Add button and start by giving your intent a name. You will see two options, to connect to a project or not. You can connect to (LUIS, question answering, or Conversational Language Understanding) projects, or choose the no option.

Create an orchestration workflow project

Once you have a Language resource created, create an orchestration workflow project.

Language Studio

1. In Language Studio, find the section labeled Understand questions and conversational language and select Orchestration Workflow.

   

2. This will bring you to the Orchestration workflow project page. Select Create new project. To create a project, you will need to provide the following details:

Value	Description
Name	A name for your project.
Description	Optional project description.
Utterances primary language	The primary language of your project. Your training data should primarily be in this language.

Once you're done, select Next and review the details. Select create project to complete the process. You should now see the Build Schema screen in your project.

REST APIs

Submit a PATCH request using the following URL, headers, and JSON body to create a new project.

Request URL

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}?api-version={API-VERSION}

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	myProject
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

Body

Use the following sample JSON as your body.

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "Orchestration",
  "description": "Project description"
 }

Key	Placeholder	Value	Example
projectName	{PROJECT-NAME}	The name of your project. This value is case-sensitive.	EmailApp
language	{LANGUAGE-CODE}	A string specifying the language code for the utterances used in your project. If your project is a multilingual project, choose the language code of the majority of the utterances.	en-us

Import an orchestration workflow project

Language Studio

You can export an orchestration workflow project as a JSON file at any time by going to the orchestration workflow projects page, selecting a project, and from the top menu, clicking on Export.

That project can be reimported as a new project. If you import a project with the exact same name, it replaces the project's data with the newly imported project's data.

To import a project, select the arrow button next to Create a new project and select Import, then select the JSON file.

REST APIs

You can import an orchestration workflow JSON into the service

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

Request URL

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}

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	myProject
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

Body

Note

Each intent should only be of one type only from (CLU,LUIS and qna)

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": "00000000-0000-0000-0000-000000000000",
            "appVersion": "string",
            "slotName": "string"
          },
          "cluOrchestration": {
            "projectName": "string",
            "deploymentName": "string"
          },
          "qnaOrchestration": {
            "projectName": "string"
          }
        }
      }
    ],
    "utterances": [
      {
        "text": "Trying orchestration",
        "language": "{LANGUAGE-CODE}",
        "intent": "string"
      }
    ]
  }
}

Key	Placeholder	Value	Example
api-version	{API-VERSION}	The version of the API you are calling. The version used here must be the same API version in the URL.	2022-03-01-preview
projectName	{PROJECT-NAME}	The name of your project. This value is case-sensitive.	EmailApp
language	{LANGUAGE-CODE}	A string specifying the language code for the utterances used in your project. If your project is a multilingual project, choose the language code of the majority of the utterances.	en-us

Export project

Language Studio

You can export an orchestration workflow project as a JSON file at any time by going to the orchestration workflow projects page, selecting a project, and pressing Export.

REST APIs

You can export an orchestration workflow project as a JSON file at any time.

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

Request URL

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}

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	EmailApp
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

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.

Get orchestration project details

Language Studio

1. Go to your project settings page in Language Studio.

2. You can see project details.

3. In this page you can update project description.

4. You can also retrieve your resource primary key from this page.

   

REST APIs

To get an orchestration workflow project's details, submit a GET request using the following URL and headers. Replace the placeholder values with your own values.

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

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	myProject
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

Response Body

Once you send the request, you will get the following response.

{
  "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}"
}

Once you send your API request, you will receive a 200 response indicating success and JSON response body with your project details.

Delete project

Language Studio

When you don't need your project anymore, you can delete your project using Language Studio. Select Projects from the left navigation menu, select the project you want to delete, and then select Delete from the top menu.

REST APIs

When you don't need your project anymore, you can delete your project using the APIs.

Create a DELETE request using the following URL, headers, and JSON body to delete a conversational language understanding project.

Request URL

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

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	The name for your project. This value is case-sensitive.	myProject
{API-VERSION}	The version of the API you are calling.	2023-04-01

Headers

Use the following header to authenticate your request.

Key	Value
Ocp-Apim-Subscription-Key	The key to your resource. Used for authenticating your API requests.

Once you send your API request, you will receive a 202 response indicating success, which means your project has been deleted.

Next Steps

Build schema