Load Taxonomy

UiPath.IntelligentOCR.Activities.TaxonomyManagement.LoadTaxonomy

Turns the taxonomy.json file created with the help of the Taxonomy Manager into a variable that can be further used with other activities.

Properties

Common

• DisplayName - The display name of the activity.

Misc

• Private - If selected, the values of variables and arguments are no longer logged at Verbose level.

Output

• Taxonomy - The taxonomy you want to load, stored in a DocumentTaxonomy variable. This output can be later used in activities that receive a taxonomy as input.
  Important: In case you use an Intel Xe GPU and Taxonomy Manager is not displayed properly, we recommend updating the graphics driver to the latest version. For more information, please visit this page.

Taxonomy Extension Methods

• Serialize(): Called on a DocumentTaxonomy object, the Serialize() method returns a JSON representation of the object, so that it can be stored and retrieved for later usage.
• Deserialize(String): The DocumentTaxonomy.Deserialize(jsonString) static extension returns a DocumentTaxonomy object, hydrated with the JSON encoded data passed as a parameter.
• GetFields(String): Called on a DocumentTaxonomy object, the GetFields() method called with a DocumentTypeId string returns a list of fields defined within that document type.

The Taxonomy Manager can be used to create and edit a Taxonomy file specific to your current automation project. This Taxonomy file contains user-defined document types, organized in Groups and Categories.

You can further use the Taxonomy file by converting it into a .NET data type with the Load Taxonomy activity, and then passing it as input for activities such as:

• Classify Document Scope
• Train Classifiers Scope
• Train Extractors Scope
• Present Validation Station

The Taxonomy Manager can be accessed only after installing a UiPath.IntelligentOCR.Activities package higher or equal to v1.6.0 as a dependency for your project. Once the package is installed, a Taxonomy Manager button appears on the Ribbon, in the Wizards section.

Figure 1. Overview of the Taxonomy Manager in the Studio ribbon

Using Taxonomy Manager

The Taxonomy Manager window lets you create document types, organized by groups and categories. When opened for the first time in a project, no groups, categories, or document types are defined.

Figure 2. The Taxonomy Manager before mapping any document types or fields

Establishing the structure

The first step is to create a group or a document type. The difference between the two of them is that a group involves a hierarchical structure while a document type can be created as a single file. A complex project implies creating groups, categories, and document types, while a simple project can only require one or two document types.

Creating a Group

When a group is created, a category is also necessary for the document type you want to create inside the group. This is done by using the Group button. Once you have chosen a name for your group, you can save it by using the Save button or by using the Enter key.

Creating a Category

Once a group is defined and selected, you can create a Category and/or a Document Type within the group, by using their defined buttons. Select Save or use the Enter key to save the configuration.

Creating a Document Type

A Document Type can be created either by part of a group or as a single document. When created inside a group, make sure that the group is selected, then select Document Type.

If the Document Type is created as a single file, then make sure that no group is selected and select Document Type. After selecting Document Type, input a name for the file and select Save.

Note: When a Document Understanding Action is submitted from Orchestrator while using Studio version 2020.10, make sure that the taxonomy has no document types created without category.

Selecting an already created Document Type lets you change its name, copy its unique ID to clipboard, reassign it to another group or category, or none of them. You can also input a code for the document type.

Once a document type is saved, a Document Type ID is generated for it. Opening the document for editing displays the ID next to the Document Type Name tab. The Document Type ID has a structure of the type Group.Category.Document and can be copied to the clipboard. The Document Type ID code is an optional functionality and it can be used to find your documents or map your documents to the Document Types that you define in the taxonomy.

Creating Fields

When the Document Type is selected, the Field button becomes available for you to create a new field. Once the Field button is selected, you can enter a name for it and select its type from the dropdown list.

The Field category has two tabs: Details and Rules. The Details tab provides information about the selected field, such as Field Name, assigned hotkey, or field type, while the Rules tab allows you to create rules that need to be fulfilled by the extraction result for the field.

The available field types are the following:

• Text
• Number
• Date - Choosing this type also lets you specify an expected format, which is optional.
  Note:

  If you want to add an expected format, use a format compliant to MSDN (MicroSoft Developer Network).

  This format may be used by extractors and is used by the Data Extraction Scope activity when trying to parse a Date into its constituent Day, Month, and Year parts.

• Name
• Address
• Set - Choosing this type lets you add multiple values to the field from a pre-established list.
• Boolean
• Table - Choosing this type lets you edit the structure of the table, as you can add columns and edit their name and type.

Details Tab

After the new Field is created, select it to view more information. By default, when you open a field, the Details tab is displayed allowing you to modify the name, color, or hotkey of the field. You can also specify whether it is multi-value (Is multi-value) or if it allows for values with no evidence in the document to be processed (Requires reference). The multi-value option allows for a field to have multiple values, without being restricted to a specific list.

For more information on how to use the two fields, check the following descriptions:

• Is Multi-Value: If a field is set as multi-value, you can have more than one value reported for that particular field. For example, you want to extract a "List of Directors" where you can have variable number of entries. Imagine a multi-value field like a single-column table.
• Requires reference: When a field requires reference, you can add a value to it only if you select something from the document you see in Validation Station. For special fields in which you want to capture values that are maybe not visible in the document, you can switch Requires Reference to Off. Effect will be that user can add a value without specifying a place in the document where that values comes from.

You can also select the Type of the field from the dropdown list, or add a Default value. Use the Default value field to define values to be populated in the Extraction Result, in case there is no value for the field identified in the document.

Figure 3. Overview of the Details tab of a field

You can choose to enable Validator notes from the Details tab. By setting up validator notes, human validator can add notes about the decision they have taken during validation. You can configure the following settings:

• Read-only: If enabled, the human validator can view any validator notes set on the ExtractionResult field in Validation Station, as a message. If disabled (default state), the human validator can also edit that note in Validation Station and thus communicate back to the robot information about the decision taken.
• Text: If Text is selected, the validator note is displayed as a text message (or editable text when editing is enabled) in Validation Station. The human validator can view, edit, or add a maximum of 200 characters message in Validation Station.
• Options: If you select Options, you can configure a series of radio buttons that the human validator can view and, if not read-only, select in Validation Station. You can add a maximum of 10 options.

Tip: Check the ExtractionResult Class page from the UiPath.DocumentProcessing.Contracts section for more information on the two methods related to validator notes, GetFieldValidatorNotes(<fieldId>) and SetFieldValidatorNotes(<fieldId>, <validatorNote>).

Created fields can be deleted by using the delete button that appears next to them or reordered by using the drag and drop function.

A field can also be deleted from the Details window, by selecting Delete.

Retracing these steps, you can create multiple groups, categories, and document types, which you can then filter by using the Search field.

Rules Tab

Field rules help you optimize the extraction results and to automatically validate them when the running your workflow. Their role is to increase the extraction efficiency and to help you easily validate the fields that need attention in Validation Station, by highlighting them. You can create multiple rules that apply to one field.

You define a rule by setting the Evaluator type and the Criticality level.

Evaluator Type

Use the Evaluator Type to specify how the defined rules should be evaluated. There are two evaluator types that you can choose from: AND, OR.

Table 1. Table showing Evaluator types, their descriptions, and examples for them

Evaluator Type	Description	Example
AND	Use this evaluator type when all the rules need to be executed.	Rule : Invoice Number starts with A And ends with X. Valid Result : The valid field value is A123X. Invalid Result : The valid field value is A123.
OR	Only one of the rules needs to be executed.	Rule : Invoice number starts with A OR is 123. Valid Result : The valid field value is A123, 123. Invalid Result : The valid field value is 234, 1A23.

Criticality Level

Indicates the criticality of all rules defined for a field. You cannot set a MUST level if the rule is broken in the Validation Station session. There are two criticality levels that you can choose from: MUST, SHOULD.

The created rule is triggered once the set criticality level is identified.

When you want to submit a rule, a MUST rule requires 100% success, otherwise the Submit operation fails. A SHOULD rule allows you to Submit it even if the rule is broken.

You can always check if a rule is broken by using the helper method from the ExtractionResult Class class, that resides in the UiPath.DocumentProcessing.Contracts activity package.

Table 2. Table displaying Criticality levels and their descriptions

	Description
MUST	Use this criticality level when the created rule is imperative to be included in the Extraction Result process.
SHOULD	Use this criticality level when the created rule is optional.

Once you have selected the Evaluator Type and the Criticality Level, you must set a type applicable for your newly created rule. There are several options you can choose from. Here's a complete list with all the available ones:

• Is not empty
• Possible values
• Starts with
• Ends with
• Contains
• Fixed length
• Is email
• RegEx
  Note: The field type for which you created a rule dictates the number of possible rule types from which you can select one. For example, a field of type Text displays all the possible rule types, while a field of type Date displays only two rule types, Is not empty and Possible values.

Type of Rules

The following table shows details for each available rule type, classified depending on the criticality level and evaluator type.

Table 3. Rule types and their descriptions, depending on the criticality level and evaluator type

	Description	Field type	Criticality level	Evaluator Type
Is not empty	The extracted value cannot be empty, meaning that the field is mandatory. If the value is missing, it requires validation/manual input.	Applicable to fields of the following types: number text date address name set boolean	MUST SHOULD	AND OR
Possible values	User defines all possible values and the extracted data is one of the values added as input while creating the rule (for example, Employer Type is either "full-time", "part-time", or "internship").	Applicable to fields of the following types: number text date	MUST SHOULD	AND OR
Expression	Define mathematical expressions that act as a rule for extracting data.	Applicable to fields of type number. A condition is required while configuring the rule. Choose one of the following options: Is equal to Is not equal to Is greater than Is greater than or equal to Is less than or equal to A mathematical expression is required. Use the predefined operators to define your expression. Check the following examples: Sum Quantity * Net unit price\n- Total = Subtotal + Delivery Discount - the Sum operator gathers all values from a table's column.	MUST SHOULD	AND OR
Starts with	This is a fixed rule meaning that the extracted value needs to start with one of the values added by the user.	Applicable to fields of the following types: text address name	MUST SHOULD	AND OR
Ends with	This is a fixed rule meaning that the extracted value needs to end with one of the values added by the user.	Applicable to fields of the following types: text address name	MUST SHOULD	AND OR
Contains	This is a fixed rule meaning that the extracted value needs to contain one of the values added by the user.	Applicable to fields of the following types: text address name	MUST SHOULD	AND OR
Fixed length	This is a fixed rule meaning that the extracted value needs to have a certain fixed length.	Applicable to fields of the following types: text address name	MUST SHOULD	AND OR
Is email	This is a fixed rule meaning that the extracted value needs to be written in an email format.	Applicable to fields of the following types: text address name	MUST SHOULD	AND OR
RegEx	This is a fixed rule meaning that the extracted value needs to contain a regular expression similar to one of the values added by the user.	Applicable to fields of the following types: text address name	MUST SHOULD	AND OR

Using Rules

Let's take a practical example to better understand the applicability of these rules. We will create a set of rules for the Address field of document. Check the following example steps to learn how you can create a new rule or a set of rules for a field:

1. Select a field in the Taxonomy panel.
2. Go to the Rules tab.
3. Select Add new, to add a new rule.
4. Type in the full address rule, for which the Type is Contains, and the Expression is st, str, street.
5. Choose the Evaluator type.

   In this example, select OR.

6. Choose the Criticality level.

   In this example, select MUST.

7. Select Add new.
8. Type in the phone number rule, for which the Type is Is not empty.
9. Select Add new.
10. Type in the city or state rule, for which the Type is Contains, and the Expression is city, state.

The following animated image shows the steps previously described.

Figure 4. Animated image displaying how to add three rules for a field

Other Options

Editing

You can Edit the name of any group, category, or document type that you have created. This can be done by selecting one of the three levels of configuration and editing the Name field.

Deleting

Groups, categories, and document types can also be deleted. There are two available options:

• Select Delete , at the parent element of the object you want to delete.
• Select Delete while selecting the object you want to delete.

In both cases, a pop-up is displayed asking you to confirm the deleting action. Select Delete to approve the action.

Customization and Accessibility

A hotkey and color are automatically allocated to the newly created field. You can use them for better visibility and faster navigation through your taxonomy. Customize them by clicking on the hotkey or the color code field.

A customized field with color and hotkey can instruct the Validation Station and the Template Manager to use the assigned color when displaying the field and to use the assigned hotkey as a shortcut for providing values to fields. Visit Validation Station for more information about how to use the field shortcuts to assign values to a field.

To assign a color and a hotkey for a field, select the field, and choose a certain color code in the Color field, and then select a specific hotkey from the Hotkey menu.

Navigate through the Taxonomy Manager by using the keyboard shortcuts. Select Show available keyboard shortcuts and activate the Toggle keyboard shortcuts option to avoid the accidental triggering of the keyboard shortcuts. Nodes can also be collapsed.

Note: The changes you make in the Taxonomy Manager are automatically saved into the taxonomy.json file specific to your project.