Using the Web Services service to invoke LiveCycle ES services with document input and output values (LiveCycle ES 8.2.1)

This article describes how to use the Web Service service in processes to invoke services that require file attachments as input values. This article also describes how to specify the format in which file attachments are returned by LiveCycle ES web services.

For example, service input and output variables of type document are represented in SOAP messages as file attachments. To provide input document values, the SOAP message includes a file attachment. Response messages include file attachments when web services have output variables of type document.

Files can be attached as MIME or MTOM attachments, base64-encoded text, or using the URL of the file:

The SOAP message and the configuration of the Invoke Web Service operation is different for each type of attachment. (See Configuring the web service request message.)
If you are invoking a LiveCycle ES web service that returns a document value, you can specify the method that is used to attach the file to the SOAP response message. (See Configuring the web service response message.)

Note: Web services that are provided by LiveCycle ES do not support MTOM attachments.

This section describes how to configure the Web Service Options property of the Invoke Web Service operation. You use this property to configure the SOAP request message that is sent to the web service:

Opening the WebService Settings dialog box
Specifying the web service properties
Generating the initial SOAP request
Configuring attachments

You use the WebService Settings dialog box to configure the Web Service Options property of the Invoke Web Service operation.

On the process diagram, click the Invoke Web Service operation.

On the Properties view, expand the Web Service Options section, and click the button next to the Options box.

You need to provide the following information about the web service so that the Web Services service retrieve the WSDL and send and receive SOAP messages:

WSDL URL: The URL of the web service definition. The URL for process WSDLs are in the following format: http://[server name]:[port]/soap/services/[process name]?wsdl For example, the following URL points to the WSDL for the process named echoDocument. The application server runs on the same computer on which LiveCycle Workbench ES is installed: http://localhost:8080/soap/services/echoDocument?wsdl User Name: The user name of the account that you can use to access the web service. You need to provide a user name only if the web service requires authentication.

Password: The password that corresponds with the user name that you provided for the User Name property.

Port: The service that you want to use, which is exposed through the WSDL. A WSDL can expose multiple services.

Target URL: The URL that provides access to the web service. For a process named echoDocument, the URL is http://localhost:8080/soap/services/echoDocument.

strong>Operation: The web service operation to invoke. The list is populated automatically when you load the web service definition.

Time Out: The amount of time that you want to wait for a response from the web service before abandoning the web service invocation. The value you provide is in seconds.

On the WebService Settings dialog box click the Settings tab.

In the WSDL URL box, type the URL of the web service WSDL.

Click Load to retrieve the WSDL. Some properties on the Settings tab are automatically populated using information from the WSDL.

If necessary, type a username and password.

If the default value for Port is not correct, type a different value.

If the default value forTarget URL is not correct, type a different URL.

Select the operation that you want to invoke.

(Optional) Specify the amount of time that passes before the service request times out.

The WebService Settings dialog box autmatically generates a SOAP message for invoking the web service. The message is based on the web service properties that you specified. The SOAP message is provided in a text box where you can edit the message as required.

On the WebService Settings dialog box, click the Request tab.

Click Generate.

The SOAP message needs to include file attachments to represent document values of service input parameters.

The following XML code shows the general structure of a SOAP message that is used to a call a web service operation:

The Body element contains one element that has the same name as the service operation.
The operation_name element contains one element for each input parameter. The names of these elements are the same as the parameter names.
The method used to attach files to the SOAP message (MIME, MTOM (excluding LiveCycle ES web services), base64-encoded text, or file URLs) determine the elements that are used to identify file attachments.

<soapenv:Envelope
		
	     xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
		
	     xmlns:ser="http://foo.net/services"> 
		
	    <soapenv:Header /> 
		
	    <soapenv:Body> 
		
	       <ser:operation_name> 
		
	          <ser:parameter_name> 
		
	             <!-- elements for file attachments are placed here --> 
		
	          </ser:parameter_name> 
		
	       </ser:operation_name> 
		
	    </soapenv:Body> 
		
	 </soapenv:Envelope>

For the web services of activated processes, the operation name is always invoke. Parameter names are the names of the input variables that are defined in the process. The following table describes how to configure the options in the WebService Settings dialog box to attach files. Example SOAP messages are provided for each method. The examples are request messages for the web service of a process with an input parameter named documentIn. The documentIn parameter is a document value.

Attachment type	Description	Example SOAP message
MIME/MTOM	The Attachment tab of the WebService Settings dialog box is used to specify the document value. Each row in the table represents a file attachment. To configure a MIME attachment: Click the Attachment tab. Click Load Attachment Part to add rows to the table for the attachments that must be specified for the web service operation that you are invoking. The Part and Type columns are populated with values automatically. Take note of the values in the Part column. You will need these values in step 6 of this procedure. The Part column contains the identification of the attachment. The web service determines the identification. For each row in the table, click the Attachment cell, and then click the ellipsis button that appears to open XPath Builder. The XPath expression that you create must resolve to the data location where the document value is saved. For each row in the table, click the Content-Type cell and type the MIME type of the file that you are attaching, for example application/pdf. Click the Request tab, and add an attachmentID element inside each element that represents the parameter that takes a file attachment as the value. Inside each attachmentID element, type the text that appears in the Part column for the attachment on the Attachment tab.	<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ xmlns:ser="http://adobe.com/idp/services"> <soapenv:Header/> <soapenv:Body> <ser:invoke> <ser:documentIn> <ser:attachmentID> part0 </ser:attachmentID> </ser:documentIn> </ser:invoke> </soapenv:Body> </soapenv:Envelope>
base64-encoded text	The content MIME type and the base64-encoded text representation of the file is included in the SOAP message: The content type is specified in a contentType element. The text is specified in a binaryData element. To obtain the base64-encoded text, you can use the getDocContentBase64 XPath function. The following procedure assumes that the base-64 encoded text that represents the document value is stored in a process variable. To configure a base-64 encoded text attachment: Click the Request tab. Add the following elements inside the element that represents the parameter that takes the document value: contentType binaryData Inside the contentType element, either type the content type or add an XPath expression that resolves to a string variable that contains the content type. Inside the binaryData element, add an XPath expression that resolves to a string variable that contains the base64-encoded text that represents the document.	<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ xmlns:ser="http://adobe.com/idp/services"> <soapenv:Header/> <soapenv:Body> <ser:invoke> <ser:documentIn> <ser:contentType> {$/process_data/@contentType$} </ser:contentType> <ser:binaryData> {$/process_data/@docBase64$} </ser:binaryData> </ser:documentIn> </ser:invoke> </soapenv:Body> </soapenv:Envelope>
File URL	The URL of the file is specified in a remoteURL element. To configure a file URL attachment: Click the Request tab. Add a remoteURL element inside the element that represents the parameter that takes the document value. Inside the remoteURL element, either type the URL of the file or add an XPath expression that resolves to a string variable that contains the URL.	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://adobe.com/idp/services"> <soapenv:Header/> <soapenv:Body> <ser:invoke> <ser:documentIn> <ser:remoteURL> http://help.adobe.com/en_US/livecycle/es/overview.pdf </ser:remoteURL> </ser:documentIn> </ser:invoke> </soapenv:Body> </soapenv:Envelope>

When a LiveCycle ES web service returns a document value, the value is an attachment to the SOAP response message. The default behavior of LiveCycle ES web services is to store the result document value on the LiveCycle ES server and include the URL to the document in the response message. However, if the SOAP request message included a MIME attachment, the response also uses a MIME attachment to return document values.

You can override the default behavior and specify the method that LiveCycle ES web services use to return document attachments. Files can be attached to SOAP response messages as MIME attachments, base64-encoded text, or using the URL of the file. To specify the way files are attached to response messages, you must append one of the values in the following table to the Target URL that is specified on the Settings tab of the WebService Settings dialog box:

Attachment type	Text to append
base64-encoded text	?blob=base64
MIME	?blob=mime
File URL	?blob=http

For example, The following value for Target URL causes the web service of a process named echoDocument to attach files to SOAP response messages as base64-encoded text:

http://localhost:8080/soap/services/echoDocument?blob=base64

To override default SOAP response message attachment behavior:

On the WebService Settings dialog box, click the Settings tab .

In the Target URL box, append one of the values to the URL:

?blob=base64
?blob=mime
?blob=http

Subtotal
Promotions
Estimated Shipping
VAT	Calculated at checkout

Total

Using the Web Services service to invoke LiveCycle ES services with document input and output values (LiveCycle ES 8.2.1)

Products Affected

Issue

Configuring the web service request message

Opening the WebService Settings dialog box

To open the WebService Settings dialog box:

Specifying the web service properties

To specify the web service properties

Generating the initial SOAP request

To generate the initial SOAP message:

Configuring attachments

Configuring LiveCycle ES web service response messages

Products

Download

Support & Learning

Buy

Company