Making Requests

The API Server can be called from anywhere by anything capable of making valid requests which meet the security requirements you've set up.

The most common areas you'll call workers from are in your forms, End Points and workflow processes.

Working in End Points

When you're working in an End Point you should use this.callWorkerMethod to call other workers. The examples below use the End point "this" object, which is described in the End Point this Object section.

Calling Another Worker

This example calls a worker on the same API Server. There's no need to provide an API key or server ID even though the target worker is internal.

function(params, credentials) {
    var articleData = this.callWorkerMethod("icmapi", "CSArticle_get", {
        "get": "ArticleHeading,ObjExtensionData",
        "set": {
            "ArticleID": 5877,
            "ExtensionDataReqd": true,
            "DetailLevel": 5
        }
    });
    return articleData;
}

Calling Other End Points

It's worth noting that End Points are themselves deployed to workers, and called as methods on those workers. If you are calling another End Point deployed to the same worker as your current End Point, use this.invokeEP, rather than creating an API Client - it's faster and more efficient.

This example calls another End Point and returns some configuration information. Note how additional parameters can be passed to the target End Point.

function(params, credentials) {
    var config = this.invokeEP("config.getConfig", {
        "application": "TimsSolution"
    });
    return config.templateId;
}

Working in Forms

When working in forms you need to be aware of where your scripts are being executed, as this will restrict the API Server workers you can access.

The majority of your requests to the API Server will need to be made server-side, because most workers are only available to scripts executed on your server, preventing them from being called by a user's browser or an external service. That means using form field default functions and server-side variables.

In a standard installation the only workers you can call browser-side are the Ajax Library (which is where public End Points are deployed), the Postcode Worker (thanks to a framework proxy), and the Forms Service itself.

Browser-Side Calls

Apart from the Postcode worker, the only other requests you can make to the API Server in your form field handlers and page/form "init" functions are to End Points deployed to the Ajax Library worker. These requests are made after the form has loaded and dynamically as field values are updated.

Take great care when writing an End Point for the Ajax Library. They can be called by anyone, anywhere and are completely public.

You can construct requests using the .utilInvokeAPIServer helper function. There are also two form fields that can be used for browser-side calls.

Ajax Template

The HTML Ajax Template field calls an End Point and displays the result using a Handlebars template. There's an example in the Getting Started article.

Ajax Call

The API Server AJAX field (found in the "Misc" category of field types), can be set up to make an AJAX request whenever its value changes, whenever the value of another field changes, or when its "makeRequest" custom function is invoked.

In this example a request is made to an End Point, which is passed the value of another field as a parameter.

The field's handler then updates another field with the result of the call.

Server-Side Calls

A form field's default function is executed server-side when the form page it is on is being generated. The result of the function is returned to the field.

The helper function .utilServerAPIServerCall can be used to call an API Server worker. The function only works server-side and is able to make calls to internal workers as standard.

In this example the iCM API worker is asked for the heading of an article.

function(helper, defaultValue, currentValue) {
    var request = helper.utilServerAPIServerCall("icmapi", "CSArticle_get", {
        "get": "ArticleHeading",
        "set": {
            "ArticleID": 1
        },
    });
    return request.ArticleHeading;
}

There are also blockly blocks you can use to call server-side End Points and the Form Utils worker.

Workflow Activities

The process modeller includes two activities that can make requests to the API Server. The workflow ​Activities article has more information on each of them.

Which you decide to use is up to you. The API Server task can communicate directly with any worker, but you'll need script activities either side of it to set up the parameters of your call and to process the "raw" result you get back. The End Point task only calls End Points.

API Server Task

The API Server task can make a request to any worker. The properties let you set the worker to call, the method on the worker, and the name of a process variable that holds the relevant parameters. The result of the call is stored in the return variable, which can be given any suitable name.

End Point Task

The End Point task is similar to the API Server task, but has prompts to help you construct the request. The End Point you want to call can be chosen from a pop-up menu and the parameters object can be populated from the schema or test cases defined in the End Point itself.