The SysUtility Object

The SysUtility Object
lac31
You can access the following services using the
SysUtility
 JavaScript object.
getResource Method
You can retrieve the value of the specified resource using the following 
getResource
 method:
SysUtility.
getResource
(resourceName, settings)
This method retrieves the value using the settings in the second parameter, which must be an object that may have the following properties:
  • filter
    ,
    sysfilter
    userfilter
    . An object with the desired filters for each resource.
    Use aliased (not table) attribute names for filter and sort.
    By default, all of these properties work with
    SysUtility
    calls. If you turn off regular filters, only the 
    sysfilter
    and
    userfilter
     properties work with
    SysUtility
    calls.
    For more information about how to turn off regular filters, see Manage your API.
  • order
    ,
    sysorder
    userorder
    . An object with the desired sorting orders for each resource.
     
    By default, all of these properties work with
    SysUtility
    calls. If you turn off regular filters, only the 
    sysorder
    and
    userorder
     properties work with
    SysUtility
    calls.
    For more information about how to turn off regular filters (and sorts), see Manage your API.
  • pagesize
    . The maximum number of row per resource level.
  • offset
    . The number or records to skip from the top resource.
  • chunksize
    . Determines the number of queries 
    CA Live API Creator
     executes to return the rows for table-based subresources.
The return value of the 
getResource()
 method is an object array, which is the JSON object returned by the call. If you require a string, call the 
getResourceAsString()
 method or stringify the result.
Example:
var parts = SysUtility.
getResource
("Products", {sysfilter: "less(price:100)", sysorder: "(price:desc)"}); for (var i = 0 ; i < parts.length ; i++) {    log.debug(JSON.stringify(parts[i])); }
For more information about how to use the JSON object, see JavaScript.
You can also pass an array of string to
sysfilter
or
sysorder
, for example:
sysfilter: ["less(...)", equal(...),"greater(...)"]
You can reference a subresource where the price of the product is less than 100 is a subresource or 
Customer.Orders.Product
 using '.' dot notation:
