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 Req Default
action "struct_buffer_import" ✓
modelpipe modelpipe group specifier ✓
originorigin name✓
object_idfile 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 Default
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 Default
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 singulars
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
Back to top