Registration

Dear SAP Community Member,
In order to fully benefit from what the SAP Community has to offer, please register at:
http://scn.sap.com
Thank you,
The SAP Community team.
Skip to end of metadata
Go to start of metadata

Global Address Cleanse – Suggestion Lists

Quick Link:

Summary
Create GAC Suggestion Lists Real-time Job
Consume GAC Suggestion Lists via DS Real-time Service SDK(Message API)
Java Sample Code
C++  Sample Code
Deploy GAC Suggestion Lists Web Service
Consume GAC Suggestion Lists Web Services

Summary:

The Suggestion Lists feature of Global Address Cleanse(GAC) transform allows you to enter partial address data, perform error-tolerant search and returns a list of possible matches for the user to select from. Via interactions between user and this feature, a complete and correct address can be made up to be used for business purpose. By integrating a web/real-time service, which have GAC transform configured and Suggestion List feature enabled, online applications are able to cleanse address data at the point of entry.  

This page shows how to setup a real time job to use GAC Suggestion Lists, how to deploy the real-time job as a web-service so that it can be consumed by various 3rd party applications, and how to use the Data Service real-time SDK to interact with the real-time job. Sample code snips in Java are presented to show a way of how the generated suggestions can be consumed.

Note DS 4.0 is used in this page; however, it should work well for DS 4.1 or later versions. In DS 3.2 or prior versions, you would have had to use Global Suggestion Lists (GSL) with Country Identification (CID), and Global Address Cleanse (GAC) to achieve the similar functionalities. In this page, the process has been simplified and only GAC transform is used.

Create the GAC Suggestion Lists real-time job in DS Designer

