Manage Functions

You can create endpoints to execute your JavaScript in  and return a JSON response. These endpoints are referred to as functions. You can call functions by way of GET operations.
lac311
You can create endpoints to execute your JavaScript in
CA Live API Creator
 and return a JSON response. These endpoints are referred to as functions. You can call functions by way of GET operations.
Unlike JavaScript resources, functions:
  • Can declare explicit arguments.
  • Are published in Swagger. They are easily discoverable.
  • Pass rows automatically. Set some fields and the row is updated (including relevant reactive logic). You do not have to issue APIs to get, alter, and save the row.
    For example, to give a raise, create a function for the Employees table and its resources, using the following code snippet as the function's JavaScript code:
    var theRaise = parameters.percentRaise * (row.Salary/100);
    row.Salary += theRaise;  // runs logic, persists change row(s) to database...
    return [ {"status": "Success"}, {"raise": theRaise} ];
    This function's JavaScript code is from the Give Raise Example.
In this article:
2
Function Types
You can define the following types of functions:
  • Resource-oriented functions.
     Resource-oriented functions are operations on a table/custom resource row. The row is made available to the function and any arguments. The function can then operate on the row (for example, sendMail to alert a colleague about an Order), including update (for example, giveRaise to an employee based on a percentRaise argument). The giveRaise example is illustrated in Business to Business Example. Resource-oriented functions advance the API interface from insert, update, and delete (CRUD) operations to whatever operations the application requires.
    You can regard functions (with reactive logic) as the methods that encapsulate your business logic. Reactive logic ensures that your API behavior is reused over all verbs (PUT, POST, and DELETE) for tables and custom resources. This contributes to a separation of concerns (SoC), where client development can enforce data integrity by proceeding based on the API interface, in parallel with API server logic.
  • Top-level functions.
     Top-level functions are functions that are not associated to a table or custom resource. Use top-level functions to define any logic or service operation as endpoints.
By default, functions are top-level functions. When you associate a function to a resource, the function is a resource-oriented function.
Create Functions
Create a New Function
  1. Go to the Create, Functions, By function tab and click 
    Create New Function
    .
    The Definition tab for the new function appears.
  2. Enter a meaningful name for your function (or accept the default name), the function's JavaScript code, and then save your changes. You call functions using this name in the URL.
    For more information about the context variables you can access in function's JavaScript code, see the "Commonly Accessed Context Variables in Function JavaScript Code" section.
  3. (Optional) On the Parameters tab, complete the following and then click 
    Add Parameter 
    to add more parameters and click 
    Save
     to save the parameters:
    • Define the parameter names and the type (number, string, or Boolean).
    • Specify whether the Parameter is required.
    • Include a comment to describe the parameter.
  4. (Optional) On the Resources tab, associate this function to one or more tables or resources. Enter each table (with database prefix) or resource in a new line. Associate allows the function to access the specific row object inside the function.
  5. On the Documentation tab, describe the purpose of this function by defining comments and the return type expected from the function. The comments and return type are included in your Swagger API documentation.
Your function is created and is active.
Commonly Accessed Context Variables in Function JavaScript Code
You code functions in JavaScript. They can reference JavaScript libraries and any Java JAR files included in your 
classpath
. Your function returns a JavaScript object, which is converted to JSON or translated if you are using XML output.
Your functions can access the following variables:
Variable
Example
Notes
Parameters
var theRaise = parameters.percentRaise * (row.Salary/100);
Define your parameters as described in Create a New Function.
row
row.Salary += theRaise;
req
var user = req.userIdentifier
 
SysUtility
var functionResponse = SysUtility.getFunction(eachTest.TestName, null);
See B2B.testB2BAll()
The following image shows an example of a function's JavaScript code on the Create, Functions, Definition tab: 
Screen Shot 2017-01-09 at 8.51.15 AM.png
Resource-Based Functions - Read/Write Row Access
You can optionally associate functions with tables or custom resources. In such cases, your function's code can reference the row variable, as shown in the previous image. Note this is 
table
row. Mapping and translation has already been provided (column de-aliasing, etc.). You can use your function code over multiple custom resources based on the same table.
You can also update the row in functions. When the function completes,
CA Live API Creator
 executes the associated logic, and (if no errors are detected), persists the row to disk.
You cannot access the
logicContext
object within functions.
Call Functions
You can call functions in the following ways:
Call Functions as Endpoints
You can call functions using the function name, optionally with parameters, using the following syntax:
http://localhost:8080/rest/default/demo/v1/
gcd?n1=0&n2=0
Call Functions on Tables or Resources
You can call functions on tables or resources and pass arguments (as illustrated in the B2B example):
http://localhost:8080/rest/default/b2bderbynw/v1/
nw:Employees/1/giveRaise?percentRaise=1
0
http://localhost:8080/rest/default/b2bderbynw/v1/
EmployeesWithRaises/1/giveRaise?percentRaise=10
When you associate functions to tables or resources, the function can access the current table 
row
 object.
Call Functions using the SysUtility.getFunction Method
You can call functions from within API Server (for example, from logic, libraries, and functions), using the 
SysUtility.getFunction
 method, for example:
 
var parms = {parm1: 1, parm2: 2};
var functionResponse = SysUtility.getFunction("myfunction", parms);
 
Test Functions from the REST Lab
You can use the REST Lab to test your functions. You can select top-level functions as an endpoint from the list. For table/resource functions, you can enter the URL directly. The following image shows the options for calling function from the REST Lab:
Screen Shot 2017-01-10 at 8.08.09 AM.png
Export Functions
You can save a function and its parameters as a JSON definition file to a download directory.
  1. Go to the Create, Functions, By function tab and click the function that you want to export.
    The function opens in edit mode.
  2. Click
    Export
    .
The function is exported as a JSON file.
Import Functions
You can import a previously exported function.
  1. Go to the Create, Functions, By function tab and click
    Import Function
    .
    The Import JSON dialog opens.
  2. Select a previously exported function JSON file by name.
     If the function name already exists, the service appends _clone and a timestamp to the duplicate name.
The new function displays in the list.
Set Function Permissions
As an admin, you can secure functions by setting the permissions at the role-level. By default, roles have permission to execute all functions. You can also set permissions to specific functions for a given role. If your auth token has more than one role with differing permissions to a function, the execute permission takes precedence.
For more information about granting permissions to roles to execute all functions and controlling a role's permission to execute specific functions, see Role-Based Endpoint Access.