AWS Textract ExecModule

Overview

AwsTextractModule brings Amazon Textract optical character recognition and structured document analysis into ValkyrAI workflows. It covers n8n's receipt and invoice use case while adding general text detection, forms, tables, signatures, document queries, immutable S3 sources, multipage asynchronous jobs, bounded pagination, verified IntegrationAccount credentials, and annotation-backed Workflow Studio discovery.

The connector implements nine operations:

• synchronous analysis: detect_document_text, analyze_document, analyze_expense
• asynchronous starts: start_document_text_detection, start_document_analysis, start_expense_analysis
• asynchronous results: get_document_text_detection, get_document_analysis, get_expense_analysis

The local DocumentTextExtractionModule extracts embedded plaintext from PDF and Word files. AWS Textract is a distinct cloud document-intelligence capability: it performs OCR on images and scans, returns page geometry and block relationships, recognizes structured forms and tables, detects signatures, answers configured document queries, and parses receipts or invoices.

Usage

1. Create a dedicated AWS IAM principal with only the Textract actions and S3 object reads required by the workflow.
2. Store its access key ID and secret access key in an AWS IntegrationAccount, verify the account, and keep it in READY status.
3. Add AwsTextractModule to a workflow and bind the account through ExecModuleConfig.authConfig.integrationAccount.
4. Choose an exact AWS region and one document source:
   • documentBase64 for a bounded synchronous request, or
   • s3Bucket, s3Key, and optional s3Version for synchronous or asynchronous processing.
5. For a multipage or long-running document, start a job with a unique clientRequestToken, preserve the returned jobId, then retrieve results with the matching get_* operation.
6. Preserve nextToken, jobId, and requestId values until the workflow has reconciled the complete result.

Never place AWS credentials in document input, logs, examples, or output. Credential-like input fields are rejected before provider access.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the nine documented operations.
region	string	Every execution	None	AWS region syntax such as us-west-2; custom endpoints are not accepted.
documentBase64	string	Optional synchronous source	None	Strict base64; decoded payload must be 1 byte through 10 MiB. Mutually exclusive with S3 fields.
s3Bucket	string	S3 source; every asynchronous start	None	Exact DNS-compatible bucket name.
s3Key	string	S3 source; every asynchronous start	None	Non-empty exact object key, at most 1,024 UTF-8 bytes.
s3Version	string	Optional S3 source	None	Exact object version, at most 1,024 characters. Prefer it for repeatable workflows.
featureTypes	array	Document analysis	["TABLES","FORMS"]	Unique values from TABLES, FORMS, QUERIES, SIGNATURES, and LAYOUT.
queries	array	Analysis with QUERIES	None	1-15 objects containing text, optional alias, and optional page selectors.
clientRequestToken	string	Every start_*	None	1-64 letters, digits, _, or -; provides AWS's seven-day start idempotency window.
jobTag	string	Optional start_*	None	1-64 letters, digits, _, -, or . for correlation.
jobId	string	Every get_*	None	Exact provider job identifier returned by the corresponding start operation.
nextToken	string	Optional get_* resume	None	Opaque token from the preceding result page.
limit	integer	get_*	1000	1-10,000 returned blocks or expense documents.
pageSize	integer	get_*	1000	1-1,000 results requested per provider call.
returnAll	boolean	get_*	false	Follow pages until exhaustion, limit, or the 100-page guard.

Each query object has this shape:

{
  "text": "What is the invoice total?",
  "alias": "INVOICE_TOTAL",
  "pages": ["1", "2-4"]
}

featureTypes must contain QUERIES when queries is present, and at least one query is required when QUERIES is enabled.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls, including result pages and safe result-read retries.
data	object	Start or expense success	Job start receipt or normalized expense documents.
blocks	array	Text/document analysis success	Bounded blocks with type, text, confidence, page/table coordinates, entity types, geometry, and relationships.
blockCount	integer	Block result	Returned block count.
text	string	Block result	Detected LINE text joined in provider order.
textTruncated	boolean	Block result	True when normalized text reaches the one-million-character guard.
pages	integer	Provider reports metadata	Document page count.
jobStatus	string	Analysis/result response	SUCCEEDED, IN_PROGRESS, PARTIAL_SUCCESS, FAILED, or another provider status.
hasMore	boolean	Result read	Whether another provider page exists.
nextToken	string	Another result page exists	Opaque continuation token.
modelVersion	string	Provider reports one	Textract model version used for the result.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation and support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Document content, extracted text, expense values, geometry, S3 coordinates, job identifiers, and result tokens are confidential workflow data. Send them only to approved downstream destinations.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / Textract
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions selected by the workflow:

• textract:DetectDocumentText
• textract:AnalyzeDocument
• textract:AnalyzeExpense
• textract:StartDocumentTextDetection and textract:GetDocumentTextDetection
• textract:StartDocumentAnalysis and textract:GetDocumentAnalysis
• textract:StartExpenseAnalysis and textract:GetExpenseAnalysis
• s3:GetObject and, for version-pinned documents, s3:GetObjectVersion on exact input object ARNs

