Silverfin Integration for developers

The following section describes how to use Silverfin Templating Language to ensure a correct types match is achieved in Penneo.

Silverfin Templating Language (STL)

Thanks to Silverfin Templating Language it is possible to instruct the integration to assign Penneo's signing flows, document types and signers roles to the caseFiles created from Silverfin documents via the integration.

For more information about Silverfin Templating Language see the docs at developer.silverfin.com.

Signing Flows

To ensure the correct signing flow (also called caseFileType in our API) a specific liquid code tag, the signing_workflow, must be set in the document or reconciliation template.

For example:

Liquid Code

{% result "signing_workflow" "Annual Accounts" %}

This will instruct the integration to automatically select the Annual Accounts signing flow in Penneo when creating the caseFile.

Note: the caseFileType must be enabled and visible/selectable in the Penneo account in which the user is creating the caseFile. If not, please contact our support centre and ask for the enablement of the correct signing flow.

Sending multiple documents/reconciliations

Since the above-mentioned tag is on the document/reconciliation level, if your user sends multiple documents to Penneo, the integration will loop through the documents to find the first available tag to identify which signing flow to use.

For this reason is highly recommended to include the signing_workflow tag in all the templates that refer to the same documents' export or reconciliations' workflow.

Document types

For the document type use the signing_doc_name tag.

Liquid Code

{% result "signing_doc_name" "Annual Report" %}

This will instruct the integration to automatically select the Annual Report type for the document uploaded in the previously created Simple Document caseFile.

Signers and Signers' roles

For the signers and their roles use the signmarker tag.

Liquid Code

{% signmarker name:"Anna Andersen" email:"[email protected]" role:"Shareholder" %}

This will instruct the integration to automatically add a signer, with name and email, to the Penneo caseFile, specifying the Shareholder role.

Read more about signmarker on Silverfin STL documentation.

🚧

Matching is done by string comparison!

Our integration will compare the value for the caseFileType, documentType or signerRole from Silverfin with what is available in Penneo based on a basic string comparison.

Please always ensure the string are technically equal (spelling, capital letters, non-latin characters) or the match will fail.

Copy recipients

The copy recipients functionality uses a combination of the capture tag and the custom tag penneo_copyrecipients.

In the following example, the capture tag will store a JSON array in a variable called copyrecipients which is then passed to the penneo_copyrecipients tag which is what the integration will read.

This will instruct the integration to add two copy recipients, with name and email, to the Penneo caseFile.

Liquid Code

{% capture copyrecipients %}[{"name":"Mette Mortensen","email":"[email protected]"},{"name":"Maria Jensen","email":"[email protected]"}]{% endcapture %}
{% result "penneo_copyrecipients" copyrecipients %}

Language

In permanent texts

During the import of documents, the integration will look for a specific result tag called language_var, expecting an ISO-639-1 valid language code, for example en, nl or fr.

If the language_var result tag is not found or an invalid language is provided, the integration will fallback to English as default.

Liquid Code

{% result "language_var" "nl" %}

This will then affect the preselected language for the caseFile created in Penneo, which will also determine, for example, the language in the email sent to the signer.

In reconciliations

Reconciliations use a slightly different approach, where using the language_var might not be the best approach and might not work at all.

Our integration is configured to work with the approach used by the standard Legal Documents handled by Silverfin, so in case of custom reconciliations, you might want to replicate the same approach.

The integration will use the Accept-Language header when fetching the documents from Silverfin, so to obtain them in the correct language, it needs first to know which language to use.

To do so, the integration will look for a specific reconciliation with a handle that includes the string company_information (like for the Legal Documents there is a reconciliation with the handle be_legal_company_information), commonly used to handle the language selection for the reconciliations of a workflow.

We suggest creating a reconciliation text with a handle like your_unique_handle_name_company_information or company_information_your_unique_handle_name.

The integration will then look for that reconciliation and search for relevant result tags or custom properties.

Regardless of how you want to handle the language in your company information reconciliation, the integration will first search for result tags named legal_doc_language (used by the Legal Documents) or language_var.

If that fails, the integration will search for a custom property with the namespace language and get the value.

Ultimately, if all the above fails, the integration will use the user's locale (controlled by the language button in the top-right menu in Silverfin).

Example in Liquid Code

Create a reconciliation_text with handle your_unique_handle_name_company_information.

In the main body, include something like this, so that the accountant can select the appropriate language:

Liquid Code

Select language: {% input custom.language.value as:select options:"English|Nederlands|French" option_values:"en|nl|fr" default:"en" required:true %}

The integration will now be able to pick up the correct language.

To use the language in one of the reconciliations, use:

Liquid Code

{% capture selected_language %}
    {{ period.reconciliations.your_unique_handle_name_company_information.custom.language.value | default:"en" }}
{% endcapture %}

For more info, please refer to Translations and Translations in dropdowns from the official Silverfin developers documentation.