Template Caching Reference

As of 22.3+, the RESTful engine has the ability to store templates, and then load them into memory for better performance, as well as eliminating the need to always include the template in all your requests. The way it works is we have a template repository that you can add templates to, and when you use that template for the first time, it loads it in memory.

Adding a Template#

To add a template to the template repository, use the POST v2/templates endpoint. The templates endpoint deals with the CachedTemplate model for the request body. The model contains the following:

  • TemplateID: The identifier associated with the template. This will be used later to call on the stored template.
  • ConnectionString: This is the connection string to the template if it is hosted somewhere. (Either populate the ConnectionString or the Data, not both)
  • Data: Is the base64 encoded data of the template (Either populate Data or ConnectionString, not both) (You can see this in our SwaggerDocumentation)

Here is an example of a request body that makes use of the ConnectionString

<CachedTemplate>
    <ConnectionString>https://windward-private-bucket.s3.amazonaws.com/Southwind_JSON.docx</ConnectionString>
    <TemplateID>testing</TemplateID>
</CachedTemplate>
note

Take note of the TemplateID you select because that's how you will interact with the stored template. By default, the templates are stored in the App_Data/cahce/ directory in your RESTful install.

Using a Stored Template#

In order to use a stored template when posting a request for processing, you will need to supply the following URI in the ConnectionString entry in the request body:

file://templates/{TEMPLATE_ID}

Where {TEMPLATE_ID} is the TemplateID you assigned when adding the template to the template repository. Here is an example request body using the template we added in the previous section:

<Template>
    <ConnectionString>file://templates/testing</ConnectionString>
    <OutputFormat>pdf</OutputFormat>
    <Datasources>
        <Datasource>
            .
            .
            .
        </Datasource>
    </Datasources>
</Template>

What this does is it tells the RESTful engine to check if the template is already loaded in memory. If it is not, it will check the template repository to see if that template exists. If it does, then it will load the template into memory and use that. For all requests going forward that use this template, the engine will use the template loaded in memory for better performance (unless the cache was cleared, covered in a later section).

Getting a Template from the Template Store#

If you want to get a template stored in the template repository, you can make use of the GET /v2/templates/{TEMPLATE_ID} endpoint. This endpoint, upon successful execution, will return a CachedTemplate with the template TemplateID as well as the template Data as a base64 encoded string.

Deleting a Template from the Template Store#

If you want to delete a template stored from the template repository, you can make use of the DELETE /v2/templates/{TEMPLATE_ID} endpoint. This endpoint, upon successful execution, will delete the template associated with the provided TEMPLATE_ID will delete the template from the template storage.

note

This endpoint does not remove templates from memory, only from the template storage. Templates are removed from memory when the cache is cleared (covered in the next section).

Clearing the Cache#

In order to clear the cache, we have a properly called mins-clear-cache. This property determines how often the templates are cleared from memory, and defaults to 5 minutes. If you want to change how frequently the cache is cleared, please change this property.

To set the property in the .NET RESTful Engine:

  • In the <AppSettings> section of the Web.config file for the RESTful engine, add the following:
<add key="mins-clear-cache" value="" />

To set the property in the Java RESTful Engine:

  • In the WindwardReports.properties file for the RESTful engine, add the following:
mins-clear-cache=XX

Where XX is the number of minutes you want the cache to clear after

important

If you are making use of a custom repository plugin, you will need to implement 3 new methods:

  • SaveTemplate
  • GetTemplate
  • DeleteTemplate

You can see an example of this in our S3 Repository Github samples: