Skip to main content

Automatic TSE Replacement

Harald Krondorfer
  • Updated

This article describes how to configure the automatic replacement of the certified technical security device (TSE/TSS).

Replacing a TSE may be necessary under certain circumstances, such as:

  • if the certificate for the TSE in use is due to expire,
    • and a switch to a different TSE manufacturer is preferred,
  • a hardware TSE is faulty and can no longer be used,
  • a cloud TSE has been marked as 'defective' by the relevant manufacturer and can no longer be used.

RetailForce provides a service that allows a TSE to be replaced automatically. The replacement can be configured so that:

  • a TSE from the same manufacturer or
  • one from a different manufacturer is used as the new TSE.

The article "Test – Automatic TSE Replacement" explains how to test the automatic TSE replacement function.

Criteria for TSE replacement

Prerequisites for automatic replacement

The Fiscal Service can only carry out the replacement under certain conditions:

  • Version
    • Version 1.11.18 of the Fiscal Middleware must be installed.
  • FiscalCountry
    • Automatic TSE replacement is, of course, only possible for German systems.
  • Configuration
    • Automatic TSE replacement must be configured and enabled in the relevant client.
  • Availability
    • If a hardware TSE is to be used for the replacement, a new hardware TSE must also be available on the system (plugged in);
    • If a cloud TSE is to be used for the replacement, it must be possible to establish an internet connection to the relevant manufacturer.
  • Open transactions
    • There must be no open transactions (createDocument has been executed, but the transaction has not yet been finalised using storeDocument or cancelDocument).
  • End-of-day (EndOfDay)
    • The automatic replacement is only carried out after a daily closing (document of type: "[99] = EndOfDay" was booked).
  • Licences
    • Licence for the current TSE;
    • Licence for the new TSE (if different from the TSE currently in use);
    • Licence for the TSE replacement ("TSE Change").

Attention: the automatic TSE replacement will not be carried out if **any of the prerequisites** are not met. For exceptions, see the sections "Certificate expiry" and "Faulty TSE".

Note: to receive status notifications vie email relating to the automatic TSE change, we recommend selecting a "Technical contact" in the RetailForce Portal (setting in Organisation: "Technical contact").

Licences

The settings for replacing a TSE can be configured at any time. However, for this to actually take place, the correct licences must be assigned.

  • TSE Change: this licence is required for a replacement to take place at all,
  • TSE Licences: a corresponding licence must also be assigned for each TSE that has been configured (Primary and Secondary TSE).

TSE Replacement Trigger

If automatic TSE replacement is configured and enabled, the RetailForce system will attempt (!) to carry out the automatic replacement when the following events occur:

  • The TSE certificate has expired or is due to expire within a specified time window,
  • The TSE is faulty (e.g. no longer functioning, has been marked as 'DEFECTIVE' by the manufacturer).

Certificate Expiry

The following sequence of events applies when the certificate of the currently used TSE expires and automatic replacement has been enabled:

  • 14 days before the certificate expires:if there are no open TSE transactions, the Fiscal Client trys to carry out the automatic replacement after a daily closing (EndOfDay document);
  • if the replacement could not be successfully carried out within the first 7 days (the period from 14 to 7 days before the certificate expires):
    • from 7 days before the certificate expires, open transactions are closed automatically be the client following an EndOfDay and an attempt is made to carry out the replacement;
    • from 3 days before, an attempt is made to carry out the replacement after every document (not just after an EndOfDay); any open transactions are closed automatically;
    • if the certificate has already expired: an attempt is made to carry out the replacement before every CreateDocument.

Note: Within the 14-day period, the Fiscal Client checks with each cloud/connect whether the criteria for a replacement are met and attempts to replace the TSE.

Faulty TSE

Faulty TSEs include, for example, hardware TSEs that are no longer recognised by the system, or cases where a fiskaly TSE has been set to 'DEFECTIVE' status and can no longer be used.

The same rules apply to faulty TSEs as in the case where the TSE certificate has already expired. Before each createDocument operation, the client attempts to replace the faulty TSE with a new one.

Attention: In this case still open transactions can no longer be closed, as signatures can no longer be generated on the old TSE and the new TSE "is unaware of the old, open transactions" (as these transactions were not initiated on the new TSE, but on the old one).

For TSEs with the status 'DEFECTIVE', the Fiscal Client carries out the replacement immediately as soon as the endpoint cloud/connect (or another endpoint that involves the transmission of CloudApiKey and CloudApiSecret) is called.

This only applies if the "Enable automatic TSE replacement" checkbox is ticked (see the "Configuration" chapter).

Note: In the case of defective fiskaly Cloud TSEs, we recommend first carrying out or testing the replacement on a single live system (client).

