REFRACT Dispatch

REFRACT Dispatch extends the REFRACT PDF render engine with a governed batch layer. Rather than submitting one document at a time, you submit an array of records in a single POST /api/render call. REFRACT Dispatch validates the records, generates a batch intake receipt, routes to an approver (when configured), and - after approval - hands off to the Processor to render and deliver each document independently.

What REFRACT Dispatch Does

Batch Lifecycle States

Template Distribution Settings

Batch dispatch is controlled by a distribution block in the template's templateSettings. This block can be set in the .rpkg template file or overridden per request in templateSettings.distribution.

{
  "templateSettings": {
    "distribution": {
      "mode": "individual",
      "requireApproval": true,
      "fileNameTemplate": "Statement_{{accountNumber}}_{BATCHID_1}",
      "approversEmail": "ap-approver@contoso.com",
      "validationFields": ["accountNumber", "balance"],
      "deliveryConfig": {
        "mode": "secure-email",
        "expiresInHours": 168
      },
      "zipBundle": false
    }
  }
}

How Batch Intake Works

Batch dispatch is triggered via the standard render endpoint with an array dataSource and the vaultDispatch feature enabled.

Delivery Results

When a batch sends its documents to recipients, the outcome of each recipient's invitation email is reported back to the batch and recorded on the batch's audit chain, one event per recipient per document.

A failed result can later be followed by a sent one for the same recipient and document, for example when a dead-lettered invitation is resubmitted by hand and then sent; that recipient counts as sent. A failed result is never recorded after a sent one.

When results appear. With the default shared email service, your Processor collects results from REFRACT's notification service every 2 minutes, so a sent result can take about 2 minutes to appear. Failures appear only after the last automatic retry, or at the next 5-minute check for dead-lettered messages, so they can take longer. With EMAIL_PROVIDER=customer-acs, your Processor sends the email itself and records the result straight away. A result that is never collected is deleted from REFRACT's service after 30 days. The batch view in REFRACT Lifecycle does not refresh by itself: select Refresh to see new results.

Where to see them

Open the batch's record in REFRACT Lifecycle and go to the Batch Timeline tab. Batch records require the Lifecycle.Reader role.

• The Completed entry summarises the batch, for example "2 documents stored and queued for delivery, 1 failed." followed by "Delivery: 5 sent, 1 failed, 2 pending." The same delivery summary appears as the Delivery row on the Properties tab and the Delivery figure in Dispatch Review. For a batch whose recipient counts were not recorded, pending reads "pending not known".
• Failed recipients are listed under the Completed entry, one line for each recipient whose latest result is a failure, with the record number, a short recipient identifier, the stage it failed at, and the error code. Sent recipients get no line, at any batch size: they are counted in the summary and recorded on the audit chain.
• The Audit chain card below the timeline lists every event on the batch's chain, every delivery result included, 50 per page, with Export, and states whether the chain verifies, for example "Verified: N events, each signed and chained to the one before." A delivery event's title names the record and recipient ("Delivery sent after a failure" when it follows one). A sent event reads "accepted by the email service at time · recorded time"; a failure gives the stage, error code, and reporting service with the same two times. The first time is when the email service reported the result and the second is when it was added to the chain, so they can differ by up to the 2-minute collection interval.

What the chain records

Each result is a BATCH_DOCUMENT_DELIVERY_SENT or BATCH_DOCUMENT_DELIVERY_FAILED event carrying the record number, the document's correlation ID, the recipient's identifier, which service reported it, and when; a failure also carries the stage and error code. The recipient identifier is a keyed hash of the address (HMAC-SHA256 of the trimmed, lower-cased address, under a key derived from your deployment's audit key), never the address itself. Your Processor computes it, so REFRACT's notification service holds only the finished hash and never the key. To read results through the API, see deliveryResults on Get Batch and kind=delivery on Get Audit Chain.

Decision comments

An approver's comments are limited to 1,000 characters, not counting leading and trailing spaces. The Dispatch Review shows a running count ("n / 1,000 characters") and disables Submit Decision while the comments are over the limit. The API refuses longer comments with 400 and code DECISION_COMMENTS_TOO_LONG, and the batch is not changed.

The batch's audit chain records a SHA-256 hash of the comments and their length, not the text. The text itself is kept with the batch record. REFRACT Lifecycle shows comments as plain text with their line breaks kept.

Per-Record Data Requirements

Each record in the dataSource array is a plain JSON object. The fields available depend on the template, but two fields have special meaning for REFRACT Dispatch:

The documentIdTemplate option in options allows dynamic document IDs per record using {{fieldName}} tokens:

{
  "options": {
    "documentIdTemplate": "STMT-{{accountNumber}}"
  }
}