Skip to main content

Rollout of the fiskaltrust.Middleware

Table of contents#

β”œβ”€β”€ [object Object]β”œβ”€β”€ [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚       └── [object Object]β”‚       └── [object Object]β”‚   └── [object Object]β”œβ”€β”€ [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚       └── [object Object]β”‚       └── [object Object]β”‚       └── [object Object]β”‚       └── [object Object]β”œβ”€β”€ [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”œβ”€β”€ [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]β”‚   └── [object Object]

Introduction#

The fiskaltrust.Middleware is the license-free base product of fiskaltrust, which is integrated by PosCreators into their POS-Systems in order to implement conformity with the new fiscalization laws. The fiskaltrust.Middleware runs as an independent service on the cash register of the PosOperator and is addressed by the POS-System via an interface.

Since fiskaltrust.middleware runs as a standalone service, it must be rolled out to the cash register of the PosOperator. Depending on the circumstances, the respective fiskaltrust.Middleware instance must be configured accordingly before going live. For example, it must be specified where the POS-System can reach the service, in which database the processed data is to be stored by the service, which TSE is to be used for the signatures, and how the TSE can be reached by the service.

In the following chapters we will explain how to configure the fiskaltrust.Middleware for the rollout. In addition, we will show you how to install and test the service and we will discuss various rollout scenarios. Finally, we will describe which automation options fiskaltrust provides for a mass rollout.

Configuration of the fiskaltrust.Middleware#

The configuration of the fiskaltrust.Middleware can be done manually via the fiskaltrust.Portal or automated via an API. But before we look at how the configuration is created, we will first go into the structure of the fiskaltrust.Middleware.

Structure of the fiskaltrust.Middleware#

The fiskaltrust.Middleware is modular and consists of several components. The most important components are the Queue and the SCU (signature creation unit). Furthermore, so-called Helpers can also be used, such as the Helipad Helper, which is responsible for the regular upload of the processed data to the fiskaltrust.Cloud. The following illustration shows how the Queue and the SCU are used:

structure of the middleware

The Queue is the component of the fiskaltrust.Middleware with which the POS-System communicates. For this purpose, the Queue provides an interface that is the same for all countries, the so-called IPOS Interface. The type of communication with the Queue is selected by the PosCreator when implementing the POS-System. For example, grpc or WCF can be used. The IPOS Interface provides the POS-System following three functions:

  • echo - to check the availability of the Queue
  • sign - for signing receipt data, as well as for executing functionality via special receipts (e.g. initial operation receipt, daily closing receipt or zero receipt)
  • journal - to export the data in the formats required by law

The Queue receives requests from the POS-System and processes them. It is responsible for the creation of the receipt number, for the chaining of the requests and for the persistence of the data.

The fiskaltrust.Middleware component SCU (signature creation unit) is responsible for signing the data. The data to be signed is sent from the Queue to the SCU, which in turn, in the German variant, communicates with a TSE. The TSE finally signs the data. The signed data and all associated information are then sent back to the Queue by the SCU. The Queue persists the data and builds the response that is returned to the POS-System. This response contains important information that must be printed on the receipt by the POS-System.

The CashBox as a configuration container#

The configuration of a fiskaltrust.Middleware instance is done via a so-called CashBox. The CashBox is a configuration container. It contains the configurations of the fiskaltrust.Middleware components used in the fiskaltrust.Middleware instance (e.g. Queue, SCU). The following example shows a CashBox that contains the configuration of a Queue and the configuration of an SCU:

CashBox

So for the example above we need to configure the Queue and the SCU and then put these two configurations into a configuration container (CashBox). But what exactly do we have to configure for the Queue and for the SCU?

Configuration of the Queue#

As mentioned above, the Queue is the component of the fiskaltrust.Middleware that is available to the POS-System for queries via the IPOS Interface. In addition, the Queue is responsible for the persistence of the processed data. And these are exactly the two points that we have to configure here:

  1. how and where exactly should the Queue be accessible for the POS-System? (e.g. via grpc on localhost:1234)
  2. where exactly should the Queue store the data? (e.g. in a MySql database with the connectionstring: "xyz")

How the communication is to take place, e.g. via grpc, is decided by the PosCreator, who implements the POS-System accordingly. Where the Queue and thus the service exactly will be attainable, thus e.g. localhost:1234 decides usually the PosDealer, depending upon conditions with the PosOperator.

Configuration of the SCU#

The SCU is responsible for creating the signatures. It receives the data to be signed from the Queue and handles communication with a TSE to have the data signed. Two configuration entries must also be made for the SCU:

  1. on the one hand the Queue must know how and where it can reach the SCU (i.e. via grpc on localhost:5678).

  2. and on the other hand the SCU must know which TSE it should access and where it is located (e.g. Swissbit - USB - TSE in drive E:).

Now you will surely ask yourself why we have to configure here how the SCU should be reachable by the Queue, if the Queue and SCU are components of the fiskaltrust.Middleware after all. Isn't the Queue already aware of how to reach the SCU? Well, the answer lies in the flexibility of the fiskaltrust.Middleware, because an instance of the fiskaltrust.Middleware operates only exactly those components, which are specified in its CashBox. For example, three cash registers can share one SCU and thus one hardware TSE:

flexibility of the middleware

Each cash register runs an instance of the fiskaltrust.Middleware, which is configured by its own CashBox. The CashBoxes of the upper and lower cash registers contain only the configuration of a Queue. The CashBox of the middle cash register contains the configuration of a Queue and a SCU. To make the SCU from the middle cash register (e.g. main cash register) reachable for the other two cash registers or Queues, we have to specify in the Queue configuration how and where the SCU is reachable (and of course release the corresponding port). To ensure that a Queue connects to the correct SCU, we must specify this connection when creating the CashBox for the Queue.

Create CashBox manually via the fiskaltrust.Portal#

Each instance of the fiskaltrust.Middleware must be configured using a CashBox. Such a CashBox can be created manually via the fiskaltrust.Portal or automated via an API. In this chapter we will show you an example of how to create a CashBox via the fiskaltrust.Portal. For this purpose, we assume the following scenario:

Szenario-CashBox-Queue-SCU

Our CashBox shall contain a Queue and a SCU. The SCU accesses a USB TSE. Specifically, we will configure a Queue that the POS-System communicates with via REST and is accessible to the POS-System at localhost:1200/fiskaltrust. The Queue stores the processed data in a SQLite database. Furthermore we configure in this example a SCU which is accessible for the Queue via grpc and under localhost:1400 and which accesses a Cryptovision USB-TSE for signing the data. The TSE is plugged into the E: drive.

Step 1: Create the SCU configuration

In the fiskaltrust.Portal, go to "Configuration -> Signature creation unit". The list of SCUs already created appears.

add-scu-1

Now press the "+ Create" button. A form for entering the SCU data appears.

add-scu-2

  1. Enter the name of the SCU here (e.g. "TEST SCU").
  2. Depending on the TSE, select the package (module) that the SCU should use (in our example we use a CryptoVision TSE).
  3. For the package version, the latest one is automatically selected
  4. Specify the outlet, the main outlet is automatically preselected by default
  5. Press "Save"

The SCU has been created and we are now forwarded to the second configuration form. This form depends on the previously selected package. In our example, we must specify the device path for the Cryptovision TSE. For another package, something else may be required here (e.g. Com-Port for a Diebold TSE).

add-scu-3

  1. Enter the device path (i.e. E: in our case).
  2. Now specify how and where the SCU is to be accessible for a Queue. First press the corresponding button for the type of communication (e.g. grpc) and then enter the path (e.g. localhost:1401).
  3. Press "Save and close" to save the data and to return to the list.

In the list we can now see that our SCU configuration has been successfully created:

add-scu-4

Step 2: Create the Queue configuration

Next, we create the Queue configuration. To do this, we go to "Configuration -> Queue". The list of already created Queues is displayed.

add-queue-1

Now press the "+ Create new" button. A form for entering the Queue data appears.

add-queue-2

  1. Enter the name of the Queue here (e.g. "TEST QUEUE"). 2.

  2. Select how the data should be persisted (e.g. SQLite database).

  3. The latest package version is automatically selected.

  4. Enter the cash register serial number in the "CashBox Identification" field. Make sure that this is unique worldwide and that it is a printable string with a maximum length of 20 characters. The cash register serial number specified here will later also be registered as the ClientId in the TSE in order to uniquely assign the signatures to the cash register. Since the different TSE manufacturers have different specifications for the formatting and for the length of the ClientId, we have agreed on the lowest common denominator (printable string, max. 20 characters).

  5. Specify the outlet, the main outlet is automatically preselected by default

  6. Press "Save"

The Queue has been created and we are now forwarded to the second configuration form. This form depends on the previously selected persistence package. In our example, we do not have to make any further entries for the SQLite database, because it is automatically created by the fiskaltrust.Middleware. However, if it was a different package, then appropriate connection specifications must be made here. For example, the specification of a connection string for a MySQL database.

add-queue-3

  1. If necessary, enter the database connection details (not necessary in this example, the SQLite DB).
  2. Now specify how the Queue should be accessible from the POS-System. First press the corresponding button for the type of communication (e.g. http(REST)) and then enter the path (e.g. localhost:1200/fiskaltrust).
  3. Press "Save and close" to save the information and to return to the list.

In the list we can now see that our Queue configuration has been successfully created:

add-queue-4

Step 3: Create the CashBox

After creating the SCU and the Queue, we next create the CashBox, meaning the configuration container for the fiskaltrust.Middleware instance. To do this, go to "Configuration->CashBox". The list of already created CashBoxes will be displayed.

add-cashbox-1

Now press the "+ Add" button. A form for entering the CashBox data will appear.

add-cashbox-2

  1. Enter the name of the CashBox here (e.g. "TEST CASHBOX")

  2. Enter the outlet, by default the main outlet will be preselected automatically

  3. Press "Save" to save the data and to return to the list.

In the list we can now see that our new CashBox has been successfully created:

add-cashbox-3

Step 4: Fill the CashBox

After creating the CashBox, it is to be filled next. In our example, we want to put the previously created Queue configuration and the SCU configuration into the CashBox. The list entry with our CashBox can be expanded. Here we can see that it is currently still empty.

fill-cashbox-1

To fill the newly created CashBox press the "Edit by list" button in the list entry of the CashBox.

fill-cashbox-2

The list of existing configurations is displayed.

We can choose here which configurations we want to add to our configuration container so into the CashBox. For our example we select the Queue and the SCU we created before and then press the "Save" button.

fill-cashbox-3

Back in the list, we can expand the list entry of our CashBox again and now see that it contains Queue and SCU.

fill-cashbox-4

Step 5: Connect the Queue with the SCU

As described above, we need to tell the Queue which SCU to use to sign the data. So we have to "connect" the Queue with the SCU. In our case, the Queue and SCU are in the same CashBox. Nevertheless, we have to create the connection. To do this, we press the "Connect" button in the expanded list entry of the CashBox, which is displayed to the right of the Queue:

connect-queue-scu-1

A popup appears with the available SCUs. From this list we can now select our previously created SCU, save and close the popup.

connect-queue-scu-2

The queue now knows with which SCU it has to communicate and where the SCU can be reached.

Step 5: Publish the CashBox (rebuild configuration)

The last step is to publish the created CashBox. This is done with the "Rebuild configuration" button available in the list line of the CasBox.

Rebuild configuration

This makes the CashBox available for download as a JSON file. This JSON configuration file can later be downloaded by a fiskaltrust.Middleware instance and used for initial initialization or for an update. In case of an update, for example update of the SCU package version due to a change in the law, the change is only made available in the CashBox after the "Rebuild configuration" button has been pressed. If the fiskaltrust.Middleware instance to which this CashBox is assigned is then restarted, it loads the new configuration and updates itself automatically, e.g. by downloading and using the new package.

Start and test the service#

To test the service, meaning a fiskaltrust.Middleware instance, we download the so-called "Launcher". We can do this in the list entry of the previously created CashBox. To do this, press the "Download .NET Launcher" button.

Download Launcher

You will receive a zip compressed folder that you can unzip on the cash register. Unzip the zip file.

Launcher unzip

The resulting folder can also be renamed if necessary. The folder contains the launcher fiskaltrust.exe, the service represented by the .dll files, a configuration file named fiskaltrust.exe.config and three command files:

  • install-service.cmd
  • uninstall-service.cmd
  • test.cmd

The command files can be used for parameterized starting or stopping of the service. They execute the fiskaltrust.exe with specification of appropriate parameters. The content of the install-service.cmd file is for example as follows:

cd /d "%~dp0%" fiskaltrust -cashboxid=259c5a7b-fc44-40d6-af7b-73fde0943ec4 -accesstoken=BL...8D6o= -sandbox -i -servicename=fiskaltrust-259c5a7b-fc44-40d6-af7b-73fde0943ec4 timeout 15

Thus fiskaltrust.exe is started with the cashobxid "259c..". Thus the started fiskaltrust.Middleware instance knows from which configuration container (CashBox) it should initialize itself. The cashboxid is the ID of the CashBox and can be seen in the fiskaltrust.Portal in the expanded list entry of the CashBox:

CashBoxId and AccessToken

To be able to load the CashBox from the fiskaltrust.Portal the service needs an access authorization. This is specified via the accesstoken parameter. The value can also be found in the fiskaltrust.Portal in the expanded list entry of the CashBox (see above).

The sandbox parameter specifies that the sandbox fiskaltrust.Portal is to be accessed. The parameter i specifies that the fiskaltrust.Middleware instance should be installed and started as a (Windows) service. The servicename parameter sets the name of the (Windows) service.

For the complete list of available parameters and further technical information about the installation of the service, please refer to our IPOS Interface documentation in chapter Installation.

To test the service we can use the command file test.cmd. The content looks like this:

cd /d "%~dp0%" fiskaltrust -cashboxid=259c5a7b-fc44-40d6-af7b-73fde0943ec4 -accesstoken=BL...8D6o= -sandbox -test

So the fiskaltrust.Middleware instance is not installed and started as a (Windows) service, but instead started directly in test mode in the console (cmd) using the test parameter. The advantage here is that we can see the log messages directly in the console and react accordingly. To activate an extended log output we can edit the test.cmd file before running it and add the parameter verbosity with the value Debug:

cd /d "%~dp0%" fiskaltrust -cashboxid=259c5a7b-fc44-40d6-af7b-73fde0943ec4 -accesstoken=BL...8D6o= -sandbox -test -verbosity=Debug

Save and run as administrator:

run test.cmd

A console appears in which the fiskaltrust.Middleware instance is started. We can see here what exactly happens at startup and make appropriate corrections (e.g. in the CashBox or in the connection of the TSE) in case of any errors.

terminal

Now you can try to send requests from the POS-System to the started fiskaltrust.Middleware instance. As a PosDealer, corresponding buttons will be available to you in the POS-System UI.

In our example we simulate a POS-System using Postman. Postman can send requests to the Queue via REST. For this we use our collection from the fiskaltrust middleware-demo-postman github repository. The repository also contains the instructions for configuring the Postman collection. Important here is the specification of the endpoint at which the Queue is accessible and the specification of the CashBoxId as values for the already created variables:

postman config

Test the availability of the Queue#

First we send a echo request to check the availability of the Queue. As a PosDealer, you will have a corresponding button available in the POS-System. In our example we use the "Echo" request from the Postman collection described above:

postman echo

The Queue responds and we now know that the fiskaltrust.Middleware instance is reachable and available for further requests. We can also see the request and its processing in the previously started console as a log message:

Terminal echo

Initialization of the fiskaltrust.Middleware instance via an initial-operation receipt#

Next, we send an "initial-operation receipt". As a PosDealer, you will have a corresponding button available in the POS-System. In our example we again use the Postman collection described above. The initial-operation receipt ensures that the fiskaltrust.Middleware is initialized, registers the Queue as a client in the TSE and if the TSE is not yet initialized, the TSE is also put into operation.

postman initial operation receipt

In the response and in the console we can now see that our Queue has been registered as a client in the TSE.

Send a pos-receipt#

Next, we can send a pos-receipt to settle a purchase. As a PosDealer, the corresponding functionality will be available to you in the POS-System. In our example, we again use the Postman Collection described above.

postman pos receipt

The fiskaltrust.Middleware processes the request and sends back a response containing important receipt data, including the required signatures. If successful, these signatures are printed on the receipt by the POS-System.

Check connection with the fiskaltrust.Cloud#

In the fiskaltrust.Portal we can see the above submitted request and the resulting receipt, because they are uploaded via the Helipad Helper every 5 minutes. To do this, go to "Configuration->Queue" and press the "ReceiptJournal" button in the list entry of the Queue.

ReceiptJournal

An overview of the processed receipt requests appears:

List of receipts

Notice:

If the receipts do not appear here, it is possible that the communication of the fiskaltrust.Middleware with the server did not work. In this case, first check whether 5 minutes have already passed since the requests were sent. If this is the case, please check the log messages in the console. It may be that you have to release the corresponding firewall ports first.

Now press the button with the eye symbol in the line with the previously sent pos-receipt request (see above). You can now view an exemplary representation of the receipt. In addition, the concrete request and the answer to the POS-System are displayed:

receipt

Firewall troubleshooting#

If errors occur when connecting fiskaltrust.Middleware to the outside world, it is possible that your firewall does not allow the connection. Check the following permissions depending on the TSE you are using:

No cloud TSE is used#

In this case, only the permissions for the required fiskaltrust servers need to be checked:

must be reachable. To assist you in troubleshooting, we provide a PowerShell Script. The script must run without errors.

####the fiskaly cloudbased TSE is used

In this case, the permissions for the required fiskaltrust servers and the permissions for the fiskaly server must be checked:

must be reachable. To assist with troubleshooting, we provide a PowerShell Script for you. The script must run without errors.

####the Swissbit cloudbased TSE is used

In this case, the permissions for the required fiskaltrust servers and the permissions for the Swissbit server must be checked:

must be reachable. To assist you in troubleshooting, we provide a PowerShell Script. The script must run without errors.

Script to check the firewall permissions#

You can download our PowerShell script to check the firewall permissions here. Unzip the zip-file and navigate with a PowerShell window to the directory where you unzipped it. You need to run the PowerShell window as an administrator.

If not already done, please set the execution policy to RemoteSigned:

Set-ExecutionPolicy RemoteSigned

To run the PowerShell script with .\CheckFirewall.ps1 specify on startup the associated csv file (includes the URLs described above) depending on the TSE you are using:

No cloud TSE is used:

.\CheckFirewall.ps1 FirewallTests-ft.csv

The fiskaly Cloud TSE is used:

.\CheckFirewall.ps1 FirewallTests-fiskalyCloud.csv

The Swissbit Cloud TSE is used:

.\CheckFirewall.ps1 FirewallTests-SwissbitCloud.csv

The script must run without errors.

If you like to send the output of the script to a file you can do it like in the following example:

.\CheckFirewall.ps1 .\FirewallTests-SwissbitCloud.csv | Out-File -FilePath C:\test\fw-script\output.txt -Width 1600

Using a Proxy#

In case your network requires the use of a proxy for outbound connections, you can specify that via the -proxy parameter of fiskaltrust.exe.

This parameter takes a semicolon-separated connection string with five arguments, specifying the hostname of the proxy and - optionally - a username and password for authentication.

ValueDescriptionRequired
addressThe URL of the proxy (defaults to HTTP if only a hostname is provided)Yes
usernameThe user which should be used for authentication against the proxyNo
passwordThe password of the proxy userNo
bypassA regular expression with host addresses and names which ought to be exempt from proxying
Can be used more than once
No
bypasslocalhostIndicates whether local connections require proxying as well (false or true)No

Examples

address=192.168.0.1address=192.168.0.1;username=proxyuser;password=proxypwaddress=proxy.example.com;username=proxyuseraddress=192.168.0.1;bypass=192\.168\.10\.1address=192.168.0.1;bypass=192\.168\.10\.1;bypass=scu\d+\.example\.com

For security reasons it is recommended not to add the -proxy parameter directly to the two launcher files test.cmd and install-service.cmd but instead call fiskaltrust.exe once manually and just pass the parameter with the desired values.

fiskaltrust.exe -proxy="address=192.168.0.1;username=proxyuser;password=proxypw"

This call will save the connection information in an encrypted fashion in the configuration and immediately return. You can verify the configuration by checking for the following key in fiskaltrust.exe.config

<add key="proxy" value="[ENCRYPTED-PROXY-INFORMATION]" />

As this information is encrypted you won't be able to edit the file manually but need to execute the same command again, should you ever need to change it. You'll only need to edit the file manually in case you want to remove the proxy configuration altogether.

Please keep in mind, any changes only take effect after a restart of fiskaltrust.Middleware.

Proxy and Swissbit Cloud TSE#

When usingthe Swissbit cloudbased TSE , the proxy settings must additionally be provided in the SCU configuration (portal or template). See: https://docs.fiskaltrust.cloud/docs/product-description/germany/products-and-services/caas/features/basics/tse/swissbit-cloud

Test data export#

A data export can be performed locally via the fiskaltrust.Middleware or via the fiskaltrust.Portal. The local export of data directly from the fiskaltrust.Middleware is free of license fees. The export via the fiskaltrust.Portal is subject to a fee and is activated via the fiskaltrust product POSArchiv per PosOperator and cash register. The product POSArchiv is also included in our fiskaltrust.CarefreeBundle s and refers to all cash registers of the outlet (but is limited to a maximum number of cash registers - see also the current product description).

Local data export#

The following data can be exported directly locally via the fiskaltrust.Middleware:

  • fiskaltrust.ActionJournal in internal fiskaltrust format (JSON)
  • Receipt journal in internal fiskaltrust format (JSON)
  • QueueItemes journal in internal fiskaltrust format (JSON)
  • DSFinV-K - a DSFinV-K (digital interface of the financial administration for POS-Systems) compatible export of the data sent to the Queue. The data is aggregated in several CSV files, according to DSFinV-K 2.2
  • TAR file export of the TSE data aggregated in a TAR file (an archive for packaging files) that can be opened with 7-zip, for example.

The export always refers to a Queue (with the exception of the TSE-TAR, see note below). The data export from the fiskaltrust.Middleware is provided by the PosCreator via the POS-System. For this purpose, the POS-System uses the 'journal' function of the IPOS interface, which is provided by the fiskaltrust.Middleware. As a PosDealer, the corresponding functionality is then available to you at the POS-System. Please test the data export in this case directly with the POS-System. Please also note the information on the DSFinV-K export and the TAR file export below.

Notes on the DSFinV-K export#

The DSFinV-K export always refers to a closed day. It requires that each day is closed with a so-called daily closing receipt. The daily closing receipt must be sent to the fiskaltrust.Middleware via the POS-System. As a PosDealer, the POS-System provides you with a corresponding button.

Notes on the TAR file export#

The TAR file export refers to all data of the TSE, even if the TSE is used by several Queues. The TSE-TAR export therefore contains the data of all Queues that use the same TSE.

The TAR export is automatically triggered by the fiskaltrust.Middleware with the daily closing receipt. The data is transferred to the database of the executing Queue and then deleted from the TSE. Furthermore, the data is uploaded to the fiskaltrust.Cloud where it is available in the fiskaltrust.Portal after activation of the fiskaltrust.PosArchive product.

Therefore, in case several Queues use the same TSE, we recommend to define a "leading Queue" which receives the TSE data at the daily-closing receipt. For the other Queues accessing the same TSE, PosCreators should ensure that the POS-System uses the receipt case flag 0x0000000004000000 for the daily-closing receipt. This prevents the automatic TAR export by the fiskaltrust.Middleware and thus the data is not distributed to different Queues, but always ends up in the leading Queue. As a PosDealer, you should have two different functions available in the POS-System for this case (e.g. daily closing with automatic TAR file export - for the leading Queue - and daily closing without automatic TAR file export for the other Queues that use the same TSE).

We are also currently working on a outlet-based export in the fiskaltrust.Portal, which will then lead to a handling simplification.

The direct export of the TSE-TAR data can be called from the POS-System via the journal function of the IPOS Interface.

The ftJournalType can be used to distinguish between two variants:

0x44450000000001 - exports the TAR-TSE data currently in the TSE (I.e. from the last daily-closing to the time of the call). 0x44450000000003 - exports the TAR-TSE data that is in the Queue database.

As a PosDealer, you should also have corresponding buttons available in the POS-System for this purpose.

Data export via the fiskaltrust.Portal#

The following data can be exported per Queue:

  • Full export (XML or CSV) - export of all data sent to the Queue. The data is aggregated in the form of an XML file or CSV file.
  • fiskaltrust.ActionJournal in internal fiskaltrust format (JSON)
  • Receipt journal in internal fiskaltrust format (JSON)
  • DSFinV-K - a DSFinV-K (digital interface of the financial administration for cash register systems) compatible export of the data sent to the Queue. The data is aggregated in several CSV files, according to DSFinV-K 2.2
  • TAR file export of the TSE data aggregated in a TAR file (an archive for packaging files) that can be opened with 7-zip, for example.

To test the data export via the fiskaltrust.Portal you can proceed as follows:

Export fiskaltrust.ReceiptJournal and fiskaltrust.ActionJournal#

In the fiskaltrust.Portal, go to the menu item "Configuration -> Queue". You will find a list entry for each Queue. The list entry of the Queue contains the buttons for exporting the journals:

portal-journal-export

Full export (XML or CSV), DSFinV-K export or TAR file export#

To do this, first go to the "Configuration -> Queue" menu item in the fiskaltrust.Portal. You will find a list entry for each Queue. In the list entry of the Queue there is an "Export" button:

portal-queue-export

The export view for the selected Queue appears. Here you can select the type of export and trigger the export:

portal export choose

Set the desired filters in the upper filter area, then select e.g. "Full export (CSV)" and press the "Start export" button at the bottom. You will be redirected to the list of triggered exports, where you will see that the export is currently being processed. As soon as the desired export is available, you can expand the list entry and download the finished export.

portal export download

The procedure described above can be performed analogously to all export formats offered in the export view. When testing the DSFinV-K and TAR file export, make sure that a corresponding dayly closing receipt has been sent to the fiskaltrust.Middelware from the POS-System.

Closing words#

In the upper chapters we have described how the fiskaltrust.Middleware is structured, how the individual instances can be configured manually via the fiskaltrust.Portal and how the service can be started and tested. Next, we would like to present a few possible rollout scenarios as inspiration for the rollout. These show how flexibly the fiskaltrust.Middleware can be deployed at the operator's outlet. After presenting various rollout scenarios, we will then go into possible automation options for mass rollout.

Rollout scenarios#

Introduction#

Instances of the fiskaltrust.Middleware can be configured and can work together in different ways depending on the situation or scenario. Each scenario presented in this chapter is related to one outlet. The following basic requirements must be fulfilled, regardless of the scenario:

  • At least one SCU including TSE must be used per outlet. The TSE can either be an on-site hardware TSE or a certified cloud TSE.
  • A TSE can only be used by one company and therefore by PosOperator (account) in the fiskaltrust.Portal. Even if two companies share an outlet, two TSEs must still be used.
  • Each Queue must be reported to the tax office as an electronic cash or recording system (cash register).
  • All Queues, SCUs and TSEs must be located in the PosOperator's operational environment. The cloud component of a certified cloud TSE is an exception. This is located in the data center of the cloud TSE provider.
  • Only one SCU can be assigned to each Queue and each SCU can only be responsible for one TSE. I.e. each cash register can only use one TSE.
  • Several terminals can be operated per cash register. (A terminal is a device without a cash register function).

Cloud TSE Info In a cloud TSE, a component runs in the data center of the cloud TSE provider. If this TSE component is no longer accessible, the fiskaltrust.middleware switches to failure mode. When using cloud TSEs, we would like to additionally refer to our Fair-Use-Policy.

Hardware TSE Info Basically, hardware TSE are connected directly to the cash register via micro SD card or USB port.

A TSE per cash register#

From a technical point of view, this is the simplest scenario, but it requires a higher number of TSEs, since a separate TSE is used for each cash register. One advantage of this solution is that if one TSE fails or is lost, other cash registers are not affected. Another advantage is that performance bottlenecks are avoided because each cash register uses its own TSE and thus only the requests of this one cash register have to be processed or signed by the TSE.

tse-per-cashregister

In the chapter Template examples you can find a template that represents this scenario.

A step-by-step guide for this configuration can be found here.

Hardware TSE(s) at local server for multiple cash registers#

The fiskaltrust.Middleware runs on each cash register and on the local server. The hardware TSE is connected to the local server (e.g. via USB). The server's CashBox configures the fiskaltrust.Middleware instance with an SCU. The SCU configured for the server accesses a hardware TSE. The CashBoxes of the individual cash registers are configured in such a way that their fiskaltrust.Middleware instance is equipped with only one Queue. The Queues used here connect to the server's SCU. This scenario enables a saving of TSEs. However, since all requests have to pass through the server's SCU, the server becomes a bottleneck. The TSE also becomes a bottleneck. If the server or the TSE fails, all cash registers are affected. Furthermore, this scenario can lead to [performance bottlenecks](#performance recommendation) in the hardware TSE.

tse-separated

In the chapter Template examples you can find a template that represents this scenario.

A step-by-step guide for this configuration can be found here.

If you decide to use this scenario, we recommend using one or more additional TSEs if you have a large number of requests. This is visualized in the image below as an example.

tse-separated

In the chapter Template examples you can find a template that represents this scenario.

Hardware TSE at the main cash register for several additional cash registers#

The fiskaltrust.Middleware runs on each cash register. The CashBox of the main cash register configures the fiskaltrust.Middleware instance with a Queue and an SCU. The SCU configured for the main cash register accesses a TSE. The CashBoxes of the other cash registers are configured so that their fiskaltrust.Middleware instances are only equipped with a Queue. The Queues used here connect to the SCU of the main cash register. This scenario enables a saving of TSEs. However, since all requests have to run via the SCU of the main checkout, the main checkout becomes a bottleneck. The hardware TSE also becomes a bottleneck. If the main cash register or the hardware TSE fails, all other cash registers are affected. Furthermore, in this scenario, performance bottlenecks may occur in the TSE. If you decide to use this scenario, we recommend using one or more additional TSEs if you have a large number of requests.

tse-on-cashregister

In the chapter Template examples you can find a template that represents this scenario.

A step-by-step guide for this configuration can be found here.

A cloud TSE for multiple cash registers#

The fiskaltrust.Middleware runs on each cash register. The CashBox of each cash register configures the fiskaltrust.Middleware instance with its own Queue and its own SCU. Each SCU accesses the same cloud TSE. This scenario enables cloud TSEs to be saved. One advantage here is that the SCU does not become a bottleneck, since each POS has its own SCU. However, since all requests are sent to the same cloud TSE, the TSE becomes a bottleneck. Furthermore, both possible [performance bottlenecks](#performance recommendation) in the cloud TSE and our fair use policy must also be taken into account here.

tse-on-cashregister

In the chapter Template examples you can find a template that represents this scenario.

A step-by-step guide for this configuration can be found here.

Rollout scenario with terminals#

Terminals are input devices such as tablets, handhelds or similar (without cash register function), where it is not possible to connect a hardware TSE or to install the fiskaltrust.Middleware on the device itself. In this case the fiskaltrust.Middleware is operated at a cash register or at a server and is always accessible for the terminals. The terminals only serve as input devices and connect to the server or to the cash register. If there are many simultaneous requests, performance bottlenecks may occur in the TSE. If you decide to use this scenario, we recommend using multiple cash registers with additional TSEs (alternatively: multiple fiskaltrust.Middleware instances with their own SCU and TSE on a server) if you have a large number of requests.

terminals-single-queue

Another possible variation of this scenario is to assign each terminal to its own Queue.

terminals-mehrere-queues

In the chapter Template examples you can find a template that represents this scenario.

A step-by-step guide for this configuration can be found here.

Data center as operational environment#

If the cash register is operated in a data center and the terminals cannot function without an (Internet) connection to it, the data center can be assumed to be the "operational environment" under certain conditions. In this case, the fiskaltrust.Middleware should be operated entirely in the data center. In this scenario, the terminals connect to the fiskaltrust.Middleware in the data center via the online POS-System. However, in the event of a failure of the (Internet) connection, the fiskaltrust.Middleware can no longer be reached and therefore no signatures generated by the fiskaltrust.Middleware can be printed on the receipts. If you are interested in this solution (BYOD - Bring your own datacenter), where the fiskaltrust.middleware runs in the datacenter of the cash register operator, you can find more information in our BYOD github repository.

cloud-middleware

In the chapter Template examples you can find a template that represents this scenario.

A step-by-step guide for this configuration can be found here.

Connection variants of the TSE to the SCU#

For the following connection variants we have prepared a legend showing the meaning of the individual arrows:

anbindungs-varianten-Legende

Cash register with hardware TSE#

In the classic connection variant, the POS-System is located in the local environment of the outlet and a hardware TSE is connected directly to the POS-System, e.g. via USB or micro SD.

anbindungs-variante-scu-hw-tse

Network printer with hardware TSE#

Another variant in the local environment is the use of a network printer with hardware TSE. The hardware TSE can be integrated directly in the printer or connected via USB. One or more cash registers use the printer.

anbindungs-variante-drucker

Local TSE server with hardware TSEs#

The third connection variant in the local environment is implemented via a TSE server in the local network. Several hardware TSEs can be connected to one TSE server. Several cash registers access the TSE server via their SCU.

anbindungs-variante-server-lokal

Cash register with cloud TSE#

A cloud TSE must be accessed over the Internet. In the following scenario, a POS-System accesses a cloud TSE over the Internet using the SCU.

anbindungs-variante-cloud

POS-System in the operator's data center with cloud TSE#

Here, too, the POS-System accesses a cloud TSE via the Internet with the help of the fiskaltrust SCU. In the local environment, there are only terminals without a cash register function that access the electronic POS-System in the PosOperator's data center via the Internet.

anbindung-rechenzentrum-cloud-tse

Proposed solutions for virtualization within an outlet#

When virtualizing the electronic cash register or recording system including fiskaltrust.Middleware, experience has shown that problems occur when accessing a hardware TSE directly connected to the local server via USB or as micro SD. An exception to this is the Diebold-Nixdorf TSE, since communication with it takes place via COM port. Due to the aforementioned access problems, we have presented proposed solutions for this scenario in the following sketches. Instead of connecting a hardware TSE directly to the local server, we recommend the following options:

SCU is within the virtual instance#

  • Connection to a local network printer with TSE
  • Connection to a TSE server in the local network
  • Connection of cloud TSEs
  • Connection to a Diebold-Nixdorf hardware TSE, as communication takes place via COM port here

virtualisierungs-vorschlag

SCU is outside the virtual instance#

A fiskaltrust.middleware runs on a second local server with this option. It is not operated in the virtualized environment. The CashBox used for this purpose merely configures an SCU that accesses the hardware TSE. The hardware TSE, in turn, is connected directly to this second server via USB or micro-SD. In the first server, in which the virtual instances run, the CashBoxes used configure the fiskaltrust.Middelware instances in such a way that they each operate only one Queue, which accesses the SCU in the second server.

virtualisierungs-vorschlag-ausserhalb

A possible optimization of the option described above could be that the fiskaltrust.Middleware that runs the SCU runs on the same server as the virtual instances, but is not virtualized. This can then also access the hardware TSE.

virtualisierungs-vorschlag-ausserhalb

Performance recommendations#

In internal tests, we have found that 3 signatures per second can be processed well by each TSE. More than 3 signatures per second will cause delays. Please note that 2 signatures per request are sent in an implicit flow. We therefore recommend that if a higher number of signatures per second is expected, additional TSEs should be taken into account in the planning.

Rollout automation#

This chapter is intended to support the rollout process by showing ways to simplify and optimize the rollout through automation.

Introduction#

Each fiskaltrust.Middleware instance is configured with a so-called CashBox. This configuration container is rolled out together with the fiskaltrust.Middleware at the PosOperator. For doing so, the launcher can be downloaded from the fiskaltrust.Portal and started in the cash register. The downloaded launcher contains the fiskaltrust.Middleware and its configuration in the form of a CashBox. The CashBox mainly contains the configurations of the Queue and the SCU but can also contain helper configurations.

CashBox

For example, communication endpoints, database access, TSE access, etc. are defined in the included configurations. Normally, one such CashBox is required per cash register. A rollout with many cash registers is therefore very time-consuming if done manually, since a separate CashBox must basically be created, compiled and published in the fiskaltrust.Portal for each cash register. Furthermore, the launcher must be downloaded and executed in the cash register.

In order to optimize this process, fiskaltrust provides various tools. A central role is played by the possibility of templating for the creation of CashBoxes and the possibility of automated execution of the templates with the help of the fiskaltrust.Portal API.

In the following, we will discuss these and other optimization options and show how you, as a PosDealer, can make use of them as needed.

Overview manual process#

As already mentioned in the introduction, basically one CashBox is required per cash register. Normally, the configuration of a Queue and a SCU is made here and these are linked with each other.

There are also other scenarios (see Rollout scenarios which we will discuss later. The configuration of the CashBox is described in the chapter Configuration of the fiskaltrust.Middleware.

As soon as the CashBox for the cash register has been created, configured and published in the portal, the Launcher can already be downloaded from the fiskaltrust.Portal and started on the cash register. As soon as the launcher is started for the first time, the included configuration is applied. Thereby the middleware is ready and will be started by the launcher in the next step.

This means that in the manual process, at least the following initial steps must be taken for each cash register during the rollout:

  1. Creation and configuration of the Queue
  2. Creation and configuration of the SCU
  3. Linking the Queue with the SCU
  4. Create and configure the CashBox
  5. Rebuild configuration for the CashBox (assembling/publishing the CashBox)
  6. Download the Launcher
  7. Start the Launcher

If you want to update the configuration later (e.g. use a new SCU package version), the following steps must be performed:

  1. Update of the affected configuration in the fiskaltrust.Portal (e.g. SCU configuration).
  2. Rebuild configuration for the CashBox in the fiskaltrust.Portal (assembling/publishing the CashBox)
  3. Stop the fiskaltrust.Middleware and restart the launcher at the cash register.

The launcher then automatically loads the new version of CashBox, applies it and starts the fiskaltrust.Middleware with the new configuration.

With a large number of cash registers, the initial rollout is very time-consuming if it is performed using the manual processes described above.

Templating to create CashBoxes#

When templating, it is possible to automatically create CashBoxes for the PosOperator with the help of a configuration template. A template is prepared for this and stored for the PosOperator in the fiskaltrust.Portal. The template then appears in the fiskaltrust.Shop within the PosOperator account as a free product. It can be checked out there in any quantity. The quantity represents the number of CashBoxes that are to be generated automatically. As soon as the checkout process is completed, the fiskaltrust.Portal automatically generates the corresponding number of CashBoxes by applying the template and stores them in the POSOPerators account.

In the following, the individual steps of the process described above are presented in detail. In addition, we provide a video on the topic of tempalting.

Creation and contents of the configuration template#

The template is a JSON string that represents a parameterizable variant of the CashBox (configuration container as JSON string) and can thus contain the configurations of Queues, SCUs and Helpers. It is parameterizable in that the structure for the CashBox to be generated can be defined here (e.g. five Queues, one SCU). In addition, variables can be used as placeholders for the values. As soon as the resulting CashBox is generated, the variables are filled with concrete, final values.

In the following snippet an example of such a template is visualized:

{    "ftCashBoxId": "|[cashbox_id]|",    "ftSignaturCreationDevices": [        {            "Id": "|[scu0_id]|",            "Package": "fiskaltrust.Middleware.SCU.DE.CryptoVision",            "Url": [                "grpc://localhost:10081"            ],            "Configuration": {                "devicePath": "t:"            }        }    ],    "ftQueues": [        {            "Id": "|[queue0_id]|",            "Package": "fiskaltrust.Middleware.Queue.SQLite",            "Configuration": {                "init_ftQueue": [                    {                        "ftQueueId": "|[queue0_id]|",                        "ftCashBoxId": "|[cashbox_id]|",                        "CountryCode": "DE",                        "Timeout": 15000                    }                ],                "init_ftQueueDE": [                    {                        "ftQueueDEId": "|[queue0_id]|",                        "CashBoxIdentification": "|[my_shopcode]|-|[my_tillcode]|",                        "ftSignaturCreationUnitDEId": "|[scu0_id]|"                    }                ],                "init_ftSignaturCreationUnitDE": [                    {                        "ftSignaturCreationUnitDEId": "|[scu0_id]|",                        "Url": "[\"grpc://localhost:10081\"]"                    }                ]            },            "Url": [                "grpc://localhost:10082"            ]        }    ]}

Variables are marked by specifying them within ``|[and]|```. Possible is the specification of system variables. Their values are generated by the fiskaltrust system during the generation. Also possible is the specification of own variables. Their values can be transferred later via an API call to generate the CashBox (see also parameterization of the API call).

In line 1 of the above example, the system variable: |[cashbox_id]|`` is specified as the value for ``"ftCashBoxId". This is the CashBoxID, a value that is automatically generated by the system and used when generating the CashBox at this point.

Line 31, on the other hand, uses its own variables (|[my_shopcode]|`` and |[my_tillcode]|`` ) whose concrete values can be passed later during the API call.

As can also be seen in line 31, the JSON string values can consist of a combination of variables and static parts. However, they can also contain only static "text" or only one variable.

The following tables show the possible contents (data structure) of a template:

FieldnameMandatoryContentDescription
ftCashBoxIdyesGUID StringIdentifies the CashBox in the fiskaltrust system and must therefore be unique. Will later be part of the authentication of the cash register with fiskaltrust. The system variable ```
ftSignaturCreationDevicesnoPackageConfiguration [ ]Array, contains the configurations of the SCUs to be used.
ftQueuesnoPackageConfiguration [ ]Array, contains the configurations of the Queues to be used.
helpersnoPackageConfiguration [ ]Array, contains the configurations of the Helpers to be used.
TimeStampnoDateTime.UtcNow.TicksTime of creation of the template.

A PackageConfiguration object is structured as follows:

FieldnameMandatoryContentDescription
IdyesGUID StringIdentifies the instance of the element that is configured here (SCU, Queue or Helper). For the Queue, the system variable queue{0-9}_id can be used. For SCU the system variable scu{0-9}_id can be used here. For Helper helper{0-9}_id.
PackageyesStringName of the package that should be used to create the element. E.g. fiskaltrust.Middleware.SCU.DE.CryptoVision for a SCU that should communicate with a Cyptovision TSE. Currently supported packages can be found below.
DescriptionnoStringName of the element. E.g. the Queue or SCU
VersionnoStringVersion of the package to be used for creating the element. If no version is specified, the latest version is used.
Configurationno<String, Object>Configuration parameters of the element. E.g. drive letter of the TSE for the Cryptovision SCU, so that the SCU knows how to access the TSE. To be filled depending on the element type. See below.
URLyesString []Array, communication endpoints of the element. E.g. REST endpoint for communication with the Queue.

Queue The following packages are currently available for Queues:

Package NameDescription
fiskaltrust.Middleware.Queue.SQLiteA SQLite database is used as a local persistence layer.
fiskaltrust.Middleware.Queue.EFEntity Framework is used as a local persistence layer.
fiskaltrust.Middleware.Queue.MySQLA MySQL database is used as a local persistence layer.

The following key-value pairs are used in the Configuration object of a Queue:

FieldnameMandatoryContentDescription
init_ftQueueyesConfigurationInitialization parameters for the Queue (general part of the Queue configuration).
init_ftQueueDEyesConfigurationInitialization parameters for the Queue (country-specific part of the Queue configuration).
init_ftSignaturCreationUnitDEnoConfigurationInitialization parameter for linking the Queue with an SCU. Connection values are stored here.
connectionstringnoStringConnection string to the persistence layer. Example see below. With SQLite this field can be omitted if no own database is available. In this case fiskaltrust automatically creates an SQLite database.

Example of a connectionstring when using Entity Framework:

Data Source=.\\!sql-instanz!;Initial Catalog=!fiskaltrust!;User ID=!user!;Password=!password!;MultipleActiveResultSets=True

Example of a connectionstring when using MySQL:

Server=myServerAddress;Database=myDataBase;Uid=myUsername;Pwd=myPassword;

Example of a connectionstring when using SQLite:

Data Source=c:\mydb.db;Version=3;Password=myPassword;

The following key-value pairs are used in the Configuration object of a Queue in the init_ftQueue field:

FieldnameMandatoryContentDescription
ftQueueIdyesGUID StringIdentification of the Queue. The system variable queue{0-9}_id can be used.
ftCashBoxIdyesGUID StringIdentification of the CashBox. The system variable ``
CountryCodeyesStringCountry code. For Germany: "DE".
TimeoutnoIntTimeout in milliseconds.

The following key-value pairs are used in the Configuration object of a Queue in the init_ftQueueDE field:

FieldnameMandatoryContentDescription
ftQueueDEIdyesGUID StringIdentification of the Queue. The system variable queue{0-9}_id can be used. (Here the same value must be used as for ftQueueId).
CashBoxIdentificationyesprintable String (20)Cash register serial number. Also used as client ID for the TSE. Printable string, max. 20 characters.
ftSignaturCreationUnitDEIdyesGUID StringThe ID of the SCU this Queue should connect to.

The following key-value pairs are used in the Configuration object of a Queue in the init_ftSignatureCreationUnitDE field:

FieldnameMandatoryContentDescription
ftSignaturCreationUnitDEIdyesGUID StringIdentification of the SCU to which this Queue should connect. The system variable scu{0-9}_id can be used.
UrlyesStringCommunication endpoints of the SCU. As an array in the string Ex: "[\"grpc://localhost:10081\", \"grpc://localhost:10082\"]" . Normally only one endpoint is needed.

SCU

Folgende Packages stehen aktuell fΓΌr SCUs zur VerfΓΌgung:

Package NameDescription
fiskaltrust.Middleware.SCU.DE.CryptoVisionThis package enables communication with a Cryptovision TSE.
fiskaltrust.Middleware.SCU.DE.DieboldNixdorfThis package enables communication with a Diebold Nixdorf TSE.
fiskaltrust.Middleware.SCU.DE.EpsonThis package enables communication with an Epson TSE.
fiskaltrust.Middleware.SCU.DE.FiskalyCertifiedThis package enables communication with a certified fiskaly Cloud-TSE.
fiskaltrust.Middleware.SCU.DE.SwissbitThis package enables communication with a Swissbit TSE.

The following key-value pairs are used in the Configuration object of a SCU depending on the manufacturer of the TSE:

Swissbit TSE

FieldnameMandatoryContentDescription
devicePathyesStringDrive letter followed by colon (e.g. E:). Represents the drive to which the Swissbit TSE is connected at the cash register.
adminPinnoStringAdmin PIN. Only to be entered if the TSE has been initialized outside fiskaltrust. If the TSE is not yet initialized, this value is not required.
timeAdminPinnoStringTime Admin PIN. Only to be specified if the TSE has been initialized outside of fiskaltrust. If the TSE is not yet initialized, this value is not required.

Cryptovision TSE

FieldnameMandatoryContentDescription
devicePathyesStringDrive letter followed by colon (e.g. E:). Represents the drive to which the Cryptovision TSE is connected at the cash register.
adminPinnoStringAdmin PIN. Only to be entered if the TSE has been initialized outside fiskaltrust. If the TSE is not yet initialized, this value is not required.
timeAdminPinnoStringTime Admin PIN. Only to be specified if the TSE has been initialized outside of fiskaltrust. If the TSE is not yet initialized, this value is not required.

Diebold Nixdorf

FieldnameMandatoryContentDescription
comPortyes (only USB)StringDefines the Com port to which the TSE is connected. For example COM6. Only to be used if it is a USB TSE without Connect Box.
urlyes (only Connect Box)StringConnection url if it is a Diebold Nixdorf Connect Box.
adminUsernoStringAdmin Username. Only to be specified if the TSE has been initialized outside fiskaltrust. If the TSE is not yet initialized, this value is not required.
adminPinnoStringAdmin PIN. Only to be entered if the TSE has been initialized outside fiskaltrust. If the TSE is not yet initialized, this value is not required.
timeAdminUsernoStringTime Admin Username. Only to be specified if the TSE has been initialized outside fiskaltrust. If the TSE is not yet initialized, this value is not required.
timeAdminPinnoStringTime Admin PIN. Only to be specified if the TSE has been initialized outside of fiskaltrust. If the TSE is not yet initialized, this value is not required.
slotNumberyes (nur Connect Box)IntSlot number of the TSE if a Diebold Nixdorf Connect Box is used.

Epson

FieldnameMandatoryContentDescription
hostyesStringUrl to connect to the TSE. Here the TSE will be reachable.
portnoStringPort to connect to the TSE. Here the TSE will be reachable.
deviceIdnoStringDevice Id if Epson Server.
timeoutnoIntTimeout in milliseconds

fiskaly

FieldnameMandatoryContentDescription
ApiKeyyesStringfiskaly API Key
ApiSecretyesStringfiskaly API Secret
TssIdyesGUID StringID of the TSE from fiskaly

The following key-value pairs can be used in the Configuration object of a SCU independent of the manufacturer of the TSE:

FieldnameMandatoryContentDescription
CounternoIntegerIf the counter is set for an SCU in it's configuration, than the counter can later be used in a template to create a CashBox that doese not include, but needs to reference this SCU. See also chapter Referencing an existing SCU in a template.

System variables#

The following system variables are available for use in the template:

VariableValue
cashbox_idRandom GUID
scu{0-9}_idRandom GUID
helper{0-9}_idRandom GUID
queue{0-9}_idRandom GUID
queue{0-9}_id_base64withoutspecialchars{queue_id}, converted to Base64 without special characters
reference_scu_{type}_{key}_{value}_{attr}References the indicated attribute of an existing SCU with the given key/value pair and of the specified type

Dynamic values are highlighted by {} in this table.

Type#

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

  • cryptovision
  • dieboldnixdorf
  • epson
  • fiskalycertified
  • swissbit
  • swissbitcloud
Attribute#

Indicates the SCU attribute you'd like to reference to. Possible values for attr are

  • id - references the ID of the respective SCU
  • url - references all URLs configured for the respective SCU
Key / Value#

For key and value any valid key / value pair can be used, that has been assigned to one of the SCUs of the chosen type and in the selected outlet.

info

By default, all SCUs purchased via fiskaltrust.Shop get a field counter assigned with an integer value unique within that CashBox.

So, for example, to reference the ID of a fiskaly SCU with a counter value of "1", you'd be using reference_scu_fiskaly_counter_1_id.

Referencing an existing SCU in a template#

A previously created SCU can be referenced in a template. This is important, for example, in the case that a queue of the new CashBox to be created has to access an already existing SCU that is located outside the new cashbox.

The SCU to be referenced is identified by the combination of its type (e.g. Swissbit) and its Counter in the template. The prerequisite is that the SCU to be referenced has a so-called Counter as a key-value pair in its configuration. SCUs created automatically by fiskaltrust (e.g. fiskaly or Swissbit cloud at checkout) already have the Counter set. For SCUs created manually or by a template, the Counter is set via the fiskaltrust.Portal in the configuration area. To do this, create the key-value pair Counter in the configuration of the SCU as follows:

counter-anlegen

When initially creating a new SCU via a template, the Counter can be set in the Configuration area. Example:

"Configuration": {    "devicePath": "E:",    "Counter": 1}

In the template that is to reference the SCU, the following specifications can now be made:

  1. In the ftSignatureCreationDevices section, specify the SCU to reference as follows:
"ftSignaturCreationDevices":[  {     "Id":"|[reference_scu_swissbit_counter_1_id]|",     "Package":"fiskaltrust.Middleware.SCU.DE.Swissbit"  }]

Depending on the type, Id uses the corresponding system variable. In the above example it is the variable reference_scu_swissbit_counter_{0-n}_id. The value {0-n} specifies which SCU should be referenced. In our example it is 1, i.e.: referencescu_swissbit_counter1_id.

Furthermore, the package of the SCU to be referenced must be specified for Package. In our example it is for the Swissbit usb the package fiskaltrust.Middleware.SCU.DE.Swissbit.

  1. The connection of a Queue with the SCU is specified in the template at the following two places:

init_ftQueueDE :

"init_ftQueueDE":[  {     "ftQueueDEId":"|[queue0_id]|",     "ftSignaturCreationUnitDEId":"|[reference_scu_swissbit_counter_1_id]|",     "CashBoxIdentification":"|[queue0_id_base64withoutspecialchars]|"  }]

and

init_ftSignaturCreationUnitDE :

"init_ftSignaturCreationUnitDE":[   {      "ftSignaturCreationUnitDEId":"|[reference_scu_swissbit_counter_1_id]|",      "Url":"[\"|[reference_scu_swissbit_counter_1_url]|\"]"   }]

Here you can find such a template as an example for download: ref-template-example

Template examples#

To simplify getting started with the template mechanism, we've created several examples for different rollout scenarios and setups. The individual examples and the respective downloads are described below. We've also provided a simple Postman collection to test the execution via the API, as described below as well.

NameFilesDescription
A TSE per cash registerDownloadRefers to the rollout scenario A TSE per cash register described above. The template creates a CashBox with a Queue and a SCU that accesses a hardware TSE located in the E: drive. The Queue is accessible via a REST endpoint.
A hardware TSE(s) at a local server for multiple cash registersDownloadRefers to the first part of the above described rollout scenario Hardware TSE(s) at local server for multiple cash registers. The template in the file tse-at-local-server-for-multiple-cashregisters-1-1.json is executed first. It creates the CashBox for the server with a SCU that accesses a hardware TSE. The SCU is given a Counter so that it can later be referenced from the cashboxes of the cash registers. For each cash register, the template from the file tse-at-local-server-for-multiple-cashregisters-1-2.json is then executed. It creates a CashBox that references the SCU from the server and creates a Queue that accesses the server's SCU.
Multiple hardware TSE(s) at a local server for multiple cash registersDownloadRefers to the second part of the above described rollout scenario Hardware TSE(s) at local server for multiple cash registers. The template in the file tse-at-local-server-for-multiple-cashregisters-2-1.json is executed first. It creates the CashBox for the server with two SCUs each accessing a hardware TSE. The SCUs are given a Counter so that they can be referenced later from the cashboxes of the cash registers. For each cash register that is to use the first SCU, the template from the file tse-at-local-server-for-multiple-cashregisters-2-2.json is then executed. It creates a CashBox that references the first SCU from the server and creates a Queue that accesses the first SCU of the server.
A hardware TSE at the main cash register for several additional cash registersDownloadRefers to the rollout scenario Hardware TSE at the main cash register for several additional cash registers described above. The template in the file hw-tse-at-main-cashregister-1.json is executed first. It creates the CashBox for the main cash register with its own Queue and a SCU that accesses a hardware TSE. The SCU gets a Counter so that it can be referenced later from the cashboxes of the other cash registers. For each other cash register, the template from the file hw-tse-at-main-cashregister-2.json is then executed. It creates a CashBox that references the SCU from the main cash register and creates a Queue that accesses the SCU of the main cash register.
A cloud TSE for multiple cash registers (without SCU)DownloadRefers to the rollout scenario described above: A cloud TSE for multiple cash registers. The template in the file a-cloud-tse-for-multiple-cashregisters-1.json is executed per cash register. The prerequisite here is that a SCU already exists, because it is not created when the CashBox is generated, but only referenced. The SCU is usually created automatically by fiskaltrust when checking out a cloud TSE in the fiskaltrust.Shop, but it can also be created manually.
A cloud TSE for multiple cash registers (with SCU)DownloadRefers to the rollout scenario described above: A cloud TSE for multiple cash registers. The template a-cloud-tse-for-multiple-cashregisters-2.json shows an example where the SCU is created as well (additionally to the Queue) in the cashbox. Individual variables are used to place the connection values. Their concrete values can be passed as query parameters when executing the template via the API. The exact procedure for passing the values for the individual variables can be found in the chapter API. This second example also creates a Queue that in contrast stores its data in a MySQL database. It can be especially useful in a BYODC environment.
A CashBox with multiple QueuesDownloadThis template is used to create a CashBox that contains multiple Queues that in turn access the same SCU. It is pictured in the Rollout scenario with terminals above, but can also be used in the case where only one fiskaltrust.Middleware instance is to be used for several cash registers. Each Queue has a different endpoint (port is different) and can be addressed individually.
Data center as operational environment (BYODC)DownloadRefers to the rollout scenario Data center as operational environment described above. Using the template from the byodc-1.json file, a CashBox is created that references an existing SCU. The SCU is usually created automatically by fiskaltrust when checking out a cloud TSE in the store, but it can also be created manually. The second template byodc-2.json shows an example where the SCU is also created in the cashbox. Individual variables are used to place the connection values. Their concrete values can be passed as query parameters when executing the template via the API. The exact procedure for passing the values for the individual variables can be found in the chapter API. The Queue created by the template stores its data in a MySQL database. This is specific for a BYODC environment.

Notes about the postmancollection

The collection can be downloaded here and can be imported with Postman. The collection contains two request entries. One for the sandbox and one for production. The difference between the two is only the Endpoint URL of the API which is addressed via POST. Please read more about the API in the chapter API. Before executing the template it is important to set the correct values in the request. In the Header, the AccountId and the AccessToken of the account for which the template is to be executed must be specified. In the Body the content of the template (json) must be placed between the quotation marks - Important: the content must be "escaped" (search for "online json escape" on the Internet for quick conversion). In the request URL, the outlet number must be passed as a parameter in the query string (e.g. outlet_number=1). Depending on ones requirements, additional parameters can optionally be passed via the query string (e.g. concrete values for individual variables in the template).

Making the configuration template available via the portal#

PosCreators, PosDealers and POSOPerators can store and release configuration templates in the fiskaltrust.Portal. They can do this under the menu item Configuration->Templates.

The template itself (JSON string) is stored in the form field Content.

When creating the template, one can select the target group for which the template is to be released.

Options for PosCreator :

OptionDescription
DeaktiviertNo release, template is still in preparation or has been paused.
Privat (nur Besitzer)Release only for the PosCreator itself (e.g. for testing)
Geteilt mit HΓ€ndlerRelease for the PosCreator itself and for all PosDealers associated with him.
Getielt mit BetreiberRelease for the PosCreator itself and for all PosOperators associated with his PosDealers.

Options for POSDealer:

OptionDescription
DeaktiviertNo release, template is still in preparation or has been paused.
Privat (nur Besitzer)Release only for the PosDealer himself (e.g. for testing).
Getielt mit BetreiberRelease for the PosDealer itself and for all PosOperators associated with him.

Options for PosOperator:

OptionDescription
DeaktiviertNo release, template is still in preparation or has been paused.
Privat (nur Besitzer)Release only for the PosOperator itself.

Furthermore, the template can be personalized with an image and link. Since the template will later appear in the fiskaltrust.Shop for approved accounts, this branding will enable better recognition.

If the PosCreator provides a template for his PosDealers, they can clone the template, possibly adapt it and make it available to their PosOperators as a new template.

Manual execution of the configuration template#

As soon as a template has been released for an account, it appears as a free product in the fiskaltrust.Shop within the released account. The account owner can now check out the template in any quantity. The quantity represents the number of CashBoxes that should be generated automatically. As soon as the checkout process is completed, the fiskaltrust.Portal automatically generates the corresponding number of CashBoxes by applying the template. They can be found here: Configuration->CashBox.

If this is the account of a PosOperator, it is possible to check out different templates depending on the outlet. Therefore, before transferring the template to the shopping cart, you should pay attention to the outlet selection (selection: outlet dropdown in the upper left corner of the fiskaltrust.Shop page).

Under certain circumstances, the PosDealer can check out the template for the PosOperator himself. This is a time-saving optimization that allows PosDealers to operate during the rollout without the intervention of the PosOperator. To do this, however, the PosDealer needs general permission from the PosOperator for the so-called "surrogation" function. With this function, the PosDealer can switch to the account of the PosOperator. See also invitation management.

FAQ: Template for one customer only#

A frequently asked question in this context is whether a template can also be made available only to a specific end customer (PosOperator). To achieve this, the PosDealer can use the "surrogation" function to switch to the account of the PosOperator and create the template there and then release it with the release level Privat (nur Besitzer). Thus, this template is visible via the fiskaltrust.Shop only in the account of this PosOperator.

Use of API and PowerShell for automated execution of the templates#

fiskaltrust provides an HTTP API that allows you to automate CashBox generation using configuration templates. This chapter describes the API and demonstrates a call using PowerShell as an example.

API#

The execution of templates can be easily automated via our HTTP API. You need the template as JSON string, the AccountId and the AccessToken of the account (e.g. of the PosOperator) for which the template should be executed. AccountId and AccessToken can be found in the fiskaltrust.Portal within the corresponding account (menu item: Company name -> Overview in the lower area there is the section API Access).

Authentifizierung

Your request should look like this:

  • Method: POST
  • Headers:
    • accountid: <your-account-id>
    • accesstoken: <your-access-token>
  • Body: JSON template
  • URLs:
    • Sandbox: https://helipad-sandbox.fiskaltrust.cloud/api/configuration
    • Production: https://helipad.fiskaltrust.cloud/api/configuration

Parameterization#

In addition, variables can be added to the query string of the URL, which will then be automatically replaced in the template. For example, change the above URL to the value:

https://helipad.fiskaltrust.cloud/api/configuration?my_variable=123

by doing so, the occurrences |[my_variable]| are replaced with the string 123 before the template is executed.

If not overwritten via the query string, system variables in the template are automatically replaced by the system as described above.

Furthermore, it is possible to pass the following additional (optional) parameters via the query string of the URL:

VariableDescriptionDefault value if not passed
outlet_numberOutlet number{max(outlets used in account's existing cashboxes) + 1}
descriptionGeneral name. Used for the CashBox, contained Queues and SCUs, if not individually overwritten with its own parameter.ft{yyyyMMddHHmmss}
cashbox_descriptionName for the cashBox. Overwrites description ft{yyyyMMddHHmmss}
cashbox_idID of the CashBox. Can be used for new creation and for modification. In case of new creation we recommend not to specify this parameter and to leave its automatic generation to the fiskaltrust system. Attention: will be overwritten by the template field ftCashBoxId.Random GUID
cashbox_ipaddressIP address of the CashBox.Empty string
cashbox_producttypeCashBox Product TypeEmpty string
queue{0-9}_idID of the Queue. This parameter can be used for new Queues and for changes. In case of new creation we recommend not to specify this parameter and to leave its automatic generation to the fiskaltrust system. Attention: will be overwritten by the template field PackageConfiguration.Id.Random GUID
queue{0-9}_descriptionName for the Queue. Overwrites description. Warning: will be overwritten by PackageConfiguration.Description.{description}
queue{0-9}_packageName of the package to create the Queue. Attention: will be overwritten by PackageConfiguration.Package.Empty String
queue{0-9}_versionVersion of the package to create the Queue. Attention: will be overwritten by PackageConfiguration.Version.Empty String
queue{0-9}_urlJSON array with URLs (strings) for the Queue. Attention: will be overwritten by PackageConfiguration.Url.http://localhost:1200/fiskaltrust for the first Queue, http://localhost:1200/fiskaltrust{1-9} for others
queue{0-9}_configurationJSON element to configure the Queue. Like PackageConfiguration.Configuration from the template. Attention: will be overwritten by PackageConfiguration.Configuration.Empty
queue{0-9}_countrycodeCountry code for the Queue. Like PackageConfiguration.Configuration.CountryCode from the template. Attention: will be overwritten by PackageConfiguration.Configuration.CountryCode.Empty
queue{0-9}_timeoutTimeout for the Queue. Like PackageConfiguration.Configuration.Timeout from the template. Attention: will be overwritten by PackageConfiguration.Configuration.Timeout.15000
scu{0-9}_idID of the SCU. Can be used for new creation and for changes. In case of new creation we recommend not to specify this parameter and to leave its automatic generation to the fiskaltrust system. Attention: will be overwritten by the template field 'PackageConfiguration.Id'.Random GUID
scu{0-9}_descriptionName for the SCU. Overwrites description . Attention: will be overwritten by PackageConfiguration.Description.{description}
scu{0-9}_packageName of the package to create the SCU. Attention: will be overwritten by PackageConfiguration.Package.Empty String
scu{0-9}_versionVersion of the package to create the SCU. Attention: will be overwritten by PackageConfiguration.Version.Empty String
scu{0-9}_urlJSON array with URLs (strings) for the SCU. Attention: will be overwritten by PackageConfiguration.Url.net.pipe://localhost/{scu_id}
scu{0-9}_configurationJSON element to configure the SCU. Like PackageConfiguration.Configuration from the template. Attention: will be overwritten by PackageConfiguration.Configuration.Empty
helper{0-9}_idID of the helper. Can be used for new creation and for changes. In case of new creation we recommend not to specify this parameter and to leave its automatic generation to the fiskaltrust system. Attention: will be overwritten by the template field PackageConfiguration.Id.Random GUID
helper{0-9}_descriptionName for the helper. Overwrites description . Warning: will be overwritten by PackageConfiguration.Description.{description}
helper{0-9}_urlJSON array with URLs (strings) for the helper. Attention: will be overwritten by PackageConfiguration.Url.net.pipe://localhost/{helper_id}
helper{0-9}_packageName of the package to create the helper. Attention: will be overwritten by PackageConfiguration.Package.Empty String
helper{0-9}_versionVersion of the package to create the helper. Attention: will be overwritten by PackageConfiguration.Version.Empty String
helper{0-9}_configurationJSON element to configure the helper. Like PackageConfiguration.Configuration from the template. Attention: will be overwritten by PackageConfiguration.Configuration.Empty

Example:

https://helipad-sandbox.fiskaltrust.cloud/api/configuration?outlet_number=55&description=Mdedarh999&queue0_description=Mdedarh999_Q1&queue1_description=Mdedarh999_Q2&queue2_description=Mdedarh999_Q3

Response#

In response, the API returns a JSON string containing the cashboxid of the created CashBox, the accesstoken and the template. The received cashboxid is important for the overall automation of the rollout. See also Rollout automation.

PowerShell#

The following example shows how to send the request to our API using PowerShell:

$headers = @{ accountid = "your-account-id" ; accesstoken = "your-access-token" }$uri = "https://helipad-sandbox.fiskaltrust.cloud/api/Configuration"# Read from template.json and escape JSON string$template = (Get-Content .\template.json -Raw).Replace('\', '\\').Replace('"', '\"')
Invoke-WebRequest -uri  $uri -Headers $headers -Method POST -ContentType "application/json" -Body "`"$template`""

Handling of outlets#

As mentioned above, the checkout of templates can be linked to the outlet of the PosOperator. This chapter shows how this function can be automated via the API.

Creating or importing the outlets in the portal#

Outlets can be created manually via the fiskaltrust.Portal in the PosOperator's account. See menu item Outlets. Furthermore, as an optimization variant under the same menu item, an entire list of locations can be imported with the help of a csv. File a whole list of locations can be imported. The structure of such a list is described in the portal.

Creating the locations is only possible via the fiskaltrust.Portal and cannot be done via the API.

Specification of the outlet in the API call#

The outlet_number parameter can be used in the query string to specify the outlet number for which the template is to be executed:

https://helipad-sandbox.fiskaltrust.cloud/api/configuration?outlet_number=12

Example automated execution of different templates considering the outlets#

Powershell:

$headers = @{ accountid = "your-account-id" ; accesstoken = "your-access-token"  }
$outlets = Import-Csv -Path .\fiskaltrustOutletsWithTemplateFile.csv -Delimiter ';'
foreach ($outlet in $outlets){    $template = (Get-Content .\$($outlet.Template) -Raw).Replace('\', '\\').Replace('"', '\"')
    $uri = "https://helipad-sandbox.fiskaltrust.cloud/api/configuration?description=$([uri]::EscapeDataString($outlet.Name))&outlet_number=$([uri]::EscapeDataString($outlet.OutletNumber))&my_shopcode=$($outlet.OutletNumber)&my_tillcode=$($outlet.TillCode)"
    Write-Output $uri    Invoke-WebRequest -uri  $uri -Headers $headers -Method POST -ContentType "application/json" -Body "`"$template`""}

Step 1: Define header (set accountId and accesstoken)

Step 2: Import outlets from the fiskaltrustOutletsWithTemplateFile.csv file. This file is used both for creating the outlets (import in the portal) and for running the templates. After import in the portal, it is read here. Sample content: LocationId;OutletNumber;Name;Address;ContactName;Telephone;Fax;PostalCode;City;County;StateOrProvince;Country;Template;TillCode ;15;Outlet 5;street address5;;;;80803;MΓΌnchen;;;DE;template1.json;till1 ;16;Outlet 6;street address6;;;;80803;MΓΌnchen;;;DE;template2.json;till2 ;17;Outlet 7;street address7;;;;80803;MΓΌnchen;;;DE;template1.json;till3

Step 3: Iterate over the lines read from the outlet file.

Step 4: for each line read in, the corresponding template is read in and prepared. E.g. for line 1 the content of the file template1.json is read in. In line 2 another template template2.json is needed for another outlet.

Step 5: for each row read in, the Uri for the API call is built. Here the outlet number is passed as a parameter in the query string.

Step 6: for each line read, a call to the HTTP API is made with the previously prepared header, Uri and template.

Summary: In the above example, using the fiskaltrustOutletsWithTemplateFile.csv file, both the outlets were created in the fiskaltrust.Portal (bulk import) and the associated template was executed for each outlet (once - as an example).

Automated rollout of the fiskaltrust.Middleware#

Via the fiskaltrust.Portal you have the possibility to download the launcher. To do so, press the "Download .NET Launcher" button of any CahsBox in the portal. You can now automatically deploy and start the downloaded launcher to all PosOperator cash registers as part of your rollout.

It is important to make sure that the fiskaltrust.Middleware is initialized correctly, i.e. with the corresponding CashBox. For this purpose, the Launcher provides a configuration file (fiskaltrust.exe.config). You can adjust this accordingly before rolling out the launcher to the operator's cash register.

To do this, please specify the values for cashboxid and accesstoken in the appSetting section. You will get these values as return values of the API call for executing the configuration template.

<configuration><appSettings>  <add key="cashboxid" value="your-cashbox-id" />  <add key="accesstoken" value="your-access-token" />

With each restart of the fiskaltrust.Middleware the values from the configuration file fiskaltrust.exe.config are read again.

When starting the launcher (fiskaltrust.exe), which in turn installs the fiskaltrust.Middleware as a service, you should know that the parameters cashboxid and accesstoken can be passed. This specification overwrites the existing configuration from the file fiskaltrust.exe.config. Therefore, especially when starting via the install.cmd or test.cmd file, make sure that the parameters passed here have also been set or adjusted accordingly before starting the launcher (to do this, open the cmd file with an editor and change it accordingly). The description of the possible start parameters can be found here.

Now you can deliver the launcher with the customized configuration file to the PosOperator's cash register and start it with fiskaltrust.exe. The launcher will automatically download the CashBox (configuration container) identified by the cashboxid specified in fiskaltrust.exe.config from the fiskaltrust server, then configure and launch the fiskaltrust.Middleware accordingly.

High degree of automation#

The procedures described above for executing the configuration templates via the API and for the automated rollout of the fiskaltrust.Middleware allow a high degree of rollout automation to be achieved. Only the outlets have to be created manually using the bulk import in the portal.

Closing words#

We hope that the procedures described above for the rollout of fiskaltrust.Middleware have been helpful to you. If you have any further questions, please visit our FAQ list. If you do not find what you are looking for there, please feel free to contact us at info@fiskaltrust.de.

Go to the section: buy and resell fiskaltrust products