Articles in this section

Unattended Document Generation Using the Templafy API

Updated
Follow

About Unattended Document Generation

Templafy’s API provides an endpoint that allows a template hosted in Templafy to be generated without the need for the user to interact with the Templafy interface. Using this endpoint, ready to consume data originating from Templafy or an intermediary system can be injected into the template.

Sections in this article:

 

Prerequisites

 
  • Admin access to Templafy tenant
  • Library module enabled
  • Public API module enabled
  • Dynamics module enabled (if template utilizes Dynamics)

 

Swagger Documentation

You can access the Templafy API Swagger documentation from this link: https://api.templafy.com/?urls.primaryName=Templafy%20Public%20API%20v2%20(preview)

 

How to Use the Templafy API to generate a document

 

How to create an API token for Unattended Document Generation

In order to interact with the API to generate documents, you must generate an API key in the Templafy Admin Center

  1. Navigate to the account section
  2. In the API Keys tab, click Create key
  3. Provide a name to the key
  4. Click Next
  5. Click Add scope and select
    • library.generate: to interact with the /generate endpoint
    • library.read or library.readwrite (optional): to retrieve the folder or asset IDs
  6. Click Create
  7. Click Copy key

 

Document Generation Endpoint

The /generate endpoint allows for the generation of documents from the Templafy Template libraries (Documents, Presentation, and Spreadsheets) and Text Elements. Each document created requires its own API call. The API call will return information about the file along with a download URL. This download URL will only be valid for a short amount of time.

 

For Documents:

POST  https://<tenantId>.api.templafy.com/v2/libraries/{spaceId}/documents/assets/{assetId}/generate

Schema:

  • email (required): Email address to identify user in Templafy
  • data (optional): Data to be used in file generation
  • includePdf (optional): If value is true, the response will include a pdf download link

Returns:

  • downloadUrl (string): Temporary access URL for generated file
  • fileSize (integer): File size in bytes
  • checksum (string): MD5 checksum of the bytes
  • mimeType (string): Mime type of the generated file
  • fileExtension (string): Suffix to the name of the file
  • pdfDownloadUrl (string): Temporary access URL for generated PDF file. Only available if the file was converted to PDF

For Presentations:

POST  https://<tenantId>.api.templafy.com/v2/libraries/{spaceId}/presentations/assets/{assetId}/generate

Schema:

  • email (required): Email address to identify user in Templafy
  • data (optional): Data to be used in file generation
  • includePdf (optional): If value is true, the response will include a pdf download link

Returns:

  • downloadUrl (string): Temporary access URL for generated file
  • fileSize (integer): File size in bytes
  • checksum (string): MD5 checksum of the bytes
  • mimeType (string): Mime type of the generated file
  • fileExtension (string): Suffix to the name of the file
  • pdfDownloadUrl (string): Temporary access URL for generated PDF file. Only available if the file was converted to PDF

For Spreadsheets:

POST  https://<tenantId>.api.templafy.com/v2/libraries/{spaceId}/spreadsheets/assets/{assetId}/generate

Schema:

  • email (required): Email address to identify user in Templafy
  • data (optional): Data to be used in file generation
  • includePdf (optional): If value is true, the response will include a pdf download link

Returns:

  • downloadUrl (string): Temporary access URL for generated file
  • fileSize (integer): File size in bytes
  • checksum (string): MD5 checksum of the bytes
  • mimeType (string): Mime type of the generated file
  • fileExtension (string): Suffix to the name of the file
  • pdfDownloadUrl (string): Temporary access URL for generated PDF file. Only available if the file was converted to PDF

For Text Elements:

POST  https://<tenantId>.api.templafy.com/v2/libraries/{spaceId}/text-elements/assets/{assetId}/generate

Schema:

  • email (required): Email address to identify user in Templafy
  • data (optional): Data to be used in file generation

Returns:

  • downloadUrl (string): Temporary access URL for generated file
  • fileSize (integer): File size in bytes
  • checksum (string): MD5 checksum of the bytes
  • mimeType (string): Mime type of the generated file
  • fileExtension (string): Suffix to the name of the file
 
  • The system that calls the Templafy API must provide the email address of the relevant user. This email address must match the email address in Templafy for that user.
  • The API is not able to retrieve information on modules enabled for users (other than the Public API module).
  • The API is not able to identify the spaces or folders the identified users have access to. This may allow users to generate documents without having access to the folder or space where that template is stored.
  • The Templafy API does not support direct PDF conversion for Text Element generation.
  • There is no size limitation on the returned document, but the document creation will time out if the creation time exceeds 20 seconds. This same limitation applies when creating the document with user interaction.

 

 
  • The API can be used to generate Static or Dynamic documents, presentations, or spreadsheets. Templates which are used via the API can also be used in the document creation flow.
  • All Dynamics modules (Templates, Compile, Metadata) are supported via the API. As opposed to Text Element generation, a slide itself cannot be generated, but a presentation containing dynamic slide insertion can be generated.
  • If a custom font is used in a template, that font can be used the generated PDF if the font is uploaded to the Fonts Resource in the Templafy tenant. If the custom font used in the template is not uploaded to the tenant, a default font of Calibri will be used in the PDF.

 

How to send Data

The data that is sent in the API request must be "ready" to consume in combination with HostSystem bindings. Data cannot be transformed by using the API. Data can, however, be used in combination with all Dynamics capabilities, including looking up values from data sources, or external data sources.

The format of the sent data should follow the below example:

  "data": {
    "Language": "en-us",
    "StringField1": "Data Value 1",
    "StringField2": "Data value 2",
    "NumberField": 0003,
    "BooleanField": true,
    "DateField1": "2023-05-29T20:00:00", 
    "DateField2": "20230529"
  }

 

How to successfully generate a document

A dynamic document, presentation, or spreadsheet will successfully be created via API if the following are true:

  • HostSystem bindings can be used to retrieve the data from the request payload in the response form as a default value or in the smart fields.  {{HostSystem.FieldName}} can be used to reference data from the API in the template, but "FieldName" must match exactly between the API request and the template.
  • Each required field in the template response form must have a default value. This default value may be a HostSystem binding to include values passed from the API call.
 
  • Non-required form fields with a default value set will be populated in the document, and any non-required form fields without a default value set will remain blank in the created document.

 

What happens if document generation is unsuccessful? 

If one of the required form fields from the document doesn't have a default value, the unattended document generation will fail and result in a 400 error. The error message returned will contain a link to open the failed presentation, document, or spreadsheet in the Templafy document creation flow. 

The most common errors are:

  • 400 Bad Request : Template contains required form fields that could not be resolved by the given request.: The document being generated contains a form without default values set. This prevents the document, spreadsheet, or presentation from being generated without user interaction. 
  • 400 Bad Request : It is not possible to create a document using an incomplete user profile.:  The document references the user profile of the user account sent in the API call, but that user's profile is missing required fields.
  • 500 InternalServerError: This is a general error message that could mean a number of things. Some common causes of this error could be:
    • The document references a field with a HostSystem binding that is not present in the API request data.
    • The API request includes a null as a field's value
    • General issue with Templafy's service

 

Related articles

 

 

Related articles

Comments

0 comments

Article is closed for comments.