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) forfilterandsort.By default, these properties work withSysUtilitycalls. If you have turned off regular filters and sorts, only named filters (thesysfilteranduserfilterproperties) work withSysUtilitycalls. 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 withSysUtilitycalls. If you have turned off regular filters and sorts, only named sorts (thesysorderanduserorderproperties) work withSysUtilitycalls. 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 queriesCA Live API Creatorexecutes 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:
- About how to use the JSON object, see JavaScript.
- About functions, see Manage Functions.
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:- Theheaderssetting. 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.
- Theproxysetting. This setting ensures that the HTTP call is made using the specified HTTP proxy server. It must include thehostnameproperty with a value set to the host name of the HTTP proxy server and theportproperty 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:
- About using data URLs, see Use Binary Data.
- About viewing an API sample that can store PDFs in binary fields and can display them in a browser by way of Data Explorer, see Document Manager API Sample.
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.