Scenario - bxp as a secure Website Data Store
From All n One's bxp software Wixi
1 Overview
bxp software (bxp) has the ability to act as a secure data store for numerous website and mobile applications. The setup and management of a data store is very straight forward but requires some background and understanding of the how and what is to be done. This scenario provides a step by step, mirroring the contents of the bxp api Bxp_API but providing a worked scenario.
There are a number of advantages to using bxp as a secure data store. The most important being security. The backup, availability, audit-ability and structured approach to data management means that focus can return to development and away from the security of data management.
2 Elements
The first part of the solution is setting up the data store in bxp. Data stores are referred to as forms. A form is a collection of tables. The two primary tables are the CDA table and the CCL table.
The first and single unit is a Record, a CDA (Campaign DAta). This is usually based on a Noun, a person, place or thing. This can be likened to a row of data in an Excel spreadsheet.
Every contact with a Record is called a Contact, a CCL (Campaign CaLl). This is a record of the interaction with the CDA.
Build and managing a form is done through the front end of bxp. Understanding the front end and building and managing forms are discussed in our training documentation. Contact_Centre_Training CC-1-1 Introduction to bxp software and CC-1-3 Introduction to Blended Form Structure.
Using the front end of bxp we now have a from set up and ready to be accessed.
There is then an external website or service which needs to interact with bxp. This is traditionally a website or web service. This external service will communicate with bxp through the bxp api. The bxp api allows for restful calls to be made with XML responses.
A dedicated user account is required in bxp, which is then configured to allow access to a form.
With access granted that user account can read and write data to the form.
3 bxp setup
3.1 User Setup
As per section 3.1 of the bxp api
Each user account that will be automatically logged in must have their External Id and External Key fields set. For Website Integration a user account is selected, as there is no differentiation between unique users when used on an external website.
A user must be selected against whom to log the records and perform searches. This is done using the System Access Management module inside bxp software. On every users account is an External System Id and External System Key field. Here the username and password used for external logging in is entered.
Main Menu > System Access Management > User Administration > Add User - Security Details Only > Primary Security Details
The IP address that the user / automated server may access from must also be set. This allocation can be done individually or as a group.
Individually, can be seen as above by placing the IP address in the IP Range box as a single IP or separated by commas.
Alternately as a group
Main Menu > System Access Management > System Management > Group User - Modify Details > Click "Lookup User" to include all users >
Select all the users you want to change, scroll to the bottom and click "Continue"
The user will also need appropriate permission to access the form. This is done using
Main Menu > System Access Management > Security - Contact Access > Form - Single Add User by Form
There are other functions available in this section to speed up group allocation of access.
3.2 Understanding the Form Structure
As per 3.2 in the bxp api
Some understanding of bxp form structures is required in order to use the interface correctly when working with Forms.
Forms can only be created using the bxp interface and each form has an id number, incrementally starting from 1, for each client system. Each form in bxp uses a number of tables to record data and the key table is the data table. Table field names are created automatically and cannot be changed.
In the bxp interface, ‘Field Mapping’ is the process of creating user friendly field names, e.g. Firstname instead of strCDA_1_field_1_1, which make the system easier to use. The API requires a programmer to use the actual table names.
When a form is built, a table called CDA_X (where X is the id of the form) is also created. Using the function calls detailed in section 3 of this document, each of the fields in the table can be seen. The demo form used in all these examples has the following layout
- ‘intCDA_X_Id’ is the internal id record for every data record added to the system. This id number is created by bxp.
- ‘strCDA_X_’ is a non displayed field that can be used for storing numeric or alphanumeric ids from other systems.
Since each form is different, the phone number field could have any name. However in the example used, strCDA_1_field_1_5 is the work phone number field. The system will perform a lookup on a field or a combination of fields, and convert the passed parameters to the CDA_Id. If more than one field is matched the system defaults to the lowest Id. With this in mind it is important that unique field combinations are used in the lookup.
To get the current form structure use:
https://ww3.allnone.ie/client/client_demo/cti/userCTI_CampaignStructure.asp?user_id=abc123&user_key=passkey&ID=1
You will need to set up the user as above to get your user_id and user_key. The Id is the internal Id of the form which is available when you build the form inside bxp.
3.3 Form setup for Website Integration
As per 3.3. in the bxp api
For a form to be accessible externally it must be made available externally as well as being in-date and active. These options are available in Form Management. The ‘Externally Available’ option only applies for functionality where bxp is used with external website integration.
If bxp is being used for systems integration this option does not need to be set since, as the user is logged into the bxp system, data does not leave bxp.
For the form to be externally available:
Main Menu > Form Management > Form - Primary Management > Form - Advanced Settings > Select your form > External
The ‘Externally Available’ must be set to ‘Public’, as it will default to ‘Private’.
The default ‘Public Outcome’ must also be set.
4 External Setup
So now we want to be able to write some data into the form and read some data from the form.
4.1 Write some data
When writing data there are two primary operations. Create a record and Update a record. bxp uses a simple system, IF the Id is set, it is an update. If the ID is not set, then a new record will be created.
The Id field is intCDA_X_Id. The function is called the formlogging.
So to write to a form, we use the material as per 7.4.4 Website – Data Logging
<?php
//=========================================================
//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);
//=========================================================
//Result management
//=========================================================
if (strpos($result,'record>-1<')) {
$strMessage = 'Sorry but that is an incorrect username or password for logging this record.<br />Please contact the site Administrator';
} elseif (strpos($result,'record>-2<')) {
$strMessage = 'Sorry but that is an incorrect IP address to log from that account.<br />Please contact the site Administrator';
} elseif (strpos($result,'record>-3<')) {
$strMessage = 'Sorry but that form is not available to the public for storing data in.<br />Please contact the site Administrator';
} elseif (strpos($result,'record>-4<')) {
$strMessage = 'Sorry but that form has not been built properly.<br />Please contact the site Administrator';
} elseif (strpos($result,'record>-5<')) {
$strMessage = 'Sorry but that form is not active.<br />Please contact the site Administrator';
} elseif (strpos($result,'record>-6<')) {
$strMessage = 'Sorry but that user cannot log data in that form.<br />Please contact the site Administrator';
} elseif (strpos($result,'record>-7<')) {
$strMessage = 'Sorry but no public outcome has been set to process that record.<br />Please contact the site Administrator';
} elseif (strpos($result,'record>0<')) {
$strMessage = 'Sorry but no Id was returned.<br />Please contact the site Administrator';
} else {
$result = str_replace("<?xml version=\"1.0\" encoding=\"UTF-8\"?>", "", $result);
$result = str_replace("\n", "", $result);
$result = str_replace("<record>", "", $result);
$result = str_replace("</record>", "", $result);
$strMessage = "The record has been logged with an Id of ".$result.".";
}
echo $strMessage;
?>
4.2 Read some data
So to read from a form, we use the material as per 7.4.3 Website – Data Query
This example looks up where the Id of the CDA record is 1 in form 56, retrieving fields strCDA_56_field_1_5 and strCDA_56_field_3_5.
<?php
//=========================================================
//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'),
'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;
}
?>
5 Login management
Creating and managing user accounts is a relatively easy exercise. There are many options available, however here is pseudocode to approaching how it might be done
Here is a flow of the process.
5.1 Session management
For a user, we want them to log into an account, so we can build up useful services for them. These services could be membership of a club or could accounts in a system. We describe the solution in terms of a public site and its pages.
5.1.1 Page 1 Log in
On this page we provide a username and password box. We also provide a link to a "Create an account" link.
This page submits the values to page 2.
The page also checks for a query string parameter to see if a log in failed. If it does, then supply help info on screen.
5.1.2 Page 2 Log in process
This reads the username and password from the form.
We perform a data look up using the "read" function above.
- If a match is found, i.e. the read function returns an Id > 0 then we have a user
- If no match is found, then we have a new account or failed login.
- On a fail, we check again, just for the username. If username found, we can provide extra feedback to Page 1, so to why log in failed.
- On not finding that username, we can go to Page 1 or to Page 3 - new user account.
On a match however.
- We create a random string.
- We data store this random string with this user id (this is a session string).
- We set the secure cookie key in the users browser to the id and a second key to the session string
- We move to Page 5 - Normal operating page.
5.1.3 Page 3 New user account
On this page we take all the details we want for a user account.
We submit these details to page 4.
We check the querystring for parameters indicating that the new user setup process has failed and provide relevant feedback
5.1.4 Page 4 New account process
- We read the form values
- We perform a lookup on the primary username to make sure it doesn't already exist
- If a new user, we use the write funtion and bxp will return a new user id
- If an existing user, bounce back to page 3, passing querystring feedback on why the setup failed.
- We create a random string.
- We data store this random string with this user id (this is a session string).
- We set the secure cookie key in the users browser to the id and a second key to the session string
- We move to Page 5
5.1.5 Page 5 Normal operating pages
- We retrieve from the session cookie the user id and session string.
- We lookup that id and session string to make sure they match
- If match found, draw the page
- If no match found, redirect back to the login page.
