# Utility nodes Utility nodes do the general-purpose work that holds a flow together: preparing files for processing, checking extracted values, routing work to a person, calling external APIs, uploading files, and running custom logic. They sit between the trigger and the systems you write back to, and most flows use several of them. Six utility nodes are available today: - **Read Files** — turn ingested files into documents the rest of the flow can read. - **Field Validation** — check extracted values against rules. - **Flag for Human Review** — send a work item to a person to review or approve. - **API Request** — call an external HTTP API. - **HTTP File Upload** — upload a file to an external endpoint. - **Custom Code Blocks** — run a custom snippet for logic the built-in nodes don't cover. **Permissions.** Adding and configuring these nodes is part of building a flow, so it requires the **Admin** or **Partner** role. The **Reviewer** role cannot build flows, but Reviewers act on the items that **Flag for Human Review** produces. See [Users and access](../onboarding/users-access.md). **Mapping.** Most fields take their values from earlier steps rather than typed-in constants. Where a field accepts a mapped value, point it at the output of an upstream node. --- ## Read Files In the Nodes library this node is labelled **Read Files** (File Preprocessing). **What it does.** Prepares the files that entered the flow — converting each into a document with its pages and a work-item reference — so extraction and other nodes have something structured to read. **When to use it.** Early in almost every document flow, right after the files arrive from a trigger (Manual File Upload, or the attachments from Download Outlook Email) and before any InsurGPT extraction. **Required inputs.** The files that entered the flow. These default from the triggering upload or download, so you usually don't set them by hand. **Optional inputs / configuration fields** - **Supported File Types** — a checklist of the file types to process. Unselected types are skipped. - **Blob Path**, **File ID**, **Filename**, **Project ID** — references to the file being read. These default from the trigger; map them only if you're feeding files from somewhere non-standard. - **Inline Data** — raw data to process in place of a file, accepting any JSON-serialisable value. Useful when the content to read is already in the flow rather than in an uploaded file. **Outputs.** A list of **documents**, each with its pages, and a matching list of **item** references (the work items created for each document). **Downstream usage.** Feed the documents into [InsurGPT nodes](./insurgpt-nodes.md) for extraction or into **Split Documents** to segment a page stream. The item references are what later nodes — including [Flag for Human Review](#flag-for-human-review) and **Mark Item as Complete** — act on. **Example.** In [Submission Intake](../use-cases/submission-intake.md), Read Files runs after Download Outlook Email and converts the broker's attachments into documents for InsurGPT to extract. **Common errors.** A file produces nothing because its type isn't selected in **Supported File Types**; or downstream extraction has no input because Read Files wasn't connected after the trigger. **Limitations.** Only the selected file types are processed; everything else is skipped silently. **Related.** [Configure triggers](./triggers.md), [InsurGPT nodes](./insurgpt-nodes.md). --- ## Field Validation In the Nodes library this node is labelled **Field Validation**. **What it does.** Checks extracted field values against a set of rules and marks the ones that fail, so the flow can react to data quality before acting on it. **When to use it.** After extraction and before any write-back or completion step — to catch low-confidence or out-of-policy values and route them to a person. **Required inputs** - **Validation Rules** — the rules to apply (required). **Optional inputs** - **Fields** — the fields to validate. Defaults to the fields produced by the upstream extraction node. **Configuration fields.** Each rule describes what to check and what to do: - **Target** — which fields the rule applies to (a specific field, or all fields). - **Clauses** — one or more conditions, each comparing a field property (such as its confidence or value) against a value with an operator (for example, "less than"). - **Combinator** — whether all clauses must match (**and**) or any (**or**). - **Action** — what happens when the rule matches, such as marking the field invalid. - **Message** — the explanation attached to a failing field. A built-in starting rule flags any field whose confidence is below 80%. **Outputs.** The same fields, annotated with each rule's result so downstream nodes can tell which passed and which failed. **Downstream usage.** Branch on the result with [Conditional Branching](./control-nodes.md), or send failing items to [Flag for Human Review](#flag-for-human-review). Validated fields then continue to write-back nodes such as [Create a Guidewire Claim](./app-integration-nodes.md). **Example.** In a loss run processing flow, Field Validation flags any extracted figure below the confidence threshold, and those items go to review instead of straight to write-back. **Common errors.** Nothing is flagged because a rule's target or condition doesn't match the field names produced upstream; or everything is flagged because the threshold is set too high. **Limitations.** Validation reports pass/fail and can mark fields invalid; it does not itself correct values — pair it with review for corrections. **Related.** [Flag for Human Review](#flag-for-human-review), [Control nodes](./control-nodes.md). --- ## Flag for Human Review In the Nodes library this node is labelled **Review**. **What it does.** Pauses the flow and routes the work item to a person to review, correct, or approve the listed fields before the flow continues. This is how human-in-the-loop control enters an otherwise automated agent. **When to use it.** Wherever a person needs to confirm or fix results — typically after validation flags low-confidence fields, or before a high-stakes write-back. **Required inputs.** The work item and the fields to review. Both default from the upstream steps (the item from Read Files, the fields from extraction or validation). **Configuration fields** - **Fields** — the fields to put in front of the reviewer. Defaults to the upstream fields. - **Approval Code** — identifies the approval step (default `MANUAL_REVIEW`). - **Reviewer** — the user responsible for the review. Leave unassigned to send it to the AI Agent's review queue. - **Exception Reason** — the reason shown to the reviewer for why the item needs attention (default explains that fields were below the confidence threshold). - **Item ID** / **Project ID** — references to the item under review; these default from the flow and rarely need changing. **Outputs.** Once the reviewer acts, the reviewed and corrected fields continue down the flow. **Downstream usage.** Connect the corrected output to write-back nodes — for example [Update a Guidewire Claim](./app-integration-nodes.md) — and finish with **Mark Item as Complete**. **Where review happens.** Reviewers pick up these items in the Monitor & Review area. See [Human review](../monitor-review/human-review.md). **Example.** In a medical bill extraction flow, items with low-confidence amounts are flagged for review so a person can confirm the figures before they're written back. **Common errors.** Items sit unactioned because no reviewer or queue picks them up; or the wrong fields appear because the **Fields** mapping doesn't match the extraction output. **Limitations.** A flagged item waits until a person acts on it — flows with review steps are not fully unattended by design. **Related.** [Field Validation](#field-validation), [Human review](../monitor-review/human-review.md), [Users and access](../onboarding/users-access.md). --- ## API Request In the Nodes library this node is labelled **HTTP**. **What it does.** Makes an HTTP request to an external API and returns the response to the flow. Use it to integrate with systems that don't have a dedicated app node. **When to use it.** For custom lookups, enrichments, or write-backs to any HTTP service beyond the built-in Outlook and Guidewire nodes. **Required inputs** - **HTTP Method** — `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` (default `GET`). - **Endpoint URL** — the URL to call. **Optional inputs / configuration fields** - **Headers** — request headers as key–value pairs (put authorization here). - **Request Body** — a JSON object or string for methods that send a body. - **Output Format** — **Full Response** (status code, headers, and content — the default), **Content Only** (response body), or **Raw Bytes** (Base64). **Outputs.** With Full Response: the **status code**, **headers**, and **content** (JSON responses are parsed automatically). Content Only returns just the body; Raw Bytes returns the encoded response. **Downstream usage.** Map the response content into later nodes — for example branching on a status code with [Conditional Branching](./control-nodes.md), or mapping a returned value into a write-back node. **Example.** A flow calls a policy-lookup API with **API Request**, then branches on whether a matching policy was found. **Common errors.** A 4xx/5xx status because of a wrong URL, missing authorization header, or malformed body — set **Output Format** to Full Response to read the status code and content. **Limitations.** One request per run, with no built-in automatic retry. Guard write-backs with [Control nodes](./control-nodes.md). Inspect failures in [Run history](../monitor-review/run-history.md), fix the cause in the draft, and re-test before publishing. To rerun programmatically, use the [API rerun endpoint](/api/flow-executions#rerun-a-flow-execution). **Security.** Supply tokens and keys through **Headers** mapped from variables; don't hard-code secrets. See [Configure environments and variables](./environments-variables.md). **Related.** [HTTP File Upload](#http-file-upload), [App integration nodes](./app-integration-nodes.md). --- ## HTTP File Upload In the Nodes library this node is labelled **HTTP File Upload**. **What it does.** Uploads a file from the flow to an external HTTP endpoint. **When to use it.** To push a processed document or generated file into an external system over HTTP. **Required inputs** - **HTTP Method** — `POST`, `PUT`, or `PATCH` (default `POST`). - **Endpoint URL** — where to upload the file. - **Upload Type** — **form-data** (multipart, default) or **binary** (raw body). **Optional inputs / configuration fields** - **File Source** — a reference to the file to upload, mapped from an upstream node. - **Form Data Fields** — additional multipart fields to send alongside the file (form-data uploads). - **Headers** — request headers; the content type is set automatically based on the upload type. - **Output Format** — Full Response, Content Only, or Raw Bytes. **Outputs.** The upload response — with Full Response, the **status code**, **headers**, and **content**. **Downstream usage.** Branch on the response or capture an identifier the receiving system returns. **Example.** After a flow generates a summary file, HTTP File Upload posts it to a downstream document store. **Common errors.** The upload is rejected because **Upload Type** doesn't match what the endpoint expects, or **File Source** isn't mapped to a real file. **Limitations.** One request per run, with no built-in automatic retry. **Security.** Authorize through **Headers** mapped from variables. See [Configure environments and variables](./environments-variables.md). **Related.** [API Request](#api-request). --- ## Custom Code Blocks In the Nodes library this node is labelled **Custom Code**. **What it does.** Runs a Python snippet in a sandbox so you can transform data or implement logic the built-in nodes don't cover. **When to use it.** As a last resort for custom transformations, reshaping data between nodes, or small calculations — when no dedicated node does the job. **Required inputs** - **Code** — the snippet to run. **Optional inputs / configuration fields** - **Return Variable** — the name of the variable whose value is returned (default `response`). - **Variables** — key–value data passed into the code from earlier steps. - **Environment Variables** — key–value environment values available to the code (use these for configuration, mapped from variables). - **Requirements** — packages to install before running, for example `requests` or `pandas~=2.0.0`. **Outputs.** The returned value (**response**), plus **stdout**, **stderr**, and the **exit code** (`0` means success). **Downstream usage.** Map the returned value into the nodes that follow. **Example.** A flow uses Custom Code Blocks to reformat extracted dates into the format a downstream API expects before calling [API Request](#api-request). **Common errors.** A non-zero exit code from an unhandled exception (check **stderr**), or a missing package that wasn't declared in **Requirements**. **Limitations.** Runs in an isolated sandbox per execution; intended for small, self-contained logic rather than long-running jobs. **Security.** Don't embed secrets in the code — pass them through **Environment Variables** mapped from variables. Treat the snippet as code you own and maintain. **Related.** [API Request](#api-request), [Configure environments and variables](./environments-variables.md). --- ## Where to go next - [Node catalog](./node-catalog.md) — every node and category at a glance. - [App integration nodes](./app-integration-nodes.md) — connect to Outlook and Guidewire. - [Control nodes](./control-nodes.md) — branch and loop based on validation results. - [InsurGPT nodes](./insurgpt-nodes.md) — extract and summarize the documents Read Files prepares. - [Human review](../monitor-review/human-review.md) — where flagged items are reviewed. - [Configure environments and variables](./environments-variables.md) — store credentials used by these nodes.