Difference between revisions of "AJAX - API"

Revision as of 19:33, 18 October 2022

1 Overview

The BXP AJAX Javascript API provides a flexible and simple interface between bxp databases and any external page you would like to build or integrate into. This API can also be used on pages within a BXP system to access information for cross-campaign or reporting purposes.

This article will cover an overview of the functions available in the API as well as a detailed breakdown of the parameters they accept and what each does. We will also cover the necessary configuration required to ensure a database is accessible through the API.

All of the functionality that will be discussed can be viewed in the publicly available library via the link below.

https://ww3.allnone.ie/library/javascript/fn_javascript_ajax_newapi.js

Users are recommended to have a basic understanding of MySQL and Javascript before attempting to utilise this API.

2 Functions

The API contains the following functions.

fn_bxp_API_FormDataSearch( )

fn_bxp_API_FormDataInsertUpdate( )

fn_bxp_API_eCourseSearch ( )

fn_bxp_API_Generic_AccountSetup ()

fn_bxp_API_Generic_POST ()

The first three functions are the only functions required to utilize the API, the remaining two are utility functions which are used by the first three to carry out generic tasks, they do not need to be called directly.

2.1 fn_bxp_API_FormDataSearch( )

This function is used to query a database for records and store them a specified global variable for further processing.

This functions full header is:

function fn_bxp_API_FormDataSearch( blDisplayErrorText, strClientSystem, strAPI_Account, strAPI_Key, blAPI_DataX, intFormId, strReturnFields, strWhereClause, strGroupBy, strOrderBy, strLimit, strVariableToPopulate, strFunctionOnStart, strFunctionOnSuccess, strFunctionOnFail )

It takes the following parameters:

blDisplayErrorText: Toggles display of verbose error messages in the developer console, can be set to true or false.

strClientSystem: Name of the system you are accessing in BXP, takes a string in the format "client_X". Can be found by examining the URL of the system you are trying to interface with. For example, if the login URL for your BXP system is ww3.allnone.ie/client/client_exampleclient/main/login2.asp, your system name is "client_exampleclient". 

strAPI_Account: The ID of the account you wish to use to authenticate with BXP for this interaction, this must be an active account in the target system, and the account itself must be correctly configured(see system configuration section above.) Should be left blank if using dataX(see blAPI_DataX section below.)

strAPI_Key: The matching security key for the account supplied via strAPI_Account. Should be left blank if using dataX(see blAPI_DataX section below.)

blAPI_DataX: Can only be used on pages that are built in BXP, such as forms or custom reports. Can be set to true or false. If set to true, the API will attempt to authenticate with the server using the login credentials of whoever is currently logged into the system. strAPI_Account and strAPI_Key should be left blank if this is set to true.

intFormId: ID of the form/database you want to query.

strReturnFields: Fields that you wish to extract in your query results, takes a string in format "strCDA_X_field_0_Y,strCDA_X_field_0_Z", where X is the form ID and Y is the field ID. You can find a full list of fields for a form/database by opening the field mapping management for it.

strWhereClause: Where clause to filter your query results with, takes a string in the format of a MySQL where clause condition(the WHERE keyword itself should not be included.) For example, "intCDA_X_Id = 123" will return all records in form/database X where the record ID = 123. 

strGroupBy: Group by clause for the query. Takes a string in the format of a MySQL Group By clause(the GROUP BY keyword itself should not be included.)

strOrderBy: Order by clause for the query. Takes a string in the format of a MySQL Order By clause(the ORDER BY keyword itself should not be included.)

strLimit: Limit to apply to the query, will cap the number of results brought back by the query to the number supplied. Takes an integer value.

strVariableToPopulate: Variable in which the results of the query will be stored, takes a variable name as a string. Variable must be global(defined outside of any functions in your script).

strFunctionOnStart: Code that will execute when the AJAX query is launched, can be left blank. 

strFunctionOnSuccess: Code that will execute when the AJAX query returns with a successful result, should be used to launch whatever function will process the data after retrieval but can be left blank if desired.

strFunctionOnFail: Code that will execute when the AJAX query returns with an unsuccessful result, can be left blank.

Below is an example on how this function can be invoked.

strReturnFields = 'intCDA_7_Id,strCDA_7_field_0_1';

fn_bxp_API_FormDataSearch(true, 'client_example', , , true, 7,strReturnFields,'(strCDA_7_field_0_5 = ' + document.getElementById('intCDA_Id').value + ' AND strCDA_7_field_0_1 > NOW())',,'intCDA_7_Id',1000,'strApiRetrieveResult','console.log("API Retrieve Start")','fn_ADS_AfterRetrieveFutureBookings();','console.log("API Retrieve Fail")');