system.mes.importConfiguration

Sepasoft MES Module Suite

importConfiguration

Overview

Version Specific: 3.81.11 RC 3 and later

The importConfiguration script function loads MES definition objects from a JSON file into the gateway database. Use it for site provisioning, disaster recovery, or CI/CD deployment when you need to replace the entire MES configuration with a file produced by system.mes.exportConfiguration(). The target database must be empty before import; call system.mes.truncateConfiguration() first when replacing an existing configuration.

Syntax

Copy Code

Python

system.mes.importConfiguration()
system.mes.importConfiguration(filePath)

Parameters

Parameter	Type	Required	Default	Description
filePath	String	Optional	{Gateway Data Directory}/MESConfig.json	Absolute or relative path to the JSON configuration file on the gateway host. When omitted, the file is read from the Ignition gateway data directory.

Return Value

Type	Description
None	The function returns void. It does not return a value.

Scope / Availability

Context	Available
Gateway scripts (MESGatewayScript)	Yes — runs import directly on the gateway
Client / Designer scripts (MESClientScript)	Yes — invokes the gateway through RPC

Both contexts expose the same system.mes module for configuration import.

Import Location

Default location

When called without parameters, the file is read from:

{Gateway Data Directory}/MESConfig.json

The gateway data directory is the Ignition system data folder (for example, the path returned by the gateway's system manager getDataDir()).

Custom location

When filePath is provided, that path is used instead. The file must exist on the gateway filesystem and be readable by the gateway process.

Imported Data

The JSON file is expected to match the format written by system.mes.exportConfiguration(). Import restores definition MES objects and their supporting data, including:

Core object properties, parent/child links, custom properties, and complex properties
Artifacts referenced by imported objects (for example, scripts and embedded content)
Definition change-log entries for imported objects (recorded as object-created events)

After a successful import, module-specific post-processing may run:

Quality module — default SPC calculation scripts are created if needed
Batch module — batch phase post-import updates run and batch states are loaded or created

Excluded / skipped during import

Item	Behavior
BatchPhase objects with creator BATCH	Skipped (built-in batch phases are not overwritten from the file)
SPCCalculationScript objects with creator SPC	Skipped (default SPC scripts are managed separately)
Response / runtime data	Not imported — only definition objects from the JSON file are loaded

Types omitted from export (such as BatchStates and MaterialRoot) are not present in a standard export file and are not part of the normal import workflow.

Behavior

When importConfiguration() runs:

Empty-database check — Fails if any MES object link rows already exist in the database.
File read — Parses the JSON file at the default or specified path.
Module version validation — Compares installed Sepasoft module versions against those recorded in the file. Import fails if a required module is missing or if the gateway is on an older version than the export.
Structural validation — Verifies required root objects and built-in event/recipe scripts match expected UUIDs and names.
Gateway pause — MES gateway startup is temporarily stopped with the message "Import in progress."
Database load — Definition objects, links, custom properties, complex properties, artifacts, and change-log rows are inserted in a single transaction.
Post-import hooks — Module-specific follow-up steps run for Quality and Batch when those modules are installed.
Gateway resume — MES gateway startup is re-enabled.

Exceptions

Exception	When raised
FileNotFoundException	The JSON file does not exist at the resolved path.
IllegalStateException	The database already contains MES definition data, or installed module versions are incompatible with the export.
IllegalArgumentException	Validation fails for required root objects or built-in scripts (wrong count, UUID, or name).
SQLException / DBException	Database errors during import.
Exception	Other failures while reading or applying the configuration (wrapped from the import transaction).

If the database is not empty, the error message directs you to run system.mes.truncateConfiguration() first.

Example Usage

Minimal example

Copy Code

Python

# Replace all MES definition data with the default export file
system.mes.truncateConfiguration()
system.mes.importConfiguration()

Complex example

Typical CI/CD or migration workflow: export from a source gateway, deploy the file, truncate the target, and import from a custom path:

Copy Code

Python

configPath = 'C:/deploy/MESConfig.json'

# Wipe existing definition data on the target gateway
system.mes.truncateConfiguration()

# Load configuration from the deployed file
system.mes.importConfiguration(configPath)

# Verify a known object exists after import
materialDef = system.mes.getMESObjectByNameAndType('Finished Product A', 'MaterialDef')
print('Imported material definition: %s' % materialDef.getName())

Round-trip export and import on the same gateway (for example, in a controlled maintenance window):

Copy Code

Python

backupPath = 'C:/backups/MESConfig_backup.json'

system.mes.exportConfiguration(backupPath)
system.mes.truncateConfiguration()
system.mes.importConfiguration(backupPath)

Related Functions

Module: system.mes

exportConfiguration() / exportConfiguration(filePath) — Exports MES definition objects to a JSON file. Produces the file format expected by importConfiguration().
truncateConfiguration() — Removes all MES definition objects from the database. Required before import when replacing an existing configuration.

Script Example set on a Perspective button

Added to buttons on a Perspective View:

Sepasoft MES Module Suite