Since I wrote my various articles on connecting forms to databases, I’ve had numerous inquiries about connecting to web services so here’s the long-overdue article on doing just that.

In Designer, you not only have the ability to create data connections to schemas (directly or based on sample XML data) and databases, you can also connect to web services. Web services are online applications that return information in response to specific requests. These requests and responses are sent and received via the SOAP protocol in various formats, as specified by the web service in an XML-based language called WSDL (you guessed it — Web Service Description Language).

Advantages of Web Services

One of the main advantages of using web services is to create an abstraction from server components such that clients ask the web service for information (via its various operations) without having to know the specifics about the server-side implementation (e.g. the web service may retrieve information from an Access database one day and later switch to a MySQL database but the client would still retrieve information in the same way, via the web service’s operations). If implemented correctly, web services can also provide better security by preventing clients from connecting directly to databases from the Internet, for example.

Supported Web Service Operation Types

To keep things simple, the WSDL basically describes the operations that are supported by the web service. To execute an operation, the client must submit a request to a web service operation and, upon receipt, the web service will execute the operation and submit a response back to the client, possibly containing data. Furthermore, these requests and responses are submitted in specific formats using specific data types which the WSDL also describes for each operation.

Document/Literal — Supported in Designer and Acrobat

The most important thing to note here is that Designer only supports executing web service operations which are specified as document/literal. This means that an operation defines XML schemas for its request and response formats. In turn, the XML data adhering to an operation’s request and response schemas can easily be gathered from a form using basic data bindings (a way, in XFA, to link a particular field’s value to a specific data node in a data connection).

RPC/Encoded — Supported in Acrobat only

Some of you more familiar with web services will note that operations may also be specified in the rpc/encoded format. Designer does not support executing such operations at this time because the data formats are more complex than straight XML schemas. The Google Search web service is an example. You may choose to connect to such operations using Acrobat’s SOAP object but beware that there is no server-side support for this object. This article will focus on doc/literal operations since they’re fully supported across all LiveCycle products.

Creating the Data Connection

Now that you have a basic understanding of web services and the document/literal operation type supported in Designer, let’s see how simple it is to execute a web service operation and receive a response.

First, you must create a new data connection to a web service. In the Data View palette’s menu, choose the "New Data Connection…" command, select "WSDL File" as the type and continue to the next step:

At the second step, you’ll be asked to specify the WSDL file to connect to. For this tutorial, you’ll connect to a little web service called "Echo Employee" which simply defines 4 fields for the request and returns their data back as the response:

http://www.whitemesa.net/wsdl/r3/compound2.wsdl

When you click the "next" button, Designer will attempt to connect to the WSDL file and retrieve a list of its document/literal operations. If successful, you’ll get to the third step where you can choose the operation that will be executed by the data connection:

In this case, there is only one operation. Choose "echoEmpolyee" and click on the "finish" button.

Designer will then use the data type definitions for the request and response formats of the echoEmployee operation to define a data structure in the new data connection in the Data View palette:

The only thing that remains is to create 2 sets of fields (one which will be used to submit the data for the request and another to receive the response) and a button to execute the operation. This can be done very easily simply by dragging and dropping the "DataConnection" node (or whatever you named your data connection earlier when you created it) onto your form. This will automatically generate all the necessary fields and bindings as well as the execute button:

Notice, in the Data View palette, that the icons pertaining to the various request/response fields are different than the usual binding icons: The request field icons have a single red arrow pointing to the left (indicating that their data is outgoing) and the response field icons have a single green arrow pointing to the right (indicating that their data is incoming).

You should now have the following object block on your form (from the earlier drag and drop operation) with fields of types matching the data which they will contain (text, numeric, etc.):

That’s it! All that remains is to preview your form using Acrobat Standard or Pro (since connecting to a web service implies importing data which is only possible using Acrobat Standard/Pro or an extended PDF, via LC Reader Extensions, in Reader).

In the preview window, fill-in the top 4 fields and click on the "Echo Employee Btn".

If you correctly configured your data connection and created the necessary fields and bindings, Acrobat should connect to the web service, submit the data you entered as the request to the "echoEmployee" operation which will, in turn, respond with the same data to Acrobat, at which point the response data will be pushed into the response fields (directly below the 4 top fields):

Note that the fact that the same data is returned is only specific to this web service and its "echoEmployee" operation. Other web service operations may return different data (e.g. you submit a record ID and the response contains all the information for an individual) or not data at all (if the operation is simply meant to add a new record in a back-end system, for example).

Update (May 24, 2007): Zee, a colleague at flexlive.net, has posted a video tutorial on connecting a form to a web service. If you’re looking for something with more context, you might want to try that since you get to see the actual steps in Designer which I’m attempting to describe.

