Using the Named entity recognition API

Sterling provides a Named entity recognition (NER) service, which analyzes natural language text and finds domain-specific entities. The service is tightly integrated with the Supply Chain Intelligence Suite data platform.

The named entity recognition service uses Supply Chain Intelligence Suite data platform as the primary data source so you do not have to train the service to recognize named entities within the Control Tower. The service is preconfigured to recognize the following entities:

Mapping of entity type to the Supply Chain Intelligence Suite data platform data model

Entity type	Supply Chain Intelligence Suite data platform object	Supply Chain Intelligence Suite data platform attribute
`category_name`	Catalog	`code`
`location_locationIdentifier`	Location	`locationIdentifier`
`location_name`	Location	`locationName`
`location_group`	Location	`locationGroupName`
`product_name`	Product	`name`
`part_number`	Product	`partNumber`
`product_plannerCode`	Product	`plannerCode`
`organization_name`	Organization	`name`
`organization_identifier`	Organization	`organizationIdentifier`
`order_orderIdentifier`	Order	`orderIdentifier`

Methods

The recognize method analyzes natural language text as an input and returns a JSON object with recognized entities.

curl -X POST https://api.ibm.com/scassistant/bluerun/named-entities/na/recognize \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --header 'X-IBM-Client-Id: <put Client-Id here>' \
   --header 'Authorization: Bearer <put JWT here>' \
   -d '{"text": "show me inventory for category pharma"}'

The response is a JSON object that contains all the mentions of named entities that are found in the text:

{
  "category_name": {
    "value": "Pharma",
    "literal": "pharma",
    "confidence": 1,
    "location": [
      31,
      37
    ],
    "values": [
      "Pharma"
    ],
    "count": 1,
    "list": [
      {
        "value": "Pharma",
        "literal": "pharma",
        "confidence": 1,
        "location": [
          31,
          37
        ]
      }
    ]
  },
  "@category_name": "Pharma"
}

The key of a JSON object corresponds to an entity type (for example category_name or location_city) while the value is a JSON object itself and contains the following fields:

literal: The detected mention of an entity in the input text.
value: The normalized value of an entity (for example Pharma or San Francisco). This value can be used in the GraphQL queries to get the data.
location: The position of the entity in a sentence.
confidence: The numeric value in the range 0 - 1 to represent confidence level. The value 1 is 100% confident.
values: An array of strings that contain all the entity values.
count: The number of different entity values.
list: An array with all the entity mentions.

values, count, and list properties can be helpful when the input text includes multiple mentions of the same entity type. You can access all the mentioned values or ask follow-up questions in cases where you do not expect more than one value.

Integrating NER with Watson Assistant

You can use the /recognize API directly from your Watson Assistant skill. You need to configure a webhook within your skill to call this API. For more information about Watson Assistant webhooks, see Making a programmatic call from dialog.

Configuring the webhook

Log in to Watson Assistant.
Go to your dialog skill and click Options.

Set the webhook URL to the following recognize endpoint.

https://api.ibm.com/scassistant/bluerun/named-entities/na/recognize

Set the following headers.
Headers for webhook
Header name Header value
Authorization Use this value:
Bearer $integrations.chat.private.jwt
X-IBM®-Client-Id Your client ID.

Header name	Header value
Authorization	Use this value: `Bearer $integrations.chat.private.jwt`
X-IBM®-Client-Id	Your client ID.

Calling the webhook

Go to the dialog node that uses the NER service.
Click Customize.
Enable Callout to webhooks/ actions skill and select Call a webhook.
Under Then call to my webhook, provide the input text from the user.

Key Value

text "<? input.text ?>"
Under Return variable, you can put the result in a context variable such as sterling_entities.
After you call the webhook, under If assistant recognizes, you can use the context variable to check whether you have any entities. To conform with the response format described in the Implementing the skill interface section, use the conditional response feature of Watson Assistant to distinguish between a successful call to the NER API and failures, by adding an anything else condition. A webhook failure should return the INTERNAL_ERROR response status code.
When testing your dialog node with the Try it out option, you can go to the Manage Context tab to manually create the context variable from step 4 to store your JWT credentials to pass to the NER API. After the call returns, you can see the values that are returned by the webhook in the return variable value you defined in Step 5.

Key	Value
text	`"<? input.text ?>"`

Disambiguation

If there are two or more mentions of the same entity type in the input, you get more than one item in values and list arrays. For example, the sentence What's available in San Francisco and New York? is recognized as containing the following entities.

{
  "location_city": {
    "value": "San Francisco",
    "literal": "San Francisco",
    "confidence": 1,
    "location": [20, 33],
    "values": ["San Francisco", "New York"],
    "count": 2,
    "list": [
      {
        "value": "San Francisco",
        "literal": "San Francisco",
        "confidence": 1,
        "location": [20, 33]
      },
      {
        "value": "New York",
        "literal": "New York",
        "confidence": 1,
        "location": [38, 46]
      }
    ]
  },
  "@location_city": "San Francisco"
}

A suggested pattern for Sterling-connected assistants is to place the NER call in a dedicated dialog node that is run at the start of the dialog tree before other dialog processing. Values that are returned from the API call are then placed in a context variable. This ensures that all user inputs are presented to the Named Entity service for recognition, and avoids having to call the Named Entity API from multiple dialog nodes within the skill.