FormbirdAjax2

Updated pdexter 2026-05-19

FormbirdAjax2 is an object/class which provides wrapper functions for connecting to third party webservices, or to Formbird's own (component) webservices.

As of May 2026, this functionality can be used in clientside rulesets for accessing Formbird's webservices.

To use

Be sure that the ruleset include document "Formbird Serverside Ajax" is installed on your environment.

Insert the following line at the top of your ruleset

#include "Formbird Serverside Ajax",

If this is not available, look for the package "Formbird Ruleset Includes" on My Metadata Releases Listing and install to your environment.

NB: The "Serverside" part of the name is now incorrect, but for backward compatibility with code already using this include, we are keeping the name as is.

A future version may separate out the new functions into a ruleset include simply called "Formbird Ajax"

callAxios

This may be called to access third party webservices, which return a JSON result.

For other datatypes, it will be necessary to resort to native usage of Axios.

This wrapper function is probationary; it may be simpler to just use Axios directly in script. However it does handle error conditions without need to try ... catch.

Syntax

var result = ft3.FormbirdAjax2.callAxios(ntf, options)

Example Usage

const options = { 
    method: 'GET',
    url : 'https://www.widgetco.com/api/getWidgetDetails',
    headers: { 'Content-Type': 'application/json; charset=utf-8', apiKey : apiKey },
    data: {
        targetId : 'WGT-45051333'
    }
};

var widgetJSON = ft3.FormbirdAjax2.callAxios(ntf, options) ;

if (widgetJSON.error) {
    ntf.logger.info('Error on webservice call - ' + widgetJSON.error.message);
}

callFBWebservice

This is a wrapper function to facilitate calling a Formbird (component) Webservice.

This function expects a JSON result to be returned. For other datatypes, it will be necessary to resort to native usage of Axios, or windows.fetch.

Syntax

var result = await ft3.FormbirdAjax2.callFBWebservice(ntf, requestJSON );

requestJSON

Example Server Usage

Applies to server event rulesets, eg PreSaveServer

Note : server side usage requires that an apiKey be submitted with the request.

#include "Formbird Serverside Ajax",
...

    const apiKey = '85247679-e039-7a86-4298-c761509a760b';
    const huntsmanId = '844451b0-f906-11e8-9e2b-7fba267621b0';

    // Prevent self edit
    if (ntf.document.documentId === huntsmanId) {
        return;
    }

    const requestJson = { 
        apiKey : apiKey,
        componentWebServiceName : "ws-document-service",
        functionName : "updateDocument",
        functionParameters: {
            "userDocumentId": ntf.user.documentId,
            "documentId": huntsmanId,
            "change": { description : 'updated by ws - 2026-05-18' }
        }
    };

    ntf.logger.info(`requestJson: ${JSON.stringify(requestJson)}`);

    var res = await ft3.FormbirdAjax2.callFBWebservice(ntf, requestJson);

    ntf.logger.info('After webservice');
    ntf.logger.info(`Result: \n${JSON.stringify(res, null, 2)}`);

Example Client Usage

Applies to client event rulesets, eg OnFieldChange

#include "Formbird Serverside Ajax",
...

    const requestJson = { 
        componentWebServiceName : "ws-document-service",
        functionName : "updateDocument",
        functionParameters: {
            "userDocumentId": ntf.user.documentId,
            "documentId": 'a60c3dc8-8870-67b7-438c-b76d9fd824e8',
            "change": { 
                description : 'updated by ws - 2026-05-18'
            }
        }
    };

    ntf.logger.info(`requestJson: ${JSON.stringify(requestJson)}`);

    var res = await ft3.FormbirdAjax2.callFBWebservice(ntf, requestJson);

    ntf.logger.info('After webservice');
    ntf.logger.info(`Result: \n${JSON.stringify(res, null, 2)}`);

Handling Error Conditions

If an error occurs as a result of the Ajax call itself, the result returned may contain "error", being the error object.

If the result contains statusCode of 401, this may be due to an invalid apiKey being sent.

If the result contains statusCode of 500, it could be due to a misnamed webservice or function name.

    var res = await ft3.FormbirdAjax2.callFBWebservice(ntf, requestJson);

    ntf.logger.info('After webservice');
    ntf.logger.info(`Result: \n${JSON.stringify(res, null, 2)}`);

    if (!res) {
        ntf.logger.error('No response from Webservice call.');
    }
    else if (res.error) {
        ntf.logger.error('Error occurred during Webservice call - ' + res.error.message);
    }
    else  {
        ntf.logger.info('All good ok !!!'); 
    }