Difference between revisions of "AJAX - API"

Latest revision as of 16:06, 20 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 Configuration

2.1 Form Configuration

When attempting to utilize this library you will need to first configure the from or forms you intend to try and interact with to ensure they are publicly accessible. To do this you will need to have Form Edit permissions for the target BXP system, as well as access to the specific form(s) you wish to use. If you do not have these permissions, ask a system administrator for assistance with this task.

Open the Advanced Settings for the form(s) you need to interact with through the API and select the External tab. Here you will find the settings for Externally Available and Public Outcome.

Externally Available controls whether a form/database is available for use through the API. By default all newly created forms have this set to Private and are not accessible outside of BXP, this value must be set to Public in order for any API calls against this form to be successful.

Public Outcome sets the default outcome to be used when a record is submitted through the API. This can be overwritten by manually specifying an outcome in your insert/update function call.

2.2 User Account Configuration

If you are attempting to use this library on a page built inside of BXP(such as keystat or form) you can use the DataX option when executing an API call to authenticate using the current users login credentials.

If however you are using the API from a page external to BXP or if you want all of your interactions to be performed by a specific user account, you must supply the security credentials for a valid, active account in the target BXP system. By default BXP user accounts do not have external security credentials defined, so they may need to be set up for the account you wish to use. As with form configuration, you will need to either have User Account Edit permissions in BXP, or request that an admin for the target system assist you.

To check the security credentials for a BXP account, open the account for editing and then open the Primary Security Details tab. Both the External System ID and External System Key fields must be set in order for the account to be able to authenticate through the API.

External System ID: Must be set and must be unique to each user account.

External System Key: Must be set. We strongly advise using a secure, generated key with both uppercase, lowercase and numerical characters.

2.3 Form Access Permissions

Whether authenticating using the the current BXP user's session or by supplying a specific accounts security credentials, the API will reject any attempts to query or update a Form if the user account being used does not have access permissions to it.

See our article on form access for more information on how to manage form access permissions for user accounts. As with form configuration, you will need both Form Edit permissions for the target BXP system as well as access to the specific form(s) you wish to use. Otherwise, request assistance from an administrator of the target BXP system.

3 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.

3.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 function's 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('searchField').value + ' AND strCDA_7_field_0_1 > NOW())',,'intCDA_7_Id',1000,'strApiRetrieveResult','console.log("API Retrieve Start")','fn_AfterRetrieveResults();','console.log("API Retrieve Fail")');

In this example the API will attempt to query Form 7 from the client_example system. The function will attempt to use the users current session to authenticate, the ID and Key fields are left blank as a result.

The query will bring back the record ID and value of field 1 for up to 1000 results where the date stored in field 1 is some time beyond the present date and the value stored in field 5 matches the value of the page element "searchField" 

The results of the query will be stored in the global variable strApiRetrieveResult, and the function fn_AfterRetrieveResults() will run after a successful query result is returned, otherwise, "API Retrieve Fail" will be printed to the console.

3.2 fn_bxp_API_FormDataInsertUpdate( )

This function is used to either insert a record into a database or update an existing record/records with new data.

This function's full header is:

