Integration examples

Intranet Rapid Addressing

This section walks you through an example integration, demonstrating how easy it is to add Pro API to your Web pages. This example shows how you can integrate Pro API functionality into a company intranet site.

The example shows the entire process; from installation of Pro API and configuring the server, through to modifying the Web pages with sample code.

Before The Integration

This example uses a fictitious company called Welly Good that sells Wellington boots. It shows how to integrate Pro API into their internal sales order system.

These Web pages enable a trained operator to take and process orders over the telephone (or from returned order forms).

The operator takes the customer's delivery details and manually enters them into the address fields of the intranet site.

This has the disadvantage that manually entering the address can result in delivery address errors. It also takes some time to enter all the customer's details in this way.

How To Integrate Pro API

Integrating Pro API onto a Web page involves the following steps:

Installing And Configuring The Program

These instructions relate to installing and configuring the Pro API program. For this example, we have chosen to install the Pro API program onto the Web server, but you may choose to keep them separate for improved scalability and reliability.

Install Pro API

When installing Pro API, we should ensure that:

  1. On the first Setup Options dialog the Pro API integration files option is selected. This enables the Pro API integration files, that contain the integration code, to be installed.
  2. On the second Setup Options dialog, we should select the integration code appropriate to that used in the construction of the original Web site.

For this example we will use C#.NET for the integration. In your own situation, you should install the integration language that matches the code that you are using for development.

Install Dataset(s)

We should install the dataset(s) appropriate to the countries that our fictitious Web site supports. For the purposes of this demonstration, we can install any dataset and additional dataset for which we have a valid license.

Configuration

Now, we should configure the product and the integration code to suit our needs. For this, we should configure the layout that we want to use for the address data; configure the integration code to use that layout; and configure the list of countries that are displayed when Pro API starts.

Configuring Layouts

We should configure a layout for every active country that can be used. Each layout should match the address fields on the Web page that we want to fill in (in terms of the number of lines and address content).

Configuring Integration Code

When the layout has been created, we must configure the integration code to use the new layout. By default, the integration code uses the " ( Standard Layout )", so we should change this to our new layout, by following these instructions:

  1. Go to the installed integration code.

  2. Open the settings file containing the layout specification, appropriate to the coding language, in a text editor, such as Notepad.

  3. The following files are available:

    web.xml JSP
    constants.inc PHP
    web.config C#.NET

  4. Find the line which specifies the layout values. By default, this line will refer to the "( Standard Layout )".

    For example, for C#.NET, this line is:

    <add key="com.qas.proweb.layout" value"( Standard Layout )"/>

Change "( Standard Layout )" to the name of the layout we want to use.

Configuring The List Of Countries

When we use Intranet Rapid Addressing, the interface offers a drop-down list of available countries for us to search. By default, the list consists of 20 countries. We should edit this list of countries to suit the needs of our integration. To change this to our new list, we should follow these instructions:

  1. Go to the installed integration code.

  2. Open the 'country list' file, appropriate to the coding language, in a text-editor, such as Notepad.

  3. This file has the following name, depending on the coding language being used:

    countries.ok.inc PHP and JSP
    countries.net.inc C#.NET

  4. We should remove countries that are not installed.

  5. Alternatively, if we only want to use one country, we can remove the drop-down <select> control from each of the Rapid Addressing pages, and replace it with a hidden field set to the country of our choice.

    In C#.NET, the following code specifies that only the GBR dataset is used:

    <input type="hidden" name="<% constants::DATA_ID %>" value="GBR" />

Test Pro API

We should test Pro API to check that everything is working as we would expect. To do this, we should:

  • Open the index page
  • Check the Diagnostics page
  • Perform some test searches

When we are happy that everything is working as expected, we are ready to proceed to the next section.

Updating The Web Pages

In this section, the following updates need to be made:

  • Add a 'Find Address' button
  • Add the function to be called when the button is clicked
  • Add the function to be called when the address is returned

These three tasks have already been implemented in the sample page, RapidIndex.htm, so we could use the code in this page and modify it to suit our fictional Web site.

Adding A 'Find Address' Button

On the page requiring address capture, we want to add an HTML button near to the address fields that the operator will be using.

To add this button to the intranet page, we should follow these instructions:

  1. In our intranet page, we should scroll down to the address fields that we want to fill, and just above or beside it, add an HTML button, which calls 'popupPro' when it is clicked. For example:

    <button onclick="popupPro();">Find address</button>

  2. Save the intranet page and view the changes.

    The intranet page will now feature a Find address button near to the address fields.

Adding A Function To The Button

The next step is to attach a function to the button. To do this, we should follow these instructions:

  1. In RapidIndex.htm, navigate to the <script> section that lists the popupPro function.

    // Pop-up the Pro API window for rapid address searching
    
    function popupPro()
    
    {
    
    // specify the initial country in DataId & function to call in Callback
    
    var ProPopup = window.open(
    
    "RapidSearch.aspx?DataID=&Callback=handleProClose",
    
    "ProPopup",
    
    "scrollbars=no,resizable=yes,width=725,height=560");
    
    }
    
  2. Copy this section of code and then open the intranet page into which we want to place this function.

  3. Paste the section of code into a <script type="text/javascript"> block in the intranet page.

  4. Now, we need to edit the page path to point to the sample code.

    Insert the relative path of the integration code from the Web site. For example, if the site is in a directory called "boots", and the integration code is installed into its default directory of "proweb", then:

    var ProPopup = window.open(
    
    "../proweb/RapidSearch.aspx?DataID=&Callback=handleProClose", "ProPopup",
    
    "scrollbars=no,resizable=yes,width=725,height=560");
    
  5. If we want to specify a data mapping for the initial country search, we need to enter the three-letter data mapping identifier for the country after the DataId= part of the code.

  6. Save the intranet page.

Now the Find address button will call popupPro when it is clicked.

Handling The Returned Address

The next step is to control how the returned address is handled. When a formatted address is returned, this function is called and should paste the address into the fields on the intranet page. To do this, we should follow these instructions:

  1. Open RapidIndex.htm and navigate to the <script> section that lists the handleProClose function in the HTML.

    // Handle the returned final address - populate the appropriate address fields
    
    // String[] asAddress - array of address lines
    
    function handleProClose(asAddress)
    
    {
    
    var aFields = document.getElementsByName("Address");
    
    for (i = 0; i < aFields.length; i++)
    
    {
    
    aFields[i].value = (i < asAddress.length) ? asAddress[i]: "";
    
    }
    
    aFields[0].focus();
    
    }
    
  2. Copy this section of code and then open the intranet page into which we want to place this function.

  3. Paste the section of code into the <script> block of the intranet page.

  4. Modify the code so that the address lines are pasted into the correct fields. For example, if the address fields that we want to fill are all named "DeliveryAddress", then we should edit the document.getElementsByName statement appropriately.

    var aFields = document.getElementsByName("DeliveryAddress");

    If, instead, we have a number of fields named "Street" followed by fields named "Zip" and "Country", then our code could like this:

    for (i = 0; i < aFields.length; i++)
    
    {
    
    aFields[i].value = (i < asAddress.length) ? asAddress[i] : "";
    
    }
    
    document.getElementById("Zip").value = (i < asAddress.length) ? asAddress[i++] : "";
    
    document.getElementById("Country").value = (i < asAddress.length) ? asAddress[i++] : "";
    
  5. Save and close the intranet page.

After The Integration

Now, with our Web page updated, we are ready to capture addresses and return them to our customer address fields.