API Selector Entries

Read the allowed selector entries (instance choices or table-row choices) for a selectable object property, for one or many properties in a single request.

Purpose

Exposes the same functionality as the Web API readselectorentries endpoint. A selector is a property whose value is chosen from a dynamically computed set of options rather than a free value — for example an ArchiveSelector (pick a configured data store set) or a FileSink selector (pick a configured file-sink object). A selector entry is one such option, carrying a human-readable label, an optional description, and the value that would be written to the property if that entry were selected.

The module resolves the selector property (by full path-spec or by property code) and returns the current set of entries via syslib.getselectorentries. Two selector shapes exist:

  • Instance selector — entries reference configuration objects (e.g. file sinks). Each entry carries the object class_code and, optionally, the resolved object path.

  • Table-row selector — entries reference rows of a configuration table (e.g. data store sets). Each entry carries an optional coding_group.

Object/property permissions are enforced by the system in the context of the authenticated user.

Invocation Modes

HTTP Endpoints

Standard endpoint:

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

Advanced endpoint:

POST {{baseurl}}/api/v2/execfunction/syslib.api-selectorentries/read
Content-Type: application/json
Authorization: Bearer {{token}}

Direct Lua

Via API index script:

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

Direct script library call:

local selectorApi = require('syslib.api-selectorentries')
local result = selectorApi:read(arg, req, hlp)

Example

Read the entries of a selector property addressed by full path-spec (object path + property name):

{
    "pathspec_or_propcode": "/IO-Home/Tags/Tag1.ArchiveSelector"
}

Response — an object with an items array, one entry per available choice:

{
    "items": [
        { "label": "Local Set", "description": "Home - Home", "value": 6510 },
        { "label": "Remote Set", "description": "Home - Remote", "value": 6511 }
    ]
}

Example Bank

Address the property by property code

pathspec_or_propcode may be an integer property code instead of a path-spec string. Use options.parent to give the object context the code is resolved against.

{
    "pathspec_or_propcode": 419,
    "options": {
        "parent": "/System/Core"
    }
}
{
    "items": [
        { "label": "Local Set", "description": "Home - Home", "value": 6510 }
    ]
}

Instance selector with resolve_path

For an instance selector (e.g. a FileSink selector), each entry carries the class_code of the referenced object; with resolve_path: true the resolved object path is included as well. value is the referenced object’s GUID.

{
    "pathspec_or_propcode": "/IO-Home/Files/FileSource1.FileSink",
    "options": {
        "resolve_path": true
    }
}
{
    "items": [
        {
            "label": "Local Sink",
            "description": "Local file sink",
            "value": "8a1f3c0e-2b4d-4e6f-9a1b-0c2d4e6f8a1b",
            "class_code": 460,
            "is_remote": false,
            "path": "/IO-Home/Files/Local Sink"
        },
        {
            "label": "Remote Sink",
            "description": "Remote file sink",
            "value": "9b2c4d1f-3c5e-5f7a-0b2c-1d3e5f7a9b2c",
            "class_code": 460,
            "is_remote": true
        }
    ]
}

Filter by class_code

options.class_code restricts instance-selector entries to objects of the given class code.

{
    "pathspec_or_propcode": 419,
    "options": {
        "parent": "/System/Core",
        "resolve_path": true,
        "class_code": 419
    }
}

Batch read with items

When items is an array, each item is resolved independently and the response wraps the per-item results in a top-level items array. Each per-item result is itself a { items: […​] } object.

{
    "items": [
        { "pathspec_or_propcode": "/IO-Home/Tags/Tag1.ArchiveSelector" },
        { "pathspec_or_propcode": "/IO-Home/Tags/Tag2.ArchiveSelector" }
    ]
}
{
    "items": [
        { "items": [ { "label": "Local Set", "description": "Home - Home", "value": 6510 } ] },
        { "items": [ { "label": "Local Set", "description": "Home - Home", "value": 6510 } ] }
    ]
}

Direct Lua

local selectorApi = require('syslib.api-selectorentries')
local result = selectorApi:read({
    pathspec_or_propcode = "/IO-Home/Tags/Tag1.ArchiveSelector",
    options = { resolve_path = true }
}, req, hlp)
-- result.items[1] = { label = "Local Set", description = "Home - Home", value = 6510 }

Request Contract

Top-level argument (SysLib.API-SelectorEntries.Arg) — also accepted as a single item:

Field Type Required Default Behavior

pathspec_or_propcode

string

integer

yes (unless items)

—

The selector property to read. A path-spec string (<objectpath>.<property>) or an integer property code. Also accepted via opt.pathspec_or_propcode or the URL query pathspec_or_propcode.

options

object

no

—

Resolution options (see below).

items

array

no

—

Per-item object (SysLib.API-SelectorEntries.Arg-Item) — same shape as the single argument:

Field Type Required Default Behavior

pathspec_or_propcode

string

integer

yes

—

Selector property for this item.

options

object

no

—

Options object (SysLib.API-SelectorEntries.Arg-Options):

Field Type Required Default Behavior

class_code

integer

no

—

Restrict instance-selector entries to objects of this class code.

parent

objspec (string

number)

no

—

Parent object context used when the selector is addressed by a property code (or a relative spec) rather than a full path.

resolve_path

boolean

no

false

Response Contract

Single read

Returns a SysLib.GetSelectorEntries.Result: an object with an items array of selector entries. The entries are one of two shapes depending on the selector type.

Instance-selector entry (SysLib.GetSelectorEntries.Result-InstanceSelector):

Field Type Present when

value

number

string

always — the value written if this entry is chosen. For instance selectors referencing objects this is the object GUID.

class_code

integer

always — class code of the referenced object.

label

string

a label is available.

description

string

a description is available.

path

string

resolve_path: true and the path is resolvable.

is_remote

boolean

Table-row-selector entry (SysLib.GetSelectorEntries.Result-TableRowSelector):

Field Type Present when

value

number

always — the row identifier written if this entry is chosen.

label

string

a label is available.

description

string

a description is available.

coding_group

integer

the row belongs to a coding group.

The function also returns a response-quality value as its second Lua return.

Batch read

When the request uses items, the response is { items: [ <per-item result>, …​ ] }, where each per-item result is itself a { items: [ <entry>, …​ ] } object, in request order.

Permissions

  • Runs in the context of the authenticated user; object/property access is enforced by the system.

  • Reading a selector property requires READ permission on that property (a table-row selector read by a user lacking READ permission is rejected).

  • When resolve_path/instance entries reference other objects, visibility of those objects follows the caller’s permissions.

Error Handling

Unlike read/write, this endpoint does not report errors per item; resolution failures are raised. Common conditions (from syslib.getselectorentries):

Condition Message

pathspec_or_propcode is the wrong type (e.g. a table)

invalid property type

Property path does not exist

invalid property type

Property is not a selector property (e.g. ObjectName)

invalid property type

In batch mode (items), each item is mapped independently; a failure resolving one item raises and aborts the batch.

Notes

  • The standard endpoint route is readselectorentries (the API index method syslib.api:readselectorentries), while the script-library function is named read; the advanced endpoint therefore uses …​/syslib.api-selectorentries/read.

  • This is not an action type — there is no syslib.api-actions wrapper for it.

  • pathspec_or_propcode resolution follows syslib.api-common.prepareOptions priority: top-level arg field, then arg.opt, then the URL query. URL-query values are strings and are coerced (numeric strings become numbers).