API Write

Write values (with optional quality and timestamp) to one or many object properties in a single request.

Purpose

Writes values to object properties via syslib.setvalue. Accepts an array of items, each addressed by object path (p) or object/property ID (i), carrying the value (v) and optional quality (q) and timestamp (t). WRITE permission is checked per item. Write-tuning options (OPC read mode, pack delay, audit, OPC method) are applied through syslib.defaults.

Invocation Modes

HTTP Endpoints

Standard endpoint:

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

Advanced endpoint:

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

Direct Lua

Via API index script:

local api = require('syslib.api')
local result, quality = api:write(arg, req, hlp)

Direct script library call:

local writeApi = require('syslib.api-write')
local result = writeApi:write(arg, req, hlp)

Action Pipeline

Also invocable as the write action type inside a syslib.api-actions pipeline (the action calls apiExec:write). The action accepts convenience keys (path, item) that are normalized into the standard items form. See syslib.api-actions.

[
    {
        "type": "write",
        "items": [
            { "p": "/IO-Home/Tags/Tag1", "v": 42 }
        ]
    }
]

Example

Write a value to two items by path:

{
    "items": [
        { "p": "/IO-Home/Tags/Tag1", "v": 42.5 },
        { "p": "/IO-Home/Tags/Tag2", "v": true }
    ]
}

Response (one entry per written item, fields per fields option, default i,p,v,q,t):

{
    "data": [
        { "i": "8a1f...", "p": "/IO-Home/Tags/Tag1", "v": 42.5, "q": 0, "t": 1719763200000 },
        { "i": "9b2c...", "p": "/IO-Home/Tags/Tag2", "v": true, "q": 0, "t": 1719763200000 }
    ]
}

Example Bank

Write value, quality, and timestamp

t may be an epoch (milliseconds) integer or an ISO 8601 string. When q is supplied without t, the current server time is used.

{
    "items": [
        { "p": "/IO-Home/Tags/Tag1", "v": 42.5, "q": 0, "t": "2026-06-30T10:00:00.000Z" }
    ]
}
{
    "data": [
        { "i": "8a1f...", "p": "/IO-Home/Tags/Tag1", "v": 42.5, "q": 0, "t": "2026-06-30T10:00:00.000Z" }
    ]
}

Write by object/property ID

{
    "items": [
        { "i": "8a1f3c0e-2b4d-4e6f-9a1b-0c2d4e6f8a1b", "v": 100 },
        { "i": 1048576, "v": 0 }
    ]
}

Respond only with errors (roe)

With roe: true, the response still uses the standard { "data": […​] } envelope, but successful items are omitted and only failed items are returned in data.

{
    "roe": true,
    "items": [
        { "p": "/IO-Home/Tags/Tag1", "v": 42.5 },
        { "p": "/IO-Home/Tags/Missing", "v": 1 }
    ]
}
{
    "data": [
        { "p": "/IO-Home/Tags/Missing", "v": 1, "error": { "message": "..." } }
    ]
}

Write-tuning options

Each tuning option has a short name and a write_-prefixed alias (both accepted). They map onto syslib.defaults for the request.

{
    "fetch": 1,
    "delay": 0,
    "audit": true,
    "items": [
        { "p": "/IO-Home/Tags/Tag1", "v": 42.5 }
    ]
}

Direct Lua

local writeApi = require('syslib.api-write')
local result = writeApi:write({
    items = {
        { p = "/IO-Home/Tags/Tag1", v = 42.5, q = 0 },
        { p = "/IO-Home/Tags/Tag2", v = true }
    }
}, req, hlp)

Request Contract

Top-level argument (SysLib.API-Write.Arg):

Field Type Required Default Behavior

items

array

yes

—

Array of write items.

fields

string or string[]

no

"i,p,v,q,t"

Fields to include in each response item.

time_zone

string

no

—

Time zone applied when rendering response timestamps.

roe

boolean

no

false

Respond Only Errors — omit successful items from the response.

fetch / write_fetch

integer

no

1

OPC read mode before write (OPC_READ_CACHE_BEFORE_WRITE).

delay / write_delay

integer

no

0

Pack delay — time to wait to collect multiple writes.

audit / write_audit

boolean

no

false

Create an audit entry in the system log for the write.

group / write_group

boolean

no

false

Force OPC DA 2.05 write method.

timeo / write_timeo

number

no

0

Write timeout. Currently has no effect.

async

boolean

no

false

No user-visible effect; avoid setting.

Per-item object (SysLib.API-Write.Arg-Item):

Field Type Required Default Behavior

p

string

conditional

—

Object path. One of p or i is required.

i

string

conditional

—

Object ID (GUID string) or property ID (String).

v

unknown

no

—

Value to write.

q

integer

no

—

Quality code of the value. When set without t, timestamp defaults to current server time.

t

integer

string

no

—

Response Contract

Returns an object with a data array. Each entry in data is a SysLib.API-ItemValueHelper.Create-Result, echoing the written i/p/v/q/t per the fields option. A failed item carries an error field. With roe: true, data contains only error items. The function also returns a response-quality value as its second Lua return.

Permissions

  • Each item requires WRITE permission on the target object/property; otherwise that item returns an error.

  • Runs in the context of the authenticated user.

Error Handling

Errors are reported per item; one failure does not abort the others. Failed entries carry an error field (and echo back the attempted v/q/t). Common messages:

Condition Message

Neither p nor i provided

Missing path or identifier.

WRITE permission denied

permission error from checkpermission

t string not ISO 8601

Invalid timestamp '<t>'. Timestamp should be in ISO 8601 format.

syslib.setvalue failure

underlying runtime error

The actual write uses a protected call (pcall); a runtime failure is captured as the item’s error rather than raised.

Notes

  • The standard endpoint contract is { items: […​] }. The write action (in syslib.api-actions) is the same operation reachable inside an action pipeline.

  • Tuning options accept both the short name (fetch, delay, audit, group, timeo) and the write_-prefixed alias (write_fetch, …). They are applied via syslib.defaults for the whole request.

  • timeo/write_timeo and async currently have no user-visible effect; do not rely on them.