The SysUtility Object

The SysUtility Object
lac32
You can access services, such as retrieving a resource or invoking another REST service, using the 
SysUtility
 JavaScript object.
In this article:
2
getResource Method
You can retrieve the value of the specified resource using the following 
getResource
 method:
SysUtility.
getResource
(resourceName, settings)
This method returns a stringified version of the response to a custom resource. This service operates on your resources in this API. The return value of the 
getResource
 method is an object array, which is the JSON object returned by the call. If a string is required, you can call the 
getResourceAsString
 method or stringify the result.
This method retrieves the value set for the 
settings
 parameter. The value must be an object that can have the following properties:
  • filter
    sysfilter
    userfilter
    . An object with the desired filters for each resource.
    Use aliased attribute names (not table attribute names) for 
    filter
     and 
    sort
    .
    By default, these properties work with 
    SysUtility
     calls. If you have turned off regular filters and sorts, only named filters (the 
    sysfilter
     and 
    userfilter
     properties) work with 
    SysUtility
     calls. For more information about how to turn off regular filters, see Manage your API.
    For more information about using named filters, see Structured Filters.
  • order
    sysorder
    userorder
    . An object with the desired sorting orders for each resource.
    By default, these properties work with 
    SysUtility
     calls. If you have turned off regular filters and sorts, only named sorts (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.
    For more information about using named sorts, see Structured Sorts.
  • 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 
settings
 parameter typically specify your filter criteria (
filter
sysfilter
userfilter
), for example:
var settings = {sysfilter: "equal(OrderID:" + row.OrderID + ")"
,"sysfilter..SupplierAlert.Order_DetailsList.Product.Supplier":
"equal(CompanyName: '" + "Pavlova, Ltd." + "')" };
The 
settings
 parameter can also specify 
pagesize
offset
, and 
chunksize
, for example:
These properties are typically defaulted. They are not required, but shown for reference in this example.
var details = {
filter: "name like 'ABC%',
order: "name asc",
pagesize: 20,
offset: 0,
chunksize: 10
};
For example, in the Business to Business (B2B) sample, we create an instance of the SupplierAlert custom resource (to match the API agreement with our supplier Pavlov), as follows:
var supplierReport_response = SysUtility.getResource("SupplierAlert", options);
For more information about the B2B sample, see Business to Business Example.
For more information:
  • About how to disallow free-form filters, see Manage your API.
  • About how to use URL parameters in GET, PUT, POST, and DELETE, see URL Parameters.
 
Example:
 
var parts = SysUtility.
getResource
("main: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 as the value for 
sysfilter
 or 
sysorder
, for example:
sysfilter: ["less(total: 100)", "equal(name: 'Acme')"]
You can reference a subresource where the price of the product is less than 100 as 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 a specified top-level function using the following 
getFunction
 method:
SysUtility.
getFunction
(functionName, parameterList)
The 
parameterList
 parameter is optional. This parameter 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:
rest<verb> - GET, PUT, POST, DELETE Methods
You can invoke other RESTful services from business logic or row events using the following methods:
SysUtility.
restGet
(url, params, settings)
SysUtility.
restPut
(url, params, settings, requestData)
SysUtility.
restPost
(url, params, settings, requestData)
SysUtility.
restDelete
(url, params, settings)
In these calls, you pass the URL, parameters, settings, and request data.
 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);
restGet 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 optional 
settings
 parameter contains the various settings for the call. It can have the following properties:
  • The 
    headers
     setting. Add this setting to the call as HTTP headers. It must include name/value pairs.
    For more information about HTTP headers, see Wikipedia Entry to for HTTP Headers.
  • The 
    proxy
     setting. This setting ensures that the HTTP call is made using the specified HTTP proxy server. It must include the 
    hostname
     property with a value set to the host name of the HTTP proxy server and the 
    port
     property with a value set to the port number for the HTTP proxy server.
restGet Example:
 
SysUtility.restGet('http://rest.example.com/myservice',
{name: 'Acme', country: 'Elbonia'},
{headers: {
Authorization : "Basic <base64string>",
"Cache-Control" : "no-cache"
},
proxy: {
hostname: "proxy.example.com",
port: 8282
}
});
The 
requestData
 JavaScript object is converted to JSON before being sent. You can send only JSON data using these methods.
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
 JSON object, perhaps obtained through the 
SysUtility.restGet
 method:
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
 JSON object, perhaps obtained through the 
SysUtility.restGet
 method:
var result = SysUtility.
restPost
(url, params, settings, requestData); var myJson = JSON.parse(result);
restPost Example:
 
The following example is from the Business to Business (B2B) sample:
var settings = { headers: { Authorization: "CALiveAPICreator supplier:1" }};
var pavlov_response = SysUtility.restPost(url, null, settings,
supplierReport_response);
The 
requestData
 JavaScript object is converted to JSON before being sent. You can send only JSON data using these methods.
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);
settings
 is an optional JavaScript object. Only the id "headers" is examined. All other ids are ignored:
var settings = {
"headers" : {
"Authorization" : "Basic base64string",
"Cache-Control" : "no-cache"
}
};
For more information about HTTP headers, see List of HTTP Headers page on the Wikipedia website.
restGetBinary Method
You can retrieve a byte array value for a specific data column using a 
/data/
 link in a URL and the following 
restGetBinary
 method:
SysUtility.
restGetBinary
(url, params, settings)
Example:
 
var resourceURL = req.baseUrl + "/v1/demo:employee_picture/1/picture";
resourceURL = resourceURL.replace("rest","data");
var params = {};
var settings = { "headers": {"Authorization" : "CALiveAPICreator demo_full:1"}};
var byteArray = SysUtility.
restGetBinary
(resourceURL, params , settings);
row.content = byteArray;// set the current row (type CLOB)
For more information:
Debug SysUtility Method
Before coding 
SysUtility
 calls, verify your URL, headers, etc. using REST tools such as Postman.
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 rules page.
View the Generated Log
A log is generated after the transaction completes and is displayed on the Logs page.
For more information about how to access the log and log entries, see View Logging Information.