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:
You use the WebService Settings dialog box to configure the Web Service Options property of the Invoke Web Service operation.
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.
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.
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:
|
<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:
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:
|
<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:
|
<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:
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