11.4. SOAP Web services As we saw in 9.3.6.5, "Starting from a SOAP Web service", on page 212, InfoPath can send and receive data from SOAP Web services. When the entire XML document is to be passed to (or retrieved from) the Web service, the setup is simply to design the form based on the Web service (as was described in that chapter). However, you may want to call a Web service as a secondary data source, for the purpose of validating or completing a form. For example, Web services are available that will validate a ZIP code and return information about it, such as the city and state. We could set up our order form to allow the user to enter a ZIP code, then call a Web service to retrieve the city and state and fill them in automatically. We will use the ZIP code Web service that was introduced in 6.2.1, "The ZIP code Web service", on page 123.[3] We set it up as a secondary data source in the same way we set up a Web service as a primary data source in 9.3.6.5, "Starting from a SOAP Web service", on page 212. [3] If you have not read that section of the book, you should do so before proceeding. We chose the operation GetInfoByZIP from the list after entering http://www.webservicex.net/uszip.asmx?WSDL as the Web service URI. We named the secondary data source GetInfoByZIP. For a working copy of this example, use the order_ws.xsn file. 11.4.1 Web services interface document We won't be using the Office Web Services Toolkit that we used with Word. It doesn't – and doesn't need to – support InfoPath. That's because InfoPath hides the complexity of SOAP natively, with built-in support for parsing and generating SOAP messages. InfoPath communicates with the Web service using SOAP documents whose envelopes contain the input and output message elements. To provide a SOAP-free interface to your scripts, it incorporates those message elements in a document that we refer to as a "Web services interface document".[4] [4] The document and its related schema documents are stored in the form template. The file names are based on the name you gave to the secondary data source. In our case, the document looks something like Example 11-6. It has two namespaces: one with the prefix ws for the Web service message elements, and one with the prefix dfs for InfoPath's housekeeping elements. Example 11-6. Interface document with message elements as sent to the Web service <dfs:myFields xmlns:dfs= "http://schemas.microsoft.com/office/infopath/2003/dataFormSolution" xmlns:ws="http://www.webserviceX.NET"> <dfs:queryFields> <ws:GetInfoByZIP> <ws:USZip>49684</ws:USZip> </ws:GetInfoByZIP> </dfs:queryFields> <dfs:dataFields> <ws:GetInfoByZIPResponse> <ws:GetInfoByZIPResult/> </ws:GetInfoByZIPResponse> </dfs:dataFields> </dfs:myFields>
We'll describe the document first, then show you how to write the script that creates and reads it. 11.4.1.1 Service request Before the document is sent to the service, the input message is complete: there is an input parameter in ws:USZip. Although there is an element in the output message for the result (ws:GetInfoByZIPResult), it is empty. 11.4.1.2 Service response After the Web service is called, the document has the service output in the content of the GetInfoByZIPResult element, roughly as shown in Example 11-7. The only change to the document is the NewDataSet element that was returned with the requested information. Example 11-7. Interface document after output element is completed by the Web service <dfs:myFields xmlns:dfs= "http://schemas.microsoft.com/office/infopath/2003/dataFormSolution" xmlns:ws="http://www.webserviceX.NET"> <dfs:queryFields> <ws:GetInfoByZIP> <ws:USZip>49684</ws:USZip> </ws:GetInfoByZIP> </dfs:queryFields> <dfs:dataFields> <ws:GetInfoByZIPResponse> <ws:GetInfoByZIPResult> <NewDataSet> <Table> <CITY>Traverse City</CITY> <STATE>MI</STATE> <ZIP>49684</ZIP> <AREA_CODE>616</AREA_CODE> <TIME_ZONE>E</TIME_ZONE> </Table> </NewDataSet> </ws:GetInfoByZIPResult> </ws:GetInfoByZIPResponse> </dfs:dataFields> </dfs:myFields>
11.4.2 Writing the script Example 11-8 shows the script that causes InfoPath to invoke the Web service and update the form with the returned city and state. Example 11-8. Script that invokes the Web service function msoxd_ns1_postal_code::OnAfterChange(eventObj) { if (eventObj.IsUndoRedo) return; //Get a reference to the Web service data source var webService = XDocument.DataObjects.Item("GetInfoByZIP") webService.DOM.setProperty("SelectionNamespaces", "xmlns:dfs=" + "'http://schemas.microsoft.com/office/infopath/" + "2003/dataFormSolution'" + " xmlns:ws='http://www.webserviceX.NET' ") //Set the value of the ZIP code node in the input message var zipParm = webService.DOM.selectSingleNode( "/dfs:myFields/dfs:queryFields/ws:GetInfoByZIP/ws:USZip" ) zipParm.text = eventObj.Site.text //call the Web service webService.Query() //Set the city and state values in the form XDocument.DOM.selectSingleNode( "//ns1:city" ).text = webService.DOM.selectSingleNode( "//CITY" ).text XDocument.DOM.selectSingleNode( "//ns1:state" ).text = webService.DOM.selectSingleNode( "//STATE" ).text }
line 1 The function is executed when a change is made to the postal_code field of the primary document. line 3 If the change is an undo or redo of a previous change, the script exits with no action. line 6 A data object is constructed with the structure and properties of an empty Web service interface document for our data source (GetInfoByZIP). The variable webService is created to point to the object. lines 8 through 11 The namespace prefixes for the interface document are declared and stored as properties of the webService object. lines 14 and 15 The variable zipParm is created as a pointer to the (currently empty) ws:USZip node of the webService object. line 16 The text of the postal_code node of the primary document (i.e. the ZIP code that was typed into the form by the user) is assigned to the USZip node of the input message through the pointer variable zipParm. line 19 Line 19 calls the Web service. InfoPath copies the input message element from the webService object and includes it in a SOAP document that it sends to the service. When it receives the return SOAP document, it extracts the content of the output message element and inserts it into the webService object. The XML linearization of the webService object now looks like Example 11-7. lines 21 through 24 The CITY and STATE values from the webService object are copied to the corresponding nodes in the primary XML document. | 
