Global Address Cleanse – Suggestion Lists
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
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_output.xsd -- The output message format for the real-time service/job
- rt_gac_suggestionlists_input.xml -- A testing file which contains a sample input
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
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,
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.
User Name: administrator
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:
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
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:
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:
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:
5. Create an RTServiceClientX object
From the main method create an RTServiceClientX object.
6. Connect to the access server
Create a connection to the Access Server on which the GAC SuggestionLists Real-time service configured
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.
8. Setup real-time service name
Specify that the service we want call is RtGacSuggestionLists
9. Send initial request to access server
Send requests from the client application using the Invoke method
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:
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.
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.
The suggestion selection is invalid. Example: 8 was selected but there are only 5 suggestions.|
The primary range in the input field is invalid. Example: Street number 244 was entered, but only numbers ranging from 100-200 are valid.
The floor number in the input field is invalid.
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.
12. Run the Java program
Click the run button to run the program and check the output from the Console tab.
Sample Code – Java
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