Invoking LiveCycle using Web Services

Most LiveCycle services in the service container are configured to expose a web service, with full support for web service definition language (WSDL) generation. That is, you can create proxy objects that consume the native SOAP stack of a LiveCycle service. As a result, LiveCycle services can exchange and process the following SOAP messages:

SOAP request: Sent to a LiveCycle service by a client application requesting an action.
SOAP response: Sent to a client application by a LiveCycle service after a SOAP request is processed.

Using web services, you can perform the same LiveCycle services operations that you can by using the Java API. A benefit of using web services to invoke LiveCycle services is that you can create a client application in a development environment that supports SOAP. A client application is not bound to a specific development environment or programming language. For example, you can create a client application using Microsoft Visual Studio .NET and C# as the programming language.

LiveCycle services are exposed over the SOAP protocol and are WSI Basic Profile 1.1 compliant. Web Services Interoperability (WSI) is an open standards organization that promotes web service interoperability across platforms. For information, see http://www.ws-i.org/.

LiveCycle supports the following web service standards:

Encoding: Supports only document and literal encoding (which is the preferred encoding according to the WSI Basic Profile). (See Invoking LiveCycle using Base64 encoding.)
MTOM: Represents a way to encode attachments with SOAP requests. (See Invoking LiveCycle using MTOM.)
SwaRef: Represents another way to encode attachments with SOAP requests. (See Invoking LiveCycle using SwaRef.)
SOAP with attachments: Supports both MIME and DIME (Direct Internet Message Encapsulation). These protocols are standard ways of sending attachments over SOAP. Microsoft Visual Studio .NET applications use DIME. (See Invoking LiveCycle using Base64 encoding.)
WS-Security: Supports a user name password token profile, which is a standard way of sending user names and passwords as part of the WS Security SOAP header. LiveCycle also supports HTTP basic authentication. (See Passing credentials using WS-Security headers.)

To invoke LiveCycle services using a web service, typically you create a proxy library that consumes the service WSDL. The Invoking LiveCycle using Web Services section uses JAX-WS to create Java proxy classes to invoke services. (See Creating Java proxy classes using JAX-WS.)

You can retrieve a service WDSL by specifying the following URL definition (items in brackets are optional):

http://<your_serverhost>:<your_port>/soap/services/<service_name>?wsdl[&version=<version>][&async=true|false][lc_version=<lc_version>]

where:

your_serverhost represents the IP address of the J2EE application server hosting LiveCycle.
your_port represents the HTTP port that the J2EE application server uses.
service_name represents the service name.
version represents the target version of a service (the latest service version is used by default).
async specifies the value true to enable additional operations for asynchronous invocation (false by default).
lc_version represents the version of LiveCycle that you want to invoke.

The following table lists service WSDL definitions (assuming that LiveCycle is deployed on the local host and the post is 8080).

Service	WSDL definition
Assembler	`http://localhost:8080/soap/services/ AssemblerService?wsdl`
Back and Restore	`http://localhost:8080/soap/services/BackupService?wsdl`
Barcoded Forms	`http://localhost:8080/soap/services/ BarcodedFormsService?wsdl`
Convert PDF	`http://localhost:8080/soap/services/ ConvertPDFService?wsdl`
Distiller	`http://localhost:8080/soap/services/ DistillerService?wsdl`
DocConverter	`http://localhost:8080/soap/services/DocConverterService?WSDL`
DocumentManagement	`http://localhost:8080/soap/services/DocumentManagementService?WSDL`
Encryption	`http://localhost:8080/soap/services/EncryptionService?wsdl`
Forms	`http://localhost:8080/soap/services/FormsService?wsdl`
Form Data Integration	`http://localhost:8080/soap/services/FormDataIntegration?wsdl`
Generate PDF	`http://localhost:8080/soap/services/ GeneratePDFService?wsdl`
Generate 3D PDF	`http://localhost:8080/soap/services/Generate3dPDFService?WSDL`
Output	`http://localhost:8080/soap/services/ OutputService?wsdl`
PDF Utilities	`http://localhost:8080/soap/services/ PDFUtilityService?wsdl`
Reader Extensions	`http://localhost:8080/soap/services/ ReaderExtensionsService?wsdl`
Repository	`http://localhost:8080/soap/services/ RepositoryService?wsdl`
Rights Management	`http://localhost:8080/soap/services/ RightsManagementService?wsdl`
Signature	`http://localhost:8080/soap/services/ SignatureService?wsdl`
XMP Utilities	`http://localhost:8080/soap/services/ XMPUtilityService?wsdl`

