The translate step converts Excel source data into JSON process files. These JSON files are the standard currency of the Xspatula framework — the same format used throughout setup and process registration. Each row in a source Excel sheet becomes one JSON process object.

Output location

Translated JSON files are written to:

./AI4SH/import_data/manage_data/<domain>/<subdomain>/process/

For example, translating analysis_method.xlsx produces:

./AI4SH/import_data/manage_data/utility/process/process_manage_analysis_method.json

File naming convention

Translated files use the prefix process_manage_ followed by the source table name. This prefix signals that the file is a manage (insert/update/delete) operation rather than a structural definition.

JSON structure

Each translated file has the same envelope structure:

{
  "process": "manage_<table_name>",
  "parameters": {
    "<column_1>": "<value_1>",
    "<column_2>": "<value_2>"
  }
}

A concrete example from process_manage_analysis_method.json:

{
  "process": "manage_analysis_method",
  "parameters": {
    "analysis_method_id": "dry_combustion",
    "title": "Dry combustion",
    "label": "High-temperature combustion for carbon and nitrogen determination"
  }
}

Pilot files

The manage step does not read JSON files directly by name — it reads a pilot file (plain text) that lists the JSON files to execute, one per line. The translate step prints this list to the notebook output. You copy that list into the appropriate pilot text file:

./AI4SH/import_data/manage_data/utility/manage_utility.txt

If you use the default directory structure from the cloned repository, the pilot files are already in place. You only need to paste the translate output into them.

Job files

Each step (translate and manage) is driven by a job file — a small JSON file that points to a folder and pilot file:

{
  "process": {
    "job_folder": "import_data/manage_data/utility",
    "process_sub_folder": "process",
    "pilot_file": "manage_utility.txt"
  }
}

The job file is the argument passed to Initiate_process() in the notebook cell. Swapping the job file switches the entire set of operations being run.

Dependency order

Foreign key constraints mean that the order of JSON files in the pilot file matters. Tables with no foreign keys must be processed before tables that reference them. The translate pilot files (translate_utility_data.txt etc.) are pre-ordered to respect these dependencies. See Foreign key handling for details.

Updated: