Connecting to a web service usually means using import bindings to capture the response but what if you wanted to do something special with the response? What if the response wasn’t exactly correct for merging into your form (e.g. you just wanted to extract a part of the response and push it into your form somewhere)?

You could still use import bindings (set using the “Object palette > Bindings tab > Import/Export Bindings property”) but then you might have to hide most — or all — of those fields if you didn’t want to expose them. You would wait for the web service data connection to execute, then find the field that contains the piece of data you want and set it where it needs to go. This isn’t ideal, however, because Designer doesn’t expose any events, in the Script Editor, that would let you know that you now have data from the web service response in your form. Furthermore, having those extra fields around could add a lot of unnecessary weight (read: file size).

postExecute event

Unless you have studied the XML spec or deciphered its existence from the LC Designer ES Scripting Reference, you most likely don’t know about this event because Designer’s Script Editor palette doesn’t expose it. It’s purpose is to allow for post-processing of a web service response after a particular data connection is executed. The response data is temporarily stored in

xfa.datasets.connectionData.{DataConnectionName}

for the duration of the data connection’s PostExecute event.

Since it’s not exposed in the Script Editor, you have to go to the XML Source in order to set it on a form object — typically a subform. What follows is the XFA definition for the WebServiceDC data connection’s PostExecute event:

<event activity="postExecute" ref="$connectionSet.WebServiceDC">
    <script contentType="application/x-javascript">
        // do something...
    </script>
</event>

Note that I said this was the PostExecute event for the WebServiceDC data connection. The PostExecute event on its own — without a ref attribute that specifies the data connection to which it pertains — is of no use. In this case, the ref attribute specifies the WebServiceDC node inside the form’s connectionSet DOM (where web service data connections are defined). (Normally, the ref attribute has a value of “$”, which means “this”, since the event usually pertains to the form object on which it is defined.)

If you combine this with the ability to get web service response data without merging it into the form (either by not checking the “Object palette > Execute tab > Re-merge Form Data property” of the execute button for the data connection or you call xfa.connectionSet.{DataConnectionName}.execute(false)), you can essentially call a web service, get data back and do whatever you like with it.

Sample Form

To demonstrate how this works, I’ve created a sample form that has two web service data connections. It may take some time to open in Designer depending on how fast Designer can download the WSDL files from the two web services.

The first one, EchoEmployee, submits data from the top 4 fields and, using the PostExecute event, adds an item for each piece of data received in the response inside the list box. The following screen shot shows a sample result:

The second one, ConvertTemperature, obtains the conversion of the specified temperature from the web service response and displays it in a message box.

Download Sample [pdf]

Sample Minimum Requirements: While I developed the sample using Designer 8.2 and Acrobat 9.1, I have set the compatibility level to Acrobat/Reader 7.0.5 since this should work back to that version however I have not tested the form with anything earlier than 8.2/9.1.

Update (Sep 2, 2010): Note that the “Echo Employee” web service is no longer operational. This means that the first web service connection in the sample form can no longer be executed. The script is still valid, however, and serves as a good example. The second web service, “Convert Temperature”, is still operational.

Pre-Processor Library Snippet

In an effort to ease the pain of having to edit the XML Source, I have created an Object Library Snippet (XFO) that you can use to easily plug into this functionality:

Library Snippet [xfo]

In order to use it, you will have to save it to your Object Library’s Custom snippet folder which, depending on whether you installed Designer on XP or Vista, will be in one of the following locations:

C:\Documents and Settings\{username}\Application Data\Adobe\Designer\{version}\EN\Objects\Custom

C:\Users\{username}\AppData\Roaming\Adobe\Designer\{version}\EN\Objects\Custom

Once inserted into your form, the snippet will look like this:

By default, it’s set to work with a web service data connection that is named “WebServiceDC”. When that data connection’s PostExecute event is fired, the script inside will find the response data and call the processResponse() function defined on a script object that is included in the snippet (which is essentially a subform). Finally, the subform hides itself when the form is initialized so you don’t have to worry about hiding it yourself.

Now all you have to do is put script in the processResponse() function using the Script Editor!

If you need to use a different data connection name, you’ll have to go to the XML Source and make two modifications, highlighted here:

The first modification is to the ref attribute of the <event> node that defines the PostExecute event and the second is in the script itself where it extracts the XML of the response.

Sep 2, 2010 — Added note that “Echo Employee” web service is no longer operational which affects the first of the two connection samples in the sample form.

---

Posted by Stefan Cameron on March 23rd, 2009
Filed under Data Binding,Designer,Events,Scripting,Tutorials,XFA
Both comments and pings are currently closed.

---