'sysfilter.Customer.Orders.Product': 'less(price:100)'
If the resource is a view, qualify it and the filter, for example:
var parts = SysUtility.getResource("
nw:
Customer Orders", {filter: {"
nw:
Customer Orders": "price < 100"}});
If the resource you are invoking is a stored procedure resource, then you can pass parameters as follows:
var orders = SysUtility.getResource("nw:MyProc", {procArgs: {empName: "Doe", amount: 123.45}});
getFunction Method
You can retrieve the value of the specified top level function using the following 
getFunction
 method:
SysUtility.
getFunction
(functionName, parameterList)
This method executes and returns the response of a JavaScript function passing in the optional
parameterList
parameterList
 is an object with the desired list of parameter names in JavaScript format.
Example:
var sum = SysUtility.
getFunction
("addNumbers", {parm1: 10, parm2: 20}); log.debug(sum);
For more information about how to use the JSON object, see JavaScript.
getBinary Method
You can retrieve the value of the specified resource URL using the following 
getBinary
 method:
SysUtility.
getBinary
(resourceURL, params, settings)
Example:
var resourceURL = req.getBaseUrl() + "/v1/demo:employee_picture/1/picture";
resourceURL = resourceURL.replace("rest","data");
var parms = {};
var settings = { "headers": {"Authorization" : "CALiveAPICreator demo_full:1"}};
var byteArray = SysUtility.
getBinary
(resourceURL, parms , settings);
row.content = byteArray;// set the current row (type CLOB)
rest<verb> - GET, PUT, POST, DELETE Methods
You can invoke other RESTful services from business logic or row events using the
restGet
,
restPut
,
restPost
, and
restDelete
methods. In these calls, you pass the URL, parameters, settings, and request data.
Example:
var params = {    name: "Acme",    country: "Elbonia"    }; var json = SysUtility.
restGet
('http://rest.example.com/myservice', params); var resultObject = JSON.parse(json);
The
params
 object contains the parameters to the call. This is equivalent to adding these parameters to the URL, for example:
http://rest.example.com/myservice?name=Acme&country=Elbonia
Do not add parameters directly in the URL. Properly encode parameters and pass them in as an object.
The
settings
 object contains the various settings for the call. You can use the header setting:
SysUtility.
restGet
('http://rest.example.com/myservice', {name: 'Acme', country: 'Elbonia'},  {headers: {   "Authorization" : "Basic <base64string>",   "Cache-Control" : "no-cache"   } });
The
requestData
 JavaScript object is converted to JSON before being sent. You can send only JSON data using these methods.
restGet Method
The
SysUtility.restGet(url, params, settings)
 method returns a stringified version of the result of a GET to the specified URL:
var result = SysUtility.
restGet
(url, params, settings); var myJson = JSON.parse(result);
restPut Method
The
SysUtility.restPut(url, params, settings, requestData)
 method returns a stringified version of the response of a PUT to the specified URL using the 
requestData
 object:
var result = SysUtility.
restPut
(url, params, settings, requestData);  // requestData is a JSON object var myJson = JSON.parse(result);
restPost Method
The
SysUtility.restPost(url, params, settings, requestData)
 method returns a stringified version of the response of a POST to the specified URL using the 
requestData
 JavaScript object:
var result = SysUtility.
restPost
(url, params, settings, requestData); var myJson = JSON.parse(result);
restDelete Method
The
SysUtility.restDelete(url, params, settings)
 method returns a stringified version of the response of a DELETE to the specified URL:
var result = SysUtility.
restDelete
(url, params, settings); log.debug(result); var myJson = JSON.parse(result);
For more information about HTTP headers, see Wikipedia Entry to for HTTP Headers.
rest<verb>Binary Method
You can invoke other RESTful services from business logic or row events using the 
restGet
restPut
restPost
, and 
restDelete
 methods. In these calls, you pass the URL, parameters, settings, and request data.
You can invoke other RESTful services from business logic or row events using binary data using the following
rest<verb>Binary
methods:
SysUtility.
restGetBinary
(url, params, settings)
SysUtility.
restPutBinary
(url, params, settings, requestData)
SysUtility.
restPostBinary
(url, params, settings, requestData)
SysUtility.
restDeleteBinary
(url, params, settings) 
The 
SysUtility.restGetBinary(url, params, settings)
 method returns a stringified version of the result of a GET to the specified URL:
var result = SysUtility.
restGetBinary
(url, params, settings); var myJson = JSON.parse(result);
The 
params
 object contains the parameters to the call. This is equivalent to adding these parameters to the URL, for example:
http://rest.example.com/myservice?name=Acme&country=Elbonia
Do not add parameters directly in the URL. Properly encode parameters and pass them in as an object.
The 
settings
 object contains the various settings for the call. You can use the header setting:
SysUtility.
restGetBinary
('
http://rest.example.com/myservice
', {name: 'Acme', country: 'Elbonia'},  {headers: {   "Authorization" : "Basic <base64string>",   "Cache-Control" : "no-cache"   } });
The 
requestData
 JavaScript object is converted to binary data before being sent. You can send only binary data using the
restPutBinary
and
restPostBinary
methods.
Debug the rest<verb> Method
Before coding the
SysUtility
calls, verify your URL, headers, etc. using REST tools such as Postman. The following image shows an example:
Error Handling
Handle Exceptions in JavaScript Try Catch Blocks
Some calls may throw exceptions, which you can handle in standard JavaScript try/catch blocks.
Test the Results of the Response
You can test the results of the response in API Creator on the Manage, Rules page. The following image shows a commit event on the Manage, Rules page:
View the Generated Log
A log is generated after the transaction completes and is displayed on the Analyze, Logs page. The following image shows the log on this page: