Introduction

The Content Engine Web Service (CEWS) is an industry standards-conformant SOAP interface to the IBM®Content Cortex Content Engine.

It allows applications to access most of the functionality available through the Content Engine Java™ and .NET APIs. Use CEWS if:
  • You are using a language or technology that can use Web services but is not compatible with the use of a Java or .NET API.
  • You have an existing application that uses CEWS, and you have no plans for immediately porting the application to the Java or .NET API.

Otherwise, use either the Content Engine Java API or the Content Engine .NET API for your application. These APIs offer much better ease of use and supportability than using CEWS directly. Even if your application component is part of a framework in which the use of Web services is the model for communicating with external systems, it is not necessary (and not advisable) to write your application by using CEWS directly; you can achieve your goal of using Web services much more easily by using the .NET or Java API with the CEWS transport.

WSDL Versions

This documentation describes the CEWS version 4.0 WSDL. The CEWS version 3.5 WSDL, which was deprecated in the IBM Content Cortex 5.0.0 release, is no longer supported.

CEWS Overview

CEWS provides general-purpose SOAP operations (methods) and elements that expose all of the Content Engine objects and most of their properties and methods. Its methods are designed with performance and scalability in mind, by virtue of:
  • Allowing several objects (and their content) to be fetched in a single operation, and allowing multiple updates to likewise be performed in a single round trip.
  • Stateless operation: Each client request is independent of any other, therefore allowing load spreading among a set of servers. Stateless operation is accomplished by having each request handle entire objects; the entire state of each object is returned in the response. When objects are updated, the modified state of each object can be provided in the request.
  • Allowing the Web service to be replicated on multiple hosts and for client requests to be directed to different instances of the Web service.
CEWS complies with the following Web services specifications:

WSDL and Namespace Support

CEWS uses the following Web Services Description Language (WSDL) format XML files:
  • Common file: FNCEWS40.wsdl
  • Content transfer interface-specific files:
    • MTOM: FNCEWS40MTOM.wsdl. Binary data is sent by using XML-binary Optimized Packaging (XOP). For more information about MTOM, see: SOAP Message Transmission Optimization Mechanism External link opens a new window or tab. Because MTOM allows for more efficient sending of binary data than SOAP inline base64 encoding, it is the preferred method for transmitting content data.
    • SOAP inline base64 encoding: FNCEWS40SOAP.wsdl. Binary data is sent as base64-encoded text in a SOAP message.
Port/binding pairs are defined in CEWS according to the supported mechanisms for content transfer and are bound to the following endpoint URLs through which the associated WSDL can be accessed at run time. The Content Engine server determines the content transfer method based on the endpoint used:
  • SOAP inline base64 encoding: /FNCEWS40SOAP/wsdl. To access the WSDL, use the following format: http://<hostname>:<port>/wsi/FNCEWS40SOAP/wsdl, where <hostname> is the name of the Content Engine host machine and <port> is the port number that is assigned to the Content Engine application server. For example: http://localhost:9080/wsi/FNCEWS40SOAP/wsdl.
  • MTOM: /FNCEWS40MTOM/wsdl. To access the WSDL, use the following format: http://<hostname>:<port>/wsi/FNCEWS40MTOM/wsdl. For example: http://localhost:9080/wsi/FNCEWS40MTOM/wsdl.
The elements and types that are defined in the CEWS schema are assigned to the following namespaces:
  • Common WSDL: http://www.filenet.com/ns/fnce/2006/11/ws/wsdl
  • Common schema: http://www.filenet.com/ns/fnce/2006/11/ws/schema
  • SOAP WSDL: http://www.filenet.com/ns/fnce/2006/11/ws/SOAP/wsdl
  • MTOM WSDL: http://www.filenet.com/ns/fnce/2006/11/ws/MTOM/wsdl

Object Identifiers

The WithObjectIdentityType element provides the basis for identifying Content Engine objects, in which information that describes an object (its class ID, object ID, and object store) are returned.

The Content Engine has two primary object types: independent and dependent:
  • An independent object is instantiated from a subclass of the IndependentObject class. It is addressable and has a unique identity by which it can be referenced for retrieval or update, and, which is returned as part of its object information in an operation response. An independent object is represented by an ObjectReference element.
  • A dependent Content Engine object is instantiated from a subclass of the DependentObject class. It is non-addressable, does not possess a unique identifier by which it can be referenced, and can be identified only by value. A dependent object exists only within the scope of an independent object (by an object-valued property) and can be persisted only by persisting the independent object to which it belongs. It is represented by a DependentObjectType element.

Duplicate Object Suppression

During object retrieval of objects that have object-valued properties, it is possible to reach the same object more than once if a property filter forces a recursion. (For example, retrieving a folder and forcing deep recursion through the Parent and SubFolders properties.) This scenario can lead to runaway recursion and excessive memory usage on the server. To prevent this recursion from occurring, the server uses a mechanism to suppress recursion into duplicate objects. This duplicate object suppression mechanism overrides the true recursion level and operates as if the maximum recursion level has already been reached for the duplicate object, therefore terminating recursion at a duplicate object. When a duplicate object is detected, an object reference (represented by an ObjectReference element) is placed into the response instead of an object value (represented by an ObjectValue element) and the serializationDuplicate attribute of the object reference is set to true. Duplicate object suppression has the following effects on returned objects:
  • If the duplicate object is reached as the value of a singleton property, that property value is returned as an ObjectReference object (instead of an ObjectValue object).
  • If the duplicate object is reached through a collection, it appears as empty (no Properties collection is present).

The scope of duplicate object detection encompasses each individual top-level component of a response (for example, an individual ObjectResponseType within a GetObjects response). Therefore, if an object appears beneath one top-level response element, and also appears beneath a different top-level response element, the second occurrence of the object is not treated as a duplicate.

Occasionally, an object value is returned for an object that occurs at a high recursion level while other copies of the same object that occur at a lower recursion level are suppressed. Because fewer properties are typically returned for objects at higher recursion levels, the client might have a copy of the object that has a much smaller subset of properties than was wanted. This scenario can result in either additional network round trips to retrieve the missing properties, or errors if the client application does not realize that it is missing properties. When an object reference is returned instead of an object value, it might not be clear to the client application whether it is because of a normal property filter evaluation or duplicate object suppression.

Accessing Multiple Object Stores

A Content Engine object store server can provide access to multiple object stores, and multiple object store servers can provide access to each object store. Each object store server can host a single CEWS server, which can access any object store server in the Content Cortex domain. CEWS clients can access any of the object stores through either of the object store servers. The following diagram shows a configuration with two object store servers and three object stores:

A diagram for configuration with two object store servers and three object stores