Skip to content

Convert XML file to JSON

The service task "Convert XML file to JSON" reads XML, as text or as a file from the Pantarey storage, and converts it into a JSON object that the following steps access with JSONata. Attributes get the prefix attr_, numbers and booleans are recognized as such. Typical use is the XML of an e-invoice that Extract PDF attachments has returned from a ZUGFeRD PDF, or the response of an XML interface.

Technical name prio_parseXML · Category in the "Select service task" dialog: Data & References

When is this service used?

  • Reading e-invoices: Musterfirma GmbH takes invoice number, date and gross amount from the factur-x.xml of its supplier invoices into the incoming invoice record.
  • XML interfaces: A price list or stock report from a distributor arrives as an XML file and is taken into records.
  • Configuration or export files from other systems are read in the process.

Input

Field Type Required Meaning
xml string or file object yes The XML as text or as {referenceId, filename, contentType}. A file is read completely as UTF-8
options object no Parser options. Default: ignoreAttributes: false, attributeNamePrefix: "attr_". Further useful options: parseTagValue: false (numbers stay text), isArray (elements always as array)
options.processEntities false or object no Limits for XML entities. The limits can be reduced or switched off with false, not increased 
{
  "xml": incomingInvoice.xmlFile,
  "options": { "ignoreAttributes": false, "attributeNamePrefix": "attr_" }
}

Directly from the result of "Extract PDF attachments" under attachments:

{ "xml": attachments[name='factur-x.xml'].data }

Output

The parsed object without a wrapper. From

<?xml version="1.0" encoding="UTF-8"?>
<rsm:Invoice xmlns:rsm="urn:x" version="2.1">
  <ID>RE-2026-0042</ID>
  <IssueDate format="102">20261108</IssueDate>
  <Line no="1"><Qty unit="H87">2</Qty><Price>19.9</Price><Text>Screws</Text></Line>
  <Total currency="EUR">40.3</Total>
</rsm:Invoice>

becomes

{
  "?xml": { "attr_version": "1.0", "attr_encoding": "UTF-8" },
  "rsm:Invoice": {
    "ID": "RE-2026-0042",
    "IssueDate": { "#text": 20261108, "attr_format": "102" },
    "Line": { "Qty": { "#text": 2, "attr_unit": "H87" }, "Price": 19.9, "Text": "Screws", "attr_no": "1" },
    "Total": { "#text": 40.3, "attr_currency": "EUR" },
    "attr_xmlns:rsm": "urn:x",
    "attr_version": "2.1"
  }
}

Rules: Namespaces stay in the key (rsm:Invoice). An element with attributes and text returns the text under #text. One child element becomes an object, several of the same name become an array. An empty element becomes "". Numbers in text form become numbers (20261108), true/false become booleans. The result is stored under the result path, e.g. invoice_xml.

In JSONata, keys with a colon or # are put in backticks:

invoice_xml.`rsm:Invoice`.IssueDate.`#text`

Errors and behavior

  • Missing input throws xml missing.; another type (e.g. a number) throws Invalid XML format. Expected: String or object with "reference".
  • Faulty XML and exceeded entity limits (protection against inflated documents) throw as well. With an error boundary event the process continues there; without one the instance ends in error with a resume point and an error email to the process owner.
  • The service never returns {status, message}.
  • Errors are not retried, as they are not transient. Time limit 900 seconds; nothing is saved.
  • In the dry run the step returns a sample output from the catalog.

Example

Incoming invoice at Musterfirma GmbH: Extract PDF attachments has returned the factur-x.xml under attachments.

  1. Convert XML file to JSON with { "xml": attachments[name='factur-x.xml'].data }, result path invoice_xml.
  2. Output: the object with rsm:CrossIndustryInvoice as the top-level key.
  3. Next step: A database step creates the incoming invoice, with an input expression such as
{
  "invoiceNumber": invoice_xml.`rsm:CrossIndustryInvoice`.`rsm:ExchangedDocument`.`ram:ID`,
  "gross": invoice_xml.`rsm:CrossIndustryInvoice`.`rsm:SupplyChainTradeTransaction`.`ram:ApplicableHeaderTradeSettlement`.`ram:SpecifiedTradeSettlementHeaderMonetarySummation`.`ram:GrandTotalAmount`.`#text`
}

Frequently asked questions

With an invoice with one item, Line is not an array, with several it is.

A single child element becomes an object, several become an array. In JSONata, [invoice_xml.…Line] always forces an array; alternatively set options.isArray for the elements concerned.

The order number 007 arrives as 7.

Numbers in text form are converted to numbers by default. With "options": { "parseTagValue": false } all values stay text; leading zeros are kept.

The access invoice_xml.rsm:Invoice returns nothing.

Keys with a colon or # have to be in backticks in JSONata: invoice_xml.`rsm:Invoice`.

Attributes should be called @_ instead of attr_.

Set options.attributeNamePrefix accordingly; with "ignoreAttributes": true attributes are omitted entirely.

Next step

Extract PDF attachments: get the XML of an e-invoice from the ZUGFeRD PDF.