To create a real-time job, we first need to create a data flow, to create a data flow we need to define what the input and output message formats are, and what transforms are used. There are 3 files as follows will be used in the following steps. Since SCN wiki disabled the functionality of attaching these file formats for security reason, user need to make them up by creating the files and copy&paste the content.

  • rt_gac_suggestionlists_input.xsd   -- The input message format for the real-time service/job
    rt_gac_suggestionlists_input.xsd
    <?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema  xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="Rt_gac_suggestion_lists" xmlns="Rt_gac_suggestion_lists">
    
      <xsd:annotation>
        <xsd:documentation xml:lang="en">
        XML Schema generated by Data Services
        </xsd:documentation>
      </xsd:annotation>
    
    
    <xsd:element name="Rt_gac_suggestionlists_in" >
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element name="country" type="xsd:string"/>
          <xsd:element name="firm" type="xsd:string"/>
          <xsd:element name="address1" type="xsd:string"/>
          <xsd:element name="address2" type="xsd:string"/>
          <xsd:element name="address3" type="xsd:string"/>
          <xsd:element name="address4" type="xsd:string"/>
          <xsd:element name="postcode" type="xsd:string"/>
          <xsd:element name="locality1" type="xsd:string"/>
          <xsd:element name="locality2" type="xsd:string"/>
          <xsd:element name="region" type="xsd:string"/>
          <xsd:element name="suggestion_reply1" type="xsd:string"/>
          <xsd:element name="suggestion_reply2" type="xsd:string"/>
          <xsd:element name="suggestion_reply3" type="xsd:string"/>
          <xsd:element name="suggestion_reply4" type="xsd:string"/>
          <xsd:element name="suggestion_reply5" type="xsd:string"/>
          <xsd:element name="suggestion_reply6" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>
    
    </xsd:schema>
    
  • rt_gac_suggestionlists_output.xsd -- The output message format for the real-time service/job
    rt_gac_suggestionlists_output.xsd
    <?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema  xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="Rt_gac_suggestion_lists" xmlns="Rt_gac_suggestion_lists">
    
    
    <xsd:complexType name="SUGGESTION_LIST_DEF">
     <xsd:sequence>
       <xsd:element ref="ENTRY" minOccurs="0" maxOccurs="unbounded" />
     </xsd:sequence>
    </xsd:complexType>
    
    
    <xsd:element name="ENTRY" >
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="SELECTION" type="xsd:string" minOccurs="0" />
            <xsd:element name="LOCALITY1" type="xsd:string" minOccurs="0" />
            <xsd:element name="LOCALITY2" type="xsd:string" minOccurs="0" />
            <xsd:element name="LOCALITY3" type="xsd:string" minOccurs="0" />
            <xsd:element name="LOCALITY4" type="xsd:string" minOccurs="0" />
            <xsd:element name="LOCALITY1_OFFICIAL" type="xsd:string" minOccurs="0" />
            <xsd:element name="LOCALITY2_OFFICIAL" type="xsd:string" minOccurs="0" />
            <xsd:element name="LOCALITY3_OFFICIAL" type="xsd:string" minOccurs="0" />
            <xsd:element name="LOCALITY4_OFFICIAL" type="xsd:string" minOccurs="0" />
            <xsd:element name="POSTCODE" type="xsd:string" minOccurs="0" />
            <xsd:element name="POSTCODE1" type="xsd:string" minOccurs="0" />
            <xsd:element name="POSTCODE2" type="xsd:string" minOccurs="0" />
            <xsd:element name="REGION1" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NUMBER_LOW" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NUMBER_HIGH" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NUMBER_DESCRIPTION" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NUMBER_EXTRA" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NUMBER_FULL" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_PREFIX1" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_PREFIX2" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NAME1" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NAME2" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NAME3" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NAME4" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_TYPE1" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_TYPE2" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_TYPE3" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_TYPE4" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_POSTFIX1" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_POSTFIX2" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NAME_FULL1" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NAME_FULL2" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NAME_FULL3" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_NAME_FULL4" type="xsd:string" minOccurs="0" />
            <xsd:element name="DELIVERY_INSTALLATION_NAME" type="xsd:string" minOccurs="0" />
            <xsd:element name="DELIVERY_INSTALLATION_QUALIFIER" type="xsd:string" minOccurs="0" />
            <xsd:element name="DELIVERY_INSTALLATION_TYPE" type="xsd:string" minOccurs="0" />
            <xsd:element name="PRIMARY_SIDE_INDICATOR" type="xsd:string" minOccurs="0" />
            <xsd:element name="FIRM" type="xsd:string" minOccurs="0" />
            <xsd:element name="BUILDING_NAME" type="xsd:string" minOccurs="0" />
            <xsd:element name="UNIT_DESCRIPTION" type="xsd:string" minOccurs="0" />
            <xsd:element name="UNIT_NUMBER_LOW" type="xsd:string" minOccurs="0" />
            <xsd:element name="UNIT_NUMBER_HIGH" type="xsd:string" minOccurs="0" />
            <xsd:element name="STAIRWELL_DESCRIPTION" type="xsd:string" minOccurs="0" />
            <xsd:element name="STAIRWELL_NAME" type="xsd:string" minOccurs="0" />
            <xsd:element name="FLOOR_NUMBER_HIGH" type="xsd:string" minOccurs="0" />
            <xsd:element name="FLOOR_NUMBER_LOW" type="xsd:string" minOccurs="0" />
            <xsd:element name="FLOOR_DESCRIPTION" type="xsd:string" minOccurs="0" />
            <xsd:element name="SECONDARY_SIDE_INDICATOR" type="xsd:string" minOccurs="0" />
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    
    
      <xsd:element name="Rt_gac_suggestionlists_out" >
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="COUNTRY_NAME" type="xsd:string"/>
            <xsd:element name="FIRM" type="xsd:string"/>
            <xsd:element name="ADDRESS_DELIVERY" type="xsd:string"/>
            <xsd:element name="BUILDING_NAME" type="xsd:string"/>
            <xsd:element name="POSTCODE" type="xsd:string"/>
            <xsd:element name="LOCALITY1" type="xsd:string"/>
            <xsd:element name="LOCALITY2" type="xsd:string"/>
            <xsd:element name="REGION" type="xsd:string"/>
            <xsd:element name="PRIMARY_NAME1" type="xsd:string"/>
            <xsd:element name="PRIMARY_NAME2" type="xsd:string"/>
            <xsd:element name="PRIMARY_NUMBER" type="xsd:string"/>
            <xsd:element name="FLOOR_NUMBER" type="xsd:string"/>
            <xsd:element name="UNIT_NUMBER" type="xsd:string"/>
            <xsd:element name="ADDR_ASMT_LEVEL_DESC" type="xsd:string"/>
            <xsd:element name="ADDR_ASMT_TYPE_DESC" type="xsd:string"/>
            <xsd:element name="ADDR_INFO_CODE_DESC" type="xsd:string"/>
            <xsd:element name="ADDR_STATUS_CODE_DESC" type="xsd:string"/>
            <xsd:element name="SUGGESTION_COUNT" type="xsd:string"/>
            <xsd:element name="SUGGESTION_STATUS" type="xsd:string"/>
            <xsd:element name="SUGGESTION_ERROR" type="xsd:string"/>
            <xsd:element name="SUGGESTION_LIST"  type="SUGGESTION_LIST_DEF"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    
    </xsd:schema>
    
    
  • rt_gac_suggestionlists_input.xml    --  A testing file which contains a sample input
    rt_gac_suggestionlists_input.xml
    <?xml version="1.0" encoding = "UTF-8" ?>
    <ns1:Rt_gac_suggestionlists_in xmlns:ns1="Rt_gac_suggestion_lists">
    	<country>AUSTRALIA</country>
    	<firm></firm>
    	<address1>Jubilee</address1>
    	<address2></address2>
    	<address3></address3>
    	<address4></address4>
    	<postcode></postcode>
    	<locality1>Mount Gambier</locality1>
    	<locality2></locality2>
    	<region>SA</region>
    	<suggestion_reply1>2</suggestion_reply1>
    	<suggestion_reply2>13</suggestion_reply2>
    	<suggestion_reply3></suggestion_reply3>
    	<suggestion_reply4></suggestion_reply4>
    	<suggestion_reply5></suggestion_reply5>
    	<suggestion_reply6></suggestion_reply6>
    </ns1:Rt_gac_suggestionlists_in>
    

Note that users can customize these formats to meet specific requirements according to their own productive systems and environments.

a)    Create the input&output message format

    1. In the Local Object Library, click the Formats tab, right-click the XML Schemas, click New, the Import XML Schema Format dialog opens up.

    2. Under Format name, input GacSuggestionListsInput.

    3. Under File name/URL, click the Browse... button, navigate to rt_gac_suggestionlists_input.xsd, click Open

    4. Under Namespace, select the Rt_gac_suggestion_lists

    5. Under Root element name select Rt_gac_suggestionlists_in

    6. Click OK

       

    7. Create another new schema, under Format name, input GacSuggestionListsOutput.

    8. Under File name/URL, click the Browse... button and navigate to rt_gac_suggestionlists_output.xsd, click Open

    9. Under Namespace, select the Rt_gac_suggestion_lists

    10. Under Root element name select Rt_gac_suggestions_out

    11. Click OK

       

b)    Create the Suggestion List data format

This format defines the structure of a suggestion list. Using this format, the data flow knows how to extract suggestion entries and address elements  for each entry, from the output message( the response).

    1. Create another new schema, under Format name, input GacSuggestionList

    2. Under File name/URL, click the Browse... button and navigate to C:\Program Files (x86)\SAP BusinessObjects\Data Services\DataQuality\gac\gac_suggestion_list.xsd,  click Open

    3. Under Namespace, select the urn:bobjsap_gac

    4. Under Root element name select SUGGESTION_LIST

    5. Click OK

       

