Scriptura Engage Document Flow Steps User Guide

Table of Contents

1. Add Email Analytics Step
2. Web Designer Output Step

This user guide describes Scriptura Engage Document Flow Steps.

1. Add Email Analytics Step

The Add Email Analytics step allows the user to add email analytics in HTML output. This is usually done in combination with email HTML output to detect if an email was read and/or if certain links were visited.

1.1. Input/output types

Input: The Add Email Analytics step accepts flow objects of type Stream. The stream must contain valid HTML.
Output: The Add Email Analytics step outputs flow objects of type Stream. The stream is HTML.

1.2. Data sources

This step has no data sources.

1.3. Properties

Add Tracking Iframe: Whether or not an iframe element should be added to the HTML to track if the document was loaded.
Add Tracking Image: Whether or not an image element should be added to the HTML to track if the document was loaded.
Additional URL Parameters: Additional parameters that should be added to the original link that when rewritten.
Secret Key: The base 64 encoded key used to encrypt the metadata passed to the link tracking service.
Key ID: The ID of the encryption key.
Metadata: Additional data to be passed to the link tracking service. This will be encrypted.
Name property
Log context property
Order Information property

1.4. Configuration Properties

Additionally there are two configuration properties that can be used to change the base URL used to rewrite links and serve as the source for the tracking elements:

/config/server/link-tracking/url-rewrite-prefix: The prefix URL when rewriting links.
/config/server/link-tracking/url-static-prefix: The prefix URL to use for the tracking image or iframe that can be added to the HTML. By default, the name of the tracking image is clear.gif under this prefix, and the iframe will be iframe.html.

1.5. Remarks

For security reasons it is a good idea to disable tracking on links that contain secret information like password reset links, or any other links that automatically authorize you when clicked.

2. Web Designer Output Step

The Web Designer Output step allows the user to create output from a Scriptura Web Designer Template.

2.1. Prerequisites

The Web Designer Output step supports the following platforms:

Microsoft Windows

All 64 bit editions of the following Microsoft Windows Operating Systems:

Microsoft Windows 7 Service Pack 1.
Microsoft Windows Server 2012R2.
Microsoft Windows Server 2016.
Microsoft Windows Server 2019.
Microsoft Windows 10.

Linux x86 64bit - GTK+ 3.x

Ubuntu Linux 16.04 LTS.
Ubuntu Linux 18.04 LTS.
Red Hat Enterprise Linux 7.
Suse Linux Enterprise Server 12.

On Linux, it is necessary to manually set the right permissions on a file when using the step to generate PDF output. Please make sure the following file is executable for the user that is used to run the Scriptura Process server: <Scriptura Installation Folder>/artifacts/plugins/com.id.wbd.html2pdf.linux.x86_64_<version>/jni/princexml/bin/prince

2.2. Input/output types

Input: The Web Designer Output step accepts flow objects of type Stream. The stream must contain a valid Scriptura Web Designer template (sdt file).
Output: The Web Designer Output step outputs flow objects of type Stream. The stream corresponds to the chosen output format. HTML and PDF are supported.

2.3. Data sources

This step has no data sources.

2.4. Properties

Input format (required): The type of input document used to generate the output. This can be either 'Template' for an .sdt file, or 'Intermediate' for an intermediate file.
Output profile (optional): The name of the output profile to use when generating output. Supported profiles are:
- web-html5: Normal HTML output for use in a modern web browser
- email: HTML output optimized for viewing in an email client
- application: Self contained and interactive HTML (Actionable Communication)
- pdf: Portable Document Format version 1.5 for use in a PDF viewer
- intermediate: Self contained intermediate format that can later be used to generate the final output
Bundle CDN (optional): The base URL where external JavaScript files and other resources are located. Contact support for more information on how to obtain the necessary files.
Name property
Log context property
Order Information property

When the Input format property is set to 'Template' the following properties are available in the 'Input' category:

Template (required): The Scriptura Web Designer template to generate output for.
Data source (optional): The data source to be used when rendering the template when Data sources. This should be XML.
Override data source (required): Whether or not the data source specified in the Scriptura Web Designer template should be overriden with the data source from the Data Source property.
Theme (optional): The theme to use when generating output.

When the Input format property is set to 'Intermediate' the following property is available in the 'Input' category:

