Execute Function

Execute Function feature makes it possible to create 'custom endpoints'.
Powered by Lua Library scripts.
HTTP methods supported: GET, POST.

Description

The Execute Function feature for the Web API allows the use of custom endpoints which can invoke user-defined or arbitrary Lua scripts from the system. The response can be anything in which an object (Lua table) is automatically converted to JSON.

Query Parameters

Query parameters are added to the request URL in order to invoke a specified function from the Web API.

Name	Type	Optional	Description
lib	string	no	Name of the script library which contains or returns the function to execute.
func	string	yes	Name of the function to execute. Required in case the library itself does not return a function.
farg	string	yes	Function argument, which will be passed to the function as a Lua table. If an HTTP GET call is used, the value of this URL query parameter must be Base64 encoded.
ctx	string	yes	Item path which specifies the context in which the provided function has to be executed.
insights	boolean	yes	Indicates if application insights should be included in the response, by default false.

Name

Type

Optional

Description

lib

string

Name of the script library which contains or returns the function to execute.

func

string

yes

Name of the function to execute. Required in case the library itself does not return a function.

farg

string

yes

Function argument, which will be passed to the function as a Lua table. If an HTTP GET call is used, the value of this URL query parameter must be Base64 encoded.

ctx

string

yes

Item path which specifies the context in which the provided function has to be executed.

insights

boolean

yes

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

Web API Call Examples

These examples demonstrate how to call a system function using the Web API. The function used for these examples returns a simple Hello message to the user and is defined in the Lua Script Example.

HTTP GET

For this example, an HTTP GET method call is used. Therefore, all of the request information must be specified within the request URL.

Request URL

If the library is stored in the context path defined by the Web API server object: /api/v2/execfunction?lib=Hello&func=say_hello&farg=eyJuYW1lIjoiQmVuIn0%3D
If the library is stored in a different hierarchical scope: /api/v2/execfunction?lib=Hello&func=say_hello&farg=eyJuYW1lIjoiQmVuIn0%3D&ctx=/System/Core/Examples

In both of these request URLs, the farg query parameter is the value '{"name":"Ben"}' which has been Base64 encoded as required.

Response Body

{
    "data": [
        {
            "p": "/System/Core/Examples",
            "v": "Hello Ben",
            "q": 0
        }
    ]
}

HTTP POST

For this example, an HTTP POST method call is used. Therefore, the parameters do not need to be specified in the request URL. These parameters should be in the request body which is used alongside the request URL to invoke the endpoint.

Request URL

/api/v2/execfunction

Request Body

{
  "ctx": [
    {
      "p": "/System/Core/APIContext"
    }
  ],
  "data": {
    "lib": "Hello",
    "func": "say_hello",
    "farg" : {
        "name" : "Ben"
    }
  }
}

Response body

{
    "data": [
        {
            "p": "/System/Core/APIContext",
            "v": "Hello Ben",
            "q": 0
        }
    ]
}

Lua Arguments

To invoke functions through the Web API, it is required that the function is defined within a library in the system. These functions takes 4 parameters as input: (self, arg, req, hlp).

Name	Description
self	The Lua 'self' parameter.
arg	The provided 'farg' parameter in the request as a Lua table.
req	A Lua table which contains the request information, like HTTP headers and access token payload. (Available since Web API version 1.38.x)
hlp	A proxy 'helper' object which contains convenience functions. The available helper functions are described in more detail in the Helper Functions section below. (Available since Web API version 1.38.x).

Name

Description

self

The Lua 'self' parameter.

arg

The provided 'farg' parameter in the request as a Lua table.

req

A Lua table which contains the request information, like HTTP headers and access token payload. (Available since Web API version 1.38.x)

hlp

A proxy 'helper' object which contains convenience functions. The available helper functions are described in more detail in the Helper Functions section below. (Available since Web API version 1.38.x).

Lua Script Example

