JSON Import Export Specification

Complete field reference for JSON-based configuration import and export.
Reference → Solution → DevOps → Git Integration | JSON Specification

JSON Structure

Standard Format (v1.1)

Every JSON file follows this three-section structure:

json

{
  "ObjectIdentification": {
    "TableType": "UnsTags",
    "SolutionName": "MyProject"
  },
  "ExportMetadata": {
    "ExportDate": "2026-01-16T10:30:00Z",
    "ExportUser": "john.doe",
    "ExportProduct": "FrameworX",
    "ExportProductVersion": "10.1.1.1011",
    "ExportFormat": "1.1"
  },
  "Data": [
    { /* object 1 */ },
    { /* object 2 */ }
  ]
}

Section Details

Note: The Data section is always an array, even for single-object exports.

Minimal Import Format

For import operations, only the Data array is required:

json

{
  "Data": [
    { "Name": "Tag1", "Type": "Double" }
  ]
}

Import Behavior

Fields Ignored on Import

These fields are auto-generated and ignored during import:

Fields Filtered from Export

These fields are excluded from export files to reduce size:

Compiled/Binary Data:

Build Results:

Calculated Fields:

Conditional:

Import Rules

Pre-defined Objects (Cannot Import)

These system objects cannot be created or modified via import:

Import Order Dependencies

When importing related objects, order matters:

1. Independent objects first: Tags, Channels, AlarmGroups, StorageLocations, DatasetDBs
2. Dependent objects after: Nodes→Channels, Points→Nodes+Tags, AlarmItems→Tags+Groups, HistorianTags→Tags+Tables

Import Modes

FrameworX 10.1.5 introduces three explicit modes that govern how an imported JSON file interacts with rows that already exist in the live solution. Earlier releases supported only a single behavior — an upsert that never deleted — which is preserved as the default Merge mode. The two additional modes give DevOps pipelines and source-of-truth workflows finer control over the live solution's drift relative to the JSON artifact.

The mode is selected per table, not for the import as a whole. A single import operation can run UnsTags in Mirror Sync while leaving DeviceChannels in Merge — useful when only part of the configuration is authoritatively tracked in Git.

Merge (default)

Merge is the historical and default behavior. Rows present in the JSON are inserted when their Name does not yet exist in the live solution, and updated when it does. Rows present in the live solution but absent from the JSON are left in place. Merge never deletes.

Merge is the right choice when the JSON file represents a partial contribution — for example, a new set of tags being added to an existing project, or a third-party module shipping a bundle of Channels and Nodes meant to coexist with the customer's own configuration.

Append

Append inserts rows whose Name does not yet exist and skips rows whose Name already exists. There is no update and no delete. Append guarantees the import will never modify an existing live row.

Append is the right choice when the JSON file is a one-shot seed — for example, importing a vendor-supplied tag library into a project that may have already customized some of those tags — and the operator wants the customer's edits preserved against any newer copy of the seed file.

Mirror Sync (10.1.5)

Mirror Sync makes the imported JSON the authoritative state of the selected table. Rows present in the JSON are inserted or updated exactly as in Merge mode. In addition, rows present in the live solution but absent from the JSON are deleted. After a successful Mirror Sync import, the live table mirrors the JSON exactly, row-for-row.

Mirror Sync targets three classes of workflow:

• Authoritative Git-tracked configuration: the JSON file in the repository is the single source of truth, and a row removed from the JSON must propagate to every environment on the next deployment.
• CI/CD deployment pipelines: a stale row left behind in the live solution from a prior build can corrupt the new deployment — for example, an obsolete Device Point that still polls a decommissioned address. Mirror Sync guarantees deployment-time hygiene.
• Test environment resets: a known-good JSON snapshot can reset a test solution to a clean baseline state without manual cleanup of leftover rows from prior test runs.

Opt-in mechanism. Mirror Sync is never the default. It is selected explicitly per table on two surfaces:

