Manage Functions

You can use functions as endpoints to call your JavaScript in  and return a JSON response.
lac32
You can use functions as endpoints to call your JavaScript in
CA Live API Creator
 and return a JSON response.
Functions:
  • Can declare explicit arguments.
  • Are published in Swagger. They are easily discoverable.
  • (Resource-oriented functions) Can be called from Data Explorer.
  • 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:
3
Function Types
You can define the following types of functions:
  • Top-level functions
    Top-level functions are functions that are not associated to a table, view, or custom resource. By default, functions are top-level functions. Use top-level functions to define any logic or service operation as endpoints.
  • Resource-oriented functions
    Resource-oriented functions are functions that are associated to a table, view, or custom resource. Resource-oriented functions are operations on a table, view, or custom resource (of type Normal) 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 the Business to Business (B2B) sample.
    For more information about the B2B sample, see 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 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.
Create Functions
Create a New Function
  1. In the Create section, click 
    Functions
    By function
    .
    If your API has existing functions, they are listed on the page.
  2. Click 
    Create New Function
    .
    The Definition page for the new function appears by default.
  3. Complete the following fields:
    Function name
    The function's name. Enter a meaningful name for your function (or accept the default name).
    Code
    Defines the function's JavaScript code. You can:
    • Click 
      Examples
      ,
       Insert
       to access and insert example JavaScript code.
      For more information about the JavaScript code examples that are available from the functions code editor, see Code Examples.
    • Code functions in JavaScript that reference JavaScript libraries and Java JAR files in your 
      classpath
      .
      For more information about the context variables that are commonly accessed in function JavaScript code, see the "Commonly Accessed Context Variables in Function JavaScript Code" section.
  4. (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.
  5. (Optional) On the Resources tab, associate this function to one or more tables, views, or resources (of type normal). This allows the function to access individual records in the function JavaScript code using the current table
    row
    object. Enter the names on separate lines in the text box.
    Use the following syntax for tables:
    <data source prefix>:<table name>
    For more information:
  6. 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.
  7. Save your changes.
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. For more information about how to define your parameters, see the "Create a New Function" section.
row
row.Salary += theRaise;
Row variable attributes are based on the column names for the table or view. Alias column names (or attributes) for resources are not available from the row variable.
For more information about Read/Write row access, see the "Resource-Based Functions - Read/Write Row Access" section.
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 in API Creator, including the JavaScript code:
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. Users of the API can call these function only on rows to which they have at least Read access. 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
 calls the associated logic, and (if no errors are detected), persists the row to disk.
You cannot access the
logicContext
object within functions.
You can call resource-oriented functions from Data Explorer.
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, Views, or Resources
Prerequisite: (Views) You have added a virtual primary key to the view. For more information about how to add a virtual primary key to a view, see Manage Views.
You can call functions on tables, views, or resources and pass arguments, using a URL with the following syntax:
.../v1/<data source prefix>:<table, view, or resource name>/1/<function name>
Examples
The following are examples from the B2B sample:
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
Call Functions using the SysUtility.getFunction() Method
You can call functions by way of GET operations. 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 resource-oriented functions, you can enter the URL directly.
For more information about how to test functions in the REST Lab, see Test your API Using the REST Lab.
Call Functions on Tables from Data Explorer
You can call resource-oriented functions using the functions drop-down in Data Explorer.
For more information about how to call functions in Data Explorer, see Data Explorer.
Export Functions
You can save a function and its parameters as a JSON definition file to a download directory.
  1. From the Create section, click
    Functions
    .
    The By function tab displays by default.
  2. Click the function that you want to export.
    The function opens in edit mode.
  3. Click
    Export
    .
The function is exported as a JSON file.
Import Functions
You can import a previously exported function.
  1. From the Create section, click
    Functions
    .
    The By function tab displays by default.
  2. Click
    Import Function
    .
    The Import JSON dialog opens.
  3. Select a previously exported function JSON file by name.
    If the function name already exists, API Server appends
    _clone
    and a timestamp to the duplicate name.
The imported function displays in the list.
Set Function Permissions
As an admin, you can control access to your functions by setting function-level permissions for roles. By default, roles have permission to call 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 privilege takes precedence.
For more information about how to control a role's permission to call specific functions, see Role-Based Endpoint Access.