In Orbita, the term Taxonomy refers to the indexing of content into categories and subcategories. Use a taxonomy when you have content that has a hierarchical structure.
...
| Table of Contents | ||
|---|---|---|
|
An Orbita taxonomy is a hierarchical tree of information that refines topics from general to more and more specific items that relate to a topic.
For example, the hierarchy of a first-aid taxonomy could have the following topics and more.
...
The top-level lists a number of medical issues that require first-aid attention, such as Broken bone, Burns, Fever, and so on.
Each medical issue can have a list of sub-items, such as Symptoms, Treatment, and so on.
Symptoms may include items such as a stiff neck, rash, trouble breathing, and so on.
Treatments may include advice to drink fluids, take medicine, call your doctor.
| Info |
|---|
The lock icon indicates that the item is being edited by someone else. Once the person who is editing the item saves, the lock disappears. |
| Info |
|---|
Tip: Try designing your taxonomy on paper before creating it so that you can determine relationships among the kinds of information before you implement the taxonomy in the software. |
| Info |
|---|
A voice experience designer builds a taxonomy so that a developer can use it in Orbita Experience Designer to create a natural conversation. This document focuses on building a taxonomy, and not using it in development. |
Creating a taxonomy
Login to Experience Manager.
Select a project.
Select Agents > Taxonomy from the side menu.
Click Add (+) to create a new taxonomy.
Enter the following information and click Add.
Title. Enter a name for the taxonomy.
Description. Enter the purpose of the taxonomy.
Enable Auto Generate Slots to create the slots for this taxonomy automatically. Orbita generates an ID automatically for any new Taxonomy Tree.
The taxonomy has the following views:
Tree View. The tree view will display a structured interface of your Taxonomy. Content is organized as a tree. Where each branch is a different topic. The Category of a branch is the top-level item in the branch. All items beneath the Category item are sub-category items.
JSON View. The underlying JSON code for the taxonomy tree is present in the JSON View. You can copy the taxonomy tree from one instance to another using the JSON code. If you are familiar with JSON then you can even tweak the JSON code to rearrange the topics.
...
Initially, the top-level node is called Home. You can change this by clicking Edit. The Taxonomy Tree dialog box appears. (See the following section.)
Editing the Home category
Every taxonomy has a Home category that anchors the taxonomy hierarchy.
Click Home to access options such as Delete, Edit, Create.
Click Edit.
In the Edit Dialog box, enter Title, Match Phrases, and content in the Multi-modal content editor.
Title. Describes the node and creates the auto-generated navigation. The title is added as one of the match phrases in the database. Do not include the title in match phrases. Keep titles short and unique for each article. Titles are used in the auto-generated navigation.
Match Phrases. Optional. Lists additional phrases to search against.
Enter the exact words and phrases needed to access this taxonomy node.You do not need to use the plural form of the words.
Match phrases are used as slot values.
Separate match phrases with a comma.
See Best Practices (end of this document) for Tips on creating slots.
Note: Do not duplicate the match phrases in another topic or subtopic (even as a title name).
Partial Phrases. Optional. Same as match phrases, except that the partial phrases are not added as slot values. Separate partial phrases with a comma.
Enter words or phrases that do not need to be an exact match. For example, if you enter blister as a partial phrase, then blister, blisters, blistering each provides access to the taxonomy node. If you do not want blistering to be part of the access phrase, then specify blister and blisters in the Match Phrases field instead.Voice. Select this tab for audio responses.
SayText. Content for voice response. Enter content for the voice assistant to speak.
RePrompt. Optional. Usually blank, because you would use the taxonomy self-navigation as a re-prompt. However, you could organize your content into a summary with SayText, with additional information in RePrompt. Enter content for the voice assistant to speak when there is no response, or response was not understood.
Text. Select this tab for textual responses such as for an automatic chatbot.
Chat Text. Enter content for the chatbot or other text display.
Reprompt. Enter content to display when there is no response, or a response was not understood.
Screen. Select this tab for responses on a display device.
Short Title. Enter a short title to display on the screen.
Long Title. Enter a long title to display on the screen.
Body. Enter the content of the taxonomy node for the screen display.
Image Small. Click Upload to open the Asset browser where you can select an image and click OK to upload it. The display device uses either the a small or large image, depending on its capability.
Image Large. Click Upload to open the Asset browser where you can select an image and click OK to upload it.
Note: You can use images that are in the Asset browser only. To upload an image from your local system to the Asset browserBrowser, click Browse. After the image is added, you can select it and click OK.
Button. Select this tab to define push-button responses. Use this for chatbots. (See image below.)
Value. Enter the value of the button.
Text. Enter the text you want to appear on the button.
Attributes. Use this field to make a notation about the taxonomy node. For example, perhaps you made an agreement with your developer to publish a taxonomy node based on whether you enter the word “Approved” into the Attributes field. Or, if you wanted multiple approvers, you can use a comma-separated list such as “approver 1, approver 2”. There may be other uses that you can discuss with your developer.
Click Save to save the edits. After saving it, the system creates and assigns an Id to this category.
You can start creating your own taxonomy by clicking Add (+) to add a category under Home.
Fill in the Title, Match Phrases, and the content in the Multi-modal content editor, then click Save.
Example: Tree view of a taxonomy.
For more information see, https://orbita.zendesk.com/hc/en-us/articles/360002956771-How-do-I-create-a-taxonomy-
Using the Taxonomy node in Experience Designer
The Taxonomy node lets you use the taxonomy tree in Experience Manager with the flows in Experience Designer. There are three actions to choose from:
Get action
Get action is used to retrieve Taxonomy data from the database. Taxonomy Node inputs leverage the mustache {{tag}} template language, which is applied to the node input either reference from msg.payload or msg
Taxonomy Id
The ID of the taxonomy tree should be given here. You can give an ID manually or can populate it dynamically populate the field using mustache tag.
For example: {{msg.payload.voiceMenuId}}
Category Phrase
You can manually fill this field or make use of a mustache tag. The node searches the first-level categories in the taxonomy tree for a match. If found, it selects that taxonomy branch.
For example, if the Category Phrase is Poison, the category is saved in a voice session so when you search for treatment or symptoms, it remembers to search only the Poison branch. If nothing is found, it searches the rest of the taxonomy for a match.
Example Mustache Tag: {{msg.payload.request.intent.slots.category.value}}
Note: The category used in the mustache tag should be the same as the slot name used in the utterances in the topic intent.
For example, the auto generated slot name for the taxonomy topics is First_Aid_Topics. The alternate slot name created to use within the intent is category, which is used in all the utterances. The same slot name (ie. category) is passed in the mustache tag in the Taxonomy node.
Session Management for Category - If a Category is found, the Taxonomy node stores the Category in the session and uses it in the next query if a category is not passed to it.
SubCategory Phrase
You can manually fill this field or make use of a mustache tag. The node Searches within the taxonomy branch mentioned in the “Category Phrase” field.
Example Mustache Tag: {{msg.payload.request.intent.slots.subCategory.value}}
Note: The subCategory used in the mustache tag should be the same as the slot name used in the utterances in the subtopic intent.
For example, the auto-generated slot name for this taxonomy subtopics is First_Aid_Subtopics. The alternate slot name created to use within the intent is subCategory, which is used in all the utterances. The same slot name (ie. subCategory) is passed in the mustache tag in SubCategory Phrase field of the Taxonomy node.
WhatAskStart
The text provided in the “WhatAskStart” can be accessed with the properties “whatYouCanAskParentChild” and “whatYouCanAsk”.
The default value of the field is,
| Code Block |
|---|
for other article{{plural}} on {{Category}}, you can say <break time="400ms"/> |
WhatAskLoop
This field is used for speech synthesis of the branch titles that are suggested in “WhatAskStart” field.
The default value of the field is,
| Code Block |
|---|
<prosody volume="x-loud"> {{FirstMatchPhrase}} </prosody><break time="500ms"/> |
Given below is the sample output payload, we used in Example flow 1:
WhatAskStart – For more info on {{Category}}, you can say
WhatAskLoop – <amazon:effect name="whispered"> {{FirstMatchPhrase}} </amazon:effect> <break time='1000ms'/>
In the output payload,
“whatYouCanAskParentChild” – This property value contains the immediate subtopics under the branch queried for.
| Code Block |
|---|
Msg.payload.orbita.taxonomy.whatYouCanAsk |
“whatYouCanAsk” – This property value contains all the child topics under the topic queried for.
| Code Block |
|---|
Msg.payload.orbita.taxonomy.whatYouCanAskParentChild |
Either of these parameters can be used in the say node as shown in the below screenshot to suggest the subtopics to the user.
Multi Category
This message will be sent to the output pin if multiple categories are found.
The default message is,
| Code Block |
|---|
There are {{length}}, main topics found, for <break time='300ms'/> {{Category}}, you can say <break time='500ms'/> |
Multi Sub Category
This message will be sent to the output pin if multiple subcategories are found.
The default message is,
| Code Block |
|---|
There are {{length}}, sub topics found, for <break time='300ms'/> {{subCategory}}, you can say <break time='500ms'/> |
Replace Words
A comma-delimited list of words to replace.
For example: "sympton:symptom,original:substitute"
Note: The language processors sometimes generate misspelled words, or words not in your context, such as byte versus bite, joking versus choking
Create Action
Using the Create action, you can create taxonomy categories or subcategories using the Taxonomy node.
Taxonomy. Select a Taxonomy Tree that you created in Experience Manager.
Payload. JSON code of the categories or subcategories you want to create in the Taxonomy Tree.
Sample code:
| Code Block |
|---|
{
"data" : {
"allowJump" : true,
"voice" : {
"sayText" : "",
"rePrompt" : ""
},
"chat" : {
"chatText" : "",
"rePrompt" : ""
},
"screen" : {
"shortTitle" : "",
"longTitle" : "",
"body" : "",
"smallImage" : "",
"largeImage" : ""
},
"buttons" : {
"type" : "dropdown",
"name" : "buttons",
"choices" : []
},
"title" : "foods",
"SayText" : "",
"RePrompt" : "",
"parentId" : 858870919717
}
} |
Note: If a valid parentId is not given then, by default, it updates the Root node.
Upsert Action
Using Upsert action, you can update any existing taxonomy categories or subcategories. If no entries are found, the system will insert the queried values into the database.
Taxonomy. Select a taxonomy tree that you created in Experience Manager.
Payload. JSON code of the categories or subcategories you want to create or upsert in the taxonomy tree.
Note: Upsert action searches the records and if nothing is found, it creates a new one.
Sample Payload format:
| Code Block |
|---|
{
"data" : {
"allowJump" : true,
"voice" : {
"sayText" : "Taxonomy level one",
"rePrompt" : "Taxonomy level one"
},
"chat" : {
"chatText" : "Taxonomy level one",
"rePrompt" : "Taxonomy level one"
},
"screen" : {
"shortTitle" : "",
"longTitle" : "",
"body" : "",
"smallImage" : "",
"largeImage" : ""
},
"buttons" : {
"type" : "dropdown",
"name" : "buttons",
"choices" : []
},
"title" : "Taxonomy level one",
"SayText" : "",
"RePrompt" : "",
"parentId" : 349932564080
}
} |
Note: If a valid parentId is not given then, by default, it updates the Root node.
Output Payload
SayText
| Code Block |
|---|
msg.payload.orbita.taxonomy.SayText |
Reprompt
| Code Block |
|---|
msg.payload.orbita.taxonomy.RePrompt |
...
If there is more than one result, the following payload contains the concatenated result.
| Code Block |
|---|
msg.payload.orbita.taxonomy.concatenateResults |
...
Ideally, there is only one array of results. If more than one document had the same weighted results then there will be multiple arrays of results.
| Code Block |
|---|
msg.payload.orbita.taxonomy.maxArrayResults |
...
The value of this payload will be true if the category was found.
| Code Block |
|---|
msg.payload.orbita.taxonomy.foundBranch |
...
The weight of the match; if 0, no match found.
| Code Block |
|---|
msg.payload.orbita.taxonomy.maxValue |
...
If true, a category was used to narrow the search.
| Code Block |
|---|
msg.payload.orbita.taxonomy.foundBranch |
...
The following payload returns the current taxonomy Id, such as 591f5792e2386b8516977df1.
| Code Block |
|---|
msg.payload.orbita.taxonomy.TaxonomyId |
...
The following payload returns the words used to search Subcategory.
| Code Block |
|---|
msg.payload.orbita.taxonomy.SubCategoryList |
...
The following payload returns the words used to search Category.
| Code Block |
|---|
msg.payload.orbita.taxonomy.category |
...
The following payload returns a list of all the titles under the selected branch.
| Code Block |
|---|
msg.payload.orbita.taxonomy.Taxonomy.BranchTitles |
...
The maxArrayResults will display an array of results found. Ideally, the .length property of this array should be 1.
| Code Block |
|---|
msg.payload.orbita.taxonomy.maxArrayResults |
...
All the information about this node, which branch it belongs to, what are the child branches, how many child branches it has are displayed in the following payload.
| Code Block |
|---|
msg.payload.orbita.taxonomy.nodeInformation |
...
The following payload contains the information of the parent node without the children.
| Code Block |
|---|
msg.payload.orbita.taxonomy.nodeInformation.parentData |
...
The following payload contains the information of the parent node including the children.
| Code Block |
|---|
msg.payload.orbita.taxonomy.nodeInformation.nodeData |
...
The following payload returns the node’s category.
| Code Block |
|---|
msg.payload.orbita.taxonomy.nodeInformation.nodeCategory |
...
The titles of the parent node and children nodes related to the node that is found, but not sub-children.
| Code Block |
|---|
msg.payload.orbita.taxonomy.nodeInformation.ParentChildTitles |
...
The following payload contains all the subcategory phrases in the Taxonomy. You should copy this to the "developer.amazon" custom slot SubCategoryList.
| Code Block |
|---|
msg.payload.orbita.taxonomy.SubCategoryList |
...
The following payload returns all the titles in the first level of the taxonomy.
| Code Block |
|---|
msg.payload.orbita.taxonomy.rootTitles |
...
The following payload returns all the categories in the taxonomy. You should copy this to the category slot.
| Code Block |
|---|
msg.payload.orbita.taxonomy.CategoryList |
...
This is formatted content such as for other articles on hypothermia. You can say treatment, symptoms, or more information.
| Code Block |
|---|
msg.payload.orbita.taxonomy.whatYouCanAsk |
This is formatted content; a limited list of navigation items to just the child nodes, (but not sub-child nodes) and parent (if it is not home). Example: for other articles on hypothermia, you can say treatment, symptoms, or more information.
...
Reorder your taxonomy tree
| Note |
|---|
Warning: Do not attempt this if you are not familiar with the JSON code. Also, make a copy of the code before proceeding. |
The JSON tab exposes the code behind the Taxonomy Tree user interface. You can edit the code, bypassing the user interface, and rearrange the taxonomy tree by cutting, pasting, and moving code.
Best Practices
Defining the slots
When creating the match phrases in the taxonomy, create utterances with multiple slots.
prefix. help with, tell me about, what is …
who. me, my daughter, my wife …
auxVerb. have, has, get…
category. This comes from the title and the match phrases of the root level taxonomy nodes. They generated automatically when you enable the Auto Generate Slots checkbox when creating a taxonomy.
Category and subcategory intents
Examples of category and subcategory intents that can be created are shown below.
...
{who} {auxVerb} {subCategory}
Creating phrases
The following examples show how to create phrases.
What are treatments for hypothermia. Treatments is the subcategory and hypothermia is the category.
What are symptoms for hypothermia.Symptoms is the subcategory and hypothermia is the category.
Hypothermia treatments
Hypothermia
Treatments. Treatments is the subcategory – it will use the last category from the session, i.e. hypothermia.
Symptoms
Treatments for hypothermia. You would include this phrase for a match phrase in treatment.
Using multi-slot utterances
You need the prefix and post slots to have Alexa and Google recognize the intent. An exact match to a phrase to what someone says generates a large weight for selecting the article.
For example, when a person says Poison for a category, only the word Poison is searched for in the taxonomy branch. The voice assistant responds with an overview of Poison and provides navigation to other articles. If the person then says, "my daughter swallowed a small battery”, then the match words swallowed, and battery provides an article about swallowed poison because it matched on two of the match phrases.
Example flows in Experience Designer
In this section, there are two example flows to get you started with using the Taxonomy node in the Experience Designer. Also, find the attachment to get the JSON code of the two flows.
Example Flow 1
The following image shows the sample flow in Experience Designer. The JSON code of the flow is attached to this document.
Slot Values and intents
If you enabled Auto Generate Slots when creating the taxonomy tree, then the topics and subtopics slots are created in the database automatically. The auto-generated slots are named Taxonomy_tree_name_Topic and Taxonomy_tree_name_Subtopic.
In this example, the taxonomy name is Test Info. The slots named Test_Info_Topic and Test_Info_Subtopic are auto-generated which can be used in the intents.
Example flow 2
Upon request, the following flow is used to list all the topics from the taxonomy tree. The JSON code of the flow is attached to this document.Also see, Taxonomy node document
Related Articles
| Filter by label (Content by label) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|