Orbeon Forms User Guide

Web Services

1. Overview

Your Orbeon Forms applications can consume and expose Web services.

2. Consuming Web Services

Applications built on Orbeon Forms call Web services using the delegation processor. For example, this is how you would call the famous highway traffic Web service to get the conditions on the 101 highway in California from an XPL:

<p:processor name="oxf:delegation"><p:input name="interface"><config><service id="ca-traffic" type="webservice" endpoint="http://services.xmethods.net/soap/servlet/rpcrouter"><operation nsuri="urn:xmethods-CATraffic" name="getTraffic"/></service></config></p:input><p:input name="call"><delegation:execute service="ca-traffic" operation="getTraffic" xmlns:delegation="http://orbeon.org/oxf/xml/delegation"><hwynums>101</hwynums></delegation:execute></p:input><p:output name="data" id="traffic"/></p:processor>

The output of that call would be:

<return xsi:type="xsd:string" xmlns:delegation="http://orbeon.org/oxf/xml/delegation" xmlns:v="http://orbeon.org/oxf/xml/validation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:f="http://orbeon.org/oxf/xml/formatting">reported as of Wednesday, July 2, 2003 at 16:18 . Slow for the Cone Zone US 101 [LOS ANGELES & VENTURA CO.'S] NO TRAFFIC RESTRICTIONS ARE REPORTED FOR THIS AREA ...</return>

3. Exposing Web Services

To expose a Web service, follow these steps:

  1. Declare the Web service in the page-flow.xml, just like a regular page with no view. The Web services will be implemented in an XPL file. The Orbeon Forms example portal features a Web service that sends instant messages to Yahoo! users. It is declared in the page-flow.xml as follows:

    <page path-info="/examples/im" model="oxf:/im/yim-webservice.xpl"/>

  2. To get the SOAP envelope sent to the Web service, use the Request generator and include the path /request/body, specifying the xs:anyURI type for the result. The resuting URI can then be parsed with the URL generator:

    <!-- Extract request body as a URI --><p:processor name="oxf:request"><p:input name="config"><config stream-type="xs:anyURI" xmlns:xs="http://www.w3.org/2001/XMLSchema"><include>/request/body</include></config></p:input><p:output name="data" id="request"/></p:processor><!-- Dereference URI --><p:processor name="oxf:url-generator"><p:input name="config" href="aggregate('config', aggregate('url', #request#xpointer(string(/request/body))))"/><p:output name="data" id="file"/></p:processor>

    You will find the SOAP envelope sent by the client of your Web service as the resulting file. For example:

    <soapenv:Envelope soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Body>...</soapenv:Body></soapenv:Envelope>

  3. Generate a SOAP envelope that responds to the client's request and send it to the client with the XML serializer, as follows:

    <p:processor name="oxf:xml-serializer"><p:input name="config"><config/></p:input><p:input name="data" href="#response"/></p:processor>