Skip to main content

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 Default
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 singulars
conf JSON object no
fields array of field definitions no
teams team database privilege map no