Intermediate (required): The intermediate file to generate output for. Intermediate files can be generated using the Web Designer Output Step by setting the output profile to 'intermediate'.

When the Output Profile is set to 'pdf' an additional category of properties 'PDF options' is also available:

PDF profile (optional): The PDF profile to use when generating PDF output. Generally speaking PDF/A profiles are used for archiving, PDF/X profiles are optimized for exchange and PDF/UA is used for producing PDF which is universally accessible. Supported values and their resulting PDF version are:

PDF Profile

PDF Version

PDF/A-1a

PDF 1.4

PDF/A-1b

PDF 1.4

PDF/A-3a

PDF 1.7

PDF/A-3b

PDF 1.7

PDF/UA-1

PDF 1.7

PDF/X-1a:2001

PDF 1.3

PDF/X-1a:2003

PDF 1.4

PDF/X-3:2002

PDF 1.3

PDF/X-3:2003

PDF 1.4

PDF/X-4

PDF 1.6

Author (optional): The author metadata field to be set in the generated PDF document.
Keywords (optional): The keywords metadata to embed in the PDF output used for searching. Keywords should be separated by spaces.
Title (optional): The title metadata field to be set in the generated PDF document.
Owner password (optional): The owner password to be set on the generated PDF document. The owner password is used to control changes to the document.
User password (optional): The user password to be set on the generated PDF document. The user password is used to control who can view and use the document.
Enable encryption (required): Encrypt the generated PDF document or not.
Encryption key size (optional): The key size to encrypt the PDF document with. Supported values are 40 and 128. The default is 128 bits.
Allow printing (optional): Allow the PDF document to be printed or not.
Device pixel ratio (optional): The value to use for the global devicePixelRatio when rendering HTML to PDF. This can be used for selecting the right image from a set of different quality images. See the Web Designer Themes and Pluggable Objects guide for more information and an example.
Group (optional): The group that should be used in order to determine which set of flow objects should be generated as a single PDF. When this property is not set or set to "None", every flow object that is processed by the step will produce a single PDF output. Works with SDT templates as well as intermediate file formats as input.

2.5. Configuration Properties

Additionally there are is a configuration property that can be used to change the number of worker processes to use when generating output in parallel:

/config/server/wbd/output/max-engine-pool-size: The number of worker processes to distribute the work amongst when generating output. Default is 10.
/config/server/wbd/output/engine-pool-type: The type of pool to use for worker processes. Can be either always or off. Default is off.
/config/server/wbd/output/resource-cache-size: The maximum number of resources to keep in the resource cache. The resource cache holds any resources that are loaded to generate output such as templates, themes, pluggable objects, etc. This setting will impact the amount of memory that is used. Default is 100. To turn off the cache completely, set to 0.

2.6. Optimizing Performance

There’s a number of things that can be done to optimize the performance when generating output using this step.

2.6.1. Use local resources

When the output format is PDF specifically, try to make all resources (fonts, images, css, javascript, …) available locally. This will speed up output generation because no external requests will need to be made to fetch these resources or check whether they are unchanged.

You can reference resources from your theme or css by using paths relative to the location of the Web Designer template file (.sdt).

For example:

@font-face {
    font-family: "Fira Sans Light";
    src: url('fonts/FiraSans-Light.ttf');   // location relative to .sdt
}

2.6.2. Enable pooling

When you need to generate a lot of output in parallel you should enable pooling by using the configuration option mentioned in the Configuration Properties section.

The higher you configure the pool size property, the more workers and subsequently the amount of system resources required.

Note that each worker in the pool has its own cache so if you want to optimize the pool’s performance you should make sure to warm up the pool with enough requests.

2.6.3. Populate the cache

Output generation can be sped up significantly by populating the cache by initially creating output using the templates that will be used. As long as the templates don’t change (the data and theme can change), output generation will be much faster once the cache is populated. When pooling is enabled, each worker in the pool has its own cache, so as mentioned in the previous section you will need to make sure that all workers have cached the templates that will be used most often. We recommend doing as many warmup requests for each template as the number of workers in the pool.

2.6.4. Increase the cache size

If output is generated for a lot of different templates or templates utilizing large sets of different resources, it may help to increase the resource cache size at the expense of using more memory.