A process must be registered in the database before it can be called from a process file. Registration stores the process name, parameter definitions and access constraints in the process schema tables.

Process hierarchy

Every process belongs to a root process. You must register the root process before registering the sub-processes under it.

Registering a root process

Use add_root_process to create a new root process group:

{
  "process": [
    {
      "process": "add_root_process",
      "overwrite": false,
      "parameters": {
        "root_process": "manage_table_data",
        "title": "Manage table data",
        "label": "Root for processes for inserting, updating and deleting table data"
      }
    }
  ]
}

Root process parameters

A root process is registered with only 3 parameters:

  • root_process, the name of the root process,
  • title, a short title,
  • label, a short description

Registering a process

Use add_process to register a process under an existing root. The nodes array defines each parameter the process accepts:

{
  "process": [
    {
      "process": "add_process",
      "overwrite": false,
      "parameters": {
        "root_process": "manage_table_data",
        "process": "manage_territory",
        "min_user_stratum": 5,
        "title": "Manage territory",
        "label": "Insert, update or delete a territory, using ISO 3166 naming convention."
      },
      "nodes": [
        {
          "parent": "process",
          "element": "parameters",
          "parameter": [
            {
              "parameter": "name",
              "parameter_type": "text",
              "required": true,
              "default_value": "",
              "hint": "Territory name",
              "schema_table": {
                "schema": "utility",
                "table": "territory",
                "write": true
              },
              "permission": {
                "update": false,
                "delete": false
              }
            }
          ]
        }
      ]
    }
  ]
}

Process parameters and nodes

A process is registered with 5 parameters:

  • root_process, the name of the root process to which the process belongs,
  • process, the name of process
  • min_user_stratum, minimum user privilege level required to run the process
  • title, a short title,
  • label, a short description

Parameters required for running the process being defined are listed in the nodes array. Each node object must include objects for parent and element, that can be used for creating nested parameter settings. The parameters accepted by a process are defined in the array parameter, where each entry must contain the following objects:

  • parameter, the name of the parameter
  • parameter_type, the data type of the parameter
  • required, true if compulsory, false if a default value exists
  • default_value, the default value to use if required is set to false and no custom value is set
  • hint, short clue on the objective of the parameter

In addition parameters that are directly translated to records in the database must also have a schema_table block that links a parameter to a target table in the database. Such parameters also have a permission block that defines if a parameter can be updated or deleted.

Process parameters data type

The following data types are accepted as values for the parameter parameter_type:

  • string
  • integer
  • float
  • boolean
  • timestamp

If a parameter represents an array, the parameter value must have the add-on “_array” of the data type defined in parameter_type.

Optional process parameter blocks

There are four additional blocks that can be used for defining process options:

  • set value, lists values accepted as input
  • minmax, defines the range accepted for numerical values
  • inherit, copies value from existing database record
  • auto naming, assigns an automatic value

Adding the process file to the pilot file

Once you have created the JSON process file, add it to the pilot file xspatula_setup_processes.txt:

# My new process group
root_process/my_root_processes.json

my_process/my_process_v10_sql.json

Lines starting with # are comments and are skipped. The root process must appear before any sub-processes that reference it.

Running setup_processes.ipynb

Open setup/setup_processes.ipynb and run all three code blocks. The notebook reads the pilot file and registers each process in the database in the listed order. Use verbose: 2 in the scheme file if you want to see the parameter details as they are inserted.

Default processes registered

The three JSON files included in the default setup illustrate the pattern described above:

File What it registers
root_processes_v10_sql.json Two root process groups: manage_table_data and translate_data
translate_tabular_data_v10_sql.json The translate_tabular_data sub-process under translate_data
territory_v10_sql.json The manage_territory sub-process under manage_table_data

Input files

File Purpose
xspatula_setup_processes.txt Pilot file; lists the JSON process files to register, in execution order
root_processes_v10_sql.json Registers the manage_table_data and translate_data root process groups
translate_tabular_data_v10_sql.json Registers the translate_tabular_data sub-process for converting spreadsheet data to JSON
territory_v10_sql.json Registers the manage_territory sub-process for inserting and updating territory records

Updated: