==================
Variable Instances
==================

.. toctree::
   :hidden:
   :glob:

1. `Structure Class`, `Structure Object`, `Variable` and `Variable Instance`
============================================================================

- `Structure Class` - is an extendable abstract definition of industrial objects or mathematical constructs with similar properties. 
- `Structure Object` - is a representation of a `Structure Class` referenced to some object.
- `Variable` - is an abstract definition of a time series property of one class common to all objects of this class. It holds meta information about meaning of property and defines default aggregation and measuring unit.
- `Variable Instance` - is a representation of abstract defined `Variable` at one `Structure Object` 


1. Get `Structure Class` definition
===================================

Parameters used
---------------

.. code:: typescript

    - TRX_ID: number // the transaction id 
    - CLASS_ID: number // the Structure Class id
    - CLASS_ROLE_ID: string // the Structure Class role id

URL
---

Get `Structure Class` definition by CLASS_ID

.. code:: console

   structure/class/get/trx=[TRX_ID]&id=[CLASS_ID]

Get array of `Structure Classes` by CLASS_ROLE_ID

.. code:: console

   structure/class/role/get_all_classes/trx=[TRX_ID]&role_id=[CLASS_ROLE_ID]


2. Get `Variable` definition
============================

Parameters used
---------------

.. code:: typescript

    - TRX_ID: number // the transaction id 
    - VARIABLE_ID: number // the variable id
    - VARIABLE_ROLE_ID: string // the variable role id

URL
---

Get `Variable` definition by VARIABLE_ID

.. code:: console

   variable/get/trx=[TRX_ID]&id=[VARIABLE_ID]

Get `Variable` definition byte VARIABLE_ROLE_ID

.. code:: console

   variable/role/get_variable/trx=[TRX_ID]&role_id=[VARIABLE_ROLE_ID]

Response
--------

.. code:: typescript

    {
      id: number,
      structure_class_id: number,
      structure_class_result_token: string,
      location: {
        id: number,
        name: string,
        value: string,
      },
      medium: {
        id: number,
        value: string,
        name: string
      },
      physical_unit: string,
      specialization: {
        id: number,
        value: string,
        name: string
      },
      source: {
        id: number,
        value: string,
        name: string,
        default_type: string,
        default_supplement_value_strategy: string
      },
      measuring_unit: string,
      aggregation: string,
      plc_source_mu: string,
      plc_raw_value_aggregation: string,
      default_calc_formula: string,
      default_custom_algorithm_id: number,
      default_custom_algorithm_dependencies_def: string,
      description: string
      default_properties: [],
      roles: [],
      values_bounds_id: number,
      instances_ids: [number]
    }

3. Query `Variable Instance` meta data
======================================

Parameters used
---------------

.. code:: typescript

    - TRX_ID: number // the transaction id 
    - VARIABLE_INSTANCE_ID: number // the variable instance id
    - VARIABLE_ID: number // the variable id
    - VARIABLE_ROLE_ID: string // the variable role id
    - OBJECT_ID: number // the object id
    - OBJECT_KEY: string // the object key as text identifier refenreces objct

URL
---

Search for `Variable Instances` over object tree according zu search policy

.. code:: console

   variable/find_over_object_tree/trx=[TRX_ID]&var_id=[VARIABLE_ID]&object_id=[OBJECT_ID]&policy=Auto

alternatively over `Variable` + `Structure Object` combination

.. code:: console

   variable/instance/get/trx=[TRX_ID]&var_id=[VARIABLE_ID]&obj_id=[OBJECT_ID]

by VARIABLE_ROLE_ID with OBJECT_KEY

.. code:: console

   variable/role/get_variable_instance/trx=[TRX_ID]&role_id=[VARIABLE_ROLE_ID]&obj_key=[OBJECT_KEY]

by `Variable Instance` id

.. code:: console

   variable/instance/get/trx=[TRX_ID]&id=[VARIABLE_INSTANCE_ID]


Response
--------

.. code:: typescript

    {
        id: number, // ID of Variable Instance
        type: string,
        supplement_value_strategy: string,
        variable_id: number,
        structure_object: {
          id: number,
          display_name: string
        },
        upper_limit_id: number,
        lower_limit_id: number,
        values_bounds_id: number,
        interpolation:,
        description: string,
        plc_source_mu:,
        plc_raw_value_aggregation:,
        archive_data_group_id: number,
        plc_instance_type: string,
        archive_datasource_key: string,
        archive_write_values_source_id: number,
        calculation_formula: string,
        custom_algorithm_id: number,
        custom_algorithm_dependencies:,
        custom_parameter: string,
        dependencies: [
          {
            dependent_on: number;
            key: string;
            description: string
          }
        ],
        link_id: number
    }