Distribution and post processing

The Pages API also exposes endpoints for document distribution. Documents can either be:

• Distributed instantly, or
• Stored in the Interact Dynamo database for postponed distribution and additional post-processing.

The common parts of every call, such as the path, the token and the response codes, are on Calling the Pages API. Paths on this page leave out the optional environment group.

Using the Dynamo database, businesses can for instance cancel (“regret”) a distribution before the scheduled batch is executed.

Instant distribution

If configured for instant distribution, documents are immediately sent to the Omnichannel service for further processing.

This setup will enable:

• Archiving to an on-premise or Metaforce archiving service
• Distribution to a digital mailbox, PSP, or other central services

Post processing, postponed distribution

If configured for postponed distribution, documents are sent to the Interact Dynamo service for further post-processing and are finally distributed in a scheduled batch.

This setup will enable:

• The option to cancel distributions or alter metadata before the batch runs
• Archiving to an on-premise or Metaforce archiving service
• Distribution to a digital mailbox, PSP, or other central services

Distribution endpoints

There are 5 endpoints specifically for doing distribution. The logic file decides where the document goes. When the document’s DISTRIBUTION index is CentralDistribution, Pages checks whether the receiver has a digital mailbox and sends the document accordingly. Sending to a digital mailbox needs a fallback print provider.

Send a document

The body has the fields of an on-demand request (MetaFile, Document, DataAsBase64, optional AttributeStoreKey, Source and Attachments) and one more:

This example sends XML data to distribute/send:

{
  "MetaFile": "OrderConfirmations",
  "Document": "OrderConfirmation",
  "DataAsBase64": "PE9yZGVyPjxDdXN0b21lcj5Ob3JkbHlzIEFTPC9DdXN0b21lcj48TnVtYmVyPjEwMDQyPC9OdW1iZXI+PC9PcmRlcj4=",
  "Id": "order-10042"
}

The call returns 202 Accepted when Pages has taken the request. The response has these fields:

Like the other document calls, a send can return 204 (no document), 406 (missing logic) and 429 (too many calls).

Send without duplicates

A network failure can leave you unsure whether a call reached Pages. The idempotent calls let you repeat a call safely. They are PUT calls, and the body has one more required field:

If Pages has already seen the same ExternalCorrelationId from the same caller, company, environment and environment group within the last 24 hours, it does not distribute the document again. It returns the stored result instead. A call that failed before is run again.

The response has ExternalCorrelationId, CorrelationId, JobId, DocId and a RequestState. Match it to your request by ExternalCorrelationId.

Mark a distribution ready

PUT /{customerEnvironment}/distribute/setconotificationready/{correlationId}

Sets the distribution with that CorrelationId to ready. The call returns 200, or 404 when no distribution has that id. It counts toward the rate limit like the send calls, so it can also return 429.

Post processing

A selected number of post processing services are described below. For a full list of services see the Pages API documentation at https://webeditor.metaforce.net/documentation-api. These endpoints let you create, read, update and delete documents in a Dynamo database. Creating a document from XML or JSON data is limited by the rate limit for Dynamo calls.

Create documents in Dynamo

The response has the JobId and DocId of the new document. Use them in the calls below.

Search

POST /{customerEnvironment}/dynamo/search

Searches the Dynamo according to the posted search model. The response will contain the document metadata based on the defined database schema in the Dynamo including the JOBID/DOCID. The JOBID/DOCID can be used for the read, update and delete calls.

The body has Top (the most rows to return), WhereConditions, and optionally Sorters and ResultColumns. Use the column names from the folder definition in WhereConditions, and the display names in ResultColumns. Add the query parameter flattenSearchResult=true to get a flat result. A search that finds nothing is not an error: it returns no rows.

Read a document

Change or cancel a document

The update and delete calls return the number of rows they changed. A successful delete of one document returns 1.

Read the folder definition

GET /{customerEnvironment}/dynamo/folder/{folderName}

Returns the folder model, which is the same as the schema, for a Dynamo folder. Use it to see the column names for a search or an update.