# Managing the taxonomy

> Manage the field groups, fields, field types, and instructions that define the data an Extract node captures from documents in UiPath Maestro™ Flow.

## Overview of prompt instructions

Prompt instructions are natural-language descriptions that give the model the context it needs to extract the right values from your documents. You can add instructions at several levels of the taxonomy:
   * for the entire taxonomy
   * for each field group
   * for each field
   * for each field type, where the instructions are shared by all fields that use that field type.

**Overall extraction instructions** - Provide context to the model that is relevant across the taxonomy, including details on the overall extraction task and the documents in the project.

**Instructions** - Provide context for the model on how to successfully extract data from the document. Iterating on instructions helps to improve predictions.

## Managing the overall prompt instructions

To add prompt instructions for the entire taxonomy, proceed as follows:

1. Hover over the Flow **Extract** node, and select **Open full view**, which will open the **Definition** tab.
2. Under the **Definition** tab, go to the **Taxonomy** section.
3. Expand **Overall extraction instructions** and add your instructions.

:::note
Node-level instructions can include a description of the industry or document type, or document-specific considerations, such as multiple occurrences of the document within one file.
:::

## Managing field groups

Manage field groups directly from the **Taxonomy** tab. This allows you to create, edit, move, or delete multiple items before saving your edits. All changes are applied at once when you save them and are saved as a single project version update, instead of generating a new version for each individual change.

### Creating and configuring field groups

To create and configure field groups, proceed as follows:

1. Hover over the Flow **Extract** node, and select **Open full view**, which will open the **Definition** tab.
2. Under the **Definition** tab, navigate to the **Taxonomy** tab.
3. Configure the following fields:
   * **Name** - The name of the field group. Field groups also show the number of fields they contain.
   * **Instructions** - The instructions for the field group. You can hide the **Instructions** column from the **Columns** filter, and select **Reset** to restore the initial view.
   * **Type** - How often the model extracts the field group. Select one of the following:
     * **Single instance** - Extracted once per document.
     * **Multiple instance** - Extracted once for every occurrence.

   To reorder rows, use the drag handle at the start of the row.
