eInvoice Validation Explorer for KoSIT – Manual

1 · Overview

eInvoice Validation Explorer for KoSIT reads a validation report that a validator has already written about an e-invoice and explains it in plain language. A rule ID such as BR-CO-10 becomes a sentence that says which field of the invoice is meant, which value it actually holds and what the rule requires.

It comes in two forms that are one product: as a WordPress plugin, which shows the drop zone on a page of your website, and as an app, that is, a folder with an HTML file that runs in the browser without a server. Both show the same report in the same way and carry the same version number. Chapters 1 to 11 describe both together; where plugin and app differ, a sentence points to chapter 12 "As an app" or chapter 13 "As a WordPress plugin".

Who it is for

• Accounts payable and accounting staff who receive a validation report and want to know what it means.
• Service providers and agencies who want to make a validation result readable for their customers.
• Developers who want to see a finding together with the business term of EN 16931 without opening the specification every time.

What it can do

• It reads the report XML of the KoSIT validator (rep:report, also called VARL) and the KoSIT validator's report as HTML.
• It also reads the reports of the plugin "eInvoice Validator for VAMPIRE", which writes the same report format.
• It shows the validator's verdict, the name of the validation scenario and every validation step with its findings.
• It gives every finding a plain-language explanation, as far as the bundled rule catalogue holds a text.
• It assigns a finding to the field of EN 16931 (BT or BG number) and shows the value the document actually holds there.
• It shows the content of the document below the findings; a click on a finding jumps to the place concerned.
• It offers a search in the document content and two switches: "BT numbers" and "findings only".
• It works in German, English and French.

What it cannot do

• It does not validate. It contains no validator. It reports what a validator decided. If the validator is wrong, the explorer explains the error too.
• It does not repair. It writes no field, creates no invoice and delivers no corrected document.
• It stores nothing. There is no archive and no history of earlier reports.
• It does not invent explanations. Where the catalogue holds no plain text, the validator's own message is shown, marked as such.
• It does not read invoices. If you hand over the invoice instead of the report, it rejects the file with a note.

In which form it comes

Neither form needs Java, an outside service, an API key or a database table of its own. The validation report comes from a validator you already use: the KoSIT validator or the plugin "eInvoice Validator for VAMPIRE".

2 · Installation

As a WordPress plugin

1. Download the ZIP file from the shop on invoicePress.de to your computer.
2. In WordPress, open Plugins → Add New Plugin and choose Upload Plugin.
3. Choose the ZIP file, click Install Now and then Activate Plugin.
4. Create a page, insert the shortcode [spx_validation_report] and publish the page.

Instead of uploading, you can also place the unpacked folder in the directory wp-content/plugins/ and then activate the plugin on the "Plugins" page. After activation there is nothing to configure; the catalogues of rules and fields are inside the plugin. Settings, updating and removing are described in chapter 13.

As an app

1. Download the ZIP file from the shop on invoicePress.de and unpack it wherever you like: in your documents, on a USB stick, on a network drive or in a directory of your web server.
2. In the folder einvoice-validation-explorer-for-kosit, open the file einvoice-validation-explorer-for-kosit.html with a double click.

The app is not installed, only placed. It needs no server and, as delivered, loads nothing from the internet. The content of the folder, the settings and updating are described in chapter 12.

3 · First steps

1. Open the page with the shortcode or the start file of the app. You see the drop zone for a validation report.

1. Drag your validator's report onto the zone, or click it and choose the file. Files with the extensions .xml, .html and .htm are allowed.
2. The explained report appears on the same page without reloading it. Read the verdict first and then the findings.
3. Click a finding. The document content below scrolls to the place concerned, and the row is briefly highlighted.

1. Drag in the next report if you want to read another one. It replaces the previous one.

4 · Working with the Validation Explorer

Opening a report

You drag a file onto the drop zone, or you click it and choose a file. With the keyboard you reach the zone with the Tab key and open the file dialogue with Enter or the space bar. In the app you can also paste a copied file from the clipboard into the page.

You always hand over one file only: the report. The content of the document that you see below the findings comes from the report itself, because a validation report of the KoSIT validator carries the validated invoice inside it. If you hand the app several files at once, only the last one counts, because two reports at once would lay two verdicts on top of each other.

In the plugin the report is sent to your website and read there; in the app the browser reads it itself. What that means for privacy is described in chapter 9.

Reading the verdict and the validation steps

At the top of the report is the validator's verdict, together with the name of the validation scenario. Below it come the validation steps with the number of their findings; the numbers carry the colour of their severity. A report that contains only warnings and no errors counts as passed, as the validator recommends.

Understanding a finding

Every rule appears once in the report. Errors and warnings have a tinted background with a coloured edge. For a rule you see:

• the plain-language explanation, as far as the catalogue holds a text, otherwise the validator's message, marked as such;
• the fields concerned, marked and shown with their name instead of the name of the XML element;
• after each field, the value the document actually holds there.

Amounts appear with two decimal places in the notation of the chosen language. When you move the mouse over such an amount, a tooltip shows the value as it stands in the document. If a finding concerns an attachment of the invoice, the report names that attachment, for example "Attachment: Aufmass.pdf".

Jumping from the finding to the place in the document

Below the findings, the content of the document stands as a list. Rows with an error or a warning are highlighted there. A click on a finding scrolls the document content smoothly to the row concerned and highlights it for a moment so that the eye finds it.

Searching the document content

Above the document content is a search box with the placeholder "Search BT field, element name or value …". While you type, only the rows whose field name, value or BT number contains the search term stay visible; the matches are highlighted. Upper and lower case do not matter. So you can search for a name, an amount or for "BT-5".

Showing and hiding BT numbers

The switch "BT numbers" shows or hides the numbers of the fields in the document content. In the app it is on when a report opens. In the plugin the operator decides whether it is on or off when a report opens (chapter 13). Every visitor can change it in the report.

Showing only the rows with findings

The switch "findings only" limits the document content to the rows with an error or a warning. This switch and the search work together: if both are active, you see only the rows with a finding that also match the search term.

Reading reports on extended profiles

If a report names fields or rules of an extension, such as ZUGFeRD / Factur-X EXTENDED or EXTENDED-CTC-FR, the report says so above the verdict. Without the add-on "Extended Profiles", a finding on such a rule shows the ID and the validator's message, and the core fields appear completely. With the add-on these rules are explained, and findings on fields of the extension show their value from the document. How the add-on reaches the app or the plugin is described in chapter 12 and chapter 13.

The language

In the plugin the interface follows the language of the page. The app has a language choice at the top right with German, English and French; it starts in the language chosen last, otherwise in the language of the browser. A change also switches the open report: headings, field names and explanations appear in the new language, and numbers and dates follow its notation. If a text has no translation, the English original appears.

Resetting

As soon as a report is open, the button Reset appears. It clears the view. The report is then gone, because the explorer does not store it.

5 · Settings

In the report itself the explorer has only the search and the two switches from chapter 4. Everything else is set by the operator, and the two forms keep these settings in different places:

• In the app the settings are in the file config.js in the folder of the app. There you decide whether the page may load anything from the internet (chapter 12).
• In the plugin they are in WordPress under eInvoice Validation Explorer → KoSIT. There you set the daily limit per role, the largest file, the default of the BT numbers and the design kit (chapter 13).

6 · Special cases

You only have the report as HTML. Hand over the HTML file. The explorer reads it as well. If you have the choice, take the report XML; it is the validator's original output.

You want to show the report once for experts and once for laypeople. In the plugin, create two pages, one with [spx_validation_report bt="1"] and one with [spx_validation_report bt="0"]. In the app the reader hides the BT numbers with the switch.

You want to rule out every request to the outside. Use the app with its default settings; it then makes no request at all (chapter 12). The plugin makes no request to third parties anyway (chapter 9).

You want to pass the tool on. Pass on the whole folder of the app, for example as a ZIP. The recipient unpacks it and opens the start file; nothing needs to be installed.

You want to print an explained report cleanly. The app includes a print style sheet of its own that you register once (chapter 12).

Your reports are very large. In the plugin, raise "Maximum file size ( MB )" (chapter 13). The app has no limit of its own.

7 · Working with other packages

The explorer works on its own. The following packages are optional.

8 · Troubleshooting

The messages appear in the chosen language. The table gives the English wording. Messages that occur in only one of the two forms are marked "(plugin)" or "(app)".

9 · Privacy and security

A validation report carries the validated invoice inside it and therefore regularly contains names, addresses, IBANs and amounts. Where it goes depends on the form.

In the app the report stays in the browser. It is read there and sent nowhere. There is no server that receives it. As delivered, the page makes no request at all; only when you change something in config.js does it fetch data packages from invoicepress.de or fonts from Google Fonts, and even then it sends nothing from the report (chapter 12).

In the plugin the report goes to your own website. The file is sent to your WordPress installation, read there and returned as an explained report. The data pass through your server's memory during the request. This belongs in your own privacy policy. Nothing goes to third parties: the plugin makes no outgoing request, no statistics, no licence check and no update service. It therefore also works without internet access and behind a firewall.

What is stored. The report is stored in neither form. The plugin reads the file from the temporary upload in memory only; it does not reach the media library, the database or any log line. The plugin stores only its settings and, per visitor and day, a counter for the upload limit. For logged-in users the counter is tied to the user account, for anonymous visitors to the IP address in hashed and shortened form; the IP address itself is not stored, and the counter expires after one day. The app only remembers the language chosen last in the browser.

Security in the plugin. Every upload carries a security token that the page fetches fresh from the server; this way it also works on pages served from a cache. The server itself checks file size, file extension and file content.

Checking it yourself. Open your browser's network panel and hand over a report. In the app with its default settings no request appears there. In the plugin only the request to your own website appears.

10 · For developers

In the plugin

Status codes of the REST route and the AJAX action spx_render:

The rendering sits in an open shadow DOM on the element with the class spx-host; the theme's styles do not apply there, but the page's own code can reach the report.

In the app

The app has no hooks, filters or events of its own. It can be configured from outside at these places:

11 · Versions

The complete list of changes is in the file CHANGELOG.md in the folder of the plugin and in the folder of the app. Up to version 1.7.1 of the plugin, the app counted a series of its own from 1.0.0 to 1.4.4; since 1.8.0 both carry the same number.

12 · As an app

12.1 Folder and start file

The app is the folder einvoice-validation-explorer-for-kosit. It must stay complete. It contains:

The start page runs with a double click from the hard disk, from a USB stick, from a network drive or from a web server. On a network drive you share the path to the start file, for example as a shortcut; nothing needs to be set up on the workstations.

12.2 The file config.js

The app has no settings page. Its settings are in config.js. You open the file with a text editor, change a value, save and reload the page in the browser.

Of the six keys, two therefore take effect in this version: dataSource and fontsLocal. If you run the app behind a firewall, leave both at their defaults. This matters because a blocked request still appears in the proxy's log, where it looks like a data leak.

For use on a public page, with fonts from Google Fonts and with a look for newer data on invoicepress.de, change two lines:

	dataSource: 'online',
	fontsLocal: false,

12.3 The add-on "Extended Profiles"

There is neither a switch nor a licence key for the add-on in config.js. It is a package of its own from the shop. Unpack it into the folder data/protected/ of the app; the page finds it by itself.

12.4 Printing

When printing, the page hides the drop zone, the line with the report name and the footer notes. If you want a view set up specifically for paper, register the included style sheet assets/css/kit-print.css. It sets a white background, hides the toolbar and draws signal edges as lines instead of shadows. To do so, add this line in the <head> of the start file after the kit:

<link rel="stylesheet" href="assets/css/kit-print.css" media="print">

The order matters: the line must come after the kit, otherwise the screen rules win.

12.5 Fonts

You may delete the folder assets/fonts/ if the folder is to become smaller. The view stays fully styled and then uses system fonts.

12.6 Embedding in SharePoint

SharePoint Online does not run HTML files from a document library, and the "Embed" web part does not accept <script> tags. Place the folder on a web server with https:// and put this frame into the "Embed" web part; ADDRESS-OF-THE-FOLDER stands for the address of the folder on your server:

<iframe src="ADDRESS-OF-THE-FOLDER/einvoice-validation-explorer-for-kosit.html" style="width:100%;height:900px;border:0"></iframe>

The administrators of the site collection must allow the server's domain for embedding.

12.7 Updating and removing

1. Back up your file config.js and, if you have set up the add-on, the folder data/protected/.
2. Replace the folder of the app with the folder from the new ZIP.
3. Transfer your settings into the new config.js and put data/protected/ back.

To remove the app, delete the folder. The app creates no database and writes nothing outside its folder to the disk.

12.8 Showing it in the viewer

The app brings an add-on for the app "eInvoice Viewer for Peppol EN 16931". With it, the viewer shows a validation report not only as a list. It also puts every message as a card under the field of the invoice it concerns, as the viewer in WordPress does.

1. Copy the folder einvoice-validation-explorer-for-kosit from this ZIP into the folder of the viewer app, next to its start file. This also applies to the viewer app as a single file.
2. Open an invoice in the viewer. The toolbar now shows the button "Open validation report".
3. Choose the validation report of this invoice. The report appears in the tab "KoSIT Report", and the messages stand as cards at the fields in the tab "Invoice".

If the report belongs to another invoice, the viewer says so and puts no cards. If the viewer has the buttons "Validate with KoSIT", "Validate with Mustang" or "Validate with VAMPIRE", they too show their messages at the fields as long as the folder lies next to the viewer.

13 · As a WordPress plugin

13.1 The shortcode

The drop zone appears on every page that carries the shortcode [spx_validation_report], in the language of the page.

[spx_validation_report]
[spx_validation_report bt="0"]
[spx_validation_report bt="1"]

13.2 The settings page

You find the settings under eInvoice Validation Explorer → KoSIT. The page is only visible to users with the right to manage the site's options.

13.3 The remaining uploads

The drop zone shows how many uploads the visitor has left on this day. The number is updated after every report read. Only a report that was read and rendered successfully counts; a rejected file uses up no upload. If a role's row is empty, there is no limit for it, and the line with the remaining uploads does not appear.

13.4 The add-on "Extended Profiles"

The add-on "eInvoice Viewer – Extended Profiles" is a plugin of its own. It requires the plugin "eInvoice Viewer for PEPPOL & EN16931". When both are active, the explorer also explains the rules of the extensions.

13.5 Updating and removing

Upload the new ZIP file from the shop under Plugins → Add New Plugin → Upload Plugin and let it replace the existing plugin. Your settings are kept, because they are in the WordPress database and not in the plugin's folder. New rule and field catalogues always come with a new version, because the plugin loads nothing at run time. WordPress does not report a new version by itself, because the plugin brings no update check of its own.

You deactivate and delete the plugin on the "Plugins" page. The plugin creates no database table of its own and stores no uploaded files. It does not clean up when deleted: its four settings stay in the database, and the daily counters of the upload limit expire by themselves after one day.

14 · List of images

This list shows which screenshots this manual expects and which were found in the folder screenshots/ of the package. An image is always named key.language.png, for example xk-bericht.en.png. The images show sample data only.