Create and deploy applications

Once you are satisfied with your Mix resources, you deploy them so that you can use them in your client application.

This section first introduces terms that help to understand application configuration and the deployment workflow.

Terminology

Application

A Mix application defines a set of credentials that you use to access Mix.asr, Mix.nlu, and Mix.dialog resources. A Mix application can be deployed to multiple runtime environments (for example, sandbox, QA, production, etc.).

By default, each user has a personal namespace (identified with the email address), which includes an application. This application, called the Mix Sample App, is specific to the user and is used for development. The Mix Sample App can only be deployed to the default sandbox environment.

App ID

An app ID uniquely identifies a Mix application in an environment. It is used to reference the resources created and managed in Mix.

App IDs have one of the following formats:

NMDPTRIAL_user_info_date_origin_geography
custom_app_name_origin_geography

Where geography specifies the tooling geography in which the application ID was created. For example, the following sample app IDs were created in the US geography (https://mix.nuance.co.uk/):

NMDPTRIAL_alex_smith_company_com_20190919T190532_origin_us
DEMO-OMNICHANNEL-APP-DEV_origin_us

The geography indicator is required to deploy an application configuration in another geography.

Resources

The Mix resources available in a Mix application are:

DLMs for Mix.asr
NLU models for Mix.nlu
Conversational applications for Mix.dialog

Application configuration

An application configuration associates an app ID with the Mix.asr, Mix.nlu, and Mix.dialog resources deployed in a runtime environment.

An application configuration is created by specifying:

A context tag, which is a name identifying this application configuration
The versions of the Mix.asr, Mix.nlu, and Mix.dialog resources to include in this application configuration

You use the application configuration at runtime by providing the app ID and context tag to load resources. The context tag is scoped by service through a URN. The URN lets you specify which resource (Mix.asr, Mix.nlu, or Mix.dialog) to load in a specific application configuration.

URN of application configuration

Uniform Resource Names (URN) are used in Mix to load a specific Mix resource, described in the application configuration. A URN helps the service determine how to parse the resources in a context tag. For example:

urn:nuance-mix:tag:model/coffee_app/mix.asr?=language=eng-USA

See URN for details.

Client ID

Nuance Mix uses the OAuth 2.0 protocol for authorization. All client applications must provide an access token to be able to access the ASR, NLU, Dialog, and TTS runtime services. To obtain an access token, a client ID and a client secret must be provided.

You can create multiple client IDs per app ID.

Client IDs have the following syntax:

appID:appID:geo:region:clientName:clientName

For example:

appID:NMDPTRIAL_alex_smith_company_com_20190919T190532:geo:qa:clientName:default

Note: In some earlier versions of Mix, the client ID had a different format; for example:

appID:NMDPTRIAL_alex_smith_company_com_20190919T190532

These client IDs are still supported.

Client secret

The client secret is generated through Mix.dashboard and used to obtain an access token. See Authorization for more information.

Webhook

Webhooks are POST requests sent to a web application when a specific event is triggered. For example, you can configure a webhook that will send a notification when a new application configuration tag is created or an application configuration is deployed.

Deployment workflow

To see the applications that are available to you:

In Mix.dashboard, click the Manage tab.
In the left-hand pane, expand the Applications section.

What you see depends on your customer status:

If you have a commercial agreement with Nuance, you will see the applications that have been defined for your company.
Otherwise, you will see your Mix Sample App.

The default landing page is the App ID tab when your application has no configurations.

reorganize tabs without approval

The following settings tabs are displayed for your application in the top bar:

Setting	Description
App ID	Provides the app ID available for the selection application and lets you generate credentials to access them. See Authorize your client application: Runtime for details.
Members	Lists members in your application.
Details	Provides information including name and organization of your application. Provides runtime ID(s) including sandbox environment.

Note: Click the settings icon whenever you need to go back to your application settings.

Create and deploy applications: Procedure

To deploy resources and use them in an application:

Create an application configuration. The application configuration defines the resource version(s) that you want to use in your application.
During this step, you assign a context tag to this application configuration; the context tag uniquely identifies your configuration. You will need this to access the Mix resources in your application.
Deploy your application configuration to an environment that is accessible by your application. Deployment is done through a deployment flow.
Authorize your client application to access the Mix runtime services from your client application.

What is a deployment flow?

The deployment flow defines the deployment environments that are available to you. This can be the Mix Sandbox or an environment in your company's deployment flow.

For example, consider the following basic deployment flow with three environments: Sandbox, QA, and Prod.

When you deploy a configuration to a new environment, all the required configuration data gets copied to that environment, where you can access and test it. For example, in the diagram above, the application configuration was successfully deployed to the Sandbox environment (as shown by the green status bar and checkmark), so you can access it from your application. When you are ready, you can promote it to the next environment in your flow, in this case the QA environment.

You move your configuration sequentially through the deployment flow; you must go through each environment in your flow.

An environment can include more than one region. As shown in the diagram above, the Prod environment is available in two regions: Eastern_US and Western_US.

Depending on your configuration, some steps may require an approval from your Nuance representative.

Mix Sandbox default deployment flow

If you do not have a commercial agreement with Nuance, you deploy your Mix Sample App in the Mix Sandbox default deployment flow. This flow has a single deployment environment—the Mix Sandbox environment.

There are no approvals required in this flow.

Set up a new configuration

When you create an application configuration, you provide the following information:

Field	Description
Context Tag	This is the information that your application will need to access your resources at runtime. A context tag is generated automatically for you. You can edit it by clicking the pencil icon. Note: Context tags cannot include spaces; you can use letters (a-z, A-Z), digits (0-9), and the underscore character (_).
Which organization?	Select the organization that contains the project you want to deploy an application from.
Which project?	Select the project that contains your resources. Note: Projects with the same name will have their project ID listed in brackets to help differentiate between projects.
NLU and ASR	Select the version of your NLU model to use in this configuration. The corresponding ASR build will be selected automatically. If your project includes multiple languages, select the version of the NLU model to use for each language.
Dialog	Select the version of your Dialog application to use in this configuration.
Configure data host aliases	If the dialog project exchanges data with an external system using a server-side integration, you can overwrite the base URL for this environment. Click the Edit icon for the alias you want to modify and enter the new base URL. This value will take precedence over any other value. See Order of precedence for URL values for details.
Where do you want to deploy?	Select the deployment flow that you want to use for your application. If a single deployment flow is available (for example, the Mix Sandbox default deployment flow), it is selected by default.

In Mix.dashboard, click the Manage tab.
In the left-hand pane, expand the Applications section.
By default, the first application in the list is expanded. To see another application, select it.
Click Create Configuration or click the plus icon .
In Create a Configuration, enter the fields as specified in the table above.
Click Set up Configuration.

The configuration is created.

Deploy an application configuration

After you have created an application configuration, you deploy it to an environment in your deployment flow.

The actual environments available depend on your configuration. This procedure uses the sample Sandbox-QA-Prod deployment above as an example.

To deploy an application configuration:

In Mix.dashboard, click the Manage tab.
In the left-hand pane, expand the Applications section.
By default, the first application in the list is expanded. To see another application, select it.
On the left panel, select the context tag for the configuration that you want to deploy.
Its deployment flow is displayed.
Select the environment and region(s) where to deploy the configuration and click Deploy. One of two status will appear with a different color:

Color	Status
Green	Configuration successfully deployed
Red	An error occurred, please redeploy the configuration

To get more information, click the information icon .
The following deployment details are presented:

User who requested the deployment
User who approved the deployment
Deployment date
Data host(s)

A data host provides information about the web service that will handle the data requests, such as the URL of the web service, an alias, and so on. For more information on data hosts, see Configure the base URL of the web service in Mix.dashboard.

Note: You can only deploy to the next environment in your deployment flow.

Download models for an application configuration

Once you've deployed an application configuration to an environment, you have the option to download model information for this application configuration.

Downloading application configuration model information is primarily directed to self-hosted customers. Self-hosted customers can download files of their NLU, ASR, or Dialog models and make them available in their self-hosted installations. All model information are within one ZIP file.

To download the NLU, ASR, and Dialog models for an application configuration in a specific environment and geography:

In Mix.dashboard, click the Manage tab.
In the left-hand pane, expand the Applications section.
By default, the first application in the list is expanded. To see another application, select it.
In the left-hand pane, select the context tag for the desired configuration.
Its deployment flow appears.
Click the Actions icon for the region where the configuration was deployed.
Click Download files.
The download is a ZIP file.

Application configuration download files

Delete a deployment

To delete an application configuration that was deployed in an environment:

In Mix.dashboard, click the Manage tab.
In the left-hand pane, expand the Applications section.
By default, the first application in the list is expanded. To see another application, select it.
In the left-hand pane, select the context tag for the configuration that you want to delete.
Its deployment flow is displayed.
Click Actions for the region where the configuration was deployed. For example:
Click Delete to confirm the action.
The application configuration is deleted.

Overriding an application configuration

As your application evolves, so will your resources. For example, you may want to update your NLU model to fix issues or integrate new annotations from utterances collected in the field.

To update the resources for an application, you override its application configuration by updating the resource versions used by your application configuration and deploying it in your deployment flow.

For example, consider the following scenario. Your application configuration, which uses v3 of your Mix.nlu model, is currently deployed in production. Based on your customers' responses to the application, you update your Mix.nlu model, which is now at v4.

The following diagram shows the deployment flow of your v3 application configuration:

When you override an application configuration and deploy it to an environment, the previous deployment is removed. For example, let's say you override your application configuration with v4 of the Mix.nlu model and then deploy it to Sandbox. When your v4 configuration is successfully deployed to Sandbox, the v3 configuration will be deleted from that environment, as shown in the following diagram:

Note that the v3 version will continue to be active in the other environments of your deployment flow, until you successfully promote your new version to that environment.

Override an application configuration: Procedure

In Mix.dashboard, click the Manage tab.
In the left-hand pane, expand the Applications section.
By default, the first application in the list is expanded. To see another application, select it.
In the left-hand pane, select the context tag for the configuration that you want to override.
Its deployment flow is displayed.
Click Override.
Enter the required information and click Set up Configuration.

A new deployment flow for the updated configuration is now displayed.

Delete an application configuration

To delete an application configuration, you must first delete all the deployments for this application configuration.

In Mix.dashboard, click the Manage tab.
In the left-hand pane, expand the Applications section.
By default, the first application in the list is expanded. To see another application, select it.
In the left-hand pane, select the context tag for the configuration that you want to delete.
Its deployment flow is displayed.
If this configuration was deployed:
1. Click the ellipses icon for the region where the configuration was deployed.
2. Click the Delete icon. For example:
3. Click Delete to confirm the action.
4. Repeat this step for all the current deployments for this application configuration.
Delete the application configuration:
1. Click the Delete icon for the application configuration. For example:
2. Click Delete to confirm the action.
3. Repeat this step for all the application configuration overrides.

Configure webhooks to receive event notifications

Mix provides a mechanism that allows you to receive event notifications with webhooks.

Webhooks are POST requests sent to a web application when a specific event is triggered. For example, you can configure a webhook that will send a notification when a new application configuration tag is created or an application configuration is deployed.

Mix webhooks provide a payload that includes data related to the triggered event. You can then use this data to call Mix.api endpoints and automate some actions.

For example, consider these use cases:

Your deployment flow requires an approval when deploying to an environment. You can create a webhook that will send a notification to your web application when a deployment request is triggered in the environment that requires approval. Using the data provided in the webhook, you can send an email to a list of approvers indicating that an approval is pending.
You are hosting your deployment environments on premises. You can create a webhook that will send a notification when a deployment request is triggered. Using the data provided in the webhook, you can call Mix.api to download the Mix resources for the application configuration and then deploy them in your environments.

Permissions

To create, update, or delete a webhook, a user must have the following application and organization roles:

Owner or viewer of the application for which webhooks are created, and
Owner or member of the organization where the application resides

To view webhooks, a user must have the following application and organization roles:

Owner or viewer of the application for which webhooks are created, and
Owner, member, or viewer of the organization where the application resides

Available events

There are two types of events that can trigger a webhook:

Application configuration events: Triggers linked to key application configuration actions
Deployment events: Triggers linked to a deployment request or approval outcome

Application configuration events

Application configurations are configurations you've deployed for your application. You can configure webhooks for the following application configuration events:

Creation (application_configuration_create event)—Notification is sent when an application configuration is created
Override (application_configuration_override event)—Notification is sent when an application configuration is overwritten
Deployment (application_configuration_deploy event)—Notification is sent when an application configuration is deployed
Undeployment (application_configuration_undeploy event)—Notification is sent when an application configuration is deleted from an environment

Deployment events

Deployment events are linked to a deployment request or approval outcome. You can configure webhooks for the following events:

Request (application_configuration_deployment_request event)—Notification is sent when a deployment is requested for an application configuration
Publish (application_configuration_deployment_request_outcome event)—Notification is sent when a deployment request is approved (published) or rejected

Workflow: Configure webhooks to receive event notifications

To configure webhooks to receive event notifications:

Implement a web application that will consume the webhook content.
Add a webhook in Mix.dashboard.

Implement the web application: Guidelines

When implementing the web application that consumes the webhook, please follow these guidelines.

Connection URL

For security considerations, outgoing traffic is only allowed on port 443, using HTTPS.

The URL for the web application that consumes the webhook must have the following format:

https://<domainname>/<path>

For example:

https://omnichannel.com/hooks

API key

When you create a webhook, you can configure an API key for identification or authentication. This key is sent in the header of the webhook, in the authorization field; for example:


{
  "content-length": "1464",
  "user-agent": "Mozilla/5.0 (compatible; pycurl)",
  "accept": "*/*",
  "accept-encoding": "gzip,deflate",
  "content-type": "application/json",
  "authorization": "Basic 6bf7456c-48e7-4236-be24-a1e382234785",
  "uber-trace-id": "4563a48988781ac9:6b45e9f99425b166:81439b786fed1563:1"
}

Payloads

The event payloads are provided in JSON. At a minimum, payloads have the following fields:


{
  "event": "event_name",
  "config": {
    // Data specific to the event
  }
}

They can also include additional fields that are specific to an event.

For a description of the payloads for the available events, see:

application configuration creation
application configuration override
application configuration deploy
application configuration undeploy
application configuration deployment request
application configuration deployment request outcome

Add a webhook in Mix.dashboard

Empty webhook form

To add a webhook:

In Mix.dashboard, click the Manage tab.
In the left-hand pane, expand the Organizations section.
Select the organization and click the Webhooks tab.
Click the Add webhook icon .

An empty form is displayed.
Enter a webhook name.
Enter the URL of the web application that will consume the webhook.
(Optional) Enter an API key.
This API key can be used for identification or authentication and is managed by your web applications.
Note: If you have previously added your API key for the web application, you won't see this field as your key has already been authenticated.
Select a Mix application.
Select one or more environments.
Select one or more events that will trigger the webhook.
Click Save.

The webhook card is displayed. You can edit or delete a webhook by clicking or in the top right corner of the card.

Webhook card

Note: Fields with an asterisk (*) are mandatory. The following special characters are not permitted: !, @, #, $, %, ^, &, *

application_configuration_create event

Example

{
  "event": "application_configuration_create",
  "config": {
    "id": 2386,
    "tag": "A207_C2383",
    "applicationId": 207,
    "applicationName": "Mix Sample App",
    "organizationName": "alex.smith@company.com",
    "projectName": "test_project_credentials",
    "deploymentFlowId": 358,
    "models": {
      "nlu": {
        "builds": [
          {
            "locale": "en_US",
            "buildVersion": 1,
            "label": "NLU_26147_1"
          }
        ],
        "projectId": 26147
      },
      "asr": {
        "builds": [
          {
            "locale": "en_US",
            "buildVersion": 1,
            "label": "ASR_26147_1"
          }
        ],
        "projectId": 26147
      },
      "dialog": {
        "projectId": 26147,
        "buildVersion": 1,
        "label": "DIALOG_26147_1"
      }
    },
    "dataHosts": []
  }
}

The application_configuration_create event payload provides information about the application configuration tag that was created. In particular, it includes the following top-level fields:

Field	Description
`event`	Name of the event that triggered the webhook.
`config`	Details about the application configuration that was created.