eInvoice Validation Explorer for VAMPIRE – Manual

1 · Overview

eInvoice Validation Explorer for VAMPIRE reads a validation report that VAMPIRE PHP or VAMPIRE JS has already written and explains this report in plain sentences. Every finding is mapped to its EN 16931 business term, shown with the actual value from the invoice and highlighted in a view of the document.

It comes in two forms that are one product: as a WordPress plugin, which shows the drop fields 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".

The explorer is meant for everyone who has a validation report of VAMPIRE in front of them and wants to know which field of the invoice is meant: accounting staff who want to send a rejected invoice back to the supplier, service providers who explain a result to their customers, and developers who correct an invoice output.

What it can do

• It reads both forms of report of VAMPIRE: the JSON report together with the invoice in CII or UBL that this report judged, and the XML report in the format of the KoSIT validator, which already contains the invoice.
• It assigns every finding to its EN 16931 business term and shows the value the invoice actually holds at that place.
• Below the findings it shows a document view with the elements of the invoice, their values and their BT numbers.
• A click on a finding leads to its place in the document view; the row lights up briefly.
• The switch "BT numbers" shows and hides the numbers, the switch "findings only" shows only the rows with errors and warnings, and a search box searches the document view.
• It explains the findings with a bundled catalogue of 14 rule sets with 8,604 rules and 311 fields of EN 16931 in total, among them EN 16931 in CII and UBL, XRechnung, Peppol BIS Billing 3, Factur-X EN16931, the French Flux 2 rules and the country adaptations for Portugal, Romania, Croatia, Belgium and Italy. Three further rule sets with 3,190 rules, Factur-X EXTENDED and EXTENDED-CTC-FR in CII and UBL, it explains only with the "Extended Profiles" add-on.
• For a finding that concerns an attachment of the invoice, it names that attachment, for example "Attachment: Aufmass.pdf".
• It works in German, English and French.

What it cannot do

• It does not validate an invoice. The verdict comes from the validator; the explorer reports and explains it.
• It contains no validator. You must already have the validation report.
• It does not manage with the JSON report alone. The JSON report does not contain the document; it only names paths. Without the invoice the document view stays empty.
• It is built for reports of VAMPIRE. The KoSIT validator and Mustang have explorers of their own.
• It accepts JSON and XML files only. A PDF, not even a ZUGFeRD PDF, can be dropped.
• It corrects nothing, writes no invoice and stores neither reports nor invoices.

In which form it comes

In both forms you need the report VAMPIRE wrote. The JSON report needs the CII or UBL invoice as an XML file that this report judged; the XML report brings it along.

2 · Installation

As a WordPress plugin

1. Download the ZIP file from your customer area in the shop on invoicePress.de.
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. Open eInvoice Validation Explorer → VAMPIRE and check that no yellow warning about missing rule data appears there.
5. Create a page, insert the shortcode [spxv_validation_report] and publish the page.

There is nothing to configure to start; the catalogues of rules and fields are inside the plugin. This package is not available through wordpress.org. 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-vampire, open the file einvoice-validation-explorer-for-vampire.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.
2. Hand over the validation report of VAMPIRE and, with a JSON report, the checked invoice. In the plugin there are two labelled drop fields for this, the upper one for the report and the lower one for the invoice. In the app you drag both files onto the one drop zone together; the order does not matter.

1. Read the explained report, which appears on the same page without reloading.
2. Click a finding to jump to its place in the document view.
3. Look at the end of the view for a box "Not placed". It lists messages that belong to no place in the document.

4 · Working with the Validation Explorer

Handing over the report and the invoice

The JSON report of VAMPIRE does not contain the invoice. It names the locations only as paths. That is why the explorer needs both files with a JSON report. The XML report contains the invoice; it is enough on its own, and an invoice handed over in addition is ignored, so that the view always shows the document the validator saw. You can drag a file in, click the drop area, or move to it with the Tab key and open it with Enter or Space.

In the plugin the page has two drop fields, and each is labelled. A filled field shows the file name. As long as one of the two files is missing, nothing is sent, and the page says which file is still missing: "Report received. The invoice is still missing." An incomplete attempt therefore costs no upload from the daily allowance. The order is free.

In the app there is one drop zone for both files. The app tells the files apart not by their names but by their content: what it recognises as a report of VAMPIRE is the report, the other file is the invoice. You can hand over both files at once or one after the other, also from the clipboard; a new file replaces the previous one of the same kind. A line below the drop zone names the report and the invoice; a missing part is marked with a dash. If you hand over only a JSON report, the box "The validated invoice is missing." appears with the button Add invoice. That is not an error message; only the second file is missing.

Reading the explained report

As soon as both files are there, the explorer reads the report and attaches the invoice to it. In the plugin this happens on your website, in the app in the browser; what that means for privacy is described in chapter 9. Then the validator's findings appear. Every finding is assigned to its EN 16931 business term and shows the value the invoice actually holds at that place. If a finding concerns an attachment, the name of that attachment stands below its fields.

Jumping to the place in the document

Below the findings is the document view. It lists the elements of the invoice with name, value and BT number. A click on a finding's link scrolls the view smoothly to the row concerned and puts it in the middle. The row stays highlighted for a moment so that you find it at once.

Showing and hiding BT numbers

