Mustang
Validate invoice XML with the Mustang CLI.
The Mustang plugin checks an invoice against the Mustang CLI. It writes the XML to a temporary file, runs java -jar, and reads the CLI report. A valid document resolves with no value. An invalid document throws ZugferdError.
Installation
Install the plugin
The machine that runs validation needs a Java runtime, with java on your PATH. When JAVA_HOME is set, setup looks in JAVA_HOME/bin. You can download a runtime from the official Java website.
npm install @node-zugferd/validator-mustang@betaInstalling the package downloads Mustang-CLI.jar. Run the installer again if that download did not finish:
npx node-zugferd-mustangAdd the plugin to your instance
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { mustang } from "@node-zugferd/validator-mustang";
export const invoicer = zugferd({
profiles: [en16931],
plugins: [
mustang(),
],
// ...
});macOS temporary directory
The default temporary directory on macOS can be a symlink, and the Mustang CLI can fail
when it receives that path. Set tempDir to a real absolute directory.
Automatic validation
autoRun defaults to true. create then validates the XML it just built, and a Mustang failure rejects that call. An afterXMLBuild hook on your zugferd() options still runs after this check.
import { invoicer } from "./invoicer";
import { data } from "./data";
await invoicer.create("en-16931", data);With the parser plugin on the same instance, parse also runs Mustang on the XML before it maps fields. Set autoRun: false to keep invoicer.mustang.validate available and skip both of those automatic checks.
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { mustang } from "@node-zugferd/validator-mustang";
import { parser } from "@node-zugferd/parser";
export const invoicer = zugferd({
profiles: [en16931],
plugins: [
parser(),
mustang({
autoRun: false,
}),
],
});Manual validation
invoicer.mustang.validate takes a profile id and the invoice XML or PDF. The id may also be an object with an id field and has to be one of the supported profiles. Mustang then reads the rules from the bytes itself.
import { readFile } from "node:fs/promises";
import { ZugferdError } from "@node-zugferd/core/error";
import { invoicer } from "./invoicer";
try {
await invoicer.mustang.validate(
"en-16931",
await readFile("invoice.pdf"),
);
} catch (error) {
if (error instanceof ZugferdError) {
console.error(error.message);
} else {
throw error;
}
}Any other profile id logs a warning and the call resolves, leaving the XML unchecked.
Supported profiles
validate and the automatic checks accept these ids. create passes the id of the profile it built.
Findings
Mustang prints an XML report. This plugin treats that report as follows:
- Errors and exceptions are joined with a blank line and thrown as a
ZugferdError.error.messageis that text. - Warnings are written with the zugferd logger. A warning on its own leaves the document valid.
- Notice-level findings are omitted.
- A report that cannot be parsed throws
ZugferdErrorwith the messageFailed to parse Mustang validation output.
Compared to XSD
Mustang is slower than the XSD validator. Each check starts a Java process and runs the CLI, while XSD validates in-process in JavaScript.
Mustang also requires a Java runtime, which XSD does not. In return, Mustang checks more than the XML schema. It also applies the business rules of each profile and checks PDF/A compliance, so it reports errors that XSD alone does not catch.
Options
Prop
Type