c)    Create a Data Flow

    1. In the Local Object Library, click the Data Flows tab

    2. Right click Data Flows, and click New

    3. Change the name of the data flow to GacSuggestionLists

    4. Double click it, the edit panel opens on the right

    5. Click the Transforms tab, open the Data Quality tree, click the GlobalSuggestions_AddressCleanse transform, drag and drop it to the GacSuggestionLists panel

       
    6. Click the Formats tab, drag the GacSuggestionListsInput to the data flow edit panel, drop it at the left of the GlobalSuggestions_AddressCleanse  transform,

    7. Select Make XML Message Source from the menu jumped out.

       

    8. Double click the GacSuggestionListsInput icon, from the Source tap, under XML test file, click the drop down arrow, select file..., navigate to rt_gac_suggestionlists_input.xml
    9. Click the checkbox to enable validation.
       

    10. Open the Data flow edit panel, connect the GacSuggestionListsInput to the GlobalSuggestions_AddressCleanse  transform
       

    11. Double click the GlobalSuggestions_AddressCleanse transform to map the inputs.
          For example, to map the country input, click the COUNTRY Input schema Column from the Input tab, from the drop down menu select country
       

    12. Map all other inputs using the same techniques. After mapping all inputs, it looks like this:
       

    13.  Click the Output tab, click the All radio box, select the filelds listed below by clicking the check box in the front of the field, finally click the In Use radio box to verify them.

       

    14.  Click the Query Transform from the tool palette and put it at the right of the GlobalSuggestions_AddressCleanse  transform, rename it to extract_suggestions
    15.  Drag and drop the GacSuggestionListsOutput format to the right of the extract_suggestions, but select Make XML Message Target from the menu.
       

    16.  Double click the GacSuggestionListsOutput icon, from the Target tap, under XML test file, click the drop down arrow, select file...,
    17.  Specify any directory you want put the output file and input rt_gac_suggestionlists_output.xml as the file name, click the checkbox to enable Delete and re-create file.
       

    18.  Connect the extract_suggestions query to the GacSuggestionListsOutput format
       

    19.  Connect the GlobalSuggestions_AddressCleanse  transform and the extract_suggestions query
       

    20.  Double click the extract_suggestion query, map all fields as in the table below by dragging one field from Schema In and dropping it on the peer field from Schema out.

           Note: Do not map the SUGGESTION_LIST item for now

    • Schema In

      Schema Out

      ASSIGNMENT_TYPE_BEST_COMPONENT_DELIVERY 

      ADDR_ASMT_TYPE_DESC

      BUILDING_NAME1_BEST_COMPONENT_DELIVERY

      BUILDING_NAME

      COUNTRY_ BEST_COMPONENT_DELIVERY

      COUNTRY_NAME

      FULL_ADDRESS_ BEST_COMPONENT_DELIVERY

      ADDRESS_DELIVERY

      FLOOR_NUMBER_ BEST_COMPONENT_DELIVERY

      FLOOR_NUMBER

      FIRM_ BEST_COMPONENT_DELIVERY

      FIRM

      LOCALITY1_FULL_BEST_COMPONENT_DELIVERY

      LOCALITY1

      LOCALITY2_FULL_BEST_COMPONENT_DELIVERY

      LOCALITY2

      POST_CODE_FULL_BEST_COMPONENT_DELIVERY

      POSTCODE

      REGION1_FULL_BEST_COMPONENT_DELIVERY

      REGION

      UNIT_NUMBER_BEST_COMPONENT_DELIVERY

      UNIT_NUMBER

      PRIMARY_NAME_FULL1_BEST_COMPONENT_DELIVERY

      PRIMARY_NAME1

      PRIMARY_NAME_FULL2_BEST_COMPONENT_DELIVERY

      PRIMARY_NAME2

      PRIMARY_NUMBER_FULL_BEST_COMPONENT_DELIVERY

      PRIMARY_NUMBER

      STATUS_NONE_SUGGESTION_NONE

      SUGGESTION_STATUS

      ERROR_NONE_SUGGESTION_NONE

      SUGGESTION_ERROR

      COUNT_NONE_SUGGESTION_NONE

      SUGGESTION_COUNT

      INFO_CODE_NONE_ASSIGNMENT_INFO_NONE

      ADDR_INFO_CODE_DESC

      ASSIGNMENT_LEVEL_NONE_ASSIGNMENT_INFO_NONE

      ADDR_ASMT_LEVEL_DESC

      STATUS_CODE_NONE_ASSIGNMENT_INFO_NONE

      ADDR_STATUS_CODE_DESC

       

    21. Double click the extract_suggestion query, from Schema Out, right click the SUGGESTION_LIST item, and select Delete. 

       
 
    22. Right click the extract_suggestions from Schema Out, select New Output Schema, input SUGGESTION_LIST under the Schema name from the dialog

       
 
    23. Right click the SUGGESTION_LIST item, and select Make Current

       
 
    24. Right click the SUGGESTION_LIST item again, and select New Function Call, from Conversion Functions select extract_from_xml, click Next

       

    25. Under XML field name, click the drop down arrow, select GlobalSuggestions_addressCleanse, click ok, select SUGGESTION_LIST_NONE_SUGGESTION_NONE, and click OK.

       
         


    26. Under DTD or Schema name, select GacSuggestionList, click OK 
       


    27. Under Enable Validation, input 1, click Next, click ENTRY         
       
 
        click the To-Right button, click Finish
       


        After all steps finish, the Schema Out looks like:
       
 
Now the GAC Suggestion Lists data flow has been created, you may want validate it to check if any errors exist  and save it if everything is ok.
 

d)   Create a Real-time job

    1. In the Jobs tab of the Local Object Library, right-click and select New, and select Real-time. The result is that a job called New_RTJob exists.

    2. Rename the job RT_gac_suggestion_lists and press Enter. Double click it; the edit canvas opens up with Rt_Process_begins and Step_ends.

    3. In the Data Flows tab of the Local Object Library, select a data flow called GacSuggestionLists, drag and drop it between the job edit canvas.

    4. Connect RT_Process_begins to GacSuggestionLists and connect GacSuggestionLists to Step_ends.

          

e)    Create a project to test the Real-time job

    1. From the DS designer menu, Click Project > New > Project..., from the Project New dialog, input RT_Gac_SuggestionLists.

    2. From the Jobs tap in the Local Object Library, right click the RT_gac_suggestion_lists job, select Add To Project,

    3. save the project by clicking the Save All button from the DS menu.

    4. Right click the job of RT_gac_suggestion_lists from the project area, select Execute...

    5. Once the job has completed successfully, view the data by opening the output XML document (rt_gac_suggestionlists_output.xml) in a text editor such as Notepad.

        Note that there is no suggestions exist because we gave two replies from the input file, 

        <suggestion_reply1>2</suggestion_reply1>  // Select the second suggestion
        <suggestion_reply2>13</suggestion_reply2> // Input 13 as the selected street number

        you may want to remove the two reply content and execute the job again, check the ouput and see what happens.

       
 
 


Deploy the GAC SuggestionLists Real-Time Web Service 

    1. Launch the Data Services Management Console by choosing Tools -> Data Services Management Console from DS Designer.

    2. Log in to the management console.

            System: gacv01

            User Name: administrator

            Password: *******

            Authentication: Enterprise

    3. Click on the Administrator icon.

    4. Open the following tree Management -- Access Server -- Add

       
 
    5. Input gacv01 for Machine name and 4000 for port, select no for SSL if the access server is configured as SSL disabled.
    6. Click Ping.  You will see a return message Access server ‘gacv01:4000’ is valid.
    7. Click Apply.
    8. Choose Real-Time -- gacv01:4000 --  Real-Time Services.
    9. Choose the Real-Time Services Configuration tab at the top.
    10.  Click Add.
    11.  Set the Service name to RtGacSuggestionLists
    12.  Click Browse Jobs.
    13.  Click the hyperlink for the job RT_gac_suggestion_lists
    14.  Click Add to add a job server as your service provider
    15.  Click Enable to enable the service
    16.  Click Apply.
       
 
    17.  Choose the Real-Time Services Status tab to view the list of available real-time services, which should include the new service just added.
    18.  Select the checkbox next to the RtGacSuggestionLists real-time service.
    19.  Click Start to start the service on the assigned job server.
       
 
    20. Continue to click the Real-time Services Status tab to refresh the screen until you see a green check mark next to the RtGacSuggestionLists service denoting it has started.
       

    21. Select the Web Services hyperlink in the tree on the left-hand side(shown below as "1")
    22. Choose the Web Services Configuration tab (shown below as “2”)
    23. In the drop-down box select Add Real-time Service… (shown below as “3”)  
       

    24. Click Apply
    25. Select the checkbox next to the real-time service called RtGacSuggestionLists
    26. Click Add and you should see a message to tell you the real-time services are successfully added.

       
    27. You should see RtGacSuggestionLists in the list of operations

       
    28. Click View WSDL to launch a Web browser with the WSDL file that a software developer would use to consume the Web service. 

           It contains all the metadata, including the schema for the source/target XML messages for the real-time job.

           In our case here, the URL for the WSDL is:

               http://gacv01:8080/DataServices/servlet/webservices?ver=2.1&wsdlxm

Consume the GAC Suggestion Lists Web Services

Now that the Web service has been published, we will use a Web Services testing tool to consume and test the Web service. The steps below are for the soapUI tool. Any other equivalent SOA or Web Services testing tool can be substituted.

    1. Download and Install soapUI from http://sourceforge.net/projects/soapui/.

    2. Launch soapUI, choose File-New soapUI Projects

    3. The New soapUI Project window provides the following details, and Click OK

        Project Name:  GAC Suggestion Lists

        Initial WSDL:  http://gacv01:8080/DataServices/servlet/webservices?ver=2.1&wsdlxml

       

    4. Drill down into Projects GAC Suggestion Lists > Real-time_Services > RtGacSuggestionLists (as shown below) to see the exposed SOAP request Request 1.

       
    5. Double-click Request 1 to see the SOAP envelope details (which is the input to our RtGacSuggestionLists Web service/real-time job).

    6. Enter the following values into the SOAP envelope:

        <country>AUSTRALIA</country>

        <address1>Jubilee</address1>

        <locality1>Mount Gambier</locality1>

    7. Click the green arrow at the top-left to submit the request.Note:  The first Web service request will take a few seconds, but subsequent requests should be much faster.
    8. After a few seconds, the response from the request will be returned as shown below with the supplied data cleansed.

        Note that there are 56 suggestions generated which have deeper information (primary number) than the input address. 

       
    9. Enter the following values into the SOAP envelope:

        <country>AUSTRALIA</country>

        <address1>Jubilee</address1>

        <locality1>Mount Gambier</locality1>

        <suggestion_reply1>2</suggestion_reply1>

        <suggestion_reply2>15</suggestion_reply2>

        In this case, the two replies indicate 1) select the secondary suggestion entry; 2) input 15 for the primary range;
        Note that the response has changed to the user selected address, and there is no further suggestion entry anymore.  

       


Consume GAC Suggestion Lists via Real-time service SDK

The GAC Suggestion List real-time services can be integrated to users’ applications through the DS message API (C++ or Java). Either of these interfaces allows user to connect to the real-time service with a persistent connection to the server, send and receive data from it, and close the connection. In this section, it shows how to create a very simple java program using the Eclipse IDE, to send/receive request/response to/from the GAC suggestion lists real-time service configured above. Any other equivalent IDE can be substituted. At the end of this section, the C++ equivalent sample program is also given.  

1.   Create a new Java Project

Create a new Java project from eclipse (or any other IDE). Name it GacSuggestionListsSample, click Finish.

         

2.   Add real-time service libs

Right click the new project, select Properties -> Java Build Path, select the Libraries tab, click Add External Jars, navigate it to C:\Program Files (x86)\SAP BusinessObjects\Data Services\lib\rtsClientX.jar, click Open to add it to the project lib path, click ok to close the dialog.  

3.   Create the main class

Right click the project again, select New -> Class, the New Java Class dialog opens up, input GacSuggestionLists under Name, enable the public static void main… , click Finish

4. Import the DS Real-time Client SDK

 At the top of GacSuggestionListsSample.java file, put the line as follows:

GacSuggestionListsSample.java
import com.businessobjects.rtsclient.*;

5. Create an RTServiceClientX object

From the main method create an RTServiceClientX object.

GacSuggestionListsSample.java
RTServiceClientX rts = new RTServiceClientX();

6. Connect to the access server

Create a connection to the Access Server on which the GAC SuggestionLists Real-time service configured

GacSuggestionListsSample.java
rts.connect("gacv01",4000, false);

7. Build initial request

A request is a string in xml format, which should be consist with the format defined by the rt_gac_suggestionlists_input.xsd in the real-time job. Check out an example from the rt_gac_suggestionlists_input.xml or the soapUI Request 1. 
Initially, the request does not contain suggestion replies, which means suggestion_reply1-6 are all empty. 

GacSuggestionListsSample.java
String xmlInputStr =
                "<?xml version=\"1.0\" encoding = \"UTF-8\"?>"+
                "<ns1:Rt_gac_suggestionlists_in xmlns:ns1=\"Rt_gac_suggestion_lists\">"+
                "<country>AUSTRALIA</country>"+
                "<firm></firm>"+
                "<address1> Jubilee        </address1>"+
                "<address2>                </address2>"+
                "<address3>                </address3>"+
                "<address4>                </address4>"+
                "<postcode>                </postcode>"+
                "<locality1> Mount Gambier </locality1>"+
                "<locality2>               </locality2>"+
                "<region>    SA            </region>"+
                "<suggestion_reply1>       </suggestion_reply1>"+
                "<suggestion_reply2>       </suggestion_reply2>"+
                "<suggestion_reply3>       </suggestion_reply3>"+
                "<suggestion_reply4>       </suggestion_reply4>"+
                "<suggestion_reply5>       </suggestion_reply5>"+
                "<suggestion_reply6>       </suggestion_reply6>"+
                "</ns1:Rt_gac_suggestionlists_in>";

8. Setup real-time service name

Specify that the service we want call is RtGacSuggestionLists

GacSuggestionListsSample.java
String serviceName = "RtGacSuggestionLists";

9. Send initial request to access server

Send requests from the client application using the Invoke method

GacSuggestionListsSample.java
String response = rts.invoke(serviceName, xmlInputStr);

10. Process the reply

Like the input message, the output(response) returned is also a xml string, which is in the format defined by rt_gac_suggestionlists_output.xsd. In user applications, professional XML parsing tools/libs such as SAX, MsXml etc, can be used to parse the output, extract the address data elements, suggestion lists information and assignment information. The suggestion lists information contains the suggestion status, the suggestion error code, the suggestion count, and the suggestion list which contains some suggestion entries. In a typical scenario, user application firstly check the suggestion status and error code, then extract all the entries, format and populate them to a well-looked UI/Web for user to selection, with user selections stored in suggestion_reply1-6, the request is re-submitted to the real-time service. Then a new response returns with different suggestion status and error code. Step 9 and Step 10 can be repeated several times until there is no suggestions generated(suggestion status is 'N'), or user cancel further process because of the address has achieved the desired level.

a) The Suggestion Status

The suggestion_status is the most import information regarding suggestions generated. It tells if there are any suggestions generated and what type of suggestions they are if any. For example, in above case the returned status is A, the SUGGESTION_LIST item contains several address-line entries that could be a match to the input address.  Check the state machine diagram as follows:

       

There are some ground rules regarding the suggestion_status returned. User can take advantages of these rules to simplify the suggestion list handling processes.

  • A follow-up state (AM) must follow after state A
  • The follow up state (AM) can occur multiple times
  • You can go from start to any state (except AM)

     

  • You can go from a less refined state to any other finer states (left to right)

     

  • You can go from any state to state “N” (end)

   
 

Here is a way of how the suggestion_status can be used to determine the next step to take:

GacSuggestionListsSample.java
            boolean stopProcessing = false;
            while (stopProcessing == false)
            {
                String currReply = rts.invoke(serviceName, currInputStr);
                // Extract suggestion status from the reply
                String suggStatus = extract_suggestion_status(reply);
                String suggStatus = "N";
                if (suggStatus == ("N"))
                {
                    // Stop process current address record
                    // stopProcessing == true;
                    break;
                }
                else if (suggStatus == ("A"))
                {
                    // Prompt user "Primary address Line suggestion Generated"
                    // Print out the available primary entries generated
                    // Get user selection
                    // Append user selection as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("AM"))
                {
                    // Prompt user
                    // "Follow-up Address Line suggestions generated"
                    // Print out the available follow up primary entries
                    // generated
                    // Get user selection
                    // Append user selection as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("R"))
                {
                    // Prompt user "Select Primary Number"
                    // Print out the available primary range(low, high)
                    // Get user input
                    // Append user inputted number as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("U"))
                {
                    // Prompt user "Secondary suggestions generated"
                    // Print out the available secondary entries generated
                    // Get user selection
                    // Append user selection as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("F"))
                {
                    // Prompt user "Select Floor Number"
                    // Print out the available floor range(low, high)
                    // Get user input
                    // Append floor number as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("S"))
                {
                    // Prompt user "Select Unit Number"
                    // Print out the available unit range(low, high)
                    // Get user input
                    // Append unit number as one more reply
                    // Reprocess the address with all replies
                }
           }
b) The Suggestion Error Code

The suggestion_error provides additional information regarding user inputs. User applications can utilize this information, together with the suggestion status, to give hints helping user make the correct inputs. Here are the meanings of the error code.

Error Code

Meanings

0

No error

1

The necessary selection information is blank. Example: a last-line suggestion list was generated, but there was no last-line selection input field data to choose from making a choice.

2

The suggestion selection is invalid. Example: 8 was selected but there are only 5 suggestions.|

3

The primary range in the input field is invalid.  Example: Street number 244 was entered, but only numbers ranging from 100-200 are valid.

4

The floor number in the input field is invalid.

5

The unit number in the input field is invalid. Example: Unit number 2B was entered but alphanumeric was invalid.

c) The Suggestion Count

The suggestion_count denotes how many suggestion entries have generated. It can help user application to loop through all suggestion entries.

Suggestion Lists Information usage

  • Suggestion_reply1-6 should be accumulated, which means when user makes secondary input, the new request should contain both reply1 and reply2, when user makes third input all reply1, reply2 and reply3 should be in the new request.
  • The replies are consumed by suggestion lists service one by one, if only reply1 is enough to make a final address, further replies (reply2-6 if not empty) will be discarded.  
  • Since user application can get all suggestion entries information, for some scenarios it can check the validity of user inputs by itself, instead of depending on the suggestion error code. This avoids another iteration of interacting between user application and the real-time service.

11. Closing the connection

Once we finish the process using the real-time service object, it’s better to close the connection. The library provides a method (Disconnect) with the Connection object that allows you to systematically close the TCP/IP socket between the client and the Access Server.

GacSuggestionListsSample.java
rts.disconnect();


12. Run the Java program

Click the run button to run the program and check the output from the Console tab.
       

Sample Code – Java

GacSuggestionListsSample.java
import com.businessobjects.rtsclient.*;

/*
 *  Java sample code to show how to consume GAC Suggestion Lists via DS Real-time SDK(Message API).
 */
public class GacSuggestionListsSample
{
    public static void main(String[] args)
    {
        try
        {
            // Create a real-time service client instance
            RTServiceClientX rts = new RTServiceClientX();

            // Connect to the access server
            rts.connect("gacv01", 4000, false);

            // The initial request
            String xmlInputStr = "<?xml version=\"1.0\" encoding = \"UTF-8\"?>"
                    + "<ns1:Rt_gac_suggestionlists_in xmlns:ns1=\"Rt_gac_suggestion_lists\">"
                    + "<country>  AUSTRALIA      </country>"
                    + "<firm>                    </firm>"
                    + "<address1> Jubilee        </address1>"
                    + "<address2>                </address2>"
                    + "<address3>                </address3>"
                    + "<address4>                </address4>"
                    + "<postcode>                </postcode>"
                    + "<locality1> Mount Gambier </locality1>"
                    + "<locality2>               </locality2>"
                    + "<region>    SA            </region>"
                    + "<suggestion_reply1>       </suggestion_reply1>"
                    + "<suggestion_reply2>       </suggestion_reply2>"
                    + "<suggestion_reply3>       </suggestion_reply3>"
                    + "<suggestion_reply4>       </suggestion_reply4>"
                    + "<suggestion_reply5>       </suggestion_reply5>"
                    + "<suggestion_reply6>       </suggestion_reply6>"
                    + "</ns1:Rt_gac_suggestionlists_in>";

            // The service name to call
            String serviceName = "RtGacSuggestionLists";

            // Send the initial request to the access server for processing
            String response = rts.invoke(serviceName, xmlInputStr);

            // Output the response
            System.out.println(response);

            /*
            // Parse the response and re-submit the request which have user replies updated
            boolean stopProcessing = false;
            while (stopProcessing == false)
            {
                String currResponse = rts.invoke(serviceName, xmlInputStr);
                // Extract suggestion status from the reply
                // String suggStatus = extract_suggestion_status(reply);
                String suggStatus = "N";
                if (suggStatus == ("N"))
                {
                    // Stop process current address record
                    // stopProcessing == true;
                    break;
                }
                else if (suggStatus == ("A"))
                {
                    // Prompt user "Primary address Line suggestion Generated"
                    // Print out the available primary entries generated
                    // Get user selection
                    // Append user selection as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("AM"))
                {
                    // Prompt user
                    // "Follow-up Address Line suggestions generated"
                    // Print out the available follow up primary entries
                    // generated
                    // Get user selection
                    // Append user selection as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("R"))
                {
                    // Prompt user "Select Primary Number"
                    // Print out the available primary range(low, high)
                    // Get user input
                    // Append user inputted number as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("U"))
                {
                    // Prompt user "Secondary suggestions generated"
                    // Print out the available secondary entries generated
                    // Get user selection
                    // Append user selection as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("F"))
                {
                    // Prompt user "Select Floor Number"
                    // Print out the available floor range(low, high)
                    // Get user input
                    // Append floor number as one more reply
                    // Reprocess the address with all replies
                }
                else if (suggStatus == ("S"))
                {
                    // Prompt user "Select Unit Number"
                    // Print out the available unit range(low, high)
                    // Get user input
                    // Append unit number as one more reply
                    // Reprocess the address with all replies
                }
            }

            System.out.println(response);
            */

            // Disconnect from the access server
            rts.disconnect();
        }
        catch (RTServiceException e)
        {
            System.out.println(e.getLocalizedMessage());
        }
    }
}

Sample Code – C++

To compile these sample code, the SDK CPP libs should be added to your C++ project lib reference path or the %PATH% environments, by default those libs' location is
C:\Program Files (x86)\SAP BusinessObjects\Data Services\SDK\RTSDK\win64_x64\lib

GacSuggestionListsSample.cpp
#include    <iostream>
#include    <windows.h>
using namespace std;

#include "C:\Program Files (x86)\SAP BusinessObjects\Data Services\SDK\RTSDK\Include\RTServiceClient.h"

void
main(int argc, char** argv)
{
    char*  host = "gacv01";
    int    portNumber = 4000;
    char*  serviceName = "RtGacSuggestionLists";


    // Load real-time service client libs
    HINSTANCE rtsClient = LoadLibrary(L"rtsClient.dll");

    // Get methods addresses
    typedef RTServiceClient* (*createEIMRTClient) ();
    createEIMRTClient _createEIMRTClient = (createEIMRTClient)GetProcAddress(rtsClient, "Create_EIMRTClient");

    typedef void (*destructEIMRTClient)(RTServiceClient* p);
    destructEIMRTClient _destructEIMRTClient = (destructEIMRTClient)GetProcAddress(rtsClient, "Destruct_EIMRTClient");

    // Create a real-time service client instance
    RTServiceClient *rts = _createEIMRTClient();
    try
    {
        //Connect to the service host, exit if the connection failed.
        rts->connect(host,portNumber);
    }
    catch(RTServiceClientError& x)
    {
        cout << "ERROR: connect to service " << serviceName << " failed: " << x.message();
        exit(-1);
    }

    // The initial request
    char* xmlInputStr =
                     "<?xml version=\"1.0\" encoding = \"UTF-8\"?> \
                      <ns1:Rt_gac_suggestionlists_in xmlns:ns1=\"Rt_gac_suggestion_lists\"> \
                      <country>  AUSTRALIA      </country> \
                      <firm>                    </firm> \
                      <address1> Jubilee        </address1> \
                      <address2>                </address2> \
                      <address3>                </address3> \
                      <address4>                </address4> \
                      <postcode>                </postcode> \
                      <locality1> Mount Gambier </locality1> \
                      <locality2>               </locality2> \
                      <region>    SA            </region> \
                      <suggestion_reply1>       </suggestion_reply1> \
                      <suggestion_reply2>       </suggestion_reply2> \
                      <suggestion_reply3>       </suggestion_reply3> \
                      <suggestion_reply4>       </suggestion_reply4> \
                      <suggestion_reply5>       </suggestion_reply5> \
                      <suggestion_reply6>       </suggestion_reply6> \
                      </ns1:Rt_gac_suggestionlists_in>";

    try
    {
        //Invoke the service with the initial request
        cout << "Invoking service '" << serviceName << "' with XML '" << xmlInputStr << "' ...\n";
        char* response = rts->invoke( serviceName, xmlInputStr );

        if (response != NULL)
            cout << "Received response: '" << response << "'\n";
    }
    catch(RTServiceClientError& x)
    {
        cout << "ERROR: Invoking service " << serviceName << ": " << x.message();
        return;
    }

    //Disconnect the client from the service host.
    rts->disconnect();

    // Destruct the client instance
    _destructEIMRTClient(rts);
}
  • No labels