Mass

Mass configuration endpoint can create, delete or modify multiple objects at once.
Required security permission - depends on the action: READ, WRITE, MODIFY.
HTTP methods supported: POST.

Description

The Web API Mass endpoint is based on the Lua syslib.mass function. Read more about syslib.mass function in the Lua API section of the documentation.

Parameters

Name Type Optional Description

body

Mass RPC data which contains a list of mass entries ('items'). The following fields are required - additional fields are dependent on the operation and object type.

Name

Description

path

Object path

operation

Mass operation type

batch_flags

undefined

yes

Affects the entire mass operation by controlling its execution type, by default 0. The value can either be a number, string, comma separated string or an array. The batch flag 'TRIM' is not allowed through the Web API.

scope_comment

string

yes

Audit trail comment.

fields

string

yes

Comma separated string to customize which fields should be included in the response, by default 'p,n'. Supported fields are c = MassStatusCode, n = MassStatusName, p = path. Provide ALL to include all fields.

insights

boolean

yes

Indicates application insights should be included in the response, by default false.

Examples

In these examples, a HTTP POST call is used to implement mass configuration functions.

Create objects

This example shows a mass endpoint request to create two folders and two generic items in the I/O Model.

Request URL: /api/v2/mass

Request Body:

{
    "items": [
        {
            "path": "/System/Core/Folder01",
            "operation": "INSERT",
            "class": "GenFolder",
            "ObjectName": "Folder01"
        },
        {
            "path": "/System/Core/Folder01/GenItem01",
            "operation": "INSERT",
            "class": "GenItem",
            "ObjectName": "GenItem01"
        },
        {
            "path": "/System/Core/Folder02",
            "operation": 1,
            "class": 123,
            "ObjectName": "Folder02"
        },
        {
            "path": "/System/Core/Folder02/GenItem02",
            "operation": 1,
            "class": 125,
            "ObjectName": "GenItem02"
        }
    ]
}

Response Body:

{
    "data": {
        "items": [
            {
                "n": "CREATED",
                "p": "/System/Core/Folder01"
            },
            {
                "n": "CREATED",
                "p": "/System/Core/Folder01/GenItem01"
            },
            {
                "n": "CREATED",
                "p": "/System/Core/Folder02"
            },
            {
                "n": "CREATED",
                "p": "/System/Core/Folder02/GenItem02"
            }
        ],
        "stats": {
            "failure": 0,
            "success": 4,
            "total": 4
        }
    }
}

Changing object properties

In this example, the mass endpoint is used to update object properties, namely the Object Names in this case. A similar function can be used to change properties such as Object Description and Engineering Units.

Request URL: /api/v2/mass

Request Body:

{
    "items": [
        {
            "path": "/System/Core/Folder01",
            "operation": "UPSERT",
            "class": "GenFolder",
            "ObjectName": "Folder01Renamed"
        },
        {
            "path": "/System/Core/Folder02",
            "operation": "UPSERT",
            "class": "GenFolder",
            "ObjectName": "Folder02Renamed"
        }
    ]
}

Response Body:

{
    "data": {
        "items": [
            {
                "n": "UPDATED",
                "p": "/System/Core/Folder01"
            },
            {
                "n": "UPDATED",
                "p": "/System/CoreFolder02"
            }
        ],
        "stats": {
            "failure": 0,
            "success": 2,
            "total": 2
        }
    }
}

Mass request failure

In this example, the mass endpoint request fails due to an invalid object path. The HTTP status code in this response is 200 (OK).

Request URL: /api/v2/mass

Request Body:

{
    "items": [
        {
            "path": "/System/Core/Folder01",
            "operation": "UPDATE",
            "class": "GenFolder",
            "ObjectName": "Folder01"
        },
        {
            "path": "/System/Core/Folder02",
            "operation": "UPDATE",
            "class": "GenFolder",
            "ObjectName": "Folder02"
        }
    ]
}

Response Body:

{
    "data": {
        "items": [
            {
                "error": {
                    "msg": "Permission denied. 'Object '/System/Core/Folder01' could not be resolved."
                },
                "n": "FAILED_DENIED",
                "p": "/System/Core/Folder01"
            },
            {
                "error": {
                    "msg": "Permission denied. 'Object '/System/Core/Folder02' could not be resolved."
                },
                "n": "FAILED_DENIED",
                "p": "/System/Core/Folder02"
            }
        ],
        "stats": {
            "failure": 2,
            "success": 0,
            "total": 2
        }
    }
}