Bxp API

The bxp api is a way for 3rd party systems to interact directly with the bxp software platform (bxp).

The formal API documentation is publicly available from File:bxp API v6-0-3.pdf

Security Note: The bxp api will not grant access by default.  It requires EXPLICIT IP address declaration to grant any form of access or engage in any communication.  
The only exception to this rule is the IsAlive function which is globally accessible to see if the service is responsive.

The current version is 6-0-3.

1 Applications

1.1 Website Integrations

For websites bxp provides read and write ability that is controlled by the website. These facilities can be applied to provide:

• Custom account management
• Customer Relationship Management
• Membership management
• Event management
• Appointment management
• Payment processing solution recording and management
• List or publication management
• CPD (Continuing Professional Development) point management

1.2 Mobile and Tablet App Integrations

As with website integrations it is possible for a mobile / tablet app to interact with bxp but it must be through a centralised website interaction. i.e. the App does not come directly to bxp.

It is possible to design one of two types of app:

• A native / hybrid app
• A mobile web app

For reference further discussions on the topic can be found here:

• http://www.nngroup.com/articles/mobile-native-apps/
• http://thenextweb.com/dd/2014/02/08/decide-responsive-website-native-mobile-app/
• http://mobiledevices.about.com/od/additionalresources/a/Native-Apps-Vs-Web-Apps-Which-Is-The-Better-Choice.htm
• http://sixrevisions.com/mobile/native-app-vs-mobile-web-app-comparison/

The native app will work locally on the device and will not be required to interact with live data. Certain aspects of the interaction can be simple listings but this information should be public information. A native app will require communication with an intermediate communications application as direct contact between bxp and the app could not be easily IP address locked.

A portal app is a redirect to an app aware and enabled web page. This enabled website is what will communicate directly with bxp and control what functions the app will have access to.

1.3 Computer Telephony Integration (CTI)

There are many instances where the phone system has valuable information. The incoming call will have the line the call came in on (DNIS), the callers number (CLID), the agent / extension the call was delivered to ( agentid / ext ) and if the call goes through an IVR a number of other key pieces of information can be gathered before it even gets to the agent.

Often these solutions have the ability to open a web page and pass information via the querystring. For this reason the phone system may not be able to POST to bxp but can pass information via the querystring.

The most common function for this in the API is 7.3.5 Login + Data Management + Data Logging. This allows for a number of parameters to be passed in and the

https://ww3.allnone.ie/client/client_demo/cti/userCTI_GenericEntry.asp?system=datalogging&user_id=abc123&user_key=passkey&campaign_code=CODE_001&parameterA=passedDataA&parameterB=passedDataB

Each of the parameters can be read in and logged in specific fields. The form can then also be extended using AJAX to perform a LiveSearch to see if the customer has other cases or records in the system.

1.4 3rd Party Software Integration

It is also possible to integrate bxp into other applications. Using the same POST and querystring approach, bxp can be built into any SDK environment.

• ASP: demonstrated in the bxp api
• ASP.Net: http://msdn.microsoft.com/en-us/library/debx8sh9.aspx
• C: http://www.linuxquestions.org/questions/programming-9/how-can-i-post-data-with-post-method-in-c-programming-542700/
• C++: http://stackoverflow.com/questions/1011339/how-do-you-make-a-http-request-with-c
• C#: http://stackoverflow.com/questions/5401501/how-to-post-data-to-specific-url-using-webclient-in-c-sharp
• Java: http://stackoverflow.com/questions/4205980/java-sending-http-parameters-via-post-method-easily
• Objective C: http://stackoverflow.com/questions/15749486/sending-an-http-post-request-on-ios
• PHP: demonstrated in the bxp api

2 Setup

2.1 Basics

All interactions are done with bxp through HTTPS Posts. Information is passed to bxp through a data "post" or the querystring parameters, depending on the sensitivity and capability of the calling 3rd party application.

The standard "User Interface" is what most agents and direct users will interact with. The interactions will be through a web address similar to https://ww3.allnone.ie/client/client_X/main/login.asp where X is change to the name of the bxp Client.

It is possible for 3rd party solutions to interact with the API which is a completely different and programmatic interface.

2.2 External Access Setup overview

The detailed setup on how to do this is explicitly detailed in the bxp api document.

The summary is:

1. Create a user but give the user no functional access to bxp
2. Apply IP address restrictions to the account, so it can only be used from controlled environments
3. Grant the user explicit access to the secure form data
4. Explicitly allow the form data to be externally accessible
5. From here the user account should be able to perform functions such as read or write to the data

2.3 Read and write functionality

There are many functions within the API but the most used are "formlogging" and "datasearch".

2.3.1 FormLogging

FormLogging is the process by which data is inserted into the secure data form.

This is detailed in function 7.4.4 Website – Data Logging of the bxp api