function fn_bxp_API_FormDataInsertUpdate( blDisplayErrorText, strClientSystem, strAPI_Account, strAPI_Key, blAPI_DataX, intFormId, strFieldAndValueListing, 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 insert into/update.

strFieldAndValueListing: A list of all fields in the form you want to update and the values you want to assign to them.

Takes a string in either of the following formats, depending on whether the user wants to enter a new record, or update an existing one. If a value for the record ID is specified, the API will attempt to update the record corresponding to that ID, otherwise it will insert a new record instead.

Insert

'&strCDA_X_Status="Example Status"&strCDA_X_field_0_Y="Example Value"'

Update

'&intCDA_X_Id=1&strCDA_X_Status="Example Status"&strCDA_X_field_0_Y="Example Value"' 

strVariableToPopulate: Variable in which the results of the update will be stored, takes a variable name as a string. Variable must be global(defined outside of any functions in your script). If attempting to insert a new record, this will return the ID of the new record if the insert was successful, otherwise it will return 0 or a negative value.

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

strFunctionOnSuccess: Code that will execute when the AJAX insert/update succeeds, can be left blank.

strFunctionOnFail: Code that will execute when the AJAX insert/update fails, can be left blank.

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

strFieldsToUpdate = '&intCDA_161_Id=100&strCDA_161_Status="Application form completed"&strCDA_161_field_0_0="' + document.getElementById('FieldA').value + '"&strCDA_161_field_0_1="' + document.getElementById('FieldB').value + '"&strCDA_161_field_0_12="' + document.getElementById('FieldC').value + '"&strCDA_161_field_0_13="' + document.getElementById('FieldD').value + '"'
strFieldsToInsert = '&strCDA_161_Status="Application form completed"&strCDA_161_field_0_0="' + document.getElementById('FieldA').value + '"&strCDA_161_field_0_1="' + document.getElementById('FieldB').value + '"&strCDA_161_field_0_12="' + document.getElementById('FieldC').value + '"&strCDA_161_field_0_13="' + document.getElementById('FieldD').value + '"'
fn_bxp_API_FormDataInsertUpdate(true, 'client_example', 'API_Example', '__123456789!!', false, '161', strFieldsToUpdate, 'strApiUpdateResult', 'console.log(\'API Insert start\')', 'console.log(\'API Insert Success: \' + strApiInsertResult);fn_AfterSubmit();', 'console.log(\'API Update Fail: \' + strApiInsertResult)');

In this example the API will attempt to update Form 161 from the client_example system. The function will attempt to use the the ID and Key for API_Example to authenticate.

The update will set the Status to "Application form completed" and the values of fields 0,1,12 and 13 to the values of page elements FieldA through FieldD respectively for record ID 100. Alternatively, if the variable strFieldsToInsert were used instead of strFieldsToUpdate, a new record with the same values as above would be inserted into the form instead.

The results of the update will be stored in the global variable strApiUpdateResult, "API Update Success will be printed to the console" and the function fn_AfterSubmit() will run after a successful result is returned, otherwise, "API Update Fail" will be printed to the console.

3.3 fn_bxp_API_eCourseSearch( )

This function is used to query BXP eCourse books for a list of their pages. URLs to each page are returned in the result as opposed to the actual page content itself.

This function's full header is:

function fn_bxp_API_eCourseSearch( blDisplayErrorText, strClientSystem, strAPI_Account, strAPI_Key, blAPI_DataX, strSearchValue, inteCourse_Ids, strCountLimit, 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.

inteCourse_Ids: IDs of the eCourse books you want to retrieve pages from. Takes a string in the form of comma separated whole numbers. For example, "1,12,15" will return all pages from the eCourse Books with IDs 1, 12 and 15(provided the total number of pages does not exceed strCountLimit). 

strCountLimit: Limit to apply to the query, will cap the number of pages retrieved. Takes an integer value. For example, if we are retrieving pages from books 1,12 and 15 as in the example above, but we have a cap of 10, only the first 10 pages will be returned. This is for the overall query and not per book, meaning that if book 1 has 9 pages, book 12 has 1 and book 15 has 3, we will receive all pages from books 1 and 12, but none from 15. 

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 insert/update is launched, can be left blank. 

strFunctionOnSuccess: Code that will execute when the AJAX insert/update succeeds, can be left blank.

strFunctionOnFail: Code that will execute when the AJAX insert/update fails, can be left blank.

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

strBookIds = '1,12,15';

fn_bxp_API_eCourseSearch(true, 'client_example', , , true, strBookIds,500,'strApiRetrieveResult','console.log("API Retrieve Start")','fn_AfterRetrieveResults();','console.log("API Retrieve Fail")');

In this example the API will attempt to query links to the pages from eCourse Books 1, 12 and 15 from the client_example system. Up to 500 pages will be retrieved. The function will attempt to use the users current session to authenticate, the ID and Key fields are left blank as a result.

The results of the query will be stored in the global variable strApiRetrieveResult, and the function fn_AfterRetrieveResults() will run after a successful query result is returned, otherwise, "API Retrieve Fail" will be printed to the console.