Templates

summary

After reading this, you can explain how templates work.

Introduction

Templates are blueprints for CashBoxes. They provide a fast way to set up fully configured CashBoxes based on pre-configured layouts.

Templates follow the same JSON structure as shown in the CashBox chapter, with the main difference that they are not the configuration of an actual CashBox instance but are used to create such in a second step. Consequently, their configuration entries are either hardcoded default values, used for all instances created with the respective template, or variables set at runtime.

Instantiating a template

There are two different ways you can use templates to create a new CashBox.

Shop

You'll find a number of pre-configured templates in the shop under Shop / Products. Either fiskaltrust, PosCreators, or PosDealers provided these templates. You can add them to your shopping cart like any other product or clone them to modify them for your needs. After submitting your order, the portal will create a new CashBox based on the template's configuration.

Please see the chapter Shop Templating for more details.

API

Another way to create CashBoxes based on templates is to use fiskaltrust's REST API. You do not need to pre-configure any template in the portal in this case but can send custom templates with your requests.

Please see the chapter API Templating for more details.

Variables

Variables are substitute entries for dynamically configured values. Your rollout replaces these with actual content. You denote a variable by its name being wrapped into |[ and ]|.

For example, to use the variable my_variable in a template, you'd use |[my_variable]| at the location where you want to use its eventual value.

Pre-defined system variables

The following variables are pre-defined and will be populated automatically by auto-generated or pre-defined values with the templates rollout.

Curly brackets denote dynamic values.

Variable	Content
`cashbox_description`	Defaults to the same value as `description`.
`cashbox_id`	A random UUID for the CashBox. Used to set or reference the CashBox ID.
`cashbox_ipaddress`	The IP address of the machine where the CashBox is running. Defaults to an empty string.
`cashbox_producttype`	The product type.
`count`	The number of queues in your account, plus one.
`description`	Description of the CashBox, defaulting to `ft{UTC timestamp}` (e.g., `ft19700101000000`).
`helper{0-9}_description`	Defaults to the same value as `description`.
`helper{0-9}_id`	Ten random UUIDs for helper components. Used to set or reference helper IDs.
`helper{0-9}_url`	Ten helper URLs, defaulting to `net.pipe://localhost/{helperX_id}`.
`outlet_number`	The number of outlets in your account, plus one.
`queue{0-9}_description`	Defaults to the same value as `description`.
`queue{0-9}_id_base64withoutspecialchars`	Base64 representation (filtered for alphanumeric characters) of the respective `queue{X}_id` value.
`queue{0-9}_id`	Ten random UUIDs for queue components. Used to set or reference queue IDs.
`queue{0-9}_url`	Ten queue URLs, defaulting to `http://localhost:1200/fiskaltrust{X}`.
`scu{0-9}_description`	Defaults to the same value as `description`.
`scu{0-9}_id`	Ten random UUIDs for SCU components. Used to set or reference SCU IDs.
`scu{0-9}_url`	Ten SCU URLs, defaulting to `net.pipe://localhost/{scuX_id}`.

Austria
France
Germany

Variable	Content
`reference_scu_{type}_{key}_{value}_{attr}`	References the indicated attribute (`attr`) of an existing SCU with the given key/value pair (`key`/`value`) and the specified type (`type`).
`reference_scu_{type}_{attr}`	References the indicated attribute (`attr`) of the first existing SCU and the specified type (`type`).

Reference variables

Reference variables allow you to reference values from other components. Their overall name structure is

reference_scu_{type}_{key}_{value}_{attr}

reference_scu_{type}_{attr}

Where the four dynamic parts (denoted by curly brackets) specify which attribute of which component you exactly want to reference. The first existing SCU is selected in the second reference where the reference doesn't contain a key/value.

Type

Indicates the SCU type you want to reference. Possible values for type are

onlinescu

Key / Value

Provides a key-value pair that you can use to filter for the SCU of the indicated SCU type. The scope is always your account and the outlet where you create the CashBox. You cannot reference SCUs from other outlets or accounts.

Attribute

The actual attribute you'd like to refer to. Currently, id and url are supported.

Example

::: info Default field with shop-bought SCUs

Any SCU bought via fiskaltrust.Shop or Rollout Management can have an incrementing integer field counter assigned.

:::

Let's say you have purchased two onlinescu SCUs for one outlet via fiskaltrust.Shop. In that case, their SCUs can have a counter field with values of 1 and '2'. Using a reference variable in your template, you can now reference these SCUs (in particular their IDs, in this example) by using the following variable.