• The Designer import dialog presents a checkbox column labeled Mirror sync next to each table in the import. The operator ticks the box only for tables that should run in Mirror Sync; unticked tables run in Merge.
• The JSON import API and MCP-side tooling expose a parameter that accepts the list of TableType values to run in Mirror Sync. Tables not listed run in Merge.

MCP parameter (10.1.5). The ConsoleMCP import_solution_json tool and its DesignerMCP equivalent expose a mirror_sync parameter on the import call. The parameter accepts either a boolean — true to enable Mirror Sync for every table in the payload, false (default) to keep every table in Merge — or a per-table opt-in list of TableType values for finer control. Example invocations: {"mirror_sync": true} applies Mirror Sync to all imported tables; {"mirror_sync": ["UnsTags", "UnsUserTypes"]} runs Mirror Sync only for the two listed tables while every other table in the same import runs in Merge. Tool naming and signatures may evolve across MCP server versions — consult the MCP tool reference for the exact verb name and parameter shape in your installed FrameworX build.

Built-in row protection. Mirror Sync deletion never touches pre-defined system objects or rows marked as built-in. The LockState and LockOwner mechanism that already protects these rows from manual edit and from import overwrite also protects them from Mirror Sync deletion. A Mirror Sync import that omits, for example, the Critical alarm group or the Default storage location will not delete them — they are silently retained. This matches the behavior of the pre-defined objects table in the Import Behavior section above.

Recommended workflow. Mirror Sync is destructive. The recommended pre-flight before a production Mirror Sync import is:

1. Export the live solution's current state of the target tables to JSON.
2. Diff the exported JSON against the JSON about to be imported. Every row that appears in the export but not in the import is a row that Mirror Sync will delete.
3. Review the delete set with whoever owns the configuration. Deletions of operator-facing rows (Tags wired into Displays, Alarms wired into reports, Historian assignments) propagate downstream and may break dependent objects.
4. Import with Mirror Sync enabled for the reviewed tables.

Mode comparison. The following table summarizes the three modes against the three operations they may perform on each row in the live solution:

Tag Types Reference

Built-in Types

UserType References

To reference a UserType in JSON, use the UserType name:

json

"Type": "LabelingMachine"

Enumeration Values Reference

Domain

Visibility

Retentive

Script Code Language

TableType Reference

Valid TableType values:

UNS Module

Devices Module

Alarms Module

Historian Module

Datasets Module

Scripts Module

Reports Module

Security Module

Displays Module

Object Reference Formats

When JSON fields reference other objects, use these formats:

UNS Objects

Tag (UnsTags)

json

