Form Message

In your form designs you'll often need to request data from other parts of the platform, or from third party services. To keep those integrations secured, they will generally only be available to server-side actions in your form, for example in field default functions when a page loads, or script actions when a page is submitted.

This field can be invoked browser-side, after the form has rendered, and securely perform requests to server-side functions. That allows you to access data and perform actions that would otherwise require a page refresh.

Request Function

When the field is invoked, this function takes the parameters passed to the field, allows you to update them, then makes a secure request, returning the response to the response function. As it is executed server-side, you are able to access variables etc that are not present on the browser.

For example, this function calls an end point deployed to the server library. The parameters are passed to it by the field invoking this message field (see making a request below).

function(helper, params) {
    let updatedParams = helper.utilServerAPIServerCall('serverlibrary', 'tim.icmapi.CSObject_get', params);
    return updatedParams;
}

Similarly the function itself could be fairly agnostic, and have the end point to call passed to it:

function(helper, params) {
    let updatedParams = helper.utilServerAPIServerCall('serverlibrary', params.endPoint, params.params);
    return updatedParams;
}

Making a Request

Requests are made by invoking the field's custom function makeRequest using .invokeCustomFieldFn.

In the first example above, the end point expects a parameter called "label". In a script button (or similarly in the handler of another field) you could do something like this to fetch the value of a field, pass it to the message field, which will then securely call the end point:

function(helper) {
    helper.invokeCustomFieldFn('CALLEP', 'makeRequest', {
        label: helper.getFieldValue('TEXTINPUT')
    });
}

Or in a field handler calling the second example above:

function(helper, fieldName, value, valid, eventName) {
    if (eventName == 'CHANGE' && valid) {
        helper.invokeCustomFieldFn('CALLEP', 'makeRequest', {
            endPoint: "tim.icmapi.CSObject_get",
            params: {
                label: "123456"
            }
        });
    }
}

Response Function

The response function is optional - you may want to use the message field to pass data to something server-side without a response.

This example shows how to save the response as a form variable. The value is the response from the request function:

Properties