LiveCycle Process WSDL definitions

You must specify the Application name and the Process name within the WSDL definition to access a WSDL that belongs to a process created in Workbench. Assume that the name of the application is MyApplication and the name of the process is EncryptDocument. In this situation, specify the following WSDL definition:

http://localhost:8080/soap/services/MyApplication/EncryptDocument?wsdl

Note: For information about the example MyApplication/EncryptDocument short-lived process, see Short lived process example.

Note: An Application can contain folder(s). In this case, specify the folder name(s) in the WSDL definition:

http://localhost:8080/soap/services/MyApplication/[<folderA>/.../<folderZ>/]EncryptDocument?wsdl

Accessing new functionality using web services

New LiveCycle service functionality can be accessed using web services. For example, in LiveCycle, the ability to encode attachments using MTOM is introduced. (See Invoking LiveCycle using MTOM.)

To access new functionality introduced in LiveCycle, specify the lc_version attribute in the WSDL definition. For example, to access new service functionality (including MTOM support), specify the following WSDL definition:

http://localhost:8080/soap/services/MyApplication/EncryptDocument?wsdl&lc_version=9.0.1

Note: When setting the lc_version attribute, ensure that you use three digits. For example, 9.0.1 is equal to version 9.0.

Web service BLOB data type

LiveCycle service WSDLs define many data types. One of the most important data types exposed in a web service is a BLOB type. This data type maps to the com.adobe.idp.Document class when working with LiveCycle Java APIs. (See Passing data to LiveCycle services using the Java API.)

A BLOB object sends and retrieves binary data (for example, PDF files, XML data, and so on) to and from LiveCycle services. The BLOB type is defined in a service WSDL as follows:

<complexType name="BLOB"> 
    <sequence> 
        <element maxOccurs="1" minOccurs="0" name="contentType" 
            type="xsd:string"/> 
        <element maxOccurs="1" minOccurs="0" name="binaryData" 
            type="xsd:base64Binary"/> 
        <element maxOccurs="1" minOccurs="0" name="attachmentID" 
            type="xsd:string"/> 
        <element maxOccurs="1" minOccurs="0" name="remoteURL" 
            type="xsd:string"/> 
        <element maxOccurs="1" minOccurs="0" name="MTOM"  
            type="xsd:base64Binary" 
            xmime:expectedContentTypes="*/*" 
            xmlns:xmime="http://www.w3.org/2005/05/xmlmime"/> 
        <element maxOccurs="1" minOccurs="0" name="swaRef"  
            type="tns1:swaRef"/> 
        <element maxOccurs="1" minOccurs="0" name="attributes" 
            type="impl:MyMapOf_xsd_string_To_xsd_anyType"/> 
    </sequence> 
</complexType>

The MTOM and swaRef fields are supported only in LiveCycle. You can use those new fields only if you specify a URL that includes the lc_version property.

Supplying BLOB objects in service requests

If a LiveCycle service operation requires a BLOB type as an input value, create an instance of the BLOB type in your application logic. (Many of the web service quick starts located in Programming with LiveCycle show how to work with a BLOB data type.)

Assign values to fields that belong to the BLOB instance as follows:

Base64: To pass data as text encoded in a Base64 format, set the data in the BLOB.binaryData field and set the data type in the MIME format (for example application/pdf) in the BLOB.contentType field. (See Invoking LiveCycle using Base64 encoding.)
MTOM: To pass binary data in an MTOM attachment, set the data in the BLOB.MTOM field. This setting attaches the data to the SOAP request using the Java JAX-WS framework or the SOAP framework's native API. (See Invoking LiveCycle using MTOM.)
SwaRef: To pass binary data in an WS-I SwaRef attachment, set the data in the BLOB.swaRef field. This setting attaches the data to the SOAP request using the Java JAX-WS framework. (See Invoking LiveCycle using SwaRef.)
MIME or DIME attachment: To pass data in a MIME or DIME attachment, attach the data to the SOAP request using the SOAP framework's native API. Set the attachment identifier in the BLOB.attachmentID field. (See Invoking LiveCycle using Base64 encoding.)
Remote URL: If data is hosted on a web server and accessible over an HTTP URL, set the HTTP URL in the BLOB.remoteURL field. (See Invoking LiveCycle using BLOB data over HTTP.)

Accessing data in BLOB objects returned from services

The transmission protocol for returned BLOB objects depends on several factors, which are considered in the following order, stopping when the main condition is satisfied:

Target URL specifies transmission protocol. If the target URL specified at the SOAP invocation contains the parameter blob="BLOB_TYPE", then BLOB_TYPE determines the transmission protocol. BLOB_TYPE is a placeholder for base64, dime, mime, http, mtom, or swaref.
Service SOAP endpoint is Smart. If the following conditions are true, then the output documents are returned using the same transmission protocol as the input documents:
- Service's SOAP endpoint parameter Default Protocol For Output Blob Objects is set to Smart.
  
  For each service with a SOAP endpoint, the Administration Console allows you to specify the transmission protocol for any returned blobs. (See LiveCycle Administration Help.)
- LiveCycle service takes one or more documents as input.
Service SOAP endpoint is not Smart. The configured protocol determines the document transmission protocol, and the data is returned in the corresponding BLOB field. For example, if the SOAP endpoint is set to DIME, then the returned blob is in the blob.attachmentID field regardless of the transmission protocol of any input document.
Otherwise. If a service does not take the document type as input, then the output documents are returned in the BLOB.remoteURL field over the HTTP protocol.

As described in the first condition, you can ensure the transmission type for any returned documents by extending the SOAP endpoint URL with a suffix as follows:

    http://<your_serverhost>:<your_port>/soap/services/<service 
    name>?blob=base64|dime|mime|http|mtom|swaref

Here is the correlation between transmission types and the field from which you obtain the data:

Base64 format: Set the blob suffix to base64 to return the data in the BLOB.binaryData field.
MIME or DIME attachment: Set the blob suffix to DIME or MIME to return the data as a corresponding attachment type with the attachment identifier returned in the BLOB.attachmentID field. Use the SOAP framework's proprietary API to read the data from the attachment.
Remote URL: Set the blob suffix to http to keep the data on the application server and return the URL pointing to the data in the BLOB.remoteURL field.
MTOM or SwaRef: Set the blob suffix to mtom or swaref to return the data as a corresponding attachment type with the attachment identifier returned in the BLOB.MTOM or BLOB.swaRef fields. Use the SOAP framework's native API to read the data from the attachment.

Important: It is recommended that you do not exceed 30 MB when populating a BLOB object by invoking its setBinaryData method. Otherwise, there is a possibility that an OutOfMemory exception occurs.

Important: JAX WS-based applications that use the MTOM transmission protocol are limited to 25MB of sent and received data. This limitation is due to a bug in JAX-WS. If the combined size of your sent and received files exceeds 25MB, use the the SwaRef transmission protocol instead of the MTOM one. Otherwise, there is a possibility of an OutOfMemory exception.

MTOM transmission of base64-encoded byte arrays

In addition to the BLOB object, the MTOM protocol supports any byte-array parameter or byte-array field of a complex type. This means that client SOAP frameworks supporting MTOM can send any xsd:base64Binary element as an MTOM attachment (instead of a base64-encoded text). LiveCycle SOAP endpoints can read this type of byte-array encoding. However, the LiveCycle service always returns a byte-array type as a base64-encoded text. The output byte-array parameters do not support MTOM.

LiveCycle services that return a large amount of binary data use the Document/BLOB type rather than the byte-array type. The Document type is much more efficient for transmitting large amounts of data.