Terrafai v2

Provides integration with Terrafai Optica, a document-processing service that extracts structured fields using configured templates or filters.

Use the Node to extract one document immediately or submit an asynchronous job and retrieve its status and result.

Revision History

0.0.0.11 - Updated Runtime compatibility.
0.0.0.5 - Sends file media types for supported document extensions.
0.0.0.8 - Uses Flowgear.Message for upload status text.

Connection

Property Type Description
BaseUrl String HTTPS API origin for the environment containing your templates. Defaults to https://api-dev.terrafai.com.
ApiKey Masked API key from the same application environment as the selected template or filter.

Setup Notes

Create a template or filter in the target Terrafai environment, then configure the Connection with that environment's API origin and key. This Node supports Cloud and Local Runtimes.

The Connection test checks /health for reachability only; it does not verify the API key or extraction permissions. Select a template and supply a document and routing name before running. Webhook delivery requires an active webhook in the same application environment.

Methods

ExtractFields

Uploads one document and waits for the extraction result in the same request.

Parameter Type Description
Connection Connection Connection used to authenticate the operation.
DocumentName String Filename including its extension. Supported media-type mappings include PDF, JPEG, PNG, BMP, TIFF, Word, and text.
Document Stream Binary document content, read from its current position. The stream remains open.
Options Object Set exactly one of templateName or filterName to an existing name. See extraction options below.
Return Type Description
Response Object The complete provider envelope plus Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request. Request metadata contains DocumentName and Options, excluding passwords and document bytes.

CreateJob

Uploads one document for asynchronous processing. This call submits the job once; it does not poll for completion.

Parameter Type Description
Connection Connection Connection used to authenticate the operation.
DocumentName String Filename including its extension. Supported media-type mappings include PDF, JPEG, PNG, BMP, TIFF, Word, and text.
Document Stream Binary document content, read from its current position. The stream remains open.
Options Object Set exactly one of templateName or filterName to an existing name. See extraction options below.
IdempotencyKey String Optional stable key when retrying the same document and settings.
ClientReference String Optional caller reference included with the job.
Return Type Description
Response Object Provider job envelope, including job.id, with the same safe upload metadata as ExtractFields. Retain the job identifier for subsequent reads.

GetJobStatus

Reads an existing job once.

Parameter Type Description
Connection Connection Connection used to authenticate the operation.
JobId String The job.id returned by CreateJob.
Return Type Description
Response Object Provider status envelope, including job state and available polling information, without added Flowgear metadata.

GetJobResult

Retrieves a completed job result after resultAvailable=true.

Parameter Type Description
Connection Connection Connection used to authenticate the operation.
JobId String Identifier of the completed job in the same environment.
Return Type Description
Response Object The complete provider result envelope without added Flowgear metadata. Extracted fields depend on the selected template or filter.

Usage Notes

Extraction options

Property Type Description
templateName String Exact template name; supply this or filterName, not both.
filterName String Exact filter name; supply this or templateName, not both.
documentSplitting Boolean Optional document-splitting control. Templates default to false.
returnDocuments Boolean Optional inclusion of documents in the provider response.
returnText Boolean Optional inclusion of extracted text.
schemaChunking String Optional auto or combined.
password String Optional password for the submitted document. Excluded from echoed request metadata.
deliveryMode String For CreateJob: poll or webhook.
documentReview Integer For CreateJob: 1 to 99; omit to disable review.

Polling a job

  1. Run CreateJob and retain Response.job.id.
  2. Run GetJobStatus with that identifier. For queued or processing, wait according to retryAfterMs before checking again.
  3. For review_required, complete approval in the Terrafai application. Investigate failed jobs.
  4. Run GetJobResult only when the job is completed and resultAvailable=true.

Each method performs one request. HTTP errors fail the invocation. A result response of HTTP 409 means unavailable, 410 means expired, and 404 means the job was not found in the selected environment.

Requests have a ten-minute timeout. There are no automatic submission retries. A timeout or cancellation does not establish whether Terrafai processed the document; check the existing job before resubmitting.