Maestro Orchestrate

maestro

latest

false

Maestro user guide

Extract

Extract structured fields from documents using IXP extraction models.

The Extract node pulls structured fields out of a document (an invoice, receipt, form, or contract) using a UiPath Intelligent eXtraction Platform (IXP) model, and returns the result for downstream nodes to act on. Use it when a step in your process needs typed data lifted out of an unstructured file.

Adding an Extract node

The Extract node runs an IXP model. You can use an existing IXP model or create a new one in-line, directly in the node.

To add the Extract node, proceed as follows:

In Maestro Flow, select Add node.
Select Document, then Extract.
Select one of the following options:
- Extract document - Creates a new node and, implicitly, a new model. You build and evaluate the model in the node.
- In this solution - Reuses the model of an existing Extract node from another flow of the same solution.
- Published - Uses a deployed IXP model, such as a model deployed from IXP Unstructured and Complex Documents or from the Extract node of another flow. Each model appears as an individual node.
  
  Note:
  The model must be deployed to a folder you can access.

For detailed steps on building, evaluating, and deploying models in the Extract node, refer to the IXP in Flow user guide:

Note:

The Extract node requires both the IXP and Document Understanding services to be enabled on your tenant, even if you only use IXP models. For more details on enabling services, refer to Enabling or disabling services.

How it works

Extraction models load dynamically from your organization, the same way connector nodes load from Integration Service. In the node palette, deployed models appear under Document processing → Extract, each as its own node. Adding one to the canvas creates an Extract node bound to that specific model.

When the node runs, Flow sends the document to the IXP model, the model digitizes and extracts it, and the structured result returns on the node's output. Extraction runs asynchronously: the node waits for the model to finish before continuing, so allow time for large documents.

Configuration

Configure the Extract node in the properties panel after adding it to the canvas.

Field	Required	Default	Description
Model	Yes	Selected model	Deployed IXP model to run. This is set when you add the node from the palette, and the model's folder and version bind automatically.
Document	Yes	None	File to extract from. Bind it to a file produced earlier in the flow, such as an attachment from a trigger or a prior node output.
Page range	No	Empty	Pages to extract from, for example `1-3`. Leave it empty to process the whole document.

Output

The Extract node returns its result at $vars.<nodeName>.output.

Variable	Description
`output`	Extraction result. Contains a single `ExtractionResult` object with document metadata, extracted fields, and per-field confidence scores. The shape is detailed in Reading the result.
`error`	Error details when the node fails. Contains `code`, `message`, `detail`, `category`, and `status`. Available when the node's error handle is connected.

Reading the result

The extraction result is a nested structure. Extracted fields live under ExtractionResult.ResultsDocument.Fields, and each field's value is in a Values array, not directly on the field:

$vars.<nodeName>.output = {
  ExtractionResult: {
    DocumentId: "<id>",
    ResultsVersion: 0,
    ResultsDocument: {
      DocumentTypeField: { Value: "Invoice", Confidence: 1.0, OcrConfidence: -1.0 },
      Fields: [
        {
          FieldId: "Test.Financial.Invoice.Total", // model-qualified id
          FieldName: "Total",                        // leaf label, use this for lookups
          FieldType: "Text",
          IsMissing: false,
          Values: [
            { Value: "12.57", Confidence: 0.604, OcrConfidence: 0.604, Components: [], Reference: {} }
          ]
        }
        // ...one entry per field in the model schema
      ]
    }
  }
}
$vars.<nodeName>.output = {
  ExtractionResult: {
    DocumentId: "<id>",
    ResultsVersion: 0,
    ResultsDocument: {
      DocumentTypeField: { Value: "Invoice", Confidence: 1.0, OcrConfidence: -1.0 },
      Fields: [
        {
          FieldId: "Test.Financial.Invoice.Total", // model-qualified id
          FieldName: "Total",                        // leaf label, use this for lookups
          FieldType: "Text",
          IsMissing: false,
          Values: [
            { Value: "12.57", Confidence: 0.604, OcrConfidence: 0.604, Components: [], Reference: {} }
          ]
        }
        // ...one entry per field in the model schema
      ]
    }
  }
}

To read a single field's value in a downstream Script node, reach ExtractionResult.ResultsDocument.Fields, find the field by its FieldName, and read Values[0].Value:

const value =
  $vars.extract1.output
    ?.ExtractionResult?.ResultsDocument?.Fields
    ?.find((f) => f.FieldName === "Total")
    ?.Values?.[0]?.Value;
const value =
  $vars.extract1.output
    ?.ExtractionResult?.ResultsDocument?.Fields
    ?.find((f) => f.FieldName === "Total")
    ?.Values?.[0]?.Value;

Because field names carry spaces and casing from the model schema (Invoice No., Vendor Name), a normalized lookup is more robust:

const fields = $vars.extract1.output?.ExtractionResult?.ResultsDocument?.Fields || [];
const norm = (s) => String(s || "").toLowerCase().replace(/\s+/g, "");
const get = (name) => {
  const f = fields.find((x) => norm(x.FieldName) === norm(name));
  return f && Array.isArray(f.Values) && f.Values[0] ? f.Values[0].Value : undefined;
};

const total = get("Total");
const vendor = get("Vendor Name");
const fields = $vars.extract1.output?.ExtractionResult?.ResultsDocument?.Fields || [];
const norm = (s) => String(s || "").toLowerCase().replace(/\s+/g, "");
const get = (name) => {
  const f = fields.find((x) => norm(x.FieldName) === norm(name));
  return f && Array.isArray(f.Values) && f.Values[0] ? f.Values[0].Value : undefined;
};

const total = get("Total");
const vendor = get("Vendor Name");

Note:

Common mistake: reading Fields.find((f) => f.FieldName === "Total").Value returns undefined. The fields sit under ResultsDocument.Fields (one level deeper than ExtractionResult), and the value lives in the Values array, not on the field directly. Examples copied from legacy Document Understanding workflows use a flatter shape and will not work here.

Missing fields

A field the model could not find has IsMissing: true and an empty or null Values array. Always guard with Values?.[0] (as the snippets above do) so a missing field reads as undefined rather than throwing.

Confidence scores

Each extracted value carries a Confidence and an OcrConfidence, both floats from 0 to 1 where higher is more certain. They sit on the value object, at Values[0].Confidence. A value of -1.0 is a sentinel meaning "not applicable" (for example, on table header rows), so filter those out before comparing. Use a Decision node to route low-confidence extractions to a Human node for review.

Table fields

A field whose FieldType is Table holds its rows under Values, not the scalar shape above. Each table value carries a Components array (a Header row and a Body row), and each component in turn holds the cell fields under its own Components, each with the familiar Values[0].Value. Walk Components recursively to reach individual cells.

Error handling

The Extract node supports an error handle. If extraction fails and the error handle is connected, execution routes to the error path with the error object at $vars.<nodeName>.error. Refer to Error handling for more information.

Notes

The list of models under the Extract category reflects what is deployed in your organization at design time. Deploy or redeploy a model in IXP, then reopen the palette to see the change.
Field values are always strings on Values[0].Value, even for dates and numbers. The model may also return parsed parts under DerivedFields (for example, Year, Month, Day on a date, or City and Country on an address).

On this page

Adding an Extract node
How it works
Configuration
Output
Reading the result
Missing fields
Confidence scores
Table fields
Error handling
Notes

Was this page helpful?

PREVIOUSDocument processing

NEXTSummarize

Adding an Extract node​

How it works​

Configuration​

Output​

Reading the result​

Missing fields​

Confidence scores​

Table fields​

Error handling​

Notes​