//=========================================================
//Data Setup
//=========================================================
$url = 'https://ww3.allnone.ie/client/client_demo/cti/userCTI_GenericEntry.asp';
//set the extrac POST variables required
$fields = array(
	'user_id' 			=> urlencode('testing'),
	'user_key' 			=> urlencode('testing'),
	'system' 			=> urlencode('formlogging'),
	'campaignid' 			=> urlencode('56')
);
//url-ify the data for the POST
foreach($fields as $key=>$value) { $fields_string .= $key.'='.$value.'&'; }

//extract data from the post
foreach($_POST as $key => $value) {
	$fields_string .= $key.'='.urlencode($value).'&';
} 
rtrim($fields_string,'&');
//=========================================================
//Process Data
//=========================================================
//open connection and set the url, number of POST vars, POST data, execute post
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,		$url		);
curl_setopt($ch, CURLOPT_POST,		1		);
curl_setopt($ch, CURLOPT_POSTFIELDS,	$fields_string	);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 	1		);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,	1		); 
$result = curl_exec($ch);
curl_close($ch);

Key Parameters

• Line 5: The BE URL which will process the request. Client_demo should be replaced with the name of your system
• Line 9: user_id is the username of the account with permission to access the form as set up in steps 2.7 and 2.8 of this document
• Line 10: user_key is the password of the account with permission to access the form as set up in steps 2.7 and 2.8 of this document
• Line 11: system is the function to be used, in this case formlogging
• Line 12: campaignid is the Id of the form to be accessed. This Id is available from Main Menu > Data Profiling > Instant – Dashboards > Dashboard – System Information.

2.3.2 DataSearch

DataSearch is the process which allows the 3rd Party app to search on any field with any data to get back any form of data.

This is detailed in function 7.4.3 Website – Data Query of the bxp api

//=========================================================
//Data Setup
//=========================================================
//set POST variables
extract($_POST);
$url = 'https://ww3.allnone.ie/client/client_demo/cti/userCTI_GenericEntry.asp';
$fields = array(
	'user_id' 		              => urlencode('testing'),
	'user_key' 		              => urlencode('testing'),
	'system' 		              => urlencode('datasearch'),
	'campaignid' 		              => urlencode('56'),
	'searchfield' 		              => urlencode('intCDA_56_Id'),
	'value' 		              => urlencode('1'),
        'strMatchingOptions'                  => urlencode('Bool'),
	'responsefields'	              => urlencode('strCDA_56_field_1_5,strCDA_56_field_3_5')
);

//url-ify the data for the POST
foreach($fields as $key=>$value) { $fields_string .= $key.'='.$value.'&'; }
rtrim($fields_string,'&');
//=========================================================
//Process Data
//=========================================================
//open connection
$ch = curl_init();
//set the url, number of POST vars, POST data
curl_setopt($ch, CURLOPT_URL,			$url				);
curl_setopt($ch, CURLOPT_POST,		1				);
curl_setopt($ch, CURLOPT_POSTFIELDS,		$fields_string			);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 	1				);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,	1				); 
//execute post
$result = curl_exec($ch);
//close connection
curl_close($ch);
//=========================================================
//Handling xml data
//=========================================================
if (strpos($result,'xml version="')) {
	$data = new SimpleXMLElement($result); 
	echo $data->getName() . "<br />";
	foreach($data->children() as $child) {
	  echo $child->getName() . ": " . $child . "<br />";
	}
}
else {
	echo $result;
}

Key Parameters

• Line 7: The BE URL which will process the request Client_demo should be replaced with the name of your system
• Line 12: user_id is the username of the account with permission to access the form as set up in steps 2.7 and 2.8 of this document
• Line 13: user_key is the password of the account with permission to access the form as set up in steps 2.7 and 2.8 of this document
• Line 14: strMatchingOptions is the type of value matching you wish to use, the following are the allowed types Exact matching, Like Matching and Boolean Matching. To use Exact Matching enter "Exact", to use Like Matching enter "Like" and to use Boolean Matching enter "Bool"
• Line 15: system is the function to be used, in this case datasearch
• Line 16: campaignid is the Id of the form to be accessed. This Id is available from Main Menu > Data Profiilng> Instant - Dashboards > Form – Profile.
• Line 17: searchfield is the field to be listed against
• Line 18: value is the value to be listed against.
• Line 19: responsefields are the fields from the form that will be returned in the data file. The responsefields are separated by commas using fields from the Field Mapping list.

Notes

If you require to use the comma character in your search value you will be required to replace all comma's in your search value with the following [ [ [ [Comma]]]]

3 Conclusion

The bxp api make bxp software extremely accessible. The All n One development team are very comfortable in dealing with all your queries and providing potential solutions. If you prefer to use us we'll be happy to quote for whatever work you need. Please get in touch with us today to see how we can help you.