JsonFieldData plugin format

The JsonFieldData plugin is a plugin that accepts a JSON document containing many parsed visits.

Most of the properties of the JSON document map 1:1 with DTO properties from the framework itself. Any visit information that a plugin can create can also be represented in this JSON format.

The format of the JSON document is the same format produced by the PluginTest /Json=outputPath option and by the FieldVisitHotFolderService when it uploads individually visits parsed from local files.

This page is intended to serve as guide for integrators who wish to produce a compatible JSON document directly, without using the above methods.

The document is an AppendedResults object

The JSON document is an AppendedResults object, serialized to JSON.

An AppendedResults object has 3 properties.

Property	Type	Description
FrameworkAssemblyQualifiedName	String	The .NET name and version of the framework version used to generate this JSON document.
PluginAssemblyQualifiedTypeName	String	The .NET name and version of the plugin used to generate the JSON content.
AppendedVisits	Array	An array of the visits and their content. Each visit is a FieldVisitInfo object. See the DataModel for details.

The FrameworkAssemblyQualifiedName and PluginAssemblyQualifiedTypeName must both exist in order for the JSON document to be parsed by the plugin. The value of each string doesn't matter, and an empty string value is fine. But neither property can be null or omitted.

It is recommended that the FrameworkAssemblyQualifiedName follows the .NET naming convention in the example below, as a hint to the plugin for any backwards-compatibility logic. When no Version={w.x.y.z} pattern can be found in the FrameworkAssemblyQualifiedName value, the most recent version of the framework is assumed.

There is no guidance for the PluginAssemblyQualifiedTypeName property, other than it must be a non-null string value.

{
    "FrameworkAssemblyQualifiedName": "FieldDataPluginFramework.IFieldDataPlugin, FieldDataPluginFramework, Version=2.3.0.0, Culture=neutral, PublicKeyToken=null",
    "PluginAssemblyQualifiedTypeName": "FlowTracker2Plugin.Plugin, FlowTracker2Plugin, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null",
    "AppendedVisits": [
    ]
}

Where is the property-by-property documentation?

There are about 200 properties of field data items which can be set by the framework. Not all of them are explicitly documented yet, but most that are not documented should have a property name and context that maps exactly to what you see in the Field Data Editor browser page.

This is still an open issue, so here is the documentation that currently exists, aside from this page:

• The DataModel section of the framework documentation guide
• The Tabular CSV plugin wiki, which documents most of the quirks of these 200 properties. That wiki should provide useful guidance on the special enumerated string values and configurable picklists values.

Known quirks in the JSON format

If you have captured a JSON document from another plugin or from the FieldVisitHotFolderService and are trying to reverse-engineer something compatible, there are a few quirks to keep in mind, to avoid grief down the road.

Quirk 1 - Omit the numeric database Id property

There are some numeric property with a "xxxId" property fields which should be completely omitted from the JSON (or at the very least, left at their default value of 0). These "xxxId" properties ended up accidentally leaking into the JSON serialized output, but were not intended to be there. No other plugins written to using the .NET Aquarius.FieldDataFramework NuGet package are able to set these properties. But if they are set to non-zero values, AQTS will reject your JSON document.

There are other string properties following the "xxxId" naming pattern (like "SensorUniqueId") and these should be kept unless otherwise noted.

These are the numeric database Id properties to omit:

AppendedVisits[]
    LocationInfo
        LocationId
    LocationId
    FieldVisitId

Quirk 2 - Some JSON properties are not used at all when AQTS receives the JSON

Only the LocationInfo.LocationIdentifier property is used to find the matching location in AQTS.

AppendedVisits[]
    LocationInfo
        LocationName
        UniqueId
        UtcOffset
    FieldVisitIdentifier

• The LocationName, UniqueId, and UtcOffset properties of LocationInfo are ignored when the JSON is received by AQTS.
• The FieldVisitIdentifier string property is ignored as well.

Quirk 3 - Some JSON properties you see are duplicates from elsewhere. They can be omitted.

Some of the properties you might see in the serialized JSON are a shortcut, read-only property that is actually set elsewhere. They have ended up serialized to JSON as an unintended side effect (like the numeric database ID properties)

Your JSON generator can either omit these duplicates completely (preferred), or ensure that their duplcate value exactly matches the source.

AppendedVisits[]
    StartDate                   (duplicates FieldVisitDetails.FieldVisitPeriod.Start)
    EndDate                     (duplicates FieldVisitDetails.FieldVisitPeriod.End)
    FieldVisitDetails
        StartDate               (duplicates FieldVisitDetails.FieldVisitPeriod.Start)
        EndDate                 (duplicates FieldVisitDetails.FieldVisitPeriod.End)
    Readings[]
        Value                   (duplicates Readings[].Measurement.Value)
        UnitId                  (duplicates Readings[].Measurement.UnitId)
    DischargeActivities[]
        MeasurementStartTime    (duplicates MeasurementPeriod.Start)
        MeasurementEndTime      (duplicates MeasurementPeriod.End)