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. |
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.
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.
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). |
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 |
---|---|
|
this parameter can be the object’s path, or the object itself, or the numeric object or property id |
|
a bitwise OR combination of SecurityAttributes flags |
|
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 | ||
---|---|---|---|
|
The returned |
||
|
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 set to true, then the 'err' will be set as follows:
|
||
|
The |
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 |
---|---|
|
this is used to set the value(s) returned by the Web API* |
|
this parameter is used to specify a custom error message and error code* |
|
HTTP status code (for debugging purposes, this can be found in the browser’s network activity tab when the function is invoked) |
|
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.
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.
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.
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.