Execute Function

  • Execute Function feature makes it possible to create 'custom endpoints'.

  • Power by Lua Library scripts.

  • HTTP methods supported: GET, POST.

Description

Request can be send to the server containing an object (Lua Table) as an argument. Response can be anything in which an object (Lua table) is automatically converted to JSON.

Parameters

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. In case of a HTTP GET the value of this URL query parameter must be Base64 encoded.

ctx

string

yes

A list of item paths, which specifies the context in which the provided function has to be executed.

insights

boolean

yes

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

Lua script example

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. In case the library is stored in a different hierarchical scope then the context path defined in the Web API server object, you need to set the context cxt in the request.

Lua Arguments

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. (Available since Web API version 1.38.x)

The available helper functions are described in more detail in the following sections.

Checkpermission 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)

    • Parameters

      • pathspec - this parameter can be either a string or table, representing the object’s path, or the object itself, or the numeric object or property id

      • sec_attr - a bitwise OR combination of SecurityAttributes flags

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

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) in case the quality returned by the Lua script is not equal to zero (GOOD).

  • createResponse(data, error, status_code, headers)

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
    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 error = nil
    local headers = {
        ["Content-Type"] = "application/csv",
    }
	return hlp:createResponse(body, error, 200, headers )
end

return lib

Get Profile Names Helper

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

Lua script example

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

Get Profile Paths Helper

The 'getprofilepaths' helper function can be used to get the object paths of the profiles the Web API user, which performs the request, is member of.

Lua script example

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

Is Admin Helper

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

Lua script example

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

Is Json Null Helper

The 'isJsonNull' helper function can be used to check if the value is equal to null, helper returns boolean value. Simple example of 'isJsonNull' helper function:

Lua script example

local inAPI = require('inmation.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 member of a specific profile.

Lua script example

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

Examples

HTTP GET

Request URL

  • Library stored in context path defined by WEB API server object /api/v2/execfunction?lib=lib&func=func

  • Library stored in a different hierarchical scope /api/v2/execfunction?lib=lib&func=func&ctx=/System/Core/Examples

Response Body

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

HTTP POST

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
        }
    ]
}