This Lua script is an example of a function 'say_hello' that can be defined within the system and invoked by using the Web API. In this case, only the 'arg' parameter is specified within the function, so the output is dependent on only this parameter. The 'self' parameter is represented by '_' indicating that it is not expected to be used within the function. The remaining two parameters are not required in this example. This function is used in all of the examples in the Web API Call Examples section above.

local lib = {}

function lib.say_hello(_, arg)
    local _arg = arg or {} -- in case no argument is set
    local name = _arg.name or 'unknown'
    local msg = string.format("Hello %s", name)
    return msg
end

return lib

Make sure the function within the library is declared with a colon notation.

In Lua: lib:myfunction(arg) is the same as lib.myfunction(lib, arg).

This feature can be tested with Swagger. If the library is stored in a different hierarchical scope than the context path defined in the Web API server object, you need to set the context cxt in the request.

Helper Functions

As mentioned in the hlp argument description above, this section contains a more detailed explanation of the available helper functions.

Check Permission Helper

The 'checkpermission' helper function is a convenience function to check whether the user, who executes the request, has permission based on the provided access token:

checkpermission(pathspec, sec_attr, verbose)

Name Description

Name	Description
`pathspec`	this parameter can be the object’s path, or the object itself, or the numeric object or property id
`sec_attr`	a bitwise OR combination of SecurityAttributes flags
`verbose`	this optional parameter is used to enable/disable additional information in the event of an error

pathspec

this parameter can be the object’s path, or the object itself, or the numeric object or property id

sec_attr

a bitwise OR combination of SecurityAttributes flags

verbose

this optional parameter is used to enable/disable additional information in the event of an error

Lua Script Example

local lib = {}
function lib.checkpermissionExample(_, arg, req, hlp)
    local _arg = arg or {}
    local result = {}
    result.arg = arg
    result.req = req

    local pathSpec = _arg.pathspec or '/System'
    local checkpermissionRes = hlp:checkpermission(pathSpec, syslib.model.flags.SecurityAttributes.READ)
    if not checkpermissionRes.granted then
        return checkpermissionRes:responsevqt()
    end

    result.granted = true
    return result
end

return lib

Check Permissions Helper Output

The output of the Check Permissions helper function is a table which has three return parameters: granted, err and statusCode. The content of these parameters is determined by the arguments in the 'checkPermissions' function call.

Name Description

granted

The returned granted parameter is a boolean value which is dependent on whether the profile/user has permissions for the specified Security Attribute group(s) or not. It is not returned if an error occurs.

err

The content of the 'err' parameter results from the input parameters in the 'checkPermission' helper function call. This parameter is only returned if an error occurs.

If the 'verbose' parameter is not specified, then the returned value for the 'err' parameter will be 'Permission denied', regardless of the error type.

If the 'verbose' parameter is set to true, then the 'err' will be set as follows:

Nil or Unspecified Value: If the 'pathspec' parameter in the 'checkPermission' helper function is nil or not specified, then the following error is returned:

{
    "error": [
        {
            "msg": "Checkpermission, pathspec cannot be nil or empty"
        }
    ]
}

Object does not exist: If the 'pathspec' parameter points to an object that does not exist or to an empty string, then the following error is returned:

{
    "error": [
        {
            "msg": "Permission denied. Object could not be resolved."
        }
    ]
}

statusCode

The statusCode parameter indicates whether the invocation of the function was successful or not. It is important for debugging purposes and can be found in the browser’s network tab if required.

Create Response Helper

The 'createResponse' helper function can be used to set the value, error, HTTP status code and response headers, which should be returned by the Web API. This function creates a ‘RunScript Response’ object, which will only be inspected by the Web API (.NET code) if the quality returned by the Lua script is not equal to zero (GOOD).

createResponse(data, error, status_code, headers)

parameter description

parameter	description
`data`	this is used to set the value(s) returned by the Web API*
`error`	this parameter is used to specify a custom error message and error code*
`status_code`	HTTP status code (for debugging purposes, this can be found in the browser’s network activity tab when the function is invoked)
`headers`	response headers returned from the call

data

this is used to set the value(s) returned by the Web API*

error

