/
/ $Header: whdev/2.0/owb/shiphome/owb/misc/mappingWS/readme.txt /main/1 2008/12/29 19:25:06 swu Exp $
/
/ readme.txt
/
/ Copyright (c) 2008, Oracle. All Rights Reserved.
/
/   NAME
/     readme.txt - <one-line expansion of the name>
/
/   DESCRIPTION
/     <short description of component this file declares/defines>
/
/   NOTES
/     <other useful comments, qualifications, etc.>
/
/   MODIFIED   (MM/DD/YY)
/   swu         12/28/08 - Creation
/

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
DESCRIPTION:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
The script "use_webservice_in_mapping.tcl" is used to for consuming webservice within mapping, this is implemented by functions. 

After run this script, an expert module "WSDL_UTL" and a public transformation package "WB_WEBSERVICE" will be created. 
There are 2 transformations and 1 procedure under "WB_WEBSERVICE":
HTTP_SET_PROXY: this procedure will be used to set the http proxy for UTL_HTTP call, often used as pre_process in mapping.
WS_INVOKE_P: this function will call a web service through UTL_HTTP package
WS_INVOKE: special case for WS_INVOKE_P, no parameters.

There are 2 experts under "WSDL_UTL":
CREATE_FUNCTION_FROM_WSDL: this expert will generate functions based on the WSDL file, the generated functions will call WS_INVOKE_P to call web service.
CREATE_UTILS_FROM_WSDL: this expert will generate pluggable mappings which is used to help extract the value from the returned xml document of UTL_HTTP call.

After the functions and pluggable mappings are generated, we can use them in the mapping to call the web service and get the result.

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
RUN SCRIPT:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
We need modify the information in the script before run it, like the repos owner information and so on.

"use_webservice_in_mapping.tcl" is a tcl script, you can run it by "OMBPlus.sh use_webservice_in_mapping.tcl" or run "OMBPlus" first, then source the script. 

Make sure you are running this script with X11 DISPLAY (like in vnc), it will failed if no X11 DISPLAY is available.

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
RUN EXPERT:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
After the script has been run, the experts and functions are created. Then we can login the owb client, then goto public project and run the expert.

We need enter a private project first before run the experts, then the expert will ask the user to select an WSDL file for processing, then we need to specify the name for holding the generated functions or pluggable mappings. The generated functions are under "Public Transformations" in the public project, and the pluggable mappings are under "Pluggable Mappings" in the chose private project.

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
USE IN MAPPING:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
After corresponding functions are generated, you can use them within mapping just as normal functions. An example wsdl is: http://www.dataaccess.nl/wk2006/footballpoolwebservice.wso?WSDL

The normal process is:
1, add the function to the mapping, like "Cities"
2, provide input for the function if there is any
3, select a pluggable mapping for extracting the value, the proper pluggable mapping name can be found from the WSDL, the output message of the operation. here it is "CITIESRESPONSE"
4, check the return result of the upstream pluggable mapping, if it is simple types which you are interested in, then it is done; otherwise, keep on finding the pluggable mapping for extracting the complex type. Here, the return of "CITIESRESPONSE" is "CITIESRESULT", still a complex type, then we need also add "CITIESRESULT" pluggable mapping for further extraction. The output of "CITIESRESULT" are simple types, then the extraction process is done. We can load the value to the target table then.
5, Since we are using UTL_HTTP to call web service, we might need set http proxy for that. Then we can add the "Pre Mapping Process" and bind it to "HTTP_SET_PROXY" procedure, then provide values for the procedure by using "Mapping Input Parameter"
6, Change the generation mode of the mapping to "SET BASED", as we are using "extractValue" for the expression in the mapping.
7, deploy the "WB_WEBSERVICE" package, deploy the used functions (goto Control Center, select an oracle module and you can find the public transformations); deploy the mapping and related tables.
8, run the mapping and get the result.

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
NOTES:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
There are several points that we should be aware of:
1, Oracle 11g has enhanced security features, so we need to add the URL of the web service to the ACL, otherwise, we will not get the correct result.
2, Pluggable mapping is treated as cardinality changing operator, so sometimes you might need use Join or Set operator to connect attributes from different groups to target table (enhancement bug 4319045), or you can simply take a look into the pluggable mapping and write your own expression operators.