Tutorial

Low-code API

Table of contents

  1. Introduction
  2. Creating an API Endpoint
    1. Permissions
    2. Input and Output Parameters
    3. Examples
  3. Calling an Endpoint
    1. Authentication
    2. Example

Introduction

The cplace Low-Code API allows to easily create a SOAP endpoint, which executes a cplaceJS script when called. The SOAP method accepts a JSON string as input parameter, and also returns a JSON string as result.

Creating an API Endpoint

To be able to use this feature, make sure that the Low-Code API Management-App is installed in the workspace.

A Low-Code API endpoint can be created through the cplace UI. Log in and create a page of type "Low-Code Endpoint" (internal name cf.cplace.api.jaxws.lowcodeApi.lowcodeEndpoint). The type has three required attributes:

  • Unique name: unique name for the Endpoint. Used to identify the endpoint when calling the SOAP API.
  • Executors: list of users who are allowed to execute the endpoint.
  • Script: Low-Code script. Read the section about parameters for more details.

Permissions

To be able to create a Low-Code API endpoint, a user (or a group the user belongs to) needs to be listed under "Permission to edit cplaceJS scripts, which can call actions" in the application settings on the permissions tab. This field is not editable through the UI. The users and groups need to be added through the server action AddRemoveCplaceJSEditPermissionsAction. Additionally, the user needs to have editor rights to the Low-Code Endpoint page type.

To call an endpoint, the authenticated user must be listed in the Executors attribute.

Input and Output Parameters

Every Low-Code API script receives one parameter as input value, and returns a single value as return value. Both are usually JSON strings.

The input parameter is called parameters and can be accessed from within the script. The JSON string provided via the API is parsed before being passed, i.e. properties of the input parameter can be accessed by their name. For example, when passing { x: "test", y: 1} as a parameter, from within the script calling parameters.x would return "test" while calling parameters.y would return 1. It is required to pass an object as parameter, passing null is not valid.

A return value can be passed using a statement like return { x: "xyz" } in the script. The script can return a primitive value, a JSON Object or an Array as result. Returning null or undefined are also possible, as well as returning nothing; all of these will yield an empty SOAP response body.

Examples

This section contains some samples for Low-Code API scripts:

Adding up two values

The following script takes two values and calculates the sum.

return parameters.x + parameters.y;

I.e., providing { x: 3, y: 5 } as an input parameter would yield 8 as result.

Returning the name of a page

var pages = new Search()
    .add(Filters.uid(parameters.uid))
    .findAllPages();
var result;
cplace.each(pages, function (page) {
  result = page.getName()
});
return result;

Providing { uid: "f2j5k3d2own5sdy065jeln5v8" } as an input parameter would either return undefined or a string representing the name of the page with the ID as provided in the input parameter.

Updating a page name

var pages = new Search()
    .add(Filters.uid(parameters.uid))
    .findAllPages();
var success = false;
cplace.each(pages, function (page) {
  cplace.actions().updatePage(page, {
    name: parameters.name,
  });
  success = true;
});
return success;

This takes an object like { uid: "f2j5k3d2own5sdy065jeln5v8", name: "test" } as input parameter, and returns either true or false, depending on whether a page with the given ID was found. Also, the page's name is updated and set to "test" if it was found.

Calling an Endpoint

The endpoints must be called using SOAP. The WSDL file can be accessed via the cplace UI by opening the Administration Dashboard and navigating to the SOAP API-Status page. This page lists all available SOAP endpoints. One of them is the lowcodeExecution endpoint used for the Low-Code API. The corresponding row contains a link to the WSDL required to access this endpoint.

The Low-Code API endpoint only contains one method called execute, which takes two parameters:

  • endpointIdentifier is the name of the Low-Code API endpoint. This corresponds to the "unique name" of an endpoint.
  • parametersJson is the JSON provided as input parameter. In any case, a JSON string must be provided, so in case you don't need any parameters, just pass an empty JSON object (i.e. {}).

The method execute returns a String, which is the serialized JSON object returned by the Low-Code API script.

Authentication

Only authenticated calls to the Low-Code API are permitted. An authentication mechanism can be implemented using a ApiAuthenticationInterceptor. Also, for instances with more than one tenant, a tenant selection mechanism needs to be implemented (for example using a ApiTenantInterceptor). Please refer to the webservices documentation for details on how to implement both authentication and tenant selection.

Example

The following snippet represents a SOAP request to an endpoint like the one shown above in the section updating a page name saved with the endpoint name cf.cplace.api.services.lowcodeApiManagement.updatePageName.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sei="http://sei.lowcodeApi.jaxws.api.cplace.cf/">
   <soapenv:Header/>
   <soapenv:Body>
      <sei:execute>
         <endpointIdentifier>cf.cplace.api.services.lowcodeApiManagement.updatePageName</endpointIdentifier>
         <parametersJson>{ uid: "page/c1oaqesuf1vpoll1q7whel5hc", name: "this is my new name"}</parametersJson>
      </sei:execute>
   </soapenv:Body>
</soapenv:Envelope>

When executed successfully, the SOAP response would look like this:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:executeResponse xmlns:ns2="http://sei.lowcodeApi.jaxws.api.cplace.cf/">
         <return xsi:type="xs:string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">true</return>
      </ns2:executeResponse>
   </S:Body>
</S:Envelope>