Tutorial: Extract contextually related data from an utterance

In this tutorial, find related pieces of data based on context. For example, an origin and destination locations for a transfer from one city to another. Both pieces of data may be required and they are related to each other.

A role can be used with any prebuilt or custom entity type, and used in both example utterances and patterns.

In this tutorial, you learn how to:

  • Create new app
  • Add intent
  • Get origin and destination information using roles
  • Train
  • Publish
  • Get intents and entity roles from endpoint

For this article, you can use the free LUIS account in order to author your LUIS application.

This app determines where an employee is to be moved from the origin city to the destination city. It uses a GeographyV2 prebuilt entity to identify the city names and it uses roles to determine the location types (origin and destination) within the utterance.

A role should be used when the entity data to extract:

  • Is related to each other in the context of the utterance.
  • Uses specific word choice to indicate each role. Examples of these words include: from/to, leaving/headed to, away from/toward.
  • Both roles are frequently in the same utterance, allowing LUIS to learn from this frequent contextual usage.
  • Need to be grouped and processed by client app as a unit of information.

Create a new app

  1. Sign in to the preview LUIS portal with the URL of https://preview.luis.ai.

  2. Select Create new app, enter the name HumanResources and keep the default culture, English. Leave the description empty.

  3. Select Done.

Create an intent to move employees between cities

  1. Make sure your Human Resources app is in the Build section of LUIS. You can change to this section by selecting Build on the top, right menu bar.

  2. Select Create new intent.

  3. Enter MoveEmployeeToCity in the pop-up dialog box then select Done.

    Screenshot of create new intent dialog with

  4. Add example utterances to the intent.

    Example utterances
    move John W. Smith leaving Seattle headed to Orlando
    transfer Jill Jones from Seattle to Cairo
    Place John Jackson away from Tampa, coming to Atlanta
    move Debra Doughtery to Tulsa from Chicago
    mv Jill Jones leaving Cairo headed to Tampa
    Shift Alice Anderson to Oakland from Redmond
    Carl Chamerlin from San Francisco to Redmond
    Transfer Steve Standish from San Diego toward Bellevue
    lift Tanner Thompson from Kansas city and shift to Chicago

    Screenshot of LUIS with new utterances in MoveEmployee intent

Add prebuilt entity geographyV2

The prebuilt entity, geographyV2, extracts location information, including city names. Since the utterances have two city names, relating to each other in context, use roles to extract that context.

  1. Select Entities from the left-side navigation.

  2. Select Add prebuilt entity, then select geo in the search bar to filter the prebuilt entities.

    Add geographyV2 prebuilt entity to app

  3. Select the checkbox and select Done.

  4. In the Entities list, select the geographyV2 to open the new entity.

  5. Add two roles, Origin, and Destination.

    Add roles to prebuilt entity

  6. Select Intents from the left-side navigation, then select the MoveEmployeeToCity intent. Notice the city names are labeled with the prebuilt entity geographyV2.

  7. In the context toolbar, select the Entity palette.

    Select Entity Palette from content toolbar

  8. Select the prebuilt entity, geographyV2, then select the Entity inspector.

  9. In the Entity inspector, select one role, Destination. This changes the mouse cursor. Use the cursor to label the text in all the utterances that is the destination location.

    Select Role in Entity Palette

  10. Return to the Entity inspector, change to the role to Origin. Use the cursor to label the text in all the utterances that is the origin location.

Add example utterances to the None intent

The client application needs to know if an utterance is not meaningful or appropriate for the application. The None intent is added to each application as part of the creation process to determine if an utterance can't be answered by the client application.

If LUIS returns the None intent for an utterance, your client application can ask if the user wants to end the conversation or give more directions for continuing the conversation.


Do not leave the None intent empty.

  1. Select Intents from the left panel.

  2. Select the None intent. Add three utterances that your user might enter but are not relevant to your Human Resources app:

    Example utterances
    Barking dogs are annoying
    Order a pizza for me
    Penguins in the ocean

Train the app so the changes to the intent can be tested

  1. In the top right side of the LUIS website, select the Train button.

    Train button

  2. Training is complete when you see the green status bar at the top of the website confirming success.

    Trained status bar

Publish the app so the trained model is queryable from the endpoint

In order to receive a LUIS prediction in a chat bot or other client application, you need to publish the app to the endpoint.

  1. Select Publish in the top right navigation.

    LUIS publish to endpoint button in top right menu

  2. Select the Production slot and the Publish button.

    LUIS publish to endpoint

  3. Publishing is complete when you see the green status bar at the top of the website confirming success.

    LUIS publish to endpoint

  4. Select the endpoints link in the green status bar to go to the Keys and endpoints page. The endpoint URLs are listed at the bottom.

Get intent and entity prediction from endpoint

  1. In the Manage section (top right menu), on the Keys and endpoints page (left menu), select the endpoint URL at the bottom of the page. This action opens another browser tab with the endpoint URL in the address bar.

    The endpoint URL looks like https://<region>.api.cognitive.microsoft.com/luis/v2.0/apps/<appID>?verbose=true&subscription-key=<YOUR_KEY>&<optional-name-value-pairs>&q=<user-utterance-text>.

  2. Go to the end of the URL in the address bar and enter Please move Carl Chamerlin from Tampa to Portland. The last querystring parameter is q, the utterance query. This utterance is not the same as any of the labeled utterances so it is a good test and should return the MoveEmployee intent with the entity extracted.

      "query": "Please move Carl Chamerlin from Tampa to Portland",
      "topScoringIntent": {
        "intent": "MoveEmployeeToCity",
        "score": 0.9706451
      "intents": [
          "intent": "MoveEmployeeToCity",
          "score": 0.9706451
          "intent": "None",
          "score": 0.0307451729
      "entities": [
          "entity": "tampa",
          "type": "builtin.geographyV2.city",
          "startIndex": 32,
          "endIndex": 36,
          "role": "Origin"
          "entity": "portland",
          "type": "builtin.geographyV2.city",
          "startIndex": 41,
          "endIndex": 48,
          "role": "Destination"

    The correct intent is predicted and the entities array has both the origin and destination roles in the corresponding entities property.

Clean up resources

When no longer needed, delete the LUIS app. To do so, select My apps from the top left menu. Select the ellipsis (...) to the right of the app name in the app list, select Delete. On the pop-up dialog Delete app?, select Ok.

Next steps

This tutorial created a new intent and added example utterances for the contextually learned data of origin and destination locations. Once the app is trained and published, a client-application can use that information to create a move ticket with the relevant information.