Browser Typedown 1. Introduction This guide is intended to walk a Developer or Project Manager through the process of integrating the Browser Typedown implementation of QAS Pro Web into their browser-based application. It does not seek to provide low-level information about the underlying APIs or Web Services used. Details of extra resources can be found in Appendix A Further Reading 2. What is Browser Typedown? Browser Typedown utilizes the QAS Pro Web Typedown Engine to interactively guide users through validating address information. Potential errors are highlighted as the address is typed, reducing the time it takes to capture an address. It is intended for use in high volume environments such as call-centers. Implementation times are quick due to the simple nature of the integration. Below are four screenshots of a typical user experience with the implementation. When the user clicks the Accept button, as shown in Fig 4, the Browser Typedown window populates into the address fields in the target application. Details of the architecture and actual integration are outlined later in this document. Fig 1. User entering Zip Code Fig 2.User has entered street and reviews available building numbers Fig 3. User enters building number Fig 4. User selects final address QAS Pro Web Browser Typedown GSG North America.doc Page 1 of 10
3. Implementation Overview and Expected Timescales The following steps cover a typical implementation steps and expected timescales of QAS Pro Web. 1. Install QAS Pro Web (1 hour) 2. Integrate sample code into a single address touch point* (1 day) 3. Test and review with project stakeholders (1 day) 4. Replicate across remaining address touch points (0.5 days per touch point) 5. Deploy to production environment (2 hours) *In order to make use of the technology a set of pages must be hosted on the same site as the target application. The estimate of one day assumes a skilled developer who understands the related technologies and modifying the target application. 4. Implementation Architecture QAS Pro Web Service/Daemon QAS Pro Web can be installed as a locally hosted Web Service on most major releases of Windows, UNIX and Linux. The application includes a built-in HTTP listener so can run standalone from a Web Server. SOAP/XML Browser Typedown pages Invoked via JavaScript Browser 0 based application or website Postal Database Reference postal data is made available on CDs or via FTP download every two months by default. It takes up approximately 1GB of storage for USA and 80MB for Canada. Reference postal data is installed to the local file system alongside QAS Pro Web. No third-party database tools are required to host the data and Live Data Updates allow the data updates to be applied without any website downtime. QAS Pro Web is also available in a Software as a Service (SaaS) model through Experian, QAS On Demand platform. NOTE: On Demand implementations are currently limited to the PHP 5, C#.NET and JSP languages. QAS Pro Web Browser Typedown GSG North America.doc Page 2 of 10
5. Installation Overview The installation of QAS Pro Web should take up to one hour on average. Full step by step instructions are included in the file webinst.pdf available in the Docs directory on the QAS Pro Web installation image. Windows installation instructions start on page 30 of the PDF page count and for UNIX/Linux on page 45 of the PDF page count In order to complete the installation you will need the following: - QAS Pro Web installation image (available via FTP at ftp://ftp.usa.qas.com/product)* - Postal data installation image(s) (available via FTP at ftp://ftp.usa.qas.com/data)* - QAS Pro Web License Key(s) (available from your Customer Account Manager) - A machine with ample disk space (1.1GB for USA data, 100MB for Canada) - A user account with at least local administrator privileges on the target installation machine *NOTE: All zip files on the FTP site are protected with a weekly refreshed password available from you Customer Account Manager or Technical Solutions Consultant. Alternative CD images are also available. Things to Remember - Make a note of where you set the sample code to install to. This is required later on. - WINDOWS ONLY: When the installer has completed, it is necessary to activate the new data using the Administrator Console for Windows installations. This tool is available through Start, Programs, QAS Pro Web 5.xx, Administrator Console. The data Updating section can be found under the Current Data option in the left hand pane. Select the Data set to be activated and click Update Data. This will make the data available to QAS Pro Web. QAS Pro Web Browser Typedown GSG North America.doc Page 3 of 10
6. Coding Overview This section outlines the coding changes necessary to implement the QAS Pro Web integration code into your site. Knowledge of your website s language, HTML and JavaScript is assumed. 6.1 Make sure you have the correct sample code The Browser Typedown sample code is optionally installed as part of the standard installation of QAS Pro Web. The code is also available on the QAS Pro Web product image. Each language has its own directory stored under the Program directory. i.e. Samples.ASP, Samples.JSP. Browser Typedown sample code is available for PHP5, C#.NET, VB.NET, Classic ASP and JSP NOTE: The Browser Typedown sample code must be installed under the same website as the pages invoking it. If not, address information will be prevented from being returned to the pages by JavaScript s cross browser scripting security measures. 6.2 Configure the format of the returned address The format of the returned address is controlled via a configuration file called QAWSERVE.INI. This file can be found within the installed image (default directory: C:\Program Files\QAS\QAS Pro Web ). The QAWSERVE.INI configuration file is split into separate sections called layouts. The Windows based Configuration Editor, available at Start, Programs, QAS Pro Web, Configuration Editor, should be used to modify these Layouts. A simple layout that covers the majority of formatting needs has been created for you called Database layout. The Database layout format is as follows: Field name Max width Capitalized Address Line 1 60 characters Title Case Address Line 1 60 characters Title Case Address Line 1 60 characters Title Case City 60 characters Title Case State 60 characters Yes Zip, +4 Code 60 characters N/A Country 60 characters Yes NOTE: All Address line information is automatically populated across the address line fields according the United States Postal Service or Canada Post standards. Street and Secondary number descriptors like Road or Apartment are abbreviated by default. QAS Pro Web Browser Typedown GSG North America.doc Page 4 of 10
Once you have configured the desired format of the returned address the Layout name needs to be specified within the Browser Typedown code. This is achieved by setting a variable in the relevant Browser Typedown configuration file. To determine the correct file and variable name to edit please refer to the table below: Language Browser Typedown configuration file name Variable containing layout name Classic ASP Constants.asp CONTROL_LAYOUT JSP WEB-INF\Web.xml QasLayout PHP 5 Constants.inc CONTROL_LAYOUT VB.NET / C#.NET Web.config com.qas.proweb.layout 6.3 Configure the location of QAS Pro Web in the Browser Typedown pages In order for address lookups to be successful it is necessary for the Browser Typedown pages to know where QAS Pro Web application is located on the network. If both the Browser Typedown pages and QAS Pro Web are installed on the same machine the default location of http://localhost:2021/ can be used. If you wish to use QAS Pro Web with applications installed across multiple web servers use the table below to determine the correct file and variable name to update: Language Browser Typedown configuration file name Variable containing location of QAS Pro Web Classic ASP Constants.asp CONTROL_WSDL_URN JSP WEB-INF\Web.xml QasEndpoint PHP 5 Constants.inc CONTROL_WSDL_URN VB.NET / C#.NET Web.config com.qas.proweb.serverurl NOTE: The Web Service must be accessible from the machine where the Browser Typedown pages are installed. To test this connectivity open a web browser on the machine where the Browser Typedown pages are installed and browse to the location of the Web Service: i.e. http://my_qas_server:2021/proweb.wsdl * * where my_qas_server is the server on which QAS Pro Web is installed. If the port is open on that machine you should see a list of XML displayed. If you do not then you need to contact your network administrator to open up port 2021 to the machine(s) on which the browser Typedown pages are installed. QAS Pro Web Browser Typedown GSG North America.doc Page 5 of 10
6.4 Test the functionality outside of your application Open a web browser and browse to RapidIndex.htm within the directory where you installed the sample code during installation. e.g. for Classic ASP: http://localhost/prowebasp/rapidindex.htm NOTE: JSP is provided in the form of a war file which will need to be deployed as per the documentation of your Web Server. Click the Find Address Button to invoke the Browser Typedown pages. Enter in the ZIP 12345. This should resolve to 12345, Schenectady, NY. Click on the Select button to display the full address as below and then Accept button to display the full address in the original page. QAS Pro Web Browser Typedown GSG North America.doc Page 6 of 10
This confirms the Browser Typedown functionality is working outside of your application. 6.5 Modify your target page In order to implement the sample code into your application the following steps need to be carried out: 6.5.1 Determine how the functionality is triggered In order to get the quickest user adoption and encourage usage there are two recommended ways to trigger the Browser Typedown functionality: - A new button called Capture Address - The event of tabbing into the first address field on your form but only when that field is empty* *The check on whether the address is populated is to prevent the Browser Typedown pages invoking automatically when the user is simply tabbing through address information that is already populated. 6.5.2 Create a function that will load the Browser Typedown pages into a new browser window A single function called popuppro should be created that is then assigned to the new Capture Address button or event. popuppro will contain a single line of JavaScript that opens a new browser window containing the Browser Typedown pages and then calls a function to handle the returned address when the user has found an address. The JavaScript varies slightly across different languages and can be found in the installed RapidIndex.htm. The example from the C#.NET sample code is below: // Pop-up the Pro window for rapid address searching function popuppro() { } var ProPopup = window.open( "RapidSearch.aspx?DataID=&Callback=handleProClose", "ProPopup", "scrollbars=no,resizable=yes,width=590,height=560"); NOTE: if you are using only one country data set you should set the DataID variable to the three letter ISO code to automatically set that country in the Country dropdown list. i.e. "RapidSearch.aspx?DataID=USA&Callback=handleProClose", QAS Pro Web Browser Typedown GSG North America.doc Page 7 of 10
6.5.3 Create a function to be called when the Address is returned When the address is returned from the Browser Typedown pages a function called handleproclose must be created to handle the return address and populate the relevant fields in your page. An example of this function is listed below. function handleproclose(asaddress) { } var afields = document.getelementsbyname("address"); for (i = 0; i < afields.length; i++) { } afields[0].focus(); afields[i].value = (i < asaddress.length)? asaddress[i] : ""; NOTE: This assumes that you have an array of address lines with the name Address on your calling page. This would need to be modified according to the structure of your address fields in your application. 7. Testing your implementation This section outlines how you should approach testing the QAS Pro Web functionality within your application. It is important to confirm that you can replicate the expected behavior of QAS Pro Web and that the implementation had not negatively impacted any of your existing functionality. 7.1 Impact to existing processes when QAS Pro Web is unavailable If QAS Pro Web is not maintained correctly the product may cease to work. In this unlikely event it is important that your users are not impacted by any QAS Pro Web downtime. For Windows, installs stop the QAS Pro Server 5.xx service; for UNIX/Linux installs kill the qaswvd daemon. Are you able to still complete your standard business processes with QAS Pro Web integrated but not functioning? The Browser Typedown pages should invoke with an error but allow users to enter the address into the new form or close the window and enter the information directly into your application. 7.2 Invoking the Browser Typedown pages The Browser Typedown pages should invoke automatically when tabbing into the first address line in your application but only when that field is empty. If the field is populated the Browser Typedown pages should not invoke. Does this invocation functionality work as expected? Does the new Capture Address button you added to your form invoke the Browser Typedown pages as expected? QAS Pro Web Browser Typedown GSG North America.doc Page 8 of 10
7.3 Populating address fields It is important that the configuration of the returned address matches your business requirements. Capture a selection of addresses and confirm that the addresses are populated into your application as expected. A table of sample addresses to locate is below: Type of Address US Example Canada Example Standard 62 Eliot Rd Arlington MA 02474-8279 115 Tweed Cres LONDON ON N5X 1Z5 High Rise 1889 Broadway Apt 306 San Francisco CA 94109-2291 PO Box PO Box 121 San Francisco CA 94104-0121 101-5625 13 Ave EDSON AB T7E 0A4 PO Box 1 Stn A TORONTO ON M5W 1A2 Organizational Experian QAS 125 Summer St Ste 1910 Boston MA 02110-1615 Canada Trust Bank 1511 Bayview Ave EAST YORK ON M4G 4E2 NOTE: If you have multiple touchpoints throughout your application you should ensure these are tested thoroughly as well. 8. Deployment and Maintenance Considerations 8.1 Deployment Once the sample code is integrated and full tested across all touchpoints of your application it will be ready to be moved into a product environment. In order the make this transition as smooth as possible it is important to follow these steps: Install QAS Pro Web and data onto your production machine and activate the data using the Administrator Console (details in section 5) Copy across your layout from your initial QAWSERVE.INI and add to the equivalent file on your newly installed production installation of QAS Pro Web. Restart the QAS Pro Server 5.x service to refresh the configuration changes. Update the layout and location of the QAS Pro Web installation as per sections 6.2 and 6.3. Test your installation as per section 7 QAS Pro Web Browser Typedown GSG North America.doc Page 9 of 10
8.2 Maintenance Once you are live in a production environment with QAS Pro Web it is highly recommended that you record the following information and email it to your Customer Account Manager. Server name where QAS Pro Web is installed Name of Layout used Copies of QAWSERVE.INI and QAWORLD.INI This will help us when we need to provide support to you should you lose your QAS environment or unexpectedly change the staff responsible for the administration of QAS. Data updates need to be applied at least every two months by default. If these data updates are not applied and a whole update cycle is missed your installation will cease to work. When you initially purchased QAS Pro Web a contact at your organization was specified to receive the Data Updates and related information. It is important to let us know if that contact changes to allow for continuity of support. You can also sign up alternative contacts to receive the same data updates related correspondence as a back up or sign up our FTP updates program. Details on the update schedule and installation process can be found here: http://www.qas.com/updates http://www.qas.com/us/support/quicksupport/data-updates.asp 9. Conclusion By following this guide you should have been able to implement QAS Pro Web using the Browser Typedown implementation method. We hope that you found this guide useful and welcome your feedback, positive or negative at us.support@qas.com. For further assistance with your integration project you can contact us or access resources in the following ways: Support Email: us.support@qas.com Support Phone: (888) 712 3332 Customer forum: www.qas.com/customers Main company website: www.qas.com Appendix A Further Reading The full documentation for the QAS Pro Web product is available within the Docs directory on the QAS Pro Web installation image. The files are as follows: Web.pdf: Generic Integration guide Webinst.pdf: Installation and Administration Guide Webrefcapi.pdf: Technical Reference Guide C API Webrefcommon.pdf: Technical Reference Guide Common Classes Webrefwsdl.pdf: Technical Reference Guide WSDL QAS Pro Web Browser Typedown GSG North America.doc Page 10 of 10