4. Select the **+ Field group** button to add more field groups, if needed.

   ![The Taxonomy tab of the Definition tab, with the Field group button highlighted.](https://dev-assets.cms.uipath.com/assets/images/ixp/ixp-flow-definition-tab-add-field-group-fced09ed.webp)

5. Select **Save**.

To define a hierarchy between field groups, create a parent field group and then add one or more child field groups within it. This structure establishes the relationship between them, which means that if no predictions are returned for the parent field group, the child field groups will also return no predictions. The parent field group effectively serves as the primary classification, with its children providing additional levels of detail.

:::note
The instructions for a parent field group do not influence a child field group.
:::

#### Example of field groups and their hierarchies

The following example shows field groups and their hierarchies:

* Invoice
  + Invoice Number
* Invoice > Line Items
  + Unit Price
  + Quantity
  + Line Amount

:::note
If the model cannot find any Invoice field group in a document, that is, the document is not an invoice, no Invoice > Line Items is returned.
:::

### Editing field groups

To edit field groups, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Select the name of your field group or instructions.
3. Make your modifications.
4. Select **Save**.

### Viewing the change history of a field group

To view the change history of a field group, proceed as follows:

1. On the **Taxonomy** tab, select the ellipsis for a field group.
2. Select **View change history**.

**Result:** The **Change history** window opens. It lists the versions of the field group, with the field group name and instruction of the selected version. For details on comparing and restoring versions, check [Viewing the change history](#viewing-the-change-history).

### Copying field definitions

You can copy all field definitions of a field group and paste them into one or more other field groups.

To copy field definitions, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Hover over the field group row whose fields you want to copy, and select the ellipsis.
3. Select **Copy all field definitions**. A checkbox appears next to each field group, and a bar with the message **Select field groups to paste the copied field** appears.
4. Select the checkbox of each field group where you want to paste the fields.
5. Select **Paste**. To cancel the copy, select **Exit** instead.
6. Select **Save**.

**Result:** The copied fields are added to the selected field groups.

### Moving field groups

You can move a field group under another field group, or move a child field group back to the top level.

To move a field group, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Hover over the field group row, and select the ellipsis.
3. Select **Move**. The **Move field group** window opens and shows the current parent of the field group.
4. From the **Select new parent** dropdown list, select the new parent field group. To move the field group to the top level, select **None**.
5. Select **Move field group**.
6. Select **Save**.

**Result:** The field group appears under its new parent.

:::note
The greater-than sign > is used to define the field group hierarchy. This sign establishes a relationship between the parent field group and the child field group.
:::

### Deleting field groups

To delete a field group, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Hover over the field group row, and select the ellipsis.
3. Select **Delete**. The **Delete field group?** window opens. Deleting a field group also removes all of its fields.
4. Select **Acknowledge**. The field group is displayed with a strikethrough until you save your changes.
5. Select **Save**.

**Result:** The field group and its fields are removed from the taxonomy.

:::warning
Deleting a field group results in the loss of its annotations. This action can only be undone by reverting to a previously deployed model version. Deploy the latest model version before making significant changes.
:::

## Managing fields

Manage fields directly from the **Taxonomy** tab. Create, edit, or delete multiple fields before saving, and all changes are applied at once when you save them.

### Creating and configuring fields

To create and configure fields, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Under the field group where you want to add the field, select **+ New field**.
3. Configure the following fields:
   * **Name** - The name of the field. Give your field a name that accurately describes the data it represents.
   * **Instructions** - The instructions for the field. Give your field a relevant and detailed description to provide the necessary context for extraction.
   * **Type** - The field type. Select one of the following pre-configured field types:
     * **Date** - Calendar date only, no time. For example, `2023-02-21`.
     * **Exact Text** - Appears verbatim in the document.
     * **Inferred Text** - May be derived rather than quoted.
     * **Monetary Quantity** - Amount with ISO currency code. For example, `12.11 USD`.
     * **Number** - Decimal number. For example, `1250.50`.
     * **Boolean** - For example, `true` or `false`.

     To create a custom field type, select **New field type** at the bottom of the dropdown list. The **Field types** tab opens with a new field type row, and the field uses the new field type. For details, refer to the **Creating and configuring field types** section of **Managing field types**.

     :::note
     * You can reuse field types across different fields, which allows you to share the instructions.
     * You can change the field type once the field is created. Changing to a type with an incompatible data type affects existing annotations. For details, refer to the **Editing fields** section.
     * Text field type can have input values that are present in the document and extracted as-is (**Exact Text**), or can be inferred from the document, if it is not explicitly stated in the text (**Inferred Text**).
     :::
4. Select **+ New field** to add more fields, if needed.
5. Select **Save**.

You can change the type of a field later. For the effect on existing annotations, refer to the **Editing fields** section.

To reorder fields within a field group, use the drag handle at the start of the row.

### Editing fields

To edit fields, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Select the name, instructions, or type of your field.
3. Make your modifications.
4. Select **Save**.

:::warning
Annotations cannot be remapped to an incompatible data type. If you change the type of a field to a type with an incompatible data type, the existing annotations of the field are no longer valid, and you must review and correct them. For example, changing an **Exact Text** field to **Date** keeps the annotated values but marks them as invalid, and changing it to a **Choice** field type clears the annotated values. Changing between compatible types, such as **Exact Text** and **Inferred Text**, keeps the annotations.
:::

### Viewing the change history of a field

To view the change history of a field, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Hover over the field row, and select the ellipsis.
3. Select **View change history**.

**Result:** The **Change history** window opens. It lists the versions of the field, with the field name, field type, and instruction of the selected version. For details on comparing and restoring versions, check [Viewing the change history](#viewing-the-change-history).

### Copying a field definition

You can copy a field definition and paste it into one or more field groups.

To copy a field definition, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Hover over the field row whose definition you want to copy, and select the ellipsis.
3. Select **Copy field definition**. A checkbox appears next to each field group, and a bar with the message **Select field groups to paste the copied field** appears.
4. Select the checkbox of each field group where you want to paste the field.
5. Select **Paste**. To cancel the copy, select **Exit** instead.
6. Select **Save**.

**Result:** The copied field is added to the selected field groups.

### Deleting fields

To delete a field, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** tab.
2. Hover over the field row, and select the ellipsis.
3. Select **Delete**. The **Delete field?** window opens. Deleting a field also removes its annotations.
4. Select **Acknowledge**. The field is displayed with a strikethrough until you save your changes. To restore the field before saving, select **Undo delete** at the end of the row.
5. Select **Save**.

**Result:** The field and its annotations are removed from the taxonomy.

Deleting a field does not delete the custom field type it uses. To delete the field type, refer to the **Deleting field types** section.

:::warning
Deleting a field results in the loss of its annotations. This action can only be undone by reverting to a previously deployed model version. Deploy the latest model version before making significant changes.
:::

## Managing field types

Field types let you share instructions across all the fields that use them. Manage field types directly from the **Field types** tab. Like fields and field groups, you can create, edit, or delete multiple field types before saving, and all changes are applied at once when you save them.

### Creating and configuring field types

To create and configure field types, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** section, and select the **Field types** tab.
2. Select **+ Field type**. A new row is added at the bottom of the table.
3. Configure the following fields:
   * **Name** - The name of the field type. The number next to the name shows how many fields use the field type.
   * **Instructions** - The shared instructions for all fields that use the field type.

     :::note
     You can reuse field types across different fields, which allows you to share the instructions.
     :::

   * **Type** - The data type of the field type. For more details, refer to [Available data types](#available-data-types).
   * **Configuration** - Additional settings for the data type. This setting is available only for the **Choice** data type. Select **Add configuration** to open the **Choices** panel, and then configure the following settings for each choice:
     * **Display value** - The value of the choice.
     * **Alternate values** - Comma-separated values that also map to this choice. For example, `USD, US Dollar`.

     Select **+ Add choice** to add a choice, the drag handle to reorder choices, and the delete icon to remove a choice.
4. Select **Save**.

You can also create a field type while you configure a field, by selecting **New field type** from the **Type** dropdown list of the field in the **Taxonomy** tab. The **Field types** tab opens with a new field type row, and the field uses the new field type.

#### Available data types

The following data types are available:

| Data type | Description |
|---|---|
| **Exact text** | Appears verbatim in the document. |
| **Inferred text** | May be derived rather than quoted. |
| **Choice** | Closed set; the value appears verbatim. |
| **Number** | Decimal number. For example, `1250.50`. |
| **Monetary quantity** | Amount with ISO currency code. For example, `12.11 USD`. |
| **Date** | Calendar date only, no time. For example, `2023-02-21`. |
| **Date and time** | Calendar date plus time of day. For example, `2023-02-21T14:05:00Z`. |
| **Time** | Time of day only, no date. For example, `14:05:00`. |
| **Duration** | A length of time, not a point in time. For example, `P30D` (30 days). |
| **Email** | For example, `invoices@acme.com`. |
| **Hostname** | For example, `acme.example.com`. |
| **IPv4 address** | For example, `192.0.2.10`. |
| **IPv6 address** | An IPv6 address. |
| **UUID** | For example, `2c01b272-7117-41f7-ca59-08ded70a0e12`. |
| **Boolean** | For example, `true` or `false`. |

### Editing field types

To edit field types, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** section.
2. Select the **Field types** tab.
3. Select the name, instructions, type, or configuration of your field type.
4. Make your modifications.
5. Select **Save**.

:::warning
Changing the data type of a field type affects all the fields that use it. Annotations cannot be remapped to an incompatible data type, so the existing annotations of those fields are no longer valid, and you must review and correct them. If you change a **Choice** data type to another data type, the configured choices are also removed.
:::

### Deleting field types

To delete a field type, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** section, and select the **Field types** tab.
2. Hover over the field type row, and select the delete icon at the end of the row. The **Delete field type** window opens.
3. Select **Delete**. The field type is displayed with a strikethrough until you save your changes. To restore the field type before saving, select **Undo delete** at the end of the row.
4. Select **Save**.

**Result:** The field type is removed from the taxonomy.

You can delete both custom and pre-configured field types. If fields use the field type that you delete, the **Delete field type** window lists those fields. From the **Replace with type** dropdown list, select the field type to assign to them. If you select **Don't replace**, the listed fields have no type, and you must select a new type for each of them in the **Taxonomy** tab before you can save your changes.

### Viewing the change history

To view the change history of a field or field group, proceed as follows:

1. In the **Definition** tab, navigate to the **Taxonomy** section.
2. On a field or field group, select the ellipsis, and then **View change history**. This displays the **Change history** window, which contains the following details:

* The list of versions. Each version shows its number, a **CURRENT** label for the current version, its score, the type of change, when the change happened, and the number of runs.
* The details of the selected version: the field name, field type, instruction, and the model configuration of that version.
* **Compare with current** - Enable this option to compare the selected version with the current version.
* **Restore all** and **Restore instruction** - These options restore the selected version.

![The Change history window for a field, with the version list and the restore options highlighted.](https://dev-assets.cms.uipath.com/assets/images/ixp/ixp-flow-definition-tab-field-change-history-70f65143.webp)

### Example of inferred and exact fields

#### Inferred fields

I work for the underwriting operations team at an insurance company, and we have hundreds of set policy categories, for example, automotive, home, health, luxury goods, and so on, that we offer to customers, each corresponding to a Type category, for example, Type A, B, C, and so on.

Based on the content of the document, I want to be able to extract and identify the Type category of the policy that needs to be processed.

In this example, there is nowhere in the message that explicitly states that this email pertains to Type E. In the instructions, context is provided for each insurance type to inform the predictions of the model. For example, claims related to luxury goods all belong to the Type E category.

Examples of fields that might need to be set up as Inferred:

* Values that are not present anywhere in a document, but are implied from its context
* Values that need to be concatenated across different areas in a document.
* Values that span across multiple paragraphs, lines, or columns.

#### Exact fields

To facilitate this request, I may need the existing policy number, name, and the value claimed. These are values that I know need to be explicitly stated in the document itself and extracted into a downstream process.

Figure 1. Example of inferred and exact fields

  ![The image shows an example of inferred and exact fields.](https://dev-assets.cms.uipath.com/assets/images/ixp/ixp-the-image-shows-an-example-of-inferred-and-exact-fields-565255-3084ad48.webp)