this parameter is used to specify a custom error message and error code*

status_code

HTTP status code (for debugging purposes, this can be found in the browser’s network activity tab when the function is invoked)

headers

response headers returned from the call

*The 'data' and 'error' parameters are used to produce the output of the Create Response Helper function.

Example custom error response

local lib = {}

function lib.errorResponseStatusCodeExample(_, _, _, hlp)
    local data = nil -- this example does not return any data.
    local err = {
        msg = 'Custom error message',
        code = 123, -- custom error code.
        loremIpsum = "Lorem Ipsum" -- custom error field.
    }
    local status_code = 503 -- this code indicates that the service cannot process the request
    return hlp:createResponse(data, err, status_code)
end

return lib

Example csv response

local lib = {}

function lib.csvResponseExample(_, _, _, hlp)
    local body = [[column01,column02,column03]] .. '\r\n' .. [[12,14,18]]
    local err = nil
    local headers = {
        ["Content-Type"] = "application/csv",
    }
    return hlp:createResponse(body, err, 200, headers)
end

return lib

If values for both the 'data' and 'error' parameters are provided, then only one will generate the output of the helper function. The output is dependent on whether the 'content-type' is specified in the 'headers' parameter.

If the 'content-type' is specified, the 'data' parameter takes precedence over the 'error' parameter and therefore, is used to produce the output. For example:

local lib = {}

function lib.testOutputExample(_, _, _, hlp)
    local body = {
        data = "This is the data"
    }
    local err = {
        msg = 'Custom error message',
        code = 123
    }
    local status_code = 200
    local headers = {
        ["Content-Type"] = "application/json"
    }

    return hlp:createResponse(body, err, status_code, headers)
end

return lib

Using the above code, the following output will be returned by the Web API.

{
    "data": "This is the data"
}

If the 'content-type' is not specified, the 'error' parameter takes precedence over the 'data' parameter and therefore, is used to produce output. For example:

local lib = {}

function lib.testOutputExample(_, _, _, hlp)
    local body = {
        data = "This is the data"
    }
    local error = {
        msg = 'Custom error message',
        code = 123
    }
    local status_code = 503

    return hlp:createResponse(body, error, status_code, headers)
end

return lib

Using the above code, the following output will be returned by the Web API.

{
    "error": [
        {
            "code": 123,
            "msg": "Custom error message"
        }
    ]
}

Get Profile Names Helper

The 'getprofilenames' helper function can be used to get the names of the profiles the Web API user, which performs the request, is a member of.

Lua Script Example

return function(_, _, hlp)
    return hlp:getprofilenames()
end

Is Admin Helper

The 'isadmin' helper function can be used to check whether the Web API user, which performs the request, is a member of a profile which has administrative access.

Lua Script Example

return function(_, _, hlp)
    return hlp:isadmin()
end

Is Admin or Reviewer Helper

The 'isadminorreviewer' helper function can be used to check whether the Web API user, which performs the request, is a member of a profile which has administrative access or review-only access.

Lua Script Example

return function(_, _, hlp)
    return hlp:isadminorreviewer()
end

Is Json Null Helper

The 'isJsonNull' helper function can be used to check if the value is equal to null. This helper returns a boolean value.

Lua Script Example

local inAPI = require('syslib.api')

return function(_, req, hlp)
    local query = {
        items = {
            {
                p = "PATH"
            }
        }
    }
    local response = inAPI:read(query, req, hlp)
    local value = response.data[1].v
    return hlp:isJsonNull(value)
end

Is Member Of Profile Helper

The 'ismemberofprofile' helper function can be used to check whether the Web API user, which performs the request, is a member of a specific profile.

Lua Script Example

return function(_, _, hlp)
    local profileObjName = 'SuperUser'
    return hlp:ismemberofprofile(profileObjName)
end

Is Reviewer Helper

The 'isreviewer' helper function can be used to check whether the Web API user, which performs the request, is a member of a profile which has review-only access.

Lua Script Example

return function(_, _, hlp)
    return hlp:isreviewer()
end