{
  "Data": [
    {
      "Name": "Temperature",
      "Type": "Double",
      "Path": "\\Line1\\Tank1",
      "Description": "Tank temperature sensor",
      "Array": 0,
      "StartValue": "25.0",
      "Min": "0",
      "Max": "100",
      "Units": "°C",
      "Format": "N1",
      "Domain": "Server",
      "Visibility": "Public",
      "Retentive": "None",
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

AssetFolder (UnsAssetTree)

json

{
  "Data": [
    {
      "Name": "Line1",
      "Path": "",
      "LinkedProvider": "",
      "Alias": "",
      "Visibility": "Public",
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    },
    {
      "Name": "Tank1",
      "Path": "\\Line1",
      "LinkedProvider": "",
      "Alias": "Primary Tank",
      "Visibility": "Public",
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

Devices Objects

Channel (DevicesChannels)

json

{
  "Data": [
    {
      "Name": "ModbusPLC1",
      "Protocol": "Modbus",
      "PrimaryStation": "192.168.1.10:502",
      "BackupStation": "",
      "Timeout": 3000,
      "Retries": 3,
      "Enabled": true,
      "Description": "Main Modbus PLC",
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

PrimaryStation Formats by Protocol:

Node (DevicesNodes)

json

{
  "Data": [
    {
      "Name": "PLC1",
      "Channel": "Channel.ModbusPLC1",
      "PrimaryStation": "1",
      "BackupStation": "",
      "Enabled": true,
      "Description": "Main PLC unit 1",
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

Point (DevicesPoints)

json

{
  "Data": [
    {
      "Node": "Node.PLC1",
      "Tag": "Tag.Line1.Tank1.Temperature",
      "Address": "HR100",
      "AccessType": "AccessType.Read",
      "Enabled": true,
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

Address Formats by Protocol:

Alarms Objects

AlarmItem (AlarmsItems)

json

{
  "Data": [
    {
      "Tag": "Tag.Line1.Tank1.Temperature",
      "Group": "Alarm.Group.Critical",
      "Area": "Alarm.Area.Plant1",
      "Condition": "GreaterThan",
      "Setpoint": "90",
      "Message": "Tank temperature high: {0}°C",
      "Priority": 800,
      "Enabled": true,
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

Condition Values:

Historian Objects

HistorianTag (HistorianTags)

json

{
  "Data": [
    {
      "Tag": "Tag.Line1.Tank1.Temperature",
      "HistorianTable": "Historian.Table.Table1",
      "Deadband": "0.5",
      "Enabled": true,
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

Scripts Objects

ScriptTask (ScriptsTasks)

json

{
  "Data": [
    {
      "Name": "ServerStartup",
      "Code": "CSharp",
      "Domain": "Server",
      "Trigger": "",
      "InitialState": 0,
      "Description": "",
      "NamespaceDeclarations": "",
      "Contents": "// C# startup code\n@Info.Trace(\"Server started\");",
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

ScriptExpression (ScriptsExpressions)

json

{
  "Data": [
    {
      "Name": "TotalFlow",
      "Expression": "Tag.Flow1 + Tag.Flow2 + Tag.Flow3",
      "TargetTag": "Tag.TotalFlow",
      "TriggerTag": "Tag.Flow1",
      "Enabled": true,
      "DateCreated": "2026-01-16T10:30:00Z",
      "DateModified": "2026-01-16T10:30:00Z"
    }
  ]
}

Common Patterns

Creating a Complete Device Communication Setup

Import order matters - create objects in dependency order:

Step 1: Create Tags

json

{ "Data": [{ "Name": "TankLevel", "Type": "Double", "Path": "\\Process" }] }

Step 2: Create Channel

json

{ "Data": [{ "Name": "ModbusCh1", "Protocol": "Modbus", "PrimaryStation": "192.168.1.10:502" }] }

Step 3: Create Node

json

{ "Data": [{ "Name": "PLC1", "Channel": "Channel.ModbusCh1", "PrimaryStation": "1" }] }

Step 4: Create Point

json

{ "Data": [{ "Name": "Point1", "Node": "Node.PLC1", "Tag": "Tag.Process.TankLevel", "Address": "HR100" }] }

Bulk Tag Creation

json

{
  "Data": [
    { "Name": "Motor1_Speed", "Type": "Double", "Path": "\\Motors", "Units": "RPM" },
    { "Name": "Motor1_Current", "Type": "Double", "Path": "\\Motors", "Units": "A" },
    { "Name": "Motor1_Running", "Type": "Digital", "Path": "\\Motors" },
    { "Name": "Motor2_Speed", "Type": "Double", "Path": "\\Motors", "Units": "RPM" },
    { "Name": "Motor2_Current", "Type": "Double", "Path": "\\Motors", "Units": "A" },
    { "Name": "Motor2_Running", "Type": "Digital", "Path": "\\Motors" }
  ]
}

Validation Rules

Name Validation

• Must be unique within object type
• Alphanumeric plus underscore
• Cannot contain dashes (reserved for expressions)
• Cannot start with number
• Max length: 256 characters
• Case-sensitive

Required Fields by Object

Summary of v1.1 Format Changes