A compose script must be an object described in valid JSON syntax. It is also allowed to provide a JSONata script. Such a script will be applied to the message request and must also resolve into a valid JSON object.

Tip: use JSONata Exerciser to experiment with JSONata scripts. Place the message request body in the left (JSON) pane, write a JSONata script in the top right (JSONata) pane and check if the result of the script in the bottom right pane resolves in the intended composition script.

The rest of this document will describe the operation of the service as if plain JSON was provided.

The JSON script must have two fields: compose and primaryOutput.

The compose field must be an array with zero or more objects, each defining an operation. Operations are executed in the order in which they are specified.

Each operation object in the compose array has three required fields: operation, inputref(s) and outputref. The operation field contains the name of the operation to apply. Whether or not to use inputref or inputrefs depends on wether the operation takes a single input or multiple inputs. The outputref field assigns an ID to the result of that operation.

Depending on the specific operation, more fields may be required. See Compose operations for more details.

Note: all input and output IDs in the script must be unique. It is not allowed for operations to assign an outputref ID that is already in use by an input defined in the message request to the API or defined as outputref of another operation in the script. Also: at the moment an operation is performed, the input(s) it requires must be available (i.e. they must be provided statically in the API request, they must have been generated from a template, or they must be the result of a previous operation in the script).

Finally, the primaryOutput field in the script is an array in which exactly one ID must be listed.

At the moment of writing there are some technical limitations that may prevent some compose scripts from completing successfully or cause an error before the script is ran.

The number of compose operations in a single compose script is limited to 100. In the unlikely event that you need to perform more than 100 operations, you need to split up the script into multiple scripts and perform them sequentially. When specifying more than 100 operations, the validation will fail before the script is started.

Currently, only one primary output is accepted for a compose script. When specifying more than one primary output, the validation will fail before the script is started.

The amount of storage available to the execution environment that runs the script is limited. Since storage use depends on the number and type of inputs and operations and the size of (intermediate or final) outputs, the amount of storage required cannot be calculated in advance. When too much storage space is used when executing the script, it will fail during its run. As a guideline it is recommended to keep the total sum size of all inputs below 200 MiB.

The script’s running time is limited to 15 minutes. This time includes fetching inputs from remote locations. When providing static input documents from a custom location (e.g. as an HTTPS URL to a document in your own data center), it is recommended to ensure that such location provides fast access.

The amount of memory available to the execution environment that runs the script is limited. Memory usage depends on the size and complexity of the input documents and images and on the resulting (intermediate or final) documents. When more memory is needed than is available, the script will fail during its run, but may not produce a clear error message. Such an out-of-memory situation has not yet been seen to occur with inputs less than 200 MiB in size.

Encrypted or password-protected PDF documents cannot be used in operations. When referencing a password-protected document in an operation, the script will fail during its run.

The append operation concatenates all supplied PDF documents in the given order.

The overlay operation places an image or a PDF page on specific pages of a base document, which must be a PDF document. You can specify the location and size of the overlay and whether it should be placed on the foreground or in the background. A background overlay could, for example, be used as a watermark on a page. You can also specify on which page(s) the overlay must be applied.

The add QR barcode operation places a QR barcode on specific pages of a base document, which must be a PDF document. You can specify the location and size of the QR code. You can also specify on which page(s) the QR code must be placed.

The rescale operation reduces the size of the content of specific pages of a base document, which must be a PDF document. Note that this operation does not reduce the size of pages as a whole: pages keep their original size, but the content is scaled down. This allows for creating blank space in which, for example, an overlay or a QR code may be placed.

Distances are used as coordinates or as length specifiers. When used as a coordinate, the distance is relative to the top left corner of a document.

A distance can be expressed as an absolute value or as a contextual value. Absolute values consist of a nonnegative whole or decimal number, optionally followed by a unit. Supported units are mm (millimeter), cm (centimeter), in (inch), pt (point) and px (pixel). When no unit is specified, the value is considered to be expressed in mm. When a value is expressed in pt or px, it is interpreted at 72 dpi; so a value of 100 pt is equal to 1.389 in or 35.278 mm.

A distance can also be expressed as a contextual value: page-width or page-height. The concrete distance this resolves to depends on the page size on which the operation applies.

Example: When specifying page-width and page-height as values for the width and height arguments of the pdf_overlay operation, the overlay will be stretched to the full page size for each page in the base document, even if not all pages in that document have the same size. This can be useful to apply a watermark, for example: a PDF document with the word SPECIMEN could be applied as a background overlay to a variety of base documents without the need to match the page size of the watermark document with the page sizes of those base documents.

