Pages
Pages creates documents (print and PDF) from your business data, in high volumes or on demand. You call it over REST from your own systems, and the documents are built from templates that you develop in Metatool.
Overview
The Pages module is a suite of programs that provides streamlined document production (print/PDF) for high volumes and on-demand needs, using data from all your business systems. It enables object-oriented and dynamic template development with the Metatool application for quick deployment and easy maintenance without IT intervention.
Pages Architecture
The Editor is a React application and the Pages API is an ASP.NET Core application. Your system calls the Pages API, the Editor calls it too, and the Pages API builds the documents with the document engine. All applications run in containers.
Services
The services exposed by the Pages API let your system create and distribute written communication efficiently.
The services can be grouped into three categories:
-
Interactive document editing and management. See Editor integration.
-
On-demand document creation. See On-demand documents.
-
Distribution and post processing. See Distribution and post processing.
The API also reads what a logic file offers (Template information) and gives access to the connected archive (Archive). What every call has in common is on Calling the Pages API.
Regarding the interactive use case the Editor is a lightweight browser based editor which allows the user to edit the document instance as a web document before approving and distributing it. See Editor documentation for more information.
Performance and caching
To maximize performance, Pages API configurations retrieved from the Doc Gen APIs are cached with a timeout of 10 minutes. Caching balances optimization with the ability to update configurations. Any configuration change takes effect when the cache expires or immediately if the object was not previously cached.
Limitations
To prevent service overload, the system enforces size limits on the following items:
| Item | Maximum size |
|---|---|
| Generated DXML file (generated when initializing an Editor session) | 7,000,000 bytes (about 6.7 MB) |
| DXML file and all attachments together | 30,000,000 bytes (about 28.6 MB) |
| Individual PDF attachment | 2,000,000 bytes (about 1.9 MB) |
| Individual AXML attachment | 10,000,000 bytes (about 9.5 MB) |
The limits can differ between installations. A document or attachment over a limit is refused with error (072), (073) or (080). See Error codes.
The size of the generated DXML for a specific document template can easily be tested by the document developer by printing from Metatool, selecting the DXML_WEB output channel, and then checking the file size of the resulting XML file.
These limitations are in place to help users understand the allowable sizes for different items, ensuring smooth and reliable operation within the system. The limits on how many calls you can make are described on Calling the Pages API.
Data retention policies
Data stored for editing is retained for 5 days by default. When the environment has a retention policy set in CenterPoint, the days of that policy are used instead.
Data stored in the Pages/Interact Dynamo will be retained up to the point when the batch is run. This period is usually configured to be no more than 24 hours.
Security
For general security of getting access tokens to access the Pages API, please refer to the REST API documentation.
Extra Editor security - JWT Authentication
As an added security concerning Editor one can configure the Editor environment to require a JWT Authentication when opening an Editor session. The generated JWT exchange token is valid for a short period of time and is received when a new Editor session is created. The JWT exchange token is replaced by a proper session token by the React client in the initial phase. A JWT exchange token can be retrieved later on if one wants to open an older Editor session. Note that Require JWT Authentication can be configured per environment. The enhanced Editor security is a good thing since it makes sure that only users of your system can access your active document instances.
JWT token lifecycle
The JWT authentication flow follows an exchange token pattern with two distinct token types:
1. Exchange token (short-lived)
When a new Editor session is created via the Pages API, a JWT exchange token is generated and returned alongside the StartURL.
This exchange token is valid for 30 seconds and is tied to the specific document instance (via the start parameter).
The client appends this token to the StartURL as a query parameter (?jwt=<token>) when opening the Editor.
2. Session token (long-lived)
When the Editor is opened with a valid exchange token, the system automatically exchanges it for a session token. This happens transparently in the initial page load. The exchange token is validated and a new session token with a 24-hour validity is issued. The session token is returned to the client via a response header and is used for all subsequent requests during the editing session.
3. Session expiration
The session token expires after 24 hours from the time of issuance. There is no explicit logout or server-side session invalidation. The session is considered ended once the token expires. The token is cryptographically bound to the specific document instance, meaning a session token for one document cannot be used to access another.
Note that the document instance itself has a separate retention period (default 5 days, or the days of the environment’s retention policy), after which the instance and its data are cleaned up regardless of token validity.
A new exchange token can be retrieved at any time using the endpoint described in the section Retrieving a new JWT token, for example to resume editing a document instance after the original session token has expired.
If “Require JWT Authentication” is on for an environment but no signing key is configured for the Editor, the call fails with error (081). Contact support.