Users are recommended to have a basic understanding of MySQL and Javascript before attempting to utilise this API.
==Configuration==
====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 either 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.
====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 simply 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, you must use 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 authentic 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.
==Functions==
This functions 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 )
strReturnFields = '<span style="color: #00ccff;">intCDA_7_Id,strCDA_7_field_0_1</span>';
fn_bxp_API_FormDataSearch(true, '<span style="color: #ffcc00;">client_example</span>'<span style="color: #cc99ff;">, , , true</span>, <span style="color: #ff00ff;">7</span>,strReturnFields,'(<span style="color: #ff99cc;">strCDA_7_field_0_5 = ' + document.getElementById('searchField').value + ' AND strCDA_7_field_0_1 > NOW()</span>)','','intCDA_7_Id',<span style="color: #99ccff;">1000</span>,'<span style="color: #ff6600;">strApiRetrieveResult</span>','console.log("API Retrieve Start")','<span style="color: #00ff00339966;">fn_AfterRetrieveResults();</span>','<span style="color: #3366ff;">console.log("API Retrieve Fail")</span>');
In this example the API will attempt to query <span style="color: #ff00ff;">Form 7</span> from the <span style="color: #ffcc00;">client_example</span> system. <span style="color: #cc99ff;">The function will attempt to use the users current session to authenticate, the ID and Key fields are left blank as a result</span>.
The query will bring back the <span style="color: #00ccff;">record ID and value of field 1</span> for <span style="color: #99ccff;">up to 1000 results</span> <span style="color: #ff99cc;">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" </span>
<span style="color: #ff99cc;"><span style="color: #000000;">The results of the query will be stored in the global variable</span> <span style="color: #ff6600;">strApiRetrieveResult,<span style="color: #000000;"> and the function <span style="color: #00ff00;"><span style="color: #339966;">fn_AfterRetrieveResults() </span> </span>will run after a successful query result is returned, <span style="color: #3366ff;">otherwise, "API Retrieve Fail" will be printed to the console</span>.</span></span></span>
This functions function's full header is:
function fn_bxp_API_FormDataInsertUpdate( blDisplayErrorText, strClientSystem, strAPI_Account, strAPI_Key, blAPI_DataX, intFormId, strFieldAndValueListing, strVariableToPopulate, strFunctionOnStart, strFunctionOnSuccess, strFunctionOnFail )
Below is an example on how this function can be invoked.
strReturnFields strFieldsToUpdate = '<span style="color: #00ccffff99cc;">intCDA_7_Id,strCDA_7_field_0_1'</span>'; fn_bxp_API_FormDataSearch(true, '<span style="color: #ffcc0099ccff;">client_example&intCDA_161_Id=100</span><span style="color: #ff99cc;">&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 + '"' <span style="color: #cc99ff000000;">, , , truestrFieldsToInsert =</span>, <span style="color: #ff00ff993366;">7'</span>,strReturnFields,'(<span style="color: #ff99cc;">strCDA_7_field_0_5 <span style="color: #993366;">&strCDA_161_Status="Application form completed"&strCDA_161_field_0_0="' + document.getElementById('FieldA').value + '"&strCDA_161_field_0_1= "' + document.getElementById('searchFieldFieldB').value + ' AND strCDA_7_field_0_1 "&strCDA_161_field_0_12="' + document.getElementById('FieldC').value + '"&strCDA_161_field_0_13="' + document.getElementById('FieldD').value + '"'</span> NOW </span></span>fn_bxp_API_FormDataInsertUpdate()true, '<span style="color: #ffcc00;">client_example</span>)','<span style="color: #cc99ff;">API_Application_Form</span>','intCDA_7_Id<span style="color: #cc99ff;">__29dhtbfji__29dhtbfji__29dhtbfji</span>',<span style="color: #99ccffcc99ff;">false</span>, '<span style="color: #ff00ff;">1000161</span>', strFieldsToUpdate,'<span style="color: #ff6600ff0000;">strApiRetrieveResultstrApiUpdateResult</span>','console.log("\'API Retrieve Start"Insert start\')','<span style="color: #00ff00339966;">fn_AfterRetrieveResultsconsole.log(\'API Insert Success: \' + strApiInsertResult);fn_AfterSubmit();</span>','<span style="color: #3366ff;">console.log(\'API Update Fail: \' + strApiInsertResult)</span>'); In this example the API will attempt to update <span style="color: #ff00ff;">Form 161</span> from the <span style="color: #ffcc00;">client_example</span> system. <span style="color: #cc99ff;">The function will attempt to use the the ID and Key for API_Application_Form to authenticate</span>. <span style="color: #ff99cc;"><span style="color: #000000;">The update will</span> 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</span> <span style="color: #99ccff;">for record ID 100. <span style="color: #000000;">Alternatively, if the variable</span> <span style="color: #993366;">strFieldsToInsert</span> <span style="color: #000000;">were used instead of strFieldsToUpdate,</span> <span style="color: #993366;">a new record with the same values as above would be inserted into the form instead.</span></span> <span style="color: #ff99cc;"><span style="color: #000000;">The results of the update will be stored in the global variable</span><span style="color: #ff99cc;"> </span><span style="color: #ff6600;">strApiUpdateResult</span><span style="color: #ff6600;">, <span style="color: #339966;">"API Update Success will be printed to the console"</span><span style="color: #ff6600;"> </span><span style="color: #000000;">and the function <span style="color: #00ff00;"><span style="color: #339966;">fn_AfterSubmit()</span> </span>will run after a successful result is returned, <span style="color: #3366ff;">otherwise, "API Retrieve Update Fail")will be printed to the console</span>.</span></span></span> ====fn_bxp_API_eCourseSearch( )====This function is used to query BXP eCourses and store them a specified global variable for further processing. 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: '''<br class="Apple-interchange-newline">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''': ID of the ecourse you want to retrieve. '''strCountLimit: '''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 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.
In this example the API will attempt to query <span style="color: #ff00ff;">Form 7</span> from the <span style="color: #ffcc00;">client_example</span> system. <span style="color'''strFunctionOnStart: #cc99ff;">The function ''' Code that will attempt to use execute when the users current session to authenticateAJAX insert/update is launched, the ID and Key fields are can be left blank as a result</span>.
The query '''strFunctionOnSuccess:''' Code that will bring back the <span style="color: #00ccff;">record ID and value of field 1</span> for <span style="color: #99ccff;">up to 1000 results</span> <span style="color: #ff99cc;">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 execute when the page element "searchField" <AJAX insert/span>update succeeds, can be left blank.
<span style="color'''strFunctionOnFail: #ff99cc;"><span style="color: #000000;">The results of the query ''' Code that will be stored in execute when the global variable</span> <span style="color: #ff6600;">strApiRetrieveResult,<span style="color: #000000;"> and the function <span style="color: #00ff00;">fn_AfterRetrieveResults() <AJAX insert/span>will run after a successful query result is returnedupdate fails, <span style="color: #3366ff;">otherwise, "API Retrieve Fail" will can be printed to the console</span>left blank.</span></span></span>
