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.

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.