Configuring JSON Connectors

JavaScript Object Notation (JSON), like XML is a hierarchically structured textual data format. A JSON object might look something like this:

{ "records": [ { "record": { "attribute1": "value1", "attribute2": null, "numericAttribute": 1.0 } }, { "record": { "attribute1": "value2", "attribute2": "abc", "numericAttribute": null } } ] }

JSON represents data as nested {"attribute" : value} pairs which constitute an object. In this example, the object has one attribute called "records" whose value is a list delimited by brackets []. In the list are two objects, each having a single attribute "record" whose value is an object delimited by braces {} and having three attributes of its own.

Querying JSON

JSON can be queried using a language called JSON Path. JSON Path is described here: http://goessner.net/articles/JsonPath/. Basic JSON Path expressions are a series of attribute names delimited by ".". Brackets are used to indicate an index in an list and start with zero. For example records[0].record.attribute1 would resolve to "value1" in the example above. JSON Path also allows for wild cards. In JSON Path this is the * character, but for connectos please use #. For example records[#].record would resolve to:

[ { "attribute1": "value1", "attribute2": null, "numericAttribute": 1.0 }, { "attribute1": "value2", "attribute2": "abc", "numericAttribute": null } ]

Defining a JSON Connector

When defining a JSON connector five fields are important in the connector and connector field configurations:

In all cases

• the Archibus Table you're importing to or exporting from
• whether it is an Import/Export
• the Connection String which is the name of the file on the application server containing JSON data

Parameter	Description	Example
CharacterEncoding	the text encoding to use when writing or reading JSON	“UTF-8”

For Imports

• the Remote Source, which is JSON Path that results in a list of objects from which records can be parsed (a single object will result in a single record)
• the Source Field which is JSON Path excluding an initial $. from the record to the field

For Exports

• the Remote Source, which is a series of nested attribute names delimited by "." and an attribute name for the record (e.g. records.record in the example above)
• the Source Field which is the name of an attribute on the record object (e.g. "attribute1" in the example)
• You may optionally set for additional attributes in connector properties:
  • recordsTemplate: a JSON object, without records, to be written to the file.
  • pathToRecordsArray: a JSON path to the JSON array in the recordsTemplate where records should be written.
  • recordTemplate: a JSON object for a record.
  • pathToRecordFields: a path in the JSON object to the JSON object on which fields are defined.

Note: When exporting, JSON writes null values as {"attribute" : null}. Use a connector rule to modify the field if a different value is desired.