Form data stencil

The form data stencil is a set of two hashes calculated from the form definition. Those data stencil hashes remain stable as long as the data fields generated when running the form definition remain the same. This is different than the fingerprint hash, which remains stable as long as the structure of the form stays the same.

The data stencil might be a bit tricky to understand, so let's start with an example to clarify this. Let's say you have created a form definition with two blocks in it. Both blocks are of the type single-line text block. The first one is called name and the second one message. When you run that form using a runner, its output is a dataset with two fields in it, both of the type string. When the block type of message is changed from single-line text to multi-line text, the structure of the form changes. Another block type is selected, and that's a structural change. The form fingerprint hash will be different. But the data fields are not. If you run this new form version, it still generates the same dataset with two fields, both of type string. So the data stencil hashes remain the same. Now another change is made to the form. A new block of type email address is added. That's again a structural change in the form, but this time also the dataset changes. This dataset now contains three fields instead of two, and so the data stencil hashes are different.

The data stencil hashes are very useful for quickly identifying similar datasets. That makes it easy to group data, for example, when exporting data to a particular format like CSV. It is hard to export two different datasets in one CSV file, but easy when the datasets have the same format.

Data stencil types

There are two types of data stencil hashes:

• exportables: Hash calculated from all the exportable fields in the dataset of a form;
• actionables: Hash calculated from all the actionable fields in the dataset of a form.

Exportable fields are all the fields generated by the blocks. This is the response data you want to save when a respondent submits a Tripetto form.

Actionable fields are a particular type of fields generated by action blocks like the mailer block. Action fields contain all the required data for executing an action. In the case of the mailer block, it contains the information for sending the email. It is generally not data that needs to be stored somewhere.

Generating the data stencil at client-side

The stencil hashes are generated by the Runner library, the engine that drives all Tripetto runners. You could generate the stencil hashes when running a form, but you can also generate them when saving a form. You then can store the stencil hashes along with the form definition if you need to. The following code shows how to do that using the calculateFingerprintAndStencil function:

import { calculateFingerprintAndStencil } from "@tripetto/runner";
import { Builder } from "@tripetto/builder";

// Generate the data stencil hashes when the form definition is saved
const builder = new Builder({
    onSave: (definition) => {
        const calculator = calculateFingerprintAndStencil(definition);
        const exportables = calculator?.stencil("exportables");
        const actionables = calculator?.stencil("actionables");

        // The stencil hashes are now available (or `undefined` when something went wrong):
        console.log(exportables);
        console.log(actionables);
    }
});

tip

In addition to the stencil hashes, we recommend that you also save the fingerprint hash of a form.

Generating the data stencil at server-side

The Runner library can also run in Node.js environments (it doesn't need a browser). So if your server-side runs Node.js you can also generate the data stencil there. For example, when you are saving a form definition to a server store.

import { calculateFingerprintAndStencil } from "@tripetto/runner";

const definition = /* Definition goes here */;
const calculator = calculateFingerprintAndStencil(definition);
const exportables = calculator?.stencil("exportables");
const actionables = calculator?.stencil("actionables");

// The stencil hashes are now available (or `undefined` when something went wrong).

tip

If you are able to generate the data stencil at server-side, always use that approach. It makes it impossible for a client to interfere with the data stencil hashes.