API Datastores Targets

Read the list of data store (and related sink/buffer/datasource) instances that are valid selection targets for a given selector property on an object.

Purpose

Given a selector property code (prp_code) and the object that owns (or will own) that property (parent), this endpoint returns the list of store/sink/buffer/datasource instances that are eligible to be selected for that property. It powers the selection dropdowns for properties such as the Data Store selector, Event Store selector, Files Sink, IP21 datasource selector, and historization (data-VQT) selectors.

The helper applies visibility rules per property:

  • Limited visibility (self + ancestor nodes, plus the initiating node): TimeSeriesDataStore, EventDataStore.

  • Global visibility (returned from anywhere in the tree): GenericTimeSeriesBuffer, GenericEventBuffer, IP21Server.

  • Local visibility only (no remote queries): EventDataStore, DatasourceIP21gRPC.

For history (data-VQT) properties it also resolves process-value links, linked items, and redundant-item links to the real target object, and marks the currently selected stores (is_selected) and the configured default store (is_default).

Invocation Modes

HTTP Endpoints

Standard endpoint (API index method readdatastoretargetsinstances):

POST {{baseurl}}/api/v2/readdatastoretargetsinstances
Content-Type: application/json
Authorization: Bearer {{token}}

Advanced endpoint:

POST {{baseurl}}/api/v2/execfunction/syslib.api-datastore-targets/readinstances
Content-Type: application/json
Authorization: Bearer {{token}}

Direct Lua

Via API index script:

local api = syslib.api
local result = api:readdatastoretargetsinstances(arg, req, hlp)

Direct script library call:

local dstApi = require('syslib.api-datastore-targets')
local result = dstApi:readinstances(arg)

Example

Read the valid Data Store selector targets for an object, addressing the object by path:

{
    "prp_code": 1234,
    "parent": "/IO-Home/Examples/Demo Data/Process Data/DC0815"
}

Response:

{
    "status": 0,
    "results": [
        {
            "label": "Local Time Series Store",
            "description": "Primary historian",
            "path": "/System/Core/Local Time Series Store",
            "class_code": 8101,
            "value": "019cfd7b-0bd5-73da-8078-7686a6176eff-A-00-0001",
            "is_remote": false
        },
        {
            "label": "Generic Buffer",
            "description": "",
            "path": "/System/Core/Generic Buffer",
            "class_code": 8201,
            "value": "019cfd7b-0bda-7321-80b5-edf8d885985c-A-00-0003",
            "is_remote": true
        }
    ]
}

prp_code is a numeric property code from the static model (for example the code of DataStoreSelectorGuid, EventStoreSelector, FilesSinkGuid, or IP21DatasourceSelectorGuid). Use the model reference / readmodel to resolve a property tag to its code. class_code and value values above are illustrative.

Example Bank

Address the owning object by GUID

parent is an ObjSpec, so it accepts a path, an object GUID, or a numeric object ID.

{
    "prp_code": 1234,
    "parent": "019cfd76-f78c-7146-804e-deb8a8aeda24"
}
{
    "status": 0,
    "results": [
        {
            "label": "Local Time Series Store",
            "description": "",
            "path": "/System/Core/Local Time Series Store",
            "class_code": 8101,
            "value": "019cfd7b-0bd5-73da-8078-7686a6176eff-A-00-0001",
            "is_remote": false
        }
    ]
}

History (data-VQT) selector — selected and default flags

When prp_code refers to a dynamic, data-VQT property, the result is a history query. Entries carry is_selected (the store is currently a historization consumer) and is_default (the configured default store).

{
    "prp_code": 5678,
    "parent": "/IO-Home/Examples/Demo Data/Process Data/DC0815"
}
{
    "status": 0,
    "results": [
        {
            "label": "Local Time Series Store",
            "description": "",
            "path": "/System/Core/Local Time Series Store",
            "class_code": 8101,
            "value": "019cfd7b-0bd5-73da-8078-7686a6176eff-A-00-0001",
            "is_remote": false,
            "is_selected": true,
            "is_default": true
        }
    ]
}

Unsupported property code (error result)

A prp_code that is not one of the supported selector/history properties returns an error result rather than throwing on the wire.

{
    "prp_code": 1,
    "parent": "/IO-Home"
}
{
    "status": 3,
    "error_msg": "Unsupported property code <tag>"
}

Direct Lua

local dstApi = require('syslib.api-datastore-targets')
local result = dstApi:readinstances({
    prp_code = 1234,
    parent = "/IO-Home/Examples/Demo Data/Process Data/DC0815"
})
-- result.status  = 0
-- result.results = { { label = ..., path = ..., value = ..., is_remote = false }, ... }

Request Contract

Top-level argument (SysLib.API-DataStore-Targets.ReadInstances-Arg):

Field Type Required Default Behavior

prp_code

integer

yes

—

Numeric property code of the selector/history property to enumerate targets for. Must resolve to a supported property (see below), otherwise an Unsupported property code error is returned.

parent

SysLib.API.ObjSpec

yes

—

The object that owns the property — or its parent object when the object has not been created yet. Accepts a path, GUID, or numeric object ID. Used as the anchor for self/ancestor visibility and for resolving history links.

Supported prp_code properties

Property Targets returned (visibility)

FilesSinkGuid

FileSink (global).

DataStoreSelectorGuid

TimeSeriesDataStore, EventDataStore (limited); GenericTimeSeriesBuffer, GenericEventBuffer, IP21Server (global). Returned value is a store ID (syslib.getstoreid).

EventStoreSelector

EventDataStore (local only).

IP21DatasourceSelectorGuid

DatasourceIP21gRPC (local only).

any dynamic, data-VQT property

TimeSeriesDataStore (limited). Triggers a history query: resolves PV-link / linked-item / redundant-item targets, sets is_selected / is_default.

anything else

Error: Unsupported property code <tag>.

Response Contract

The function returns a single result object (SysLib.API-DataStore-Targets.ReadInstances-Result):

Field Type Present when Meaning

status

integer

always

Status code (see Error Handling). 0 = success.

results

Entry[]

success

Array of target instance entries (see below). Empty array when there are no eligible targets.

error_msg

string

on failure

Human-readable error message.

Each entry (SysLib.API-DataStore-Targets.Entry):

Field Type Present when Meaning

label

string

normal entry

Instance object name.

description

string

normal entry

Instance object description.

path

string

normal entry

Full path of the instance object.

class_code

integer

normal entry

Class code of the instance.

value

string

always

Selection value — the store ID (for DataStoreSelectorGuid) or the instance object ID otherwise. This is the value written to the selector property.

is_remote

boolean

normal entry

true when the instance lives on a node other than the one that handled the request.

is_selected

boolean

history query

true when the store is a current historization consumer.

is_default

boolean

history query

true when the store is the configured default. A default-store entry the user cannot list is appended carrying only value, is_default: true, is_selected: true (no label/path/class_code).

Permissions

  • Runs in the context of the authenticated user.

  • Instances are enumerated through syslib.get_object_info_list, so only instances the user has LIST permission on are returned.

  • For history queries, if the configured default store is not listable by the user, a minimal placeholder entry (just value + is_default/is_selected) is still appended so the default selection is represented.

Error Handling

Errors from the underlying get_instances are returned as a status / error_msg pair rather than thrown to the caller (instance gathering runs under pcall in the helper).

status Name Meaning

0

SUCCESS

Instances returned in results.

1

ERR_REMOTE_COMMUNICATION

Remote communication issue; instances from the initiating node are still returned. Retry later for the full set.

2

ERR_INTERNAL_REMOTE

Internal error on a remote node; local instances still returned.

3

ERR_INTERNAL_LOCAL

Internal local error; no instances returned. error_msg describes the cause (e.g. Unsupported property code <tag>, The destination object could not be resolved, or exceeding the maximum reference nesting depth of 1000).

Notes

  • Module require name is singular. In direct Lua, require the module as require('syslib.api-datastore-targets') (singular), even though the endpoint route uses the plural datastores-targets.

  • Response key is results (plural array). The response field is results, an array of Entry — the entry list for the single requested property (read results[1]).

  • Standard endpoint route. The route name is readdatastoretargetsinstances, consistent with how read → /api/read and readmodel → /api/readmodel are registered.

  • Single property per request. This endpoint reads exactly one { prp_code, obj } pair and returns the entry list for that one property.

  • is_remote is computed relative to the node that handles the request (syslib.getnodepath GUID); it is not relative to parent.

  • prp_code is a numeric model property code, not a property tag string. Resolve tags such as DataStoreSelectorGuid to their codes via the model reference before calling.