A page identification is a comma-separted list of pages, page ranges, or shortcuts on which an operation should apply. If nothing is specified, it depends on the operation what the default behavior will be.

A page is specified as a positive whole number where the first page in a document is treated as page 1.

A page range is either a set of two positive whole numbers separated by a dash, or an open range consisting of a single positive number and a dash. For example 5 - 10 (denoting pages 5, 6, 7, 8, 9 and 10), - 3 (denoting pages 1, 2 and 3), 3 - (denoting all pages in the document, except 1 and 2).

Finally, a page can also be specified as a shortcut: first, last, odd, even and all. Here first denotes page 1, last denotes the last page in the document, however many pages might be in it; odd denotes pages 1, 3, 5, etc; even denotes pages 2, 4, 6, etc; and all denotes all pages in the document.

Examples:

Note: a page specifier that includes more pages than are present in a base document (e.g. the range 1 - 10 applied to a base document with only three pages), or a page specifier that includes pages more than once (e.g. 1 - 5, odd, first, last, 3) has no adverse effects.

Scenario: You want to generate a sample of a document by placing the words SPECIMEN in the background.

Prerequisites: A template and datasource for the document to generate and a single-page PDF document that contains the word SPECIMEN in a shade of gray. In this sample the template is generated from Templates/invoice.sdt and receives ID basedocument. The specimen document is provided statically as PDFs/specimen.pdf and receives ID specimen.

Sample message request:

Compose script:

Note that numbers and booleans can be specified as a string or as a native value as in the example above.

The result of the request will be available in the Deliverable output object with ID watermarked.

Scenario: A customer wants to receive his digital invoices by regular mail. To prevent having to create multiple invoice templates (one for delivery as attachment to an e-mail and one with a mail address at the correct position for a windowed envelope), we generate the invoice from the regular digital invoice template and add a cover page that contains the customer’s address at the correct position. We also add a small QR code to the cover page to steer the enveloping machine. Finally, we add a pregenerated 'terms of service' page to the document.

Prerequisites: An invoice template and datasource: Templates/invoice.sdt receives ID invoice. An addressee template and datasource: Templates/addressee-cover-page.sdt receives ID addressee. A static PDF containing the terms of service: PDFs/terms-of-service-v1.3.pdf receives ID terms.

Sample message request:

Compose script:

The result of the request will be available in the Deliverable output object with ID mailable-invoice. It will be a single PDF document with the first page containing the customer’s address, the following page(s) containing the invoice information and the last page(s) containing the terms of service.

Scenario: You want to add a narrow information banner to an invoice, notifying customers of a relevant promotion or offer. Since such a promotion or offer is time-bound and may be targeted to specific customer segments, you don’t want to create multiple templates or edit templates frequently. Moreover, the marketing department that creates the promotional collateral may not be in a position to alter invoice templates. In order to add transpromo banners to invoices, we take a regular invoice statement, downscale the content slightly in the vertical dimension and add the promotional banner.

Prerequisites: An invoice template and datasource: Templates/invoice.sdt receives ID invoice. A banner image supplied by the marketing department: Marketing/promo-banner-black-friday.tiff receives ID banner.

Sample message request:

Compose script:

Note: In this sample we expect that the invoice is generated in A4 size (210 x 297 mm). We scale vertically by 0.88 with a bottom anchor, meaning that a space of 35 mm at the top of the page is freed. When placing the banner we leave a blank space of 5mm at the top of the page and make the banner fit in the next 30mm. We use a fit of aspect-down so that the banner keeps its original aspect ratio and is not scaled up (which might cause aliasing artifacts).

The result of the request will be available in the Deliverable output object with ID invoice-with-banner.

As mentioned in Formal definition, it is possible for a compose script to contain JSONata. One example of the advantage of using JSONata is that it can allow you to create reusable compose scripts that are not dependent on predefined input names or a fixed number of inputs.

Below is a compose script that appends all inputs specified in the API request. An example use case could be a request to generate PDF output from one or more templates and adding zero or more statically referenced PDF attachments.

This JSONata script is applied to the API request. Regardless of how many inputs it defines (generated from a template or provided statically), they will all be appended into a single PDF document that will be available in the Deliverable output object with ID merged.

Note: when using JSONata this way, the order in which inputs are defined in the request becomes important as it defines the order in which the documents will be appended.