The current connector supports a long-lived access-key pair. Temporary session credentials, role assumption, adapters, Amazon Augmented AI human loops, customer-managed output buckets, KMS output configuration, lending analysis, and identity-document analysis are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, document source, analysis features, job identity, and pagination belong in module parameters or mapped input; result-read retries use the normalized retry policy.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-textract-production"
  },
  "retryPolicy": {
    "maxAttempts": 3
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"analyze_expense\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
detect_document_text	Detects PAGE, LINE, and WORD blocks for one synchronous document.	Billable external processing; exactly one provider attempt.
analyze_document	Detects all text plus selected forms, tables, queries, signatures, or layout.	Billable external processing; exactly one provider attempt.
analyze_expense	Parses normalized receipt/invoice summary fields and line-item groups.	Billable external processing; exactly one provider attempt.
start_document_text_detection	Starts text detection for an S3 document and returns jobId.	Billable job start; requires an idempotency token; exactly one provider attempt.
get_document_text_detection	Retrieves job status and paginated text blocks.	Read-only result retrieval; transient failures retry within policy.
start_document_analysis	Starts structured analysis for an S3 document.	Billable job start; requires an idempotency token; exactly one provider attempt.
get_document_analysis	Retrieves job status and paginated structured blocks.	Read-only result retrieval; transient failures retry within policy.
start_expense_analysis	Starts multipage receipt/invoice analysis for an S3 document.	Billable job start; requires an idempotency token; exactly one provider attempt.
get_expense_analysis	Retrieves job status and paginated expense documents.	Read-only result retrieval; transient failures retry within policy.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing or ambiguous source, malformed region/S3 input, unsupported feature, invalid query, missing client token/job ID, or out-of-range pagination.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_TEXTRACT_HTTP_400	Unsupported document, invalid S3 source, request limit, or query/feature mismatch.	Usually no	Validate the document, region, IAM access, source, and selected operation.
AWS_TEXTRACT_HTTP_403	IAM denies Textract or S3 access.	No	Grant only the missing action on the intended object.
AWS_TEXTRACT_HTTP_429 / 500 / 503	Provider throttle or transient service pressure.	Only for get_*	Result reads can retry; reconcile billable analyses by client token/job ID before replay.
AWS_TEXTRACT_JOB_FAILED	An asynchronous job reached FAILED.	No automatic replay	Inspect the immutable source and AWS job evidence before starting another job.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Only for get_*	Treat analysis/start outcomes as ambiguous and reconcile with the client token/job ID.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve the operation, source version, client token, job ID, and request ID.

Provider exception text is never copied into output, preventing credential echoes and unbounded provider payloads.

Example

Extract invoice fields from an immutable S3 object:

{
  "operation": "analyze_expense",
  "region": "us-west-2",
  "s3Bucket": "finance-documents",
  "s3Key": "invoices/2026/invoice-1042.pdf",
  "s3Version": "immutable-version-id"
}

Expected result shape:

{
  "status": "success",
  "operation": "analyze_expense",
  "attempts": 1,
  "pages": 1,
  "jobStatus": "SUCCEEDED",
  "modelVersion": "provider-model-version",
  "requestId": "aws-request-reference",
  "hasMore": false,
  "data": {
    "expenseDocumentCount": 1,
    "expenseDocuments": [
      {
        "expenseIndex": 1,
        "summaryFields": [
          {
            "type": {"text": "TOTAL", "confidence": 99.1},
            "value": {"text": "$125.00", "confidence": 98.7},
            "pageNumber": 1
          }
        ],
        "lineItemGroups": []
      }
    ]
  }
}

Notes

• Pagination: synchronous operations return one complete provider response. Asynchronous get_* operations expose nextToken; returnAll=true follows pages until exhaustion, limit, or 100 provider calls.
• Rate limits: Textract quotas vary by operation and region. Result reads honor a bounded RetryPolicy.maxAttempts from 1 through 5 for throttling and transient service failures. The AWS SDK's own retries are disabled so module attempt accounting remains deterministic.
• API limits: synchronous payloads are capped at 10 MiB and are intended for single-page JPEG, PNG, PDF, or TIFF input. Multipage and larger PDF/TIFF documents belong in S3 asynchronous jobs. Result pages request at most 1,000 items, accumulate at most 10,000 results, and normalize LINE text up to one million characters.
• Idempotency: every asynchronous start requires clientRequestToken. AWS reuses the same job for identical start parameters and token during its seven-day token lifetime. Changing parameters with a reused token is rejected by AWS.
• Billable ambiguity: synchronous analyses and all start_* operations are sent exactly once by the module. If the connection fails after AWS accepted a request, reconcile by the start token, job ID, immutable S3 version, and request logs before replaying.
• Destructive behavior: this connector never changes or deletes input documents, S3 objects, or Textract jobs. It does initiate billable external processing and sends document data to AWS.
• Query behavior: Textract returns all detected LINE and WORD blocks even when only structured analysis features are selected. Query results appear as QUERY_RESULT blocks linked to QUERY blocks.
• Output shape: geometry uses normalized bounding boxes and polygons. Relationships retain provider block IDs so downstream workflows can reconstruct tables, forms, and query links without receiving SDK-specific objects.
• Data handling: scanned documents and extracted fields may contain personal, financial, or regulated data. Bind only approved accounts and destinations; do not put raw blocks or expense fields into logs.
• Provider verification boundary: deterministic tests cover validation, fixed regional routing, account isolation, inline/S3 source mapping, query contracts, pagination, result-read retries, billable single-attempt behavior, normalization, redaction, registration, and job failure handling. Live AWS behavior remains unverified until an authorized Textract credential and reviewed sample document are supplied.
• Functional reference: n8n's AWS Textract node focuses on analyzing a receipt or invoice. ValkyrAI adds general OCR, forms/tables/signatures/queries/layout, immutable S3 sources, multipage asynchronous workflows, normalized blocks, explicit idempotency, bounded output, verified account enforcement, and conservative replay behavior.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsTextractModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS S3 ExecModule
• AWS Lambda ExecModule
• AWS SQS ExecModule
• AWS SNS ExecModule
• AWS DynamoDB ExecModule
• Integration Account Console