The JSON File source connection allows for the import of data stored in JavaScript Object Notation (JSON) files.  The connection designer is capable of converting a JSON document into an XML document and inferring the structure if no schema definition files exist.  The connection uses the inferred or static schema definitions to build a hierarchy of the source document which is presented in the user interface as a tree structure that can be used to drag-and-drop visual elements from the tree on key areas of the user interface to write macro commands to process the source data.


XML Primer

This connection makes use of XML, XSD, and XPATH technology as documented here.


JSON Data Source Page


In order to map the JSON file, the file must first be represented as an XML document.  In order to guarantee the document can be represented as well-formed XML, the JSON data must be assigned a root element name and an object name in order to address situations where a JSON document is represented as a nameless collection at the top level.  Additionally, field names that are illegal XML tag names are properly escaped when generating the XML document.


Deserialization Root Element Name:  The name of the root element assigned to the XML representation of the JSON file.

Deserialization Object Name: The name of the element that will contain the JSON file represented as XML.


JSON Schema Definition Page

This connection uses the XML Schema Definition common import UI as documented here.


JSON Mapping Page


The JSON Mapping Page will display the structure of the XML document based on setting on the JSON Schema Definition page and allow elements and attributes to be mapped to an incoming line.  Clicking and dragging a node from the tree will dynamically create XPath macro commands.


General Tab


The General tab is used to define the base element path and specify relative XPath macro commands for mapping fields commonly used by the wizard.


Base Element XPath:  This is the XPath expression that specifies selection criteria for the document elements that represents an account line.  These will typically be a repeating element within the XML document.  This field is required to be filled in first if using drag and drop to generate XPath macros for the remaining fields as they will be written automatically by the program relative to this expression path.  While this field is macro enabled for those that want more control over the process the XPath macro command cannot be used in this field - only XPath expressions.

Account Code:  The account code for a journal line.  This is a macro-enabled field.

Matching Account Code:  The matching account code for a journal line.  This is a macro-enabled field.

Description:  The description for a journal line.  This is a macro-enabled field.

Reference:  The reference for a journal line.  This is a macro-enabled field.

Transaction Date:  The transaction date for a journal line.  This is a macro-enabled field.

Period:  The period for a journal line.  This is a macro-enabled field.


Amount Tab


The Amount tab will allow you to specify multiple amounts to be processed, each as an individual journal line.  Dragging a tree node into the data grid will add a new amount with a specified macro command.


Amount Macro Command: This is XPath macro command relative to the Base Element XPath used to extract the amount from the document.

Account Suffix: Optional field that specifies a suffix that will be appended to the Account Code specific to journal lines based on the amount macro command.

Offset: If checked an offset entry will be created for all lines based on this import expression.

Allow Zero Amount: If checked lines with zero-values amounts are imported and not suppressed.  Useful when you have a quantity to import or a statistical entry.

Processing Style: Determines how currency values are imported.

Quantity: Optional macro expression to import a quantity from the document.

Transaction Date: Optional macro expression that if provided will override the transaction date specified on the general tab.

Period: Optional macro expression that if provided will override the period specified on the general tab.


Attributes Tab


XML tags from any location in the hierarchy can be made into imported from the source data. Drag and drop of tags from the hierarchical document tree onto any control with a yellow background will automatically write XPath macro commands


Base Element Relative XPath: This is an optional value used to specify an XPath expression used to establish a path relative to the Base Element XPath used to select the elements that contain zero, one, or more attribute name/value pairs.  When this option is used the Attribute Name Macro and Attribute Value Command should both be XPath macro expressions.

Attribute Name Macro: This is a name or macro expression used to name the source attribute during import.  When a Base Element Relative XPath is specified this should be a XPath macro command.  When recursion is not used this is likely to be a hard-coded name.

Attribute Value Macro: This is a macro command that extracts the value from the XML document to populate the imported attribute named by the Attribute Name Macro field.


Copyright © 2023 pasUNITY, Inc.


Send comments on this topic.