|[reference_scu_onlinescu_counter_1_id]|
|[reference_scu_onlinescu_counter_2_id]|

or if you have only one onlinescu in your outlet, the key/value can be ignored by using the following variable.

|[reference_scu_onlinescu_id]|

In a different example, let's assume you assign a field masterPOS manually to your SCU and want to reference the URL of the SCU where masterPOS is set to true. In that case, you'd use the following variable.

|[reference_scu_onlinescu_masterPOS_true_url]|

Variable	Content
`company_name`	The company name.
`siret`	The SIRET identifier of the outlet.

Variable	Content
`reference_scu_{type}_{key}_{value}_{attr}`	References the indicated attribute (`attr`) of an existing SCU with the given key/value pair (`key`/`value`) and the specified type (`type`).

Reference variables

Reference variables allow you to reference values from other components. Their overall name structure is

reference_scu_{type}_{key}_{value}_{attr}

Where the four dynamic parts (denoted by curly brackets) specify which attribute of which component you exactly want to reference.

Type

Indicates the SCU type you want to reference. Possible values for type are

cryptovision
dieboldnixdorf
epson
fiskalycertified
swissbit
swissbitcloud

Key / Value

Attribute

The actual attribute you'd like to reference. Currently, id and url are supported.

Example

Default field with shop-bought SCUs

Any TSE bought via fiskaltrust.Shop will automatically have an incrementing integer field counter assigned.

Let's say you have purchased fiskaly TSEs for all your outlets via fiskaltrust.Shop. In that case, their SCUs should all have a counter field with the value of 1. Using a reference variable in your template, you can now reference these SCUs (in particular their IDs, in this example) by using the following variable.

|[reference_scu_fiskalycertified_counter_1_id]|

In a different example, let's assume you assign a field masterPOS manually to all your SCUs and want to reference the URL of the SCU where masterPOS is set to true. In that case, you'd use the following variable.

|[reference_scu_fiskalycertified_masterPOS_true_url]|

Custom variables

In addition to the pre-defined system variables, API templating also allows you to use custom variables and set their respective values when running the API request.

Please see the chapter API Templating for more details.

caution

Custom variables are only available when using the API.

Template structure

Templates are classic JSON documents with a root object and five root-level fields.

{
    "ftCashBoxId": "|[cashbox_id]|",
    "ftSignaturCreationDevices": [],
    "ftQueues": [],
    "helpers": [],
    "TimeStamp": 0
}

Field	Type	Required	Description
`ftCashBoxId`	String	yes	Indicates the ID of the CashBox. Typically, the variable `cashbox_id` here, to ensure a unique value is selected when the template is instantiated.
`ftSignaturCreationDevices`	Array of package objects	no	A list of all SCUs managed by this CashBox.
`ftQueues`	Array of package objects	no	A list of all queues managed by this CashBox.
`helpers`	Array of package objects	no	A list of all helpers managed by this CashBox.
`TimeStamp`	Number	no	The time when the CashBox was updated. Please see DateTime for more details on the format.

The arrays ftSignaturCreationDevices, ftQueues, and helpers each contain package object entries for each component the Middleware is supposed to service for the given component type.

Package object

A package object specifies the entire setup configuration of an individual component (e.g., queue or SCU).

{
    "Id": "",
    "URL": [],
    "Package": "",
    "Version": "",
    "Configuration": {},
    "Description": ""
}

Field	Type	Required	Description
`Id`	String	yes	The identifier of this component. Typically, you'll use one of the relevant system variables here.
`URL`	Array of strings	yes	One or more URLs under which you can reach this component.
`Package`	String	yes	The package name
`Version`	String	no	The package version to be used. If not specified, you will use the current version.
`Configuration`	Object	no	The configuration data for this component.
`Description`	String	no	A description of this component.

Templates

Introduction​

Instantiating a template​

Shop​

API​

Variables​

Pre-defined system variables​

Reference variables​

Type​

Key / Value​

Attribute​

Example​

Reference variables​

Type​

Key / Value​

Attribute​

Example​

Custom variables​

Template structure​

Package object​

Introduction

Instantiating a template

Shop

API

Variables

Pre-defined system variables

Reference variables

Type

Key / Value

Attribute

Example

Reference variables

Type

Key / Value

Attribute

Example

Custom variables

Template structure

Package object