Dynamic Documents

Once you have specified a document as dynamic, you can upload a template that Socotra will inject with data when it renders the document. Dynamic documents pass through stages as the platform generates instances, including the following:

dataReady: all the data to be made available to the document template has been persisted, including any additional data or metadata specified by the Document Data Snapshot Plugin.
ready: the document has been rendered and can be downloaded from the platform.

Template Languages

Dynamic document templates can be written in Liquid or Velocity templating languages. Socotra offers several dedicated endpoints to create new dynamic document templates or to update existing ones.

Velocity Example

Suppose you wish to include a summary document on every issued quote that includes the name of the product. Here’s a basic template:

Summary for Product $data.productName

Lorem ipsum...

Note

You can provide HTML markup in your templates, including references to external resources like stylesheets and images. Examples in this guide are deliberately concise.

After you upload the template with a name in an applicable resource group configuration and create a quote, you’ll see the document appear as a DocumentInstanceResponse in the list returned by Fetch Documents for Quote. The renderingData property will contain a map of the data object available to the template. The documentInstanceState property changes as the document passes through the rendering cycle, with the successful ready state indicating that the rendered document can be downloaded from the platform. Rendered documents can be retrieved with the Fetch Document Resource endpoint.

Data in renderingData can be referenced from the data object in the Velocity template. For example, given renderingData like the following:

{
    "groupLocator": "01J8JXETQSQHCH2W62BHXEKFR1",
    "underwritingStatus": "none",
    "currency": "USD",
    "accountLocator": "01J8GC55Y1VYVTKSW1FY85NR53",
    "durationBasis": "months",
    "billingLevel": "inherit",
    "productName": "Commercial"
}

You could reference any of the values in the template with $data.productName, $data.currency, $data.startTime, and so on. Similarly, you can use any of the standard Velocity statements to traverse the data tree and iterate over elements. For instance, if you had an array of insureds in renderingData, each of which had lastName and location data fields, you could display an HTML summary list of insured last names and locations like this:

<ul>
#foreach ($insured in $data.insureds)
    <li>${insured.data.lastName}: $insured.data.location</li>
#end
</ul>

Controlling Template Data

The Document Data Snapshot plugin allows you to modify or augment both the data and metadata available to document templates.

Document Snippets

You can define reusable document snippets for inclusion in your templates, using the typical syntax for Liquid or Velocity. For example, after configuring and uploading snippets, you may include them in Velocity templates with the #parse or #include directives. You can also include snippets in bootstrap configuration, just as you can with other document templates.

Document snippets can be included in the bootstrap configuration, and managed in a fashion similar to other document resources. In document templates, you refer to snippets for inclusion by static name, using the usual syntax for such references (e.g. in Velocity, the #parse or #include directives), and rely upon the platform’s resource selection facilities to include the correct instance of the snippet.

Snippets Example (Velocity)

Suppose you would like to include a footer snippet in a document template, and decide that the static name of the snippet will be footer. First, update your main document template to include the footer with either #include or #parse, like this:

#parse( "footer" )

Next, update your top-level configuration to define the snippet:

{
    // ...,
    "templateSnippets": {
        "footer": {
            "selectionTimeBasis": "policyStartTime"
        }
    },
    // ...,
}

Then include the snippet name in the templateSnippets array in the requisite DocumentConfigRef:

{
    // ...,
    "templateSnippets": ["footer"],
    // ...,
}

After deploying, you can upload instances of your snippet. There are snippet-specific upload endpoints for both Velocity and Liquid. After uploading instances, assign them to appropriate resource groups so that the expected instance is included in the document when the document is rendered.

Custom Fonts

You may include custom fonts in document templates intended for PDF rendering. Custom fonts are managed as a resource.

In order to use a custom font, declare a static name for the font in the customFonts array in the top-level configuration. For any documents that require the custom font, add the static name to the DocumentConfigRef customFonts array.

After deploying the configuration, you can upload the font as a resource with the Add Font endpoint, in TTF or OTF format. Then you can add the font to one or more resource groups.

Note

The selectionTimeBasis for custom fonts is always now.

Templates can reference custom fonts just as they would in any other context. For example, a Velocity template could specify CSS styling like this:

.custom {
    font-family: "Faculty Glyphic", sans-serif;
    font-weight: 400;
    font-style: normal;
}

If the “Faculty Glyphic” font was configured as specified, then the custom font will render as expected. If the font cannot be found, the platform will default to rendering with standard fonts.

Troubleshooting and Template Development

Socotra enforces Velocity’s strict rendering option.

Streamlining the rendering feedback loop

You can use the ad-hoc document rendering endpoint to see how a template would be rendered against a given reference item, such as a quote, policy, or term. This can help with troubleshooting and template refinement since you don’t have to conduct any actual transactions to induce document rendering for testing purposes.