Update (Sep 2, 2010): faith pointed-out that the “Echo Employee” web service I had based this tutorial’s sample on no longer works. In fact, it doesn’t seem to exist anymore. I have kept the original sample since the tutorial is based on it and I have provided a new sample PDF based on a different web service (see below).

Sample Form

In case you have trouble following these steps, you may download the "solution" file here:

Download (original) [pdf]

Download (updated Sep 2, 2010) [pdf]

Minimum Sample Requirements: Designer 7.x, Acrobat 7.x.

Sep 2, 2010 — Add new sample PDF based on different web service since original sample PDF’s web service is no longer available online.

---

Posted by Stefan Cameron on May 21st, 2007
Filed under Acrobat,Data Binding,Tutorials

---

I’ve lost count of how many times, over the past year, I’ve been asked if there was a good book on designing forms using LiveCycle Designer. Until now, the answer was always an unfortunate “no”.

Well, I’m very happy to announce that J.P. Terry from SmartDoc Technologies has been hard at work over the past few months on a book titled, Creating Dynamic Forms with Adobe LiveCycle Designer.

Based on some of the chapters I’ve reviewed so far, this is going to be an excellent resource for those of you who might not know where to start or perhaps would like a few pointers on good form design. I, for one, am really excited about this since it’s the first (of hopefully many more to come) book about the product and technologies I work on every day. It’s almost like a milestone — Designer’s first book.

No word yet on a specific release date but I’ll keep you all posted as I get more details over the coming months.

So how about you? Are you looking forward to a book on Designer and dynamic forms?

---

Posted by Stefan Cameron on May 18th, 2007
Filed under Books,Designer,Instance Manager,Scripting,Tables,Tutorials

---

Just a quick note to let all of you know I’ll be attending BFMA Symposium 2007 in St. Louis, Missouri, over the course of the next few days. I’m looking forward to meeting many of our customers to get some feedback on Designer 8.0 and answer some questions in person for a change.

I’ll also be giving a demo of all the new and exciting features available in Designer 8.0 along with a sneak peak at what’s in store for the next release during Adobe’s “Product Tutorial” session (#09 at 9:45am on Monday, May 7, for those of you attending) led by Alain Roy, one of our Product Managers. Please join us if you can!

If you’re attending, you’ll also want to make sure you check-out Adobe’s “E-Forms Come of Age” session (#40 at 3:00pm on Tuesday, May 8 ) where Alain will demonstrate a new feature we’ve been working-on that will completely change the way your users/customers interact with your forms — you won’t want to miss this!

---

Posted by Stefan Cameron on May 5th, 2007
Filed under BFMA Symposium,Conferences

---

Description

If an exception is thrown during a web service (WSDL) data connection request call (you’re executing a request to a web service in order to get a response in return), the bound data accumulated by Acrobat (for submitting the request to the web service) is not cleared from the data connection’s "request data buffer/queue" (to put it in simple terms).

For example, if your form attempts to execute a WSDL data connection while there is no active connection to the Internet, the call to the

xfa.connectionSet.WSDLConnectionName.execute

method will fail with an exception (which you can catch by placing the call within a try-catch block) however the form data accumulated to be sent as part of the request operation isn’t cleared. If you are then resetting the form by clearing repeatable subform instances that contained data at the time the data connection was executed and then re-execute the data connection, the old instance data will still be sent as part of the new request even though it’s no longer part of the form (which is clearly not what you would want/expect).

Workaround

Fortunately, you can manually clear the "request data buffer/queue", located in

xfa.datasets.connectionData.WSDLConnectionName

where "WSDLConnectionName" is the name of your WSDL data connection, simply by using the "remove" function as follows:

xfa.datasets.connectionData.WSDLConnectionName.remove();

Fix

Please refer to the Bug List for updated information on the version(s) affected by this bug as well as if and when it was/will be fixed.

---

Posted by Stefan Cameron on May 5th, 2007
Filed under Acrobat,Bugs

---

Description

When executing a web service (WSDL) data connection, only the last instance of a repeatable element is included in the request.

Here’s an example of a repeatable WSDL element (the “Detail” element containing item number information):

<xsd:element name="Details">
   <xsd:complexType>
      <xsd:sequence>
         <xsd:element name="Detail" maxOccurs="unbounded">
            <xsd:complexType>
               <xsd:sequence>
                  <xsd:element name="ItemNumber" type="xsd:string"/>
               </xsd:sequence>
            </xsd:complexType>
         </xsd:element>
      </xsd:sequence>
   </xsd:complexType>
</xsd:element>

The correct behaviour is that all instances of a repeatable section are used in the request sent to the web service.

Workaround

Unfortunately, there are no workarounds for this problem however the bug will be fixed in the next release of Acrobat.

Fix

Please refer to the Bug List for updated information on the version(s) affected by this bug as well as if and when it was/will be fixed.

---

Posted by Stefan Cameron on May 2nd, 2007
Filed under Acrobat,Bugs

---