@uipath/skills 1.195.0

package/skills/uipath-rpa/references/activity-docs/UiPath.IntelligentOCR.StudioWeb.Activities/3.1/activities/ExtractDocumentData/data-type-patterns.md

@@ -0,0 +1,224 @@
+# Data Type Patterns for Document Understanding Pipelines
+
+When using `ExtractDocumentDataWithDocumentData<T>`, the type argument `T` determines how extraction results are accessed and how downstream validation activities must be typed. This document covers the two patterns and their pipeline-wide implications.
+
+## Overview
+
+| Pattern | Type Argument | `GenerateData` | Field Access | Agent-Compatible |
+|---------|--------------|-----------------|--------------|------------------|
+| **DictionaryData** | `dux:DictionaryData` | `False` | `GetField("fieldName")`, `GetFieldValue("fieldName")` | Yes (recommended) |
+| **Generated Type** | Studio-generated subclass | `True` | `extractionResults.Data.FieldName` | No (requires Studio JIT compilation) |
+
+**For agent-generated workflows, always use `DictionaryData` with `GenerateData="False"`.** The generated type pattern requires Studio's design-time code generation, which is not available when an LLM agent produces XAML directly. Additionally, `GenerateData=True` is incompatible with `ModernDocumentTypeId="use_classification_result"`.
+
+## DictionaryData API Reference
+
+`UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction.DictionaryData`
+
+`DictionaryData` extends `ExtendedExtractionResultsForDocumentData` and provides methods to access extracted fields and tables by name or ID.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Handler` | `ExtractionResultHandler` | Low-level handler for direct access to the underlying extraction result. |
+
+### Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `GetFields()` | `ResultsDataPoint[]` | Returns all non-table extracted fields. |
+| `GetTables()` | `ResultsTable[]` | Returns all extracted tables. |
+| `GetField(string fieldIdOrName)` | `ResultsDataPoint` | Returns a single field by its ID or name. Case-insensitive. Throws if multiple fields match. |
+| `GetTable(string tableIdOrName)` | `ResultsTable` | Returns a single table by its ID or name. Case-insensitive. Throws if multiple tables match. See [Table Access Patterns](#table-access-patterns) for the full `ResultsTable` → `ResultsTableValue` → `ResultsTableCell` type hierarchy. |
+| `GetFieldValue(string fieldIdOrName)` | `ResultsValue` | Returns the first value of a field. Returns `null` if the field is missing. Throws if the field is not found. |
+| `GetFieldValue(string fieldIdOrName, int index)` | `ResultsValue` | Returns the value at a specific index. Throws if the index is out of range. |
+| `GetFieldValues(string fieldIdOrName)` | `ResultsValue[]` | Returns all values of a field. Returns an empty array if the field is missing. |
+| `SetFieldValue(string fieldIdOrName, ResultsValue value)` | `void` | Replaces all values of a field with a single value. |
+| `SetFieldValue(string fieldIdOrName, ResultsValue value, int index)` | `void` | Sets the value at a specific index. |
+| `SetFieldValues(string fieldIdOrName, ResultsValue[] values)` | `void` | Replaces all values of a field. |
+
+### Field Lookup Behavior
+
+`GetField`, `GetFieldValue`, `GetFieldValues`, `GetTable`, and their setter counterparts resolve fields in this order:
+1. Match by **full field ID** (case-insensitive)
+2. Match by **short field ID** (the part after the last `.` in the field ID, case-insensitive)
+3. Match by **field name** (case-insensitive)
+
+If more than one field matches at any step, an `ArgumentException` is thrown.
+
+## Table Access Patterns
+
+Extraction results can contain **tables** (e.g., line items on a receipt or invoice). Accessing table data requires navigating a specific type hierarchy that differs from simple field access.
+
+### Type Chain
+
+```
+DictionaryData
+  .GetTable("fieldId")        → ResultsTable
+    .Values                   → ResultsTableValue[]  (typically one element)
+    .GetValue()               → ResultsTableValue     (shorthand for Values(0))
+
+ResultsTableValue
+  .NumberOfRows               → Int32                 (includes header row)
+  .ColumnInfo                 → ResultsTableColumnInfo[]
+  .Cells                      → ResultsTableCell[]    (flat array, row-major order)
+  .GetCell(rowIndex, colIndex)→ ResultsTableCell       (helper, avoids manual indexing)
+  .GetRow(rowIndex)           → IEnumerable(Of ResultsTableCell)
+  .GetRows()                  → IEnumerable(Of ResultsTableCell())
+
+ResultsTableCell
+  .Values                     → ResultsValue[]        (typically one element)
+  .GetValue()                 → ResultsValue           (shorthand for Values(0))
+  .RowIndex                   → Int32
+  .ColumnIndex                → Int32
+  .IsHeader                   → Boolean
+  .IsMissing                  → Boolean
+
+ResultsTableColumnInfo
+  .FieldId                    → String                 (column identifier, e.g., "description")
+  .FieldName                  → String                 (display name)
+
+ResultsValue
+  .Value                      → String                 (the extracted text)
+  .Confidence                 → Single
+  .OcrConfidence              → Single
+  .OperatorConfirmed          → Boolean
+```
+
+### Key Points
+
+- **`ResultsTable.Values`** returns `ResultsTableValue[]`, **not** `ResultsValue[]`. Do not confuse with `ResultsDataPoint.Values`.
+- **`ResultsTableCell.Values`** returns `ResultsValue[]` (same as simple fields). Access the text with `.Values(0).Value` or the shorthand `.GetValue().Value`.
+- **`Cells` is a flat row-major array.** To access a cell manually: `Cells(rowIndex * ColumnInfo.Length + columnIndex)`. Prefer the helper methods `GetCell(row, col)`, `GetRow(row)`, or `GetRows()` instead.
+- **Row 0 is the header row.** Data rows start at index 1. `NumberOfRows` includes the header.
+
+### Iterating Table Rows (VB.NET)
+
+Find columns by `FieldId`, then iterate data rows:
+
+```vb
+' Get the table and its first value
+Dim table As ResultsTable = extractionResults.Data.GetTable("items")
+Dim tv As ResultsTableValue = table.GetValue()
+
+' Find column indices by FieldId
+Dim descCol As Integer = -1
+Dim amountCol As Integer = -1
+For i As Integer = 0 To tv.ColumnInfo.Length - 1
+    Select Case tv.ColumnInfo(i).FieldId
+        Case "description" : descCol = i
+        Case "line-amount" : amountCol = i
+    End Select
+Next
+
+' Iterate data rows (row 0 is the header, skip it)
+For row As Integer = 1 To tv.NumberOfRows - 1
+    Dim description As String = tv.GetCell(row, descCol).GetValue().Value
+    Dim amount As String = tv.GetCell(row, amountCol).GetValue().Value
+    ' ... use description and amount
+Next
+```
+
+### Alternative: Using GetRows()
+
+```vb
+Dim table As ResultsTable = extractionResults.Data.GetTable("items")
+Dim tv As ResultsTableValue = table.GetValue()
+
+For Each row As ResultsTableCell() In tv.GetRows()
+    ' Skip header row
+    If row(0).IsHeader Then Continue For
+    ' Access cells by column index
+    Dim description As String = row(descCol).GetValue().Value
+    Dim amount As String = row(amountCol).GetValue().Value
+Next
+```
+
+### Predefined Extractor Table Fields
+
+The Predefined project extractors define these table fields and column IDs:
+
+**Receipts** (`DocType="receipts"`) — table field: `items`
+
+| Column FieldId | Column Name |
+|----------------|-------------|
+| `description` | Description |
+| `quantity` | Quantity |
+| `unit-price` | Unit Price |
+| `line-amount` | Line Amount |
+
+**Invoices** (`DocType="invoices"`) — table field: `items`
+
+| Column FieldId | Column Name |
+|----------------|-------------|
+| `description` | Description |
+| `quantity` | Quantity |
+| `unit-price` | Unit Price |
+| `line-amount` | Line Amount |
+| `item-po-no` | Purchase Order Number |
+| `line-no` | Line Number |
+| `part-no` | Part Number |
+
+**Purchase Orders** (`DocType="purchase_orders"`) — table field: `items`
+
+| Column FieldId | Column Name |
+|----------------|-------------|
+| `description` | Description |
+| `quantity` | Quantity |
+| `unit-price` | Unit Price |
+| `line-amount` | Line Amount |
+
+> **Note:** For custom DU projects, the table field IDs and column IDs are project-specific. Ask the user for the table field name and column names.
+
+## Pipeline-Wide Type Propagation
+
+The type argument `T` chosen for `ExtractDocumentDataWithDocumentData<T>` must be used consistently across **all** downstream activities that handle extraction results. Mismatched type arguments will cause runtime errors.
+
+| Activity | Generic Parameter | DictionaryData Type Argument |
+|----------|-------------------|------------------------------|
+| `ExtractDocumentDataWithDocumentData<T>` | `T` | `dux:DictionaryData` |
+| `CreateValidationAction<T>` | `T` | `dux:DictionaryData` |
+| `WaitForValidationAction<T>` | `T` | `dux:DictionaryData` |
+| `ValidateDocumentDataWithDocumentData<T>` | `T` | `dux:DictionaryData` |
+| `CreateDocumentValidationArtifacts<T>` | `T` | `dux:DictionaryData` |
+
+Classification validation activities (`CreateClassificationValidationAction`, `WaitForClassificationValidationAction`, `CreateClassificationValidationActionAndWait`) are **not** generic and are unaffected by this choice.
+
+## Variable Declarations for DictionaryData Pipeline
+
+Complete variable block for a pipeline with classification validation and extraction validation:
+
+```xml
+<Sequence.Variables>
+  <!-- Classification -->
+  <Variable x:TypeArguments="duc:DocumentData" Name="classificationResults" />
+  <Variable x:TypeArguments="duVal:CreatedClassificationValidationAction" Name="classificationTask" />
+  <Variable x:TypeArguments="duc:DocumentData" Name="validatedClassificationResults" />
+  <!-- Extraction (DictionaryData) -->
+  <Variable x:TypeArguments="dux:IDocumentData(dux:DictionaryData)" Name="extractionResults" />
+  <Variable x:TypeArguments="duVal:CreatedValidationAction(dux:DictionaryData)" Name="extractionValidationTask" />
+  <Variable x:TypeArguments="dux:IDocumentData(dux:DictionaryData)" Name="validatedExtractionResults" />
+</Sequence.Variables>
+```
+
+Required XAML namespace prefixes for these variables:
+
+```xml
+xmlns:duc="clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DocumentClassification;assembly=UiPath.IntelligentOCR.StudioWeb.Activities"
+xmlns:dux="clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction;assembly=UiPath.IntelligentOCR.StudioWeb.Activities"
+xmlns:duVal="clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataValidation;assembly=UiPath.IntelligentOCR.StudioWeb.Activities"
+```
+
+## GenerateData=True Pattern (Studio Only)
+
+When `GenerateData=True`, Studio generates a subclass of `ExtendedExtractionResultsForDocumentData` at design time with strongly-typed properties for each extracted field. The generated type has a dynamic name and assembly (e.g., `AdiTest11InvoicesV3` in assembly `ExtendedExtractionRe.O9Rcc1EXZGC1VPCKY1e5Dfq3`).
+
+This pattern:
+- Requires Studio's design-time JIT compilation
+- Produces a user/project-specific type name that cannot be predicted
+- Enables `extractionResults.Data.InvoiceNumber`, `extractionResults.Data.TotalAmount`, etc.
+- All downstream validation activities must use the same generated type as their type argument
+- **Incompatible with `ModernDocumentTypeId="use_classification_result"`**
+
+**Agents should never use this pattern.** Always set `GenerateData="False"` and use `DictionaryData` as the type argument.

package/skills/uipath-rpa/references/activity-docs/UiPath.IntelligentOCR.StudioWeb.Activities/3.1/activities/ExtractDocumentData.md

@@ -0,0 +1,249 @@
+# Extract Document Data
+
+`UiPath.IntelligentOCR.StudioWeb.Activities.ExtractDocumentDataWithDocumentData`
+
+Extracts data from a document and stores the results into automatically generated variables. Supports pretrained extractors for standard document types (invoices, receipts, id_cards, passports, purchase_orders, utility_bills, remittance_advices, bills_of_lading, checks) and custom DU project extractors.
+
+**Package:** `UiPath.DocumentUnderstanding.Activities`
+**Category:** Document Understanding
+
+## References
+
+- [Data Type Patterns](ExtractDocumentData/data-type-patterns.md) — DictionaryData API, type propagation rules, and pipeline variable declarations
+
+## Properties
+
+### Input
+
+| Name | Display Name | Kind | Type | Required | Default | Description |
+|------|-------------|------|------|----------|---------|-------------|
+| `ProjectId` | Document Understanding project | InArgument | `string` | Yes | | The Document Understanding project ID. Should be a GUID-formatted string (parsed via `Guid.Parse()` at runtime). The Predefined project GUID is `"00000000-0000-0000-0000-000000000000"`. For custom projects, if the GUID is unknown, set `ProjectName` to the project's display name and use a non-GUID placeholder string for ProjectId (e.g., ProjectId="placeholder"). Do not use "00000000-0000-0000-0000-000000000000" — that is the Predefined project's real GUID and will be accepted as-is without triggering name-based resolution — **Studio resolves `ProjectId` from `ProjectName` at design time**. Set as a **literal attribute value** (not a VB expression). |
+| `ProjectVersionNumber` | Version | InArgument | `int` | No | | The version number referencing a snapshot of the Document Understanding project. Use this **or** `ProjectTag` (not both). For the Predefined project, use `0`. |
+| `ProjectTag` | Tag | InArgument | `string` | No | | An alternative to version number. A tag referencing a snapshot of the Document Understanding project. For the Predefined project, use `"Production"`. |
+| `DocType` | Extractor | InArgument | `string` | Conditional | | The extractor identifier (**lowercase**). Required unless `ModernDocumentTypeId="use_classification_result"` is used (in which case set `DocType="{x:Null}"`). Pretrained values (Predefined project only): `invoices`, `receipts`, `id_cards`, `passports`, `purchase_orders`, `utility_bills`, `remittance_advices`, `bills_of_lading`, `checks`. For custom DU projects: use the **document type name** as it appears in the project (e.g., `"invoices"`) — ask the user for this name if not provided (they can find it in the project's Document Types tab). Studio resolves it to the correct extractor at design time. Alternatively, use the extractor GUID if known. See Enum Reference. |
+| `ModernDocumentTypeId` | Document type | InArgument | `string` | Conditional | | The document type ID defining the fields to extract. Required unless `DocType` is set (both can be set together). **For pretrained extractors, use the same lowercase identifier as `DocType`** (e.g., `"invoices"`, `"receipts"`). For custom DU projects, use the **document type name** from the project's Document Types tab (e.g., `"invoices"`) — ask the user for this name if not provided. Studio resolves the name to the internal GUID at design time. The GUID can also be used directly if known. Set to `"use_classification_result"` to dynamically resolve the document type from the upstream ClassifyDocument result (requires `FileInput` to be a `DocumentData`; set `DocType="{x:Null}"` when using this). Together with `DocType`, these two properties fully specify the extraction target. |
+| `FileInput` | Input | InArgument | `IResource` | Yes | | Document Data referencing the digitized input file, or the input file itself if Document Data has not been created yet. Accepts a `DocumentData` object from ClassifyDocument directly. |
+| `TimeoutInSeconds` | Timeout (seconds) | InArgument | `int` | Yes | `3600` | Maximum execution time in seconds. If exceeded, the operation is terminated. |
+
+### Configuration
+
+| Name | Display Name | Type | Default | Description |
+|------|-------------|------|---------|-------------|
+| `ApplyAutoValidation` | Auto-validation | `bool` | `false` | Whether to apply automatic validation based on configurations provided as input or at the Document Understanding project level. |
+| `AutoValidationConfidenceThreshold` | Confidence threshold | `int?` | `0` | Extraction results below this confidence threshold are auto-validated when `ApplyAutoValidation` is enabled. |
+| `GenerateData` | Generate data type | `bool` | `false` | When `true`, generates a strongly-typed output with fields available under the `Data` property. When `false`, fields are retrieved via method calls by ID (using `DictionaryData`). **Agents should always set this to `False`** — `True` requires Studio's design-time JIT compilation which agents cannot trigger. Also, `GenerateData=True` is incompatible with `ModernDocumentTypeId="use_classification_result"`. See Type Reference for details. |
+| `ActivityMajorVersion` | Activity major version | `int` | | Internal version flag. **Always set `ActivityMajorVersion="2"`** in generated XAML. If omitted or set to a value less than `2`, Studio displays a migration warning banner ("The activity has been updated to a new major version…") that requires manual acknowledgement. Setting this to `2` suppresses the warning. |
+| `RuntimeAssetPath` | Runtime Credentials Asset | `string` | | Orchestrator credentials asset path for cross-org authentication. Format: `<orchestratorFolder>/<assetName>`. |
+| `RuntimeTenantUrl` | Runtime Tenant Url | `string` | | URL to an external tenant for cross-org authentication. Format: `https://<base_url>/<organization>/<tenant>`. |
+
+### Output
+
+| Name | Display Name | Kind | Type | Description |
+|------|-------------|------|------|-------------|
+| `ExtractionResults` | Document data | OutArgument | `IDocumentData<ExtendedExtractionResultsForDocumentData>` | Extracted data in a (field-name, field-value) format. For example: ('invoice-date', '01/04/2022'). See Type Reference below. |
+
+### Studio UI Display Properties
+
+These properties control how Studio's designer renders dropdown selections and drive name-based resolution. When generating XAML programmatically, always set them alongside their corresponding functional properties. They are marked `Browsable(false)` in the source code but are serialized in XAML by Studio.
+
+| Property | Type | Role | Example Value (for `invoices` extractor) |
+|----------|------|------|------------------------------------------|
+| `ProjectName` | `string` | **Drives resolution of `ProjectId`** — Studio looks up the project by this name and populates `ProjectId` with the GUID at design time. | `"Predefined"` |
+| `ProjectVersionName` | `string` | Mirrors `ProjectTag` | `"Production"` |
+| `ExtractorName` | `string` | Mirrors `DocType` | `"Invoices"` (capitalized display name) |
+| `ModernDocumentTypeName` | `string` | Mirrors `ModernDocumentTypeId` | `"Invoices"` (capitalized display name) |
+
+## Type Reference
+
+### IDocumentData\<T\>
+
+**CLR type:** `UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction.IDocumentData<T>`
+**Assembly:** `UiPath.IntelligentOCR.StudioWeb.Activities`
+**XAML xmlns:** `clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction;assembly=UiPath.IntelligentOCR.StudioWeb.Activities`
+
+The output `ExtractionResults` implements `IDocumentData<T>` where `T` is `ExtendedExtractionResultsForDocumentData` (or a Studio-generated subclass when `GenerateData=True`).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Data` | `T` | Strongly-typed extraction results (available when `GenerateData=True`). |
+| `DocumentType` | `DocumentType` | The document type used for extraction. |
+| `SubDocuments` | `IDocumentData[]` | Subdocuments (if splitting occurred upstream). |
+| `FileDetails` | `FileDetails` | File path, name, extension, and page range. |
+| `DocumentMetadata` | `DocumentMetadata` | OCR text (`Text`), DOM (`DocumentObjectModel`), and `ResultsAsDataTables` for tabular export. |
+
+### ExtendedExtractionResultsForDocumentData
+
+**CLR type:** `UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction.ExtendedExtractionResultsForDocumentData`
+**XAML xmlns:** `clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction;assembly=UiPath.IntelligentOCR.StudioWeb.Activities`
+
+Base type argument for the generic activity. When `GenerateData=True`, Studio generates a type-specific subclass at design time with strongly-typed properties for each extracted field, accessible via `ExtractionResults.Data`. The generated subclass has a dynamic assembly name and namespace — this is normal and handled automatically by Studio.
+
+### DictionaryData
+
+**CLR type:** `UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction.DictionaryData`
+**XAML xmlns:** `clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction;assembly=UiPath.IntelligentOCR.StudioWeb.Activities` (prefix `dux`)
+
+Extends `ExtendedExtractionResultsForDocumentData`. Provides methods to access extracted fields and tables by name or ID without requiring Studio's design-time code generation. **Recommended type argument for agent-generated workflows** when `GenerateData=False`.
+
+Key methods: `GetField(string)`, `GetFieldValue(string)`, `GetTable(string)`, `GetFields()`, `GetTables()`. See [Data Type Patterns](ExtractDocumentData/data-type-patterns.md) for the full API reference.
+
+## Enum Reference
+
+### Pretrained Extractor Identifiers (DocType and ModernDocumentTypeId values)
+
+Use these **lowercase** identifiers for both `DocType` and `ModernDocumentTypeId`. Do not use the capitalized display names for these properties (use capitalized names only for the display properties `ExtractorName` and `ModernDocumentTypeName`).
+
+| Identifier (DocType & ModernDocumentTypeId) | Display Name (ExtractorName & ModernDocumentTypeName) |
+|---------------------------------------------|------------------------------------------------------|
+| `invoices` | `Invoices` |
+| `receipts` | `Receipts` |
+| `id_cards` | `ID Cards` |
+| `passports` | `Passports` |
+| `purchase_orders` | `Purchase Orders` |
+| `utility_bills` | `Utility Bills` |
+| `remittance_advices` | `Remittance Advices` |
+| `bills_of_lading` | `Bills of Lading` |
+| `checks` | `Checks` |
+
+**Special ModernDocumentTypeId values:**
+- `use_classification_result` — Dynamically resolves the document type from the upstream ClassifyDocument result. When using this value, set `DocType="{x:Null}"` and pass a `DocumentData` from ClassifyDocument as `FileInput`. The activity determines the extractor and document type from the classification output at runtime. Works with both Predefined and custom DU projects. **Cannot be used with `GenerateData=True`.**
+
+**Custom DU project values:**
+When targeting a custom DU project (not Predefined), set `DocType` to the document type name from the project's Document Types tab (e.g., `"invoices"`). Ask the user for this name if not provided. Studio resolves the name to the correct extractor at design time. The predefined identifiers listed above only work with the Predefined project (`ProjectId="00000000-0000-0000-0000-000000000000"`). For custom projects, the document type names are project-specific.
+
+## XAML Example
+
+Extracts invoice data using the Predefined project with a pretrained extractor. Replace `[inputFile]` with an `IResource` variable pointing to the document (or a `DocumentData` from ClassifyDocument).
+
+```xml
+<du:ExtractDocumentDataWithDocumentData
+    x:TypeArguments="dux:ExtendedExtractionResultsForDocumentData"
+    DisplayName="Extract Document Data"
+    ActivityMajorVersion="2"
+    ProjectId="00000000-0000-0000-0000-000000000000"
+    ProjectName="Predefined"
+    ProjectTag="Production"
+    ProjectVersionName="Production"
+    ProjectVersionNumber="0"
+    DocType="[&quot;invoices&quot;]"
+    ExtractorName="Invoices"
+    ModernDocumentTypeId="invoices"
+    ModernDocumentTypeName="Invoices"
+    FileInput="[inputFile]"
+    TimeoutInSeconds="[3600]"
+    ExtractionResults="[extractionResults]">
+  <du:ExtractDocumentDataWithDocumentData.GptPromptWithVariables>
+    <scg:Dictionary x:TypeArguments="x:String, InArgument(x:String)" />
+  </du:ExtractDocumentDataWithDocumentData.GptPromptWithVariables>
+</du:ExtractDocumentDataWithDocumentData>
+```
+
+**Required variable declaration:**
+
+```xml
+<Variable x:TypeArguments="dux:IDocumentData(dux:ExtendedExtractionResultsForDocumentData)" Name="extractionResults" />
+```
+
+### DictionaryData Variant
+
+When generating workflows programmatically, use `DictionaryData` as the type argument. This provides field access methods without requiring Studio's JIT code generation:
+
+```xml
+<du:ExtractDocumentDataWithDocumentData
+    x:TypeArguments="dux:DictionaryData"
+    DisplayName="Extract Document Data"
+    ActivityMajorVersion="2"
+    ProjectId="00000000-0000-0000-0000-000000000000"
+    ProjectName="Predefined"
+    ProjectTag="Production"
+    ProjectVersionName="Production"
+    ProjectVersionNumber="0"
+    DocType="[&quot;invoices&quot;]"
+    ExtractorName="Invoices"
+    ModernDocumentTypeId="invoices"
+    ModernDocumentTypeName="Invoices"
+    FileInput="[inputFile]"
+    TimeoutInSeconds="[3600]"
+    ExtractionResults="[extractionResults]">
+  <du:ExtractDocumentDataWithDocumentData.GptPromptWithVariables>
+    <scg:Dictionary x:TypeArguments="x:String, InArgument(x:String)" />
+  </du:ExtractDocumentDataWithDocumentData.GptPromptWithVariables>
+</du:ExtractDocumentDataWithDocumentData>
+```
+
+**Required variable declaration:**
+
+```xml
+<Variable x:TypeArguments="dux:IDocumentData(dux:DictionaryData)" Name="extractionResults" />
+```
+
+### Custom DU Project Variant
+
+When targeting a custom DU project, use the document type name from the project for both `DocType` and `ModernDocumentTypeId`. Studio resolves these to the correct internal identifiers at design time. `ProjectId` must still be a GUID.
+
+```xml
+<du:ExtractDocumentDataWithDocumentData
+    x:TypeArguments="dux:DictionaryData"
+    DisplayName="Extract Document Data"
+    ActivityMajorVersion="2"
+    ProjectId="{your-project-guid}"
+    ProjectName="{Your Project Name}"
+    ProjectTag="{your-version-tag}"
+    ProjectVersionName="{your-version-tag}"
+    ProjectVersionNumber="{version-number}"
+    DocType="invoices"
+    ExtractorName="invoices"
+    ModernDocumentTypeId="invoices"
+    ModernDocumentTypeName="invoices"
+    FileInput="[inputFile]"
+    TimeoutInSeconds="[3600]"
+    GenerateData="False"
+    ExtractionResults="[extractionResults]">
+  <du:ExtractDocumentDataWithDocumentData.GptPromptWithVariables>
+    <scg:Dictionary x:TypeArguments="x:String, InArgument(x:String)" />
+  </du:ExtractDocumentDataWithDocumentData.GptPromptWithVariables>
+</du:ExtractDocumentDataWithDocumentData>
+```
+
+After opening the workflow in Studio, the designer resolves `ModernDocumentTypeId` from the name to the project-specific GUID. The `DocType` name is also validated against the project's registered extractors.
+
+**Required XAML namespace prefixes:**
+
+```xml
+xmlns:du="clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities;assembly=UiPath.IntelligentOCR.StudioWeb.Activities"
+xmlns:dux="clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction;assembly=UiPath.IntelligentOCR.StudioWeb.Activities"
+xmlns:scg="clr-namespace:System.Collections.Generic;assembly=mscorlib"
+```
+
+**Required expression namespace imports:**
+
+```xml
+<TextExpression.NamespacesForImplementation>
+  <scg:List x:TypeArguments="x:String">
+    <x:String>UiPath.IntelligentOCR.StudioWeb.Activities</x:String>
+    <x:String>UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction</x:String>
+    <x:String>UiPath.IntelligentOCR.StudioWeb.Activities.DocumentClassification</x:String>
+  </scg:List>
+</TextExpression.NamespacesForImplementation>
+<TextExpression.ReferencesForImplementation>
+  <scg:List x:TypeArguments="AssemblyReference">
+    <AssemblyReference>UiPath.IntelligentOCR.StudioWeb.Activities</AssemblyReference>
+  </scg:List>
+</TextExpression.ReferencesForImplementation>
+```
+
+## Notes
+
+- This is a generic activity. In XAML, use `x:TypeArguments="dux:ExtendedExtractionResultsForDocumentData"` (from namespace `UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction`, prefix `dux`).
+- `ProjectId` should be a GUID-formatted string at runtime (`Guid.Parse()` is used). The Predefined project GUID is `00000000-0000-0000-0000-000000000000`. For custom projects, Studio resolves `ProjectId` from `ProjectName` at design time — so if `ProjectName` is set to a valid project name, the GUID does not need to be known at authoring time. When `ProjectTag` is set, `ProjectVersionNumber` is also auto-resolved by Studio — agents can set `ProjectVersionNumber="0"` as a placeholder.
+- Properties backed by Studio dropdown widgets (`ProjectId`, `ProjectTag`, `ProjectVersionNumber`) should be set as **literal attribute values** rather than VB/C# expressions to ensure the dropdown displays correctly in the designer.
+- For the Predefined project, the standard version configuration is: `ProjectTag="Production"`, `ProjectVersionNumber="0"`, `ProjectVersionName="Production"`.
+- `ProjectVersionNumber` and `ProjectTag` are alternatives. Use one or the other.
+- `DocType` values are **lowercase identifiers**. For the Predefined project, use predefined names (e.g., `invoices`). For custom DU projects, use the document type name as it appears in the project (e.g., `"invoices"` if the project defines a document type named "invoices") — ask the user for this name if not provided (found in the project's Document Types tab). Studio resolves names to the correct extractor at design time.
+- `ModernDocumentTypeId` uses the **same lowercase identifier** as `DocType` for pretrained extractors (e.g., both are `"invoices"`). For custom DU projects, use the document type name — Studio resolves it to the internal GUID at design time. The GUID can also be used directly if known.
+- The legacy `ExtractorDocumentType` property does **not** exist on this activity. Use `DocType` (extractor identifier) and `ModernDocumentTypeId` (document type definition) instead.
+- **Always set `ActivityMajorVersion="2"`** in generated XAML. Without this, Studio shows a migration warning banner ("The activity has been updated to a new major version…") that requires manual acknowledgement before the activity can be used.
+- **Agents should always set `GenerateData="False"`.** `GenerateData=True` requires Studio's design-time JIT compilation which agents cannot trigger, and is incompatible with `ModernDocumentTypeId="use_classification_result"`.
+- When `GenerateData=True`, Studio generates a type-specific assembly at design time, producing a subclass of `ExtendedExtractionResultsForDocumentData` with typed field properties accessible via `ExtractionResults.Data`. The generated type has a dynamic assembly name — this is expected behavior.
+- `RuntimeAssetPath` and `RuntimeTenantUrl` enable cross-organization access. Both must be set together.
+- The type argument chosen for this activity (`ExtendedExtractionResultsForDocumentData`, `DictionaryData`, or a generated type) **must be used consistently** across all downstream validation activities (`CreateValidationAction<T>`, `WaitForValidationAction<T>`, `ValidateDocumentDataWithDocumentData<T>`, `CreateDocumentValidationArtifacts<T>`). Mismatched type arguments cause runtime errors. See [Data Type Patterns](ExtractDocumentData/data-type-patterns.md) for details.

package/skills/uipath-rpa/references/activity-docs/UiPath.IntelligentOCR.StudioWeb.Activities/3.1/activities/RetrieveDocumentValidationArtifacts.md

@@ -0,0 +1,50 @@
+# Retrieve Document Validation Artifacts
+
+`UiPath.IntelligentOCR.StudioWeb.Activities.DataValidation.Artifacts.RetrieveDocumentValidationArtifacts`
+
+Retrieves completed validation artifacts from an Orchestrator storage bucket and reconstructs the validated extraction results. Used after a UiPath App-based validation flow has been completed.
+
+**Package:** `UiPath.DocumentUnderstanding.Activities`
+**Category:** Document Understanding
+
+## Properties
+
+### Input
+
+| Name | Display Name | Kind | Type | Required | Default | Description |
+|------|-------------|------|------|----------|---------|-------------|
+| `ContentValidationData` | Content Validation Data Object | InArgument | `ContentValidationData` | Yes | | The output of the **Create Document Validation Artifacts** activity. |
+| `CompletedAppAction` | Completed Action Object | InArgument | `object` | | | The completed action object from the UiPath App validation flow. |
+
+### Configuration
+
+| Name | Display Name | Type | Default | Description |
+|------|-------------|------|---------|-------------|
+| `RemoveDataFromStorage` | Remove Data From Storage | `bool` | `false` | If true, all associated data is deleted from the storage bucket after retrieval. |
+| `ReturnAutomaticExtractionResults` | Return Automatic Extraction Results | `bool` | `false` | If true, returns the original automatic extraction results instead of the validated results. |
+
+### Output
+
+| Name | Display Name | Kind | Type | Description |
+|------|-------------|------|------|-------------|
+| `ValidatedExtractionResults` | Document data | OutArgument | `IDocumentData<DictionaryData>` | Validated extracted data containing changes made by the reviewer, or automatic extraction results if `ReturnAutomaticExtractionResults` is true. |
+
+## XAML Example
+
+```xml
+<duArt:RetrieveDocumentValidationArtifacts
+    DisplayName="Retrieve Document Validation Artifacts"
+    ContentValidationData="[contentValidationData]"
+    CompletedAppAction="[completedAction]"
+    RemoveDataFromStorage="[True]"
+    ValidatedExtractionResults="[validatedResults]" />
+```
+
+> Namespace prefix `duArt` maps to `clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataValidation.Artifacts;assembly=UiPath.IntelligentOCR.StudioWeb.Activities`.
+
+## Notes
+
+- Use this activity after **Create Document Validation Artifacts** and a UiPath App-based validation flow.
+- The output type is `IDocumentData<DictionaryData>` (not the generic `ExtendedExtractionResultsForDocumentData`), as the validated data is deserialized from storage in a generic format.
+- Set `RemoveDataFromStorage` to `true` to clean up the storage bucket after retrieval.
+- Set `ReturnAutomaticExtractionResults` to `true` if you want to skip the validated results and use the original automatic extraction instead.

package/skills/uipath-rpa/references/activity-docs/UiPath.IntelligentOCR.StudioWeb.Activities/3.1/activities/WaitForClassificationValidationTaskAndResume.md

@@ -0,0 +1,40 @@
+# Wait for Classification Validation Task & Resume
+
+`UiPath.IntelligentOCR.StudioWeb.Activities.DataValidation.WaitForClassificationValidationAction`
+
+Waits for the completion of a Classification Validation Task (created by the **Create Classification Validation Task** activity) and resumes the workflow with the validated classification results.
+
+**Package:** `UiPath.DocumentUnderstanding.Activities`
+**Category:** Document Understanding
+
+## Properties
+
+### Input
+
+| Name | Display Name | Kind | Type | Required | Default | Description |
+|------|-------------|------|------|----------|---------|-------------|
+| `CreatedClassificationValidationAction` | Created Classification Validation Task | InArgument | `CreatedClassificationValidationAction` | Yes | | The output of the **Create Classification Validation Task** activity. |
+
+### Output
+
+| Name | Display Name | Kind | Type | Description |
+|------|-------------|------|------|-------------|
+| `ValidatedClassificationResults` | Document data | OutArgument | `DocumentData` | Validated classification data containing changes made by the reviewer in Classification Station. |
+
+## XAML Example
+
+```xml
+<duVal:WaitForClassificationValidationAction
+    DisplayName="Wait for Classification Validation Task"
+    CreatedClassificationValidationAction="[createdClassificationAction]"
+    ValidatedClassificationResults="[validatedClassification]" />
+```
+
+> Namespace prefix `duVal` maps to `clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataValidation;assembly=UiPath.IntelligentOCR.StudioWeb.Activities`.
+
+## Notes
+
+- This is a **persistent activity**. The workflow suspends while waiting for the validation task to be completed in Action Center. The project must have `"supportsPersistence": true` in `project.json` (under `"runtimeOptions"`). Without this, the workflow will fail at runtime.
+- Cannot be placed inside a No Persist Scope.
+- Must be used after a **Create Classification Validation Task** activity. The `CreatedClassificationValidationAction` input must come from that activity's output.
+- In a typical pipeline, the `ValidatedClassificationResults` output (`DocumentData`) is passed as `FileInput` to **Extract Document Data**. `DocumentData` implements `IResource`, so it can be used directly.

package/skills/uipath-rpa/references/activity-docs/UiPath.IntelligentOCR.StudioWeb.Activities/3.1/activities/WaitForValidationTaskAndResume.md

@@ -0,0 +1,63 @@
+# Wait for Validation Task and Resume
+
+`UiPath.IntelligentOCR.StudioWeb.Activities.DataValidation.WaitForValidationAction`
+
+Waits for the completion of a Document Validation Task (created by the **Create Validation Task** activity) and resumes the workflow with the validated extraction results.
+
+**Package:** `UiPath.DocumentUnderstanding.Activities`
+**Category:** Document Understanding
+
+## Properties
+
+### Input
+
+| Name | Display Name | Kind | Type | Required | Default | Description |
+|------|-------------|------|------|----------|---------|-------------|
+| `CreatedValidationAction` | Created document validation task | InArgument | `CreatedValidationAction<ExtendedExtractionResultsForDocumentData>` | Yes | | The output of the **Create Validation Task** activity. |
+
+### Output
+
+| Name | Display Name | Kind | Type | Description |
+|------|-------------|------|------|-------------|
+| `ValidatedExtractionResults` | Document data | OutArgument | `IDocumentData<ExtendedExtractionResultsForDocumentData>` | Validated extracted data containing changes made by the reviewer in Validation Station. |
+
+## XAML Example
+
+```xml
+<duVal:WaitForValidationAction
+    x:TypeArguments="du:ExtendedExtractionResultsForDocumentData"
+    DisplayName="Wait for Validation Task and Resume"
+    CreatedValidationAction="[createdValidationAction]"
+    ValidatedExtractionResults="[validatedResults]" />
+```
+
+> Namespace prefix `duVal` maps to `clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataValidation;assembly=UiPath.IntelligentOCR.StudioWeb.Activities`.
+> Namespace prefix `du` maps to `clr-namespace:UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction;assembly=UiPath.IntelligentOCR.StudioWeb.Activities`.
+
+### DictionaryData Variant
+
+When using `DictionaryData` for the extraction pipeline (recommended for agent-generated workflows):
+
+```xml
+<duVal:WaitForValidationAction
+    x:TypeArguments="du:DictionaryData"
+    DisplayName="Wait for Validation Task and Resume"
+    CreatedValidationAction="[createdValidationAction]"
+    ValidatedExtractionResults="[validatedResults]" />
+```
+
+**Required variable declarations:**
+
+```xml
+<Variable x:TypeArguments="duVal:CreatedValidationAction(du:DictionaryData)" Name="createdValidationAction" />
+<Variable x:TypeArguments="dux:IDocumentData(du:DictionaryData)" Name="validatedResults" />
+```
+
+## Notes
+
+- This is a **persistent activity**. The workflow suspends while waiting for the validation task to be completed in Action Center. The project must have `"supportsPersistence": true` in `project.json` (under `"runtimeOptions"`). Without this, the workflow will fail at runtime.
+- This is a generic activity. In XAML, use `x:TypeArguments="du:ExtendedExtractionResultsForDocumentData"` or `x:TypeArguments="du:DictionaryData"`.
+- The type argument **must match** the type argument used in `ExtractDocumentDataWithDocumentData` and `CreateValidationAction`. All three must use the same `T`.
+- Cannot be placed inside a No Persist Scope.
+- Must be used after a **Create Validation Task** activity. The `CreatedValidationAction` input must come from that activity's output.
+- In a typical pipeline, this is the final extraction validation step. The `ValidatedExtractionResults` output contains the human-reviewed data.