Struct Actions

Struct actions are complex data actions designed to be used with XINA Structs. Unlike most API actions, they may involve complex multi-step operations, and are dependent on the structs configuration of groups and databases.

Data Actions

STRUCT BUFFER IMPORT

Imports a buffer source file into a model.

Property	Value	Required	Default
action	`"struct_buffer_import"`	yes
model	model group specifier	yes
origin	origin name	yes
object_id	object ID of data file	yes
format	`string`	yes
conf	`jsonobject`	no
strict_units	`boolean`	no	`false`

If the mn column is an integer it will be interpretted as a literal mnemonic ID. Otherwise the name will be parsed from this format:

<name>[(<unit>[;n0=v0|n1=v1|...])]

<name> will be used for the mnemonic name lookup. The comparison is case insensitive and any whitespace is treated as a single underscore. <unit> is optional. If provided, it must match the unit of an associated mnemonic definition, otherwise an error is thrown. The section after unit defines discrete value mapping.

When a data set is imported the XINA server will run the following steps:

For each row:
- validate time and value
- process mnemonic
  - If mnemonic ID
    - If found in definitions database:
      - If mnemonic is deprecated, throw error
      - Else, use mnemonic for row
    - Else, throw error due to unrecognized ID
  - Else, parse name and optional unit
    - If name match found:
      - If unit is provided and does not match, throw error
      - If mnemonic is deprecated, throw error
      - Else, use mnemonic for row
    - Else, mnemonic is new, create new temporary mnemonic definition based on provided information
If any rows contain same mnemonic and time, throw error
Check for time overlap in database
- If found
  - If on_overlap = fail, throw error
  - Else If on_overlap = delete, delete all data from database in time range of imported data
  - Else (on_overlap = ignore), do nothing
If new mnemonic definitions created, insert into mnemonic definition database
Insert data into mnemonic database

STRUCT MN ALIAS

Adds one or more aliases of name/unit pairs to a single existing mnemonic.

Property	Value
`action`	`"struct_mn_edit"`
`database`	mnemonic definition database specifier
`mn`	mnemonic ID
`aliases`	`string[]`, name/unit pair alias(es) for mnemonic

STRUCT MN EDIT

Edits one or more properties of a single existing mnemonic.

Property	Value	Required
`action`	`"struct_mn_edit"`	yes
`database`	mnemonic definition database specifier	yes
`mn`	mnemonic ID	yes
`name`	`string`, new name/unit pair for mnemonic	no
`state`	`string`	no

STRUCT MN MERGE

Merges one or more existing mnemonics into a single existing mnemonic.

STRUCT INT OPEN

Opens one or more intervals in a model.

STRUCT INT CLOSE

Closes one or more intervals in a model.

Schema Actions

STRUCT CREATE

The STRUCT CREATE action is used to create a variety of XINA Structs compatible schema elements.

STRUCT CREATE PROJECT

Creates a structs project group.

Property	Value	Required	Default
action	`"struct_create"`	yes
create	`"project"`	yes
parent	group specifier	no
name	`string`	yes
label	`string`	no	name
desc	`string`	no	label

If a parent group is specified, it may not include a structs definition (since project groups must be at the top level of a struct heirarchy). The name (and label, if provided) must not be in use by any group siblings, or the action will fail.

STRUCT CREATE CATEGORY

Creates a structs category group.

Property	Value	Required	Default
action	`"struct_create"`	yes
create	`"category"`	yes
parent	group specifier	yes
name	`string`	yes
label	`string`	no	name
desc	`string`	no	label

The parent group must be either a project group or category group, or the action will fail. The name (and label, if provided) must not be in use by any group siblings, or the action will fail.

STRUCT CREATE MODEL

Creates a structs model group.

Property	Value	Required	Default
action	`"struct_create"`	yes
create	`"model"`	yes
parent	group specifier	yes
name	`string`	yes
label	`string`	no	name
desc	`string`	no	label
event	`boolean`	no	`false`
eventf	`boolean`	no	`false`
eventfs	`boolean`	no	`false`
group_teams	team group privilege map	no
database_teams	team database privilege map	no

The parent group must be either a project group or category group, or the action will fail. The name (and label, if provided) must not be in use by any group siblings, or the action will fail.

STRUCT CREATE ORIGIN

Creates a structs origin group.

Property	Value	Required	Default
action	`"struct_create"`	yes
create	`"origin"`	yes
model	group specifier	yes
name	`string`	yes
label	`string`	no	name
desc	`string`	no	label
event	`boolean`	no	`false`
eventf	`boolean`	no	`false`
eventfs	`boolean`	no	`false`
group_teams	team group privilege map	no
database_teams	team database privilege map	no
partition	`boolean` or `{"from": <start year>, "to": <end year>}`	no	`false`

The parent group must be either a project group or category group, or the action will fail. The name (and label, if provided) must not be in use by any group siblings, or the action will fail.

STRUCT CREATE DEF

Creates a structs definitions group, with associated databases.

Property	Value	Required
action	`"struct_create"`	yes
create	`"def"`	yes
parent	group specifier	yes

The parent group must be either a project, category, or model group, or the action will fail.

STRUCT CREATE EVENT

Creates a new structs event database.

Property	Value	Required	Default
action	`"struct_create"`	yes
create	`"event"`	yes
parent	group specifier	yes
type	`"none"`, `"file"`, or `"files"`	no	`"none"`
name	string	no	`"event"`, `"eventf"`, or `"eventfs"`
label	string	no	name
desc	string	no	label
singular	string	no	`"event"`
plural	string	no	singular`s`
conf	JSON object	no
fields	array of field definitions	no
teams	team database privilege map	no