technical note 562 using a local business service to customize the soap envelop
TRANSCRIPT
Technical Note 562: Using a Local Business Service To Customize the SOAP Header for an Outbound Web Service in Siebel 7.5.x
Background In many instances, Web services utilize specialized Simple Object Access Protocol (SOAP) headers for common tasks such as authentication, authorization and logging. To support this Web service extensibility mechanism, Siebel Applications support the notion of a local business service as a transport option for Outbound Web Services. For assistance in setting up an Outbound Web Service, please refer to Technical Note 475. Summary The intention of this document is to explain the concept and provide a sample script to demonstrate how to customize the SOAP header using a local business service. When a local business service is specified as the transport mechanism, the Siebel Web Services infrastructure can route the outbound message to a specified business service. Within this business service, you can perform additional processing of the SOAP Message before the message’s delivery to the Web Service Endpoint as shown in the diagram below.
The input to the local business service is a property set that represents the SOAP request. Once the SOAP request is inside the local business service, additional SOAP headers may be added to address infrastructure requirements. This is done by direct modification of the input property set via eScript or Siebel VB. A portion of the sample script for a local business service used to add a custom SOAP header to an Outbound Web Service request in Version 7.5 and in Version 7.7 and higher is shown below. NOTE: The following scripts are provided as an example only. The Version 7.5 script and the Version 7.7 and higher script are identical up to and including line 45. They differ after this because of differences in the structure of the output property set returned to the local business service, called hpOut in the samples, which includes the SOAP response. To successfully use either script, you will need to define the local variables, set up error handling, and destroy objects. Version 7.5 sample script
…
1 // local variables & error handling are omitted for clarity
2 soapHdr.SetType("SOAP-ENV:header");
3
4 // populate SOAP header elements
5 appId.SetType("ns1:ApplicationID");
6 appId.SetValue("Siebel");
7 pwd.SetType("ns1:PWS");
8 pwd.SetValue("123456789");
9 langCd.SetType("ns1:Lang");
10 langCd.SetValue("ENU");
11 uName.SetType("ns1:userID");
12 uName.SetValue("[email protected]");
13
14 // populate the eProfileHeader element
15 profileHeader.SetType("authHeader");
16 profileHeader.SetProperty("xmlns:ns1",
"http://siebel.com/authHeaders");
17 profileHeader.AddChild(appId);
18 profileHeader.AddChild(pwd);
19 profileHeader.AddChild(langCd);
20 profileHeader.AddChild(uName);
21
22 // SOAP header property set. Once this is complete, add the SOAP
header
23 // as a child of the Input property set (which contains the
SOAP:body)
24 soapHdr.InsertChildAt(profileHeader, 0)
25 Inputs.InsertChildAt(soapHdr, 0);
26
27 // convert property set to well defined SOAP/XML document
28 // due to XML Hierarchy Converter, need to create add a child
element of type XMLHierarchy
29 childPS.SetType("XMLHierarchy");
30 childPS.AddChild(Inputs);
31 inPs.AddChild(childPS);
32 inPs.SetProperty("EscapeNames", "FALSE");
33 inPs.SetProperty("GenerateProcessingInstructions", "FALSE");
34 xmlSvc.InvokeMethod("XMLHierToXMLDoc", inPs, outPs);
35
36 // proxy the request through trace utility to view SOAP document
37 // set custom HTTP header - SOAPAction
38 outPs.SetProperty("HTTPRequestURLTemplate",
"http://localhost:9000/search/beta2");
39 outPs.SetProperty("HTTPRequestMethod", "POST");
40 outPs.SetProperty("HTTPContentType", "text/xml; charset=UTF-8");
41 outPs.SetProperty("HDR.SOAPAction","customSOAPActionValue");
42
43 // invoke Web Service using standard HTTP protocol
44 httpSvc.InvokeMethod("SendReceive", outPs, hpOut);
45
46 // Converting the SOAP document to a XMLHierarchy propset47
xmlSvc.InvokeMethod("XMLDocToXMLHier", hpOut, tmp);48
49 // removing XMLHierarchy, returning the SOAP header and SOAP body
50 soapDoc = tmp.GetChild(0).GetChild(0);
51 Outputs.AddChild(soapDoc);
52 …
Version 7.7 and Higher sample script
…
1 // local variables & error handling are omitted for clarity
2 soapHdr.SetType("SOAP-ENV:header");
3
4 // populate SOAP header elements
5 appId.SetType("ns1:ApplicationID");
6 appId.SetValue("Siebel");
7 pwd.SetType("ns1:PWS");
8 pwd.SetValue("123456789");
9 langCd.SetType("ns1:Lang");
10 langCd.SetValue("ENU");
11 uName.SetType("ns1:userID");
12 uName.SetValue("[email protected]");
13
14 // populate the eProfileHeader element
15 profileHeader.SetType("authHeader");
16 profileHeader.SetProperty("xmlns:ns1",
"http://siebel.com/authHeaders");
17 profileHeader.AddChild(appId);
18 profileHeader.AddChild(pwd);
19 profileHeader.AddChild(langCd);
20 profileHeader.AddChild(uName);
21
22 // SOAP header property set. Once this is complete, add the SOAP
header
23 // as a child of the Input property set (which contains the
SOAP:body)
24 soapHdr.InsertChildAt(profileHeader, 0)
25 Inputs.InsertChildAt(soapHdr, 0);
26
27 // convert property set to well defined SOAP/XML document
28 // due to XML Hierarchy Converter, need to create add a child
element of type XMLHierarchy
29 childPS.SetType("XMLHierarchy");
30 childPS.AddChild(Inputs);
31 inPs.AddChild(childPS);
32 inPs.SetProperty("EscapeNames", "FALSE");
33 inPs.SetProperty("GenerateProcessingInstructions", "FALSE");
34 xmlSvc.InvokeMethod("XMLHierToXMLDoc", inPs, outPs);
35
36 // proxy the request through trace utility to view SOAP document
37 // set custom HTTP header - SOAPAction
38 outPs.SetProperty("HTTPRequestURLTemplate",
"http://localhost:9000/search/beta2");
39 outPs.SetProperty("HTTPRequestMethod", "POST");
40 outPs.SetProperty("HTTPContentType", "text/xml; charset=UTF-8");
41 outPs.SetProperty("HDR.SOAPAction","customSOAPActionValue");
42
43 // invoke Web Service using standard HTTP protocol
44 httpSvc.InvokeMethod("SendReceive", outPs, hpOut);
45
46 // Converting the SOAP document to a propset using the XML
Converter, returning the SOAP header and SOAP body
47 xmlCtr.InvokeMethod("XMLToPropSet", hpOut, Outputs);
48 …
After you have created your business service, make sure to compile it into the Siebel SRF. The example below displays the resulting SOAP document generated by the local business service. Note that the addition of the <authHeader> element in the SOAP header corresponds to the structure defined between lines 4 through 20 in the sample code above.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:header>
<authHeader xmlns:ns1="http://siebel.com/authHeaders">
<ns1:ApplicationID>Siebel</ns1:ApplicationID>
<ns1:PWS>123456789</ns1:PWS>
<ns1:Lang>ENU</ns1:Lang>
<ns1:userID>[email protected]</ns1:userID>
</authHeader>
</SOAP-ENV:header>
<SOAP-ENV:Body>
…
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
To use the local business service in an Outbound Web Service, the Outbound Web definition should be changed as follows:
1. In the Siebel client, navigate to the Web Services Administration view via the Site Map.
2. Select Outbound Web Services from the Web Services Administration view.
3. Highlight the desired Outbound Web Service on Outbound Web Services List Applet.
4. In the Service Ports list applet, change the Transport and Address columns as follows:
a. Select Local Business Service in the Transport column. b. Enter the name of the local business service in the Address column.
5. Restart the Siebel component after changing the Outbound Web Service definition to
allow the changes to take effect.