Document Creation Service (Spec)

Introduction

While the enfore platform provides a built-in capability to generate business documents that can then be printed or shared via email/SMS, it does not allow for an in-depth customization of such documents.

For merchants that want to have full control about the design and content of the generated documents, the enfore platform allows the inclusion of an external service for the creation of documents. That service is called a "Document Creation Service" (DCS) and must implement the "enfore Document Creation Service"-API.

The DCS must be configured for the organization and the configuration must specify for which business document types the service is to be used. This allows the service to only be used for those types of documents where custom design or content are necessary and frees the implementor of the service from the need to support all 30+ business document types.

While an instance of the custom document creation service must be available via the internet from the enfore Cloud, additional instances can be configured for each POS location. Those local instances are then used by the clients running at their POS location and are thus accessed via the local network. This enables full offline capability, provided the custom document creation service does work offline.

The following diagam shows the components and their relationships in a setup with local DCS instances:

Given this setup, the main use case is the creation and printing of an invoice document as part of the checkout of a sales order:

In the "receipt step" of the enforePOS checkout & payment flow, the enforePOS client requests the creation of the invoice document (1). The request will contain the invoice data (customer, amounts, line items, etc), the output format that the generated document is expected to have (e.g., A4 PDF) as well as context information (e.g., the organization, POS location and register the client is running on).

The DCS is expected to return the generated docment binary and, optionally, some "external data" (2). The external data will be persisted in the enfore platform together with the business document data so that it can later be passed back to the DCS in case a new document binary is needed.

This re-requesting of a document binary is needed because a) a document binary for a different output format may be needed and b) the enforePOS client will not upload the generated document binary to the enfore server as port of storing the invoice data (4).

The binary is not uploaded to avoid potential problems with limited network bandwith.

Note that, as the document is not uploaded to the enfore server, a later request to send the document via email (for example), requires a new document binary to be generated:

Design decisions

The current version of the DCS API has been designed around some decisions that have been made to be able to provide a useful API but not impose excessive requirements on the implementors and users of the API.

Directly returning document binary

The current DCS API requires the service to directly return the generated document binary in the response to the "createDocument" request.

While this requires the HTTP request/response to "wait" for the document generation, it avoids the need to implement a complete "job management" API with a "create job, poll status, download result" loop.

Document creation is expected to be done in less than 2 seconds and "parked" HTTP connections do not use up much resources, so the benefit of a simpler and easier to implement and use API should outweigh the drawbacks.

As a future extension, the requirement for the direct return of the document binary may be replaced with an option to return a "job ID" instead. Additional API for querying job status and downloading the binary will then need to be added.

Not uploading document binary

The enforePOS client will not upload the document binary to the enfore server platform. Instead, the enfore server platform will (re-)request the binary from the cloud-based DCS instance.

This is done as storing and uploading the document binaries on the client side imposes significant storage and bandwith requirements. Especially for the offline-capabale enforePOS2 clients, storing and uploading 100+ documents is not feasible.

Additionally, even if the design would include the document being uploaded from the client, the enfore server platform must be able to request documents directly from the DCS as the client will only invoke the DCS if the document is to be printed as part of the checkout. If the user chooses to not print the document during checkout, no document binary will be created as that would only slow down the checkout. Instead, the document will then be created only if explicitly requested via some action in the sales history.

No support for receipt output format

The current API does not define the parameters for the receipt output format. While the DCS will need to support creation of receipt printer documents at some point, this isn't necessary for the first roll-out as only page printers are used there.

Versioning

The DCS API supports versioning in two places:

  • the actual OpenAPI endpoints
  • the document data structures

Those versions will get increased separately, making them semi-independent. Note that they are not fully independent as specific versions of the document data structures may only be uable with specific versions of the OpenAPI endpoints.

The "createDocument" operation

For now, the DCS-API consists of just the "createDocument" operation. For this operation, a client executes a POST request against the DCS and provides the following information:

  • Request ID
  • Document Type Identifier
  • Document Data
  • Meta Data
  • Locale
  • Output Format
  • (optional) External Data
  • (optional) Duplicate Flag

The response is expected to be multipart/form-data consisting of one or two parts. The mandatory part named binary must contain the generated document binary and use content type application/octet-stream or application/pdf. Optionally, the DCS can provide an "external data" via a part named external_data using content type text/plain. The parts can be in any order, they must be identified by their Content-Disposition header field.

For example, a "createDocument" response may look like:

content-type: multipart/form-data; boundary="BOUNDARY"

--BOUNDARY
content-type: text/plain
content-disposition: form-data; name="external_data"

This is external data...
--BOUNDARY
content-type: application/pdf
content-disposition: form-data; name="binary"

<<< binary data of PDF >>>
--BOUNDARY--

Security considerations

Offloading the creation of business document binaries to an external service requires both the enforePOS clien/enfore server platform that calls the DCS as well as the DCS that is being called to trust the other part.

The enforePOS client/enfore server platform must ensure that it is receiving document binaries from a trusted DCS source as it is unable to verify the contents of the binary (e.g., PDF). Otherwise, the system may print documents stating information that is not true.

Similarly, the DCS must ensure it only creates document binaries for a trusted client (enforePOS client or enfore server platform) as otherwise it could be used to create documents for business operations that have not happened or documents that contain data different from what actually happened.

The exact means of establishing two-way trust will still need to be worked out. Options that have been mentioned are:

  • client -> DCS
    • Use of client certificates
    • Use of authorization header
    • add cryptographic signature in application layer (i.e., part of request)
  • DCS -> client
    • rely on HTTPS
    • add cryptographic signature in application layer (i.e., part of response)