Web Services - data collections example
This example demonstrates how to extract data from data collections returned by a Web Service. See Using Web Services in FileNet workflow for examples of other features.
The LocInfo ZipCode Web Service used in this example is provided by Tilisoft, and is accessible from XMethods com. At runtime, the launch user enters a telephone area code, and the Invoke step sends the request message to the specified Web Service, which returns zip code data for all areas with the specified area code. We use two user steps to view the returned zip code data and to view extracted items.
To create the demonstration workflow
- In Process Configuration Console, use the following steps to allow the workflow author to directly enter links for Web Services.
- Select the isolated region, then select Properties from the context menu.
- On the UDDI Registry List tab, select Enable Process Designer to enter WSDL links without browsing for Web Services.
- Save the configuration change.
- In Process Designer, specify the workflow name and Web Service for this workflow.
- In Workflow Properties >> General tab, specify a workflow name and subject (ZipDataCollection).
- Specify the Web Services.
- On the Web Services >> Partner Links tab, enter a name for the Partner Link (inv1).
- In the WSDL URL field, enter the following:
http://www.tilisoft.com/ws/LocInfo/ZipCode.asmx?WSDL
- Click in the Port Type field and wait a few seconds for the connection to the service.
Select the returned port, ZipCodeSoap.
TIP Click Invoke in the Type field to update the data. A new blank line will display in the Partner Links table.
- Leave the Workflow Properties dialog box open.
- From the Web Services step palette, add an Invoke step to the workflow map.
- In the Step Properties pane, on the General tab, select the Partner Link—inv1, then select the Operation—ListByAreaCode.
- For Message type, select XML.
- In the Outgoing Message, note that this web service requires input data (string) for AreaCode; in the Incoming XML Data Field, it requires an XML data field for the reply message.
On the Workflow Properties >> Data Fields tab, create two string fields: AreaCode and XMLReturn.
(For this example we are defining XMLReturn as a string rather than an XML data field because we want to be able to see the returned data in the step processor—the default HTML step processor does not display XML data fields. If you want to see an XML data field in the step processor, use the Java™ step processor for the CheckReturn step below.)
- On the General tab of InvokeZip step properties, substitute AreaCode for _string in the outgoing message, and specify XMLReturn for the Incoming XML Data Field.
- On the workflow map, select the Launch step and specify the AreaCode as a parameter—the launch user will provide a valid telephone area code as input for this Web Service.
- To enable the user to check the returned data, add an Activity step after the Invoke step. Name the Activity step CheckReturn.
- Specify yourself (or F_Originator) as the participant for this step.
- Specify AreaCode and XMLReturn as parameters. At runtime, the XMLReturn field contains the data returned by the web service.
- Add another Activity step—ViewValues—and specify yourself as the participant. We will use Assignments at this step to extract data from the XML data returned by the web service.
- On the Workflow Properties >> Data Fields tab, create the following fields:
- ArrayOfAll (string array) - each element in this array will contain the data of one element of the returned collection.
- ArrayOfZips (string array) - each element in this array will contain the zip code from the corresponding element in the collection.
- SingleStructure (string) - this field will contain all of the data in a specified element in the collection.
- Select the ViewValues step and select these three data fields as parameters for the step.
- With the ViewValues step selected, click the Assignments tab, and specify the following field assignments for Before Execution:
Name |
Expression |
ArrayOfAll |
xmlstringarrayexpr(XMLReturn, "/", "/*[local-name()=""ListByAreaCodeResponse""]/*[local-name()=""ListByAreaCodeResult""]/*[local-name()=""diffgram""]/*[local-name()=""ZipCodeData""]/*[local-name ()=""ZipCodeInfo""]") |
ArrayOfZips |
xmlstringarrayexpr(XMLReturn, "/", "/*[local-name()=""ListByAreaCodeResponse""]/*[local-name()=""ListByAreaCodeResult""]/*[local-name()=""diffgram""]/*[local-name()=""ZipCodeData""]/*[local-name()=""ZipCodeInfo""]/*[local-name()=""ZIPCODE""]") |
SingleStructure |
ArrayOfAll[5] |
- Add the appropriate routes between the steps.
- Validate, save, transfer, and launch the workflow.
-
In your inbox, open the CheckReturn step and check XMLReturn for the data returned by the web service.
The first part of this data is a schema. The rest of the data contains the information for the area code you entered. The amount of data can be quite large, depending on the area code.
Complete the step.
- Open the ViewValues step and check the data extracted into the three data fields.
- In ArrayOfAll, the data for each zip code in the area code is extracted into each element of the string array.
- In ArrayOfZips, each zip code is extracted into an element.
- SingleStructure contains all the data from a single element of ArrayOfAll.
NOTE When using the procedure described above for extracting data from the returned data collection, it is important to be aware of data elements that might be blank or missing. For example, in the ArrayOfZips array, the following cases are possible.
ZIPCODE element with data |
ZIPCODE element blank |
ZIPCODE tag missing |
 |
 |
 |
The zip code data is present in the ZIPCODE tag. |
The ZIPCODE tag is present in XMLReturn, but the data for the second item is blank. |
The ZIPCODE tag is missing for the second set of data in XMLReturn, so the zip code from the third set of data fills the second element in the ArrayOfZips--all zip code values 'move up' in the array. |