Mass

  • Mass configuration endpoint can create, delete or modify multiple object 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

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.

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

Creating objects example

In this example two folders and two generic items are created in the I/O model. Note that operation and class can be supplied as a string or as numeric value.

First part of the response body returns the mass operation status code. The second part of the response body returns a statistical summary of the execution.

HTTP POST
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 example

In the below example the names of the folders will be changed by mass function. Similar function can be used to change other object properties, such as object description, engineering unit, etc.

In the response body, field "stats" provide the statistical summary of the call execution.

HTTP POST
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 failure response

The below example contains failed response of the UPDATE mass request, due to incorrect object path. The HTTP status code of the response is in this example 200 (OK). The items section in the response contain the error object.

HTTP POST
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": "Object could not be resolved."
                },
                "n": "FAILED_DENIED",
                "p": "/System/Core/Folder01"
            },
            {
                "error": {
                    "msg": "Object could not be resolved."
                },
                "n": "FAILED_DENIED",
                "p": "/System/Core/Folder02"
            }
        ],
        "stats": {
            "failure": 2,
            "success": 0,
            "total": 2
        }
    }
}