Configuration

Automatic TSE replacement is defined via the Germany configuration.

Since release 1.11.18, the following configuration options have been available in the portal:

  • Selection of TSE for replacement (Primary TSE & Secondary TSE)
    • "Use for new clients" – when a new client is first initialized, a TSE of this type is used,
    • "Use for replacements" – when a replacement is to be carried out, a TSE of this type is used.
  • Option to enable automatic TSE replacement ("Enable automatic TSE replacement")

Attention: automatic TSE replacement is only activated after "Enable automatic TSE replacement" checkbox is also ticked!

Selecting a TSE for replacement

For each TSE defined in the configuration (Primary TSE & Secondary TSE), you can specify which of these TSEs should be used during initial commissioning and for replacements.

Possible settings

The following combinations are possible:

Same TSE for replacement

In this case, the same TSE is used both during initial commissioning and in the event of a replacement. To do this, you must:

  • Either configure a Primary TSE or a Secondary TSE,
  • and set both options ("Use for new clients" and "Use for replacements") for this TSE.

In the example below, a Secondary TSE of type "[3] = Swissbit Cloud 2.0" is configured as a secondary TSE, with both options selected.

This means that every terminal to which this configuration has been assigned uses the Swissbit Cloud TSE 2.0 during activation. If, for example, the certificate of the activated TSE expires, a new Swissbit Cloud TSE 2.0 is activated.

TSE-replacement-secondary-both-options.png

As described above, the replacement will only take place if the "Enable automatic TSE replacement" tick box is also ticked!

Different TSE for replacement

In this case, a specific TSE is configured for initial commissioning ("Use for new clients") and a TSE from a different manufacturer is configured in the event of a replacement. To do this, you must:

  • configure two TSEs, both
    • a Primary TSE and
    • a Secondary TSE
  • set the "Use for new clients" option for one TSE, and 
  • the "Use for replacements" option for the other TSE

In the example below, terminals are commissioned using the Secondary TSE (fiskaly Cloud). If the criteria for automatic TSE replacement are met, a new TSE of the type Swissbit Cloud TSE 2.0 will be activated and used from that point onwards.

TSE-replacement-different-TSE.png

Distribution of Configuration

There are two options available for distributing the new configuration to all clients that are already in operation:

  • Trigger automatic distribution from the Cloud Portal using the "Push Configuration TSE" button, or
  • Update the client's configuration using PUT /api/v1/management/clients/byCloud/{clientId}.

With both methods, the new configuration – which contains rules for TSE replacement – is transmitted to the client(s).

Push Configuration TSE

You will find this button as an action item under the "Configuration" menu item once you have selected (clicked on) the relevant configuration.

When the button is pressed, the behaviour differs between local clients (local middleware installation) and clients in the Cloud Fiscalisation Service:

Behaviour for local middleware installation

This button is intended solely for distributing the configuration and activating automatic TSE exchange!

After pressing the button, a command is sent to all connected clients to download the current configuration from the portal. In this context, 'connected' means: clients to whom this configuration is assigned directly or indirectly (via organisation, company or store).

Clients that do not have an active cloud connection at that moment (no active connection to the portal via 'cloud/connect') will NOT receive the new configuration.

It may therefore be necessary to trigger "Push Configuration TSE" several times until all clients have retrieved the configuration.

Each client reports the successful retrieval of the configuration back to the portal. A notification is displayed via the bell icon (top right). The "TSE replacement" dashboard view also provides an overview of the status of the TSE replacement (see Article: Dashboard Germany – TSE Information).

Behaviour of the Cloud Fiscalisation Service

As with the local installation, a command is triggered here to update the configuration on the clients. However, the command is only delivered the next time the client calls the 'cloud/connect' function.

The portal "remembers" the command status (which client is currently not connected and which has already retrieved the configuration).

This means that, with the Cloud Fiscalisation Service, it is not necessary to reactivate "Push Configuration TSE".

Notifications

Notifications and messages relating to the replacement of a TSE are:

- displayed via the bell icon in the portal (top right),
- shown in the log events (for each terminal), and
- sent by email.

Bell

The bell icon displays the following types of messages:

- Hardware TSE is not available on the relevant system (not plugged in),
- Notifications relating to PushConfiguration (configuration has been retrieved by the relevant client or could not be carried out).

Log Events

The "Log Events" log can be accessed via the corresponding action item on each terminal. It contains all events relating to the replacement of the TSE on the respective terminal.

Email notifications

Success and error messages can also be sent via email. Email notifications are only sent if a technical contact (setting in Organisation: "Technical Contact") has been selected in the portal.

Messages are sent in batches, hourly.

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk