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	Req	Default
action	`"struct_buffer_import"`	✓
pipe	pipe group specifier	✓
file	object ID of data file	✓
format	`string`	✓
conf	`jsonobject`
strict_units	`boolean`		`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"`	✓
`database`	mnemonic definition database specifier	✓
`mn`	mnemonic ID	✓
`name`	`string`, new name/unit pair for mnemonic
`state`	`string`

STRUCT MN MERGE

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

STRUCT EVENT

Performs context-aware event operations.

Unlike typical record operations, these actions support event definition lookup and creation. Event records or updates may specify a "name" property, as if it were a database field. This will be used to lookup a corresponding event ID from the event definitions associated with the database, and create a new definition with the name if one is not found. Alternatively, the "name" may reference an event definition by external ID, by starting with the $ character.

If an event specifies both a "name" and "e_id", the action will fail, as the outcome is ambiguous. If the "name" property value is numeric or numeric text, it will interpretted as a direct event ID reference (as if it had been provided as "e_id").

"e_id" values are validated against existing event definitions, and the action will fail if the event ID is not found.

STRUCT EVENT INSERT

Inserts one or more events into a single event database.

Property	Value	Req
action	`"struct_event"`	✓
op	`"insert"`	✓
database	event database	✓
events	event records	✓

If the event database has an associated event change database, the event change database will be checked for any update records, and the changes will be applied to the incoming events before they are inserted. Incoming open intervals will also be checked for close change records.

If any inserted UEIDs are already present in the database, the action will fail.

STRUCT EVENT CLOSE

Closes one or more open interval event(s).

Property	Value	Req	Default
action	`"struct_event"`	✓
op	`"close"`	✓
database	event database	✓
t	`instant(us)` closing time		now
events	events specifier	✓
update	field value map

The closing time is specified by the t property. The events property may be a string UEID, array of string UEIDs, or "*", to indicate all currently open intervals. If the update property is provided, updates the value(s) of the specified field(s) in the map for all events being closed.

If the event database has an associated event change database, a close record is also created.

STRUCT EVENT UPDATE

Updates one or more events, storing the updates as a change record(s) if possible.

Property	Value	Req	Default
action	`"struct_event"`	✓
op	`"update"`	✓
database	event database	✓
t	`instant(us)` update time		now
events	event UEID(s)
fields	field(s) to update	✓

STRUCT EVENT CLEAR

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	Req	Default
action	`"struct_create"`	✓
create	`"project"`	✓
parent	group specifier
name	`string`	✓
label	`string`		name
desc	`string`		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	Req	Default
action	`"struct_create"`	✓
create	`"category"`	✓
parent	group specifier	✓
name	`string`	✓
label	`string`		name
desc	`string`		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	Req	Default
action	`"struct_create"`	✓
create	`"model"`	✓
parent	group specifier	✓
name	`string`	✓
label	`string`		name
desc	`string`		label
event	`boolean`		`false`
eventf	`boolean`		`false`
eventfs	`boolean`		`false`
group_teams	team group privilege map
database_teams	team database privilege map

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 PIPE

Creates a struct pipe group.

Property	Value	Required	Default
action	`"struct_create"`	✓
create	`"origin"`	✓
model	group specifier	✓
name	`string`	✓
label	`string`		name
desc	`string`		label
group_teams	team group privilege map
database_teams	team database privilege map
partition	`boolean` or `{"from": <start year>, "to": <end year>}`		`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	Req
action	`"struct_create"`	✓
create	`"def"`	✓
parent	group specifier	✓

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	Req	Default
action	`"struct_create"`	✓
create	`"event"`	✓
group	group specifier	✓
type	`"none"`, `"file"`, or `"files"`		`"none"`
name	string		`"event"`, `"eventf"`, or `"eventfs"`
label	string		name
desc	string		label
singular	string		`"event"`
plural	string		singular`s`
conf	JSON object
fields	array of field definitions
teams	team database privilege map

STRUCT CREATE NOTEBOOK

Creates a new structs notebook database.

Property	Value	Req	Default
action	`"struct_create"`	✓
create	`"notebook"`	✓
parent	group specifier	✓
name	string	✓
label	string		name
desc	string		label
fields	array of field definitions
teams	team database privilege map