Above the document view is the switch "BT numbers". When it is on, every element carries its number from EN 16931. When it is off, the numbers disappear and the view becomes calmer. In the app the switch is on when a report opens. In the plugin the setting "Show BT numbers by default" and the shortcode attribute bt decide how it stands when the report opens (chapter 13).

Showing findings only and searching the document

The switch "findings only" limits the document view to the rows that carry an error or a warning. The search box with the placeholder "Search BT field, element name or value …" searches the document view while you type. It searches the element name, its value and its BT number; upper and lower case do not matter. Matches are marked, all other rows are hidden. The search and "findings only" work together: if both are active, you see only rows with a finding that also match the search term.

The box "Not placed"

Some messages point to no place in the document, for example because they concern the schema and not a single element. These messages stand in a box of their own at the end, with their number in the heading. Every row names the rule ID or "without a rule ID", the reason why it could not be placed and, if present, the path from the report.

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, and a change also switches the open report. Numbers and dates follow the language. If a translation is missing, the English original appears.

Resetting

As soon as a report is open, the button Reset appears. It clears the drop area and removes the report view and all notes. Report and invoice are then gone, because the explorer does not store them.

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 → VAMPIRE. 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 handed over an invoice that does not belong to the report. The explorer does not reject the attempt. It shows all findings and above them a note that the invoice could not be matched to the report, or it lists the messages under "Not placed". Check whether it really is the file the validator judged, and hand over both files again.

You only have the report. The explorer still reads it completely and shows the messages. The document view stays empty.

You checked an invoice in the EXTENDED profile. Without the "Extended Profiles" add-on, a finding on a rule of the extension shows the ID and the validator's message, and a note says what the add-on would add. With the add-on, the fields and rules of the extension appear. How the add-on reaches the app or the plugin is described in chapter 12 and chapter 13.

You want to show the report once for experts and once for accounting. In the plugin, put [spxv_validation_report bt="0"] on the page for accounting and [spxv_validation_report bt="1"] on the page for experts. 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.

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 and an invoice regularly contain names, addresses, bank details and amounts. Where they go depends on the form.

In the app both files stay in the browser. They are read there and not sent; there is no server that receives them. 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; the server concerned then learns your IP address for technical reasons, but invoice and report are not sent even then (chapter 12). In the browser the app only remembers the language chosen last.

In the plugin both files go to your own website as soon as both fields are filled. The explanation is created there. The files are read from the temporary upload and processed in memory; they are not moved to the upload directory, and their content is written to no log. They go neither to invoicePress nor to any third-party service; the plugin makes no request to another server and loads no fonts from outside. For the daily limit it keeps a counter per visitor and calendar day: per user for logged-in users, and by a hash of the IP address for anonymous visitors. The counter expires after one day. Only the settings are stored permanently.

Security in the plugin. Every upload needs a fresh security token from the server; it is fetched before every send, so a page from a page cache works as well. The server itself checks the extension, content type and size of every file. The settings page is reserved for users who may manage options.

Checking it yourself. Open your browser's network panel and hand over report and invoice. 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

The server answers errors with a fitting status code: 400 for a missing or unreadable file, 403 for an invalid security token (AJAX), 413 for a file that is too large, 415 for a wrong file type, 422 for an unreadable report and 429 when the daily limit is reached.

add_filter( 'spxv_force_enqueue', '__return_true' );

In the app

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

The app's file dialogue accepts .xml, application/xml and text/xml.

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. Plugin and app carry the same version number.

12 · As an app

12.1 Folder and start file

The app is the folder einvoice-validation-explorer-for-vampire. 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; 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.

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. 'local' means not online at all, not "later": the page makes not a single request, not even a failing one, because a blocked request would still appear in the proxy's log.

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 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 Data status and printing

Above the report view, a small line says what the report was explained with: the recognised profile, the syntax and the names of the data packages used, with their version. If the invoice is there, the app determines the profile from the invoice itself, otherwise from the report.

When printing, the page hides the drop zone, the status line and the footnotes. 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 existing style sheet:

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

The order matters: the line must come after the existing style sheet, 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 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. In the browser only the language chosen last stays remembered, under the key einvoice.lang.

12.7 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-vampire 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 "VAMPIRE 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 two drop fields appear on every page that carries the shortcode [spxv_validation_report], in the language of the page.

The shortcode has no further attributes.

[spxv_validation_report]
[spxv_validation_report bt="0"]
[spxv_validation_report bt="yes"]

13.2 The settings page

The settings are under eInvoice Validation Explorer → VAMPIRE. The table gives the English labels as they appear on an English site. Above the table the page names the shortcode. If the plugin does not find its rule data, a yellow warning appears there as well.

13.3 The remaining uploads

Below the drop fields stands how many uploads the visitor has left today. The number is updated after every explained report. Only a report that was actually explained counts; a rejected or incomplete attempt does not. 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 confirm that WordPress should replace the existing version. Your settings are in the database and are kept. WordPress does not report a new version by itself, because the plugin brings no update check of its own.

To remove it, deactivate and delete the plugin under "Plugins" and take the shortcode [spxv_validation_report] off your pages, otherwise it stands there as text. The plugin creates no database table of its own. It does not clean up its settings when deleted; they stay in the database. The counters of the daily 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 xv-bericht.en.png. The images show sample data only.