Content Engine Web Service

This topic describes changes necessary to your Content Engine Web Service (CEWS) applications so that they can run in a 4.5 environment. This topic covers the following scenarios:

Upgrading 4.0.x Applications to run in a 4.5 Environment using the 4.0 Endpoints

This section describes the changes required for P8 4.0.x Content Engine Web Service (CEWS) applications using the 3.5 endpoints to run in a P8 4.5.0 environment using the 4.0 endpoints. The 4.0 WSDL contains all of the elements, operations, enumerations, subelements, and attributes that are included in the 3.5 WSDL and adds a new operation and several new elements. The 4.0 WSDL does not support IBM Rational Application Developer Java clients. In addition to the WSDL enhancements, the Content Engine object model has also been updated for the P8 4.5 release. For more information, see the "What’s New in 4.5.0" section of the IBM® FileNet® P8 Release Notes.

In the P8 4.5.0 release, the use of the Direct Internet Message Encapsulation (DIME) standard to upload and retrieve content is deprecated. Support for DIME attachments will be dropped in a future P8 release. Because DIME support is deprecated in this release, the DIMEAttachmentReference and DIMEContent elements in the 4.0 and 3.5 WSDLs are also deprecated. Therefore, any existing .NET client applications that use DIME should be ported to work with the 4.0 endpoints and use either Message Transmission Optimization Mechanism (MTOM) or SOAP with inline, base64 encoding to upload and retrieve content data. Because MTOM is more efficient, it is the preferred method for handling content data.

For a 4.0 WSDL-based application, you can upload and retrieve content data with either MTOM or SOAP with inline, base64 encoding using one of the following techniques:

In addition, when you use MTOM it is possible to upload or retrieve content data using streaming instead of as an array of bytes. However, a WSE 3.0 hotfix is required from Microsoft and specialized XML code is required. For details, refer to the sample CEWS .NET C# application posted on the IBM documentation site.

In order to use MTOM, a .NET-based client application (written in either C# or Visual Basic) must be upgraded from a Microsoft® Visual Studio® .NET 2003 with Web Service Enhancements (WSE) 2.0 environment to a Microsoft Visual Studio 2005 with WSE 3.0 environment. Note that WSE 3.0 must be installed as an add-on to Visual Studio 2005; it is incompatible with Visual Studio .NET 2003. A WSE 2.0-based client application being ported to WSE 3.0 must have its existing authentication code rewritten to support WSE 3.0.

The following steps provide general guidance on upgrading a client application using the 3.5 SOAP or DIME endpoints and developed in a VIsual Studio .NET 2003 with WSE 2.0 environment to use the 4.0 SOAP or MTOM endpoints in a Microsoft Visual Studio 2005 with WSE 3.0 environment. For additional information on migrating a WSE 2.0-based project to WSE 3.0, see "Migrating Applications from WSE 2.0 to 3.0" on the Microsoft Developer Network (http://msdn.microsoft.com/) web site. For information about the Content Engine Web Service Interface, see the Content Engine Web Service Developer's Guide:

  1. Open the VIsual Studio .NET 2003 project in Microsoft Visual Studio 2005, which will automatically launch the Visual Studio Conversion Wizard for converting the project into the new Visual Studio 2005 format.
  2. Add the assembly reference Microsoft.Web.Services3.
  3. Replace all occurrences of Microsoft.Web.Services2 in the project with Microsoft.Web.Services3. This can leave some assembly usages invalid (for example, Microsoft.Web.Services3.Dime).
  4. Remove the assembly reference Microsoft.Web.Services2.
  5. Remove the original web reference generated from the CEWS 3.5 WSDL. Note the name used for original web reference so it can be used for the new web reference.
  6. Depending on whether your application will handle content data using MTOM or SOAP with inline, base64 encoding, add a new web reference using either the CEWS 4.0 MTOM or SOAP endpoint. The 4.0 MTOM endpoint is of the form “http://<host>:<port>/wsi/FNCEWS40MTOM/wsdl”. The 4.0 SOAP endpoint is of the form “http://<host>:<port>/wsi/FNCEWS40SOAP/wsdl”. Use the same name that as used for the original web reference; for example, CEWS. This name translates to the namespace of the generated classes.
  7. During the conversion, Visual Studio will might have derived the main web service binding class from the generic System.Web.Services.Protocols.SoapHttpClientProtocol class instead of from the WSE 3.0 WebServicesClientProtocol class. If so, modify the generated code in Reference.cs to change the base class to Microsoft.Web.Services3.WebServicesClientProtocol and add the suffix “Wse” to the class name (for example, FNCEWS40ServiceWse). This change must be performed each time you regenerate the web reference.
  8. Replace all occurrences of the name of the old binding class (for example, FNCEWS35ServiceWse) with the new name (for example, FNCEWS40ServiceWse).
  9. In applications using WSE 2.0, the client’s credentials are configured on the binding class instance by adding a SecurityToken instance to the Security.Tokens collection of the SoapContext object (for example, objCtx.Security.Tokens.Add(tok)). Change this code to call SetClientCredential() on the binding instance (for example, objBinding.SetClientCredential(tok)).
  10. Add a Policy object to the binding class instance with the appropriate security assertions added. The Policy class is in the assembly Microsoft.Web.Services3.Design. For example:
    1. C#
      Policy MyPolicy = new Policy();
      MyPolicy.Assertions.Add(new UsernameOverTransportAssertion());
      objBinding.SetPolicy(MyPolicy);
      Visual Basic
      Dim MyPolicy As Policy = New Policy
      MyPolicy.Assertions.Add(New UsernameOverTransportAssertion)
      binding.SetPolicy(MyPolicy)
  11. Remove any code that uses DIME attachments (DIMEContent and DIMEAttachmentReference objects).
  12. With the following exceptions, the code for uploading or retrieving content data (described below) is identical whether you use MTOM or SOAP with inline, base64 encoding and is the same as the code used in a 3.5 WSDL-based application to handle content data using SOAP with inline, base64 encoding:
    1. MTOM: Set the RequireMtom property on the instance of the binding class to true (for example, objBinding.RequireMtom = true). The application must have a web reference set to the 4.0 MTOM endpoint.
    2. SOAP with inline, base64 encoding: The application must have a web reference set to the 4.0 SOAP endpoint.
  13. To upload content data using MTOM or SOAP with inline, base64 encoding, verify that your application does the following:
    1. Set the content as the Binary property of an InlineContent object.
    2. Set the InlineContent object as the Value property of a ContentData object. By default, the Binary property of the generated InlineContent class is a byte array. For example:
      1. C#
        Byte[] data; // content data to upload
        CEWS.InlineContent objIC = new CEWS.InlineContent();
        objIC.Binary = data;
        
        // Set on a ContentData object:
        objContentData.Value = objIC;
        
        Visual Basic
        Dim data() As Byte  ‘content data to upload
        Dim objIC As CEWS.InlineContent = New CEWS.InlineContent objIC.Binary = data
        
        'Set on a ContentData object:
        objContentData.Value = objIC;
        
  14. To retrieve content data using MTOM or SOAP with inline, base64 encoding, read the Binary property of the InlineContent object returned as the Value property of a ContentData object. For example:
    1. C#
      CEWS.InlineContent objIC = (CEWS.InlineContent)objContentData.Value;
      Byte[] byteContent = objIC.Binary;     
      Visual Basic
      Dim objIC As CEWS.InlineContent = objContentData.Value
      Dim byteContent() As Byte = objIC.Binary
      
  15. Alternatively, you can retrieve content data in a 4.0 WSDL-based client application with the GetContent operation instead of the Content pseudo-property in a GetObjects response, as described above. Using a GetContent operation, an application has the advantage of being able to retrieve a portion of the content data or to retrieve the content data at a specific offset. For sample code that retrieves content using a GetContent operation, refer to the sample CEWS .NET applications posted on the IBM documentation site (FolderTree.cs in the C# sample, and RetrieveDoc.vb in the Visual Basic sample).

Upgrading 4.0.x Applications to run in a 4.5 Environment using the 3.5 Endpoints

If you have already modified your 3.5.x applications to run in a 4.0.x environment using the 3.5 endpoints, there are no additional modifications needed to run your applications in a 4.5 environment. However, if your applications use DIME attachments to upload or retrieve content data, be aware that support for the DIME standard has been deprecated.

DIME Support Deprecated

In the IBM FileNet P8 4.5.0 release, the use of the Direct Internet Message Encapsulation (DIME) standard to upload and retrieve content is deprecated. Support for DIME attachments will be dropped in a future release. Because DIME support is deprecated in this release, the DIMEAttachmentReference and DIMEContent elements in the 4.0 and 3.5 WSDLs are also deprecated. Therefore, any existing .NET client applications that use DIME should be ported to work with the 4.0 endpoints and use either Message Transmission Optimization Mechanism (MTOM) or SOAP with inline, base64 encoding to upload and retrieve content data. Because MTOM is more efficient, it is the preferred method for handling content data.

Upgrading 3.5.x Applications to run in a 4.5 Environment using the 4.0 Endpoints

To modify a 3.5.x application that uses the 3.5 endpoints to instead use the 4.0 endpoints and run in a 4.5 environment, follow the guidelines in the following topics:

Upgrading 3.5.x Applications to run in a 4.5 Environment using the 3.5 Endpoints

This section describes changes necessary to your 3.5.x Content Engine Web Service applications so they can run in a 4.x environment (while continuing to use the 3.5 endpoints). Note that this interface continues to support Microsoft .NET Framework 1.1, Web Services Enhancements (WSE) 2.0, and DIME attachments only.

Documentation for this interface is only available as a zip file on the IBM Information Management support page on www.ibm.com. To download this zip file from the IBM support page, see Accessing IBM FileNet documentation.

Content Engine 4.0 introduced a number of new object types and also added properties to existing object types. These are visible to, and can be manipulated by, web service client applications. In addtion, some object types and properties of existing object types were removed in Content Engine 4.0, invalidating any web service client code that relies upon those objects or properties. The following sections provide details of the removals.

Classes Not Supported

As of release 4.0, the following classes are no longer supported by the Content Engine:

Properties Not Supported

As of release 4.0, the Content Engine does not support a number of properties that existed in the 3.5.x Content Engine (although in some cases these properties were deprecated in the 3.5.x release). These unsupported properties include the following:

Additional information on removed properties is provided in sections below.

Security

Extensible Authentication Framework

The Extensible Authentication Framework was introduced in IBM FileNet P8 3.5 to facilitate integration with Single-Sign-On (SSO) solutions that would not allow the transmission of a username and password to the IBM FileNet system. IBM FileNet P8 4.0 introduced a standards-based methodology for authentication using the J2EE Java Authentication and Authorization (JAAS) framework.

If you have implemented the Extensible Authentication Framework in your 3.5 application, for the 4.x release you must write a JAAS LoginModule using the IBM FileNet Web Service Extensible Authentication Framework. Note that this approach does not require any modifications to existing applications, as the existing client-side logic to submit custom values in the username and password fields will remain in place.

You write the custom JAAS LoginModule on the server, conforming to IBM FileNet's Web Service Extensible Authentication Framework (WS-EAF). This custom LoginModule will extract the username and password values from the UsernameToken instance in the incoming WS-Security header, get the same custom values that were used in the 3.5.2 Extensible Authentication solution, and then invoke whatever custom logic is required to authenticate based on those parameters. For more information, see the Web Service Extensible Authentication Framework Developer’s Guide.

Directory Service Lookups

In IBM FileNet P8 3.5.x, LDAP directory lookups could be done using a system configured account, or the user context. Beginning in IBM FileNet P8 4.0, directory service lookups based on the user context are no longer supported. If you have an existing application that enumerates users, more results might be returned in the 4.x release (since lookups done using the user context would have returned only those users and groups to which the user had access).

User Credentials

Web service clients supply credentials for authentication through a security header in each SOAP request, typically one containing a UsernameToken token. Content Engine 4.x uses a different authentication framework to 3.5, with consequences for the form of credentials that might be provided. This affects particularly the format of user names that might be used in the Username element of a UsernameToken token, as described below.

Pre-Windows 2000 Login Format

In 3.5.x, the Content Engine server supported a pre-Windows 2000 login format (domain\loginname) through Microsoft-specific authentication APIs. The functionality is no longer directly available through the J2EE application server-based authentication modules. You are limited to what the application server (or the independent authentication provider that it uses) supports in terms of authentication login-name formats.

Events and Subscriptions

Event Actions

Content Engine 3.5.x supported scripts and COM objects for event actions. Beginning in the 4.0 release, event actions must be Java-based. Any EventAction objects that your application uses must be modified to use a Java class instead of a script or a COM object. Furthermore, the Java class must be located on the server; it cannot be on a client and streamed to the server for execution as for CE 3.5.x. (For information on how to create a Java-based event action, see Work with event actions in the Help for Content Engine Administration.) In addition, changes in the following EventAction properties might require modifications in your application:

Priority Property Deprecated

In 3.5.x, you could specify a value used to order the firing of subscriptions in response to an event via the Priority property on a Subscription object. However, the server did not use this property, and therefore the property was deprecated in the 4.0 release.

Workflow Subscription Filter Expressions

In 3.5.x, a Process Engine filter expression could be supplied with a workflow subscription using the Expression property. This type of filter expression was evaluated by the Process Engine after the workflow event was launched. Because the filter expression evaluation occurred well after the original transaction was complete, this capability was inefficient and often inaccurate. In the 3.5.x documentation, we recommended that you use the FilterExpression property instead, as the FilterExpression property is evaluated within the transaction that initiates the event (before an event is queued).

Beginning in 4.0, the Expression property is no longer supported. During the upgrade to Content Engine 4.x, if the Expression property contains a value, then the value will be moved to the FilterExpression property (but only if the FilterExpression property was not populated with a value). If both properties were populated with a value, then the upgrade tool will not move the contents of the Expression property but will produce a report of these cases.

Note that the Expression property supported certain SQL syntax that is not supported in the FilterExpression property. Specifically, with the exception of the LIKE operator, all other operators requiring a database query (such as the EXISTS operator) are not supported in the FilterExpression property. For a list of unsupported operators, see FilterExpression Property in the Content Engine Java and .NET Developer's Guide.

If your application uses the Expression property, you must modify your code to use the FilterExpression property instead. In addition, if any 3.5.x Expression values included a SQL operator that is not supported in the FilterExpression property, you must resolve these instances by either programmatically setting the value of the FilterExpression property to a string that includes only supported operators or by using Enterprise Manager to correct the value.

IsolatedRegion Property Deprecated

Beginning in the 4.0 release, the IsolatedRegion property on the ClassWorkflowSubscription and InstanceWorkflowSubscription classes has been renamed to IsolatedRegionNumber. Any existing code that accesses the old name (IsolatedRegion) must be rewritten to use the new name.

Query

Content Based Retrieval

Content Engine 3.5.x integrated the Verity VDK for CBR. As of the Content Engine 4.0 release, Autonomy K2 (the former Verity product) is integrated for CBR. The following changed search behaviors are a result of integrating Autonomy K2 as the CBR engine:

For more information, see the SQL Syntax Reference topic in the Content Engine Java and .NET Developer's Guide.

Query-related ObjectStore Properties

The following query configuration-related properties on an ObjectStore object are no longer supported:

As of the 4.0 release, the functionality supplied by these properties has been replaced with properties on the new ServerCacheConfiguration class:

Query Results

If your application uses the ExecuteSearch operation to perform a query that retrieves all information from a Content Engine 4.x table (using SELECT *), a much larger result set will be returned than in Content Engine releases prior to 4.0. This is because many system properties were previously marked as not selectable. Beginning in Content Engine 4.0, all properties are selectable.

Some of the newly selectable properties can be quite large; in particular, any properties of type ListOfObject (such as Permissions or PropertyDefinitions). This extra data can cause an increase in response times for queries. For any application that traverses all properties in a result set, this can cause a further increase in response time, and could change behavior if new, unexpected data types are encountered. Queries that specify an explicit list of columns in their SELECT clause will not be affected.

Unevaluated Properties in Query Results

If your application uses the ExecuteSearch operation to perform a query that retrieves information from a Content Engine 4.x table, some new properties that are returned from the query might be of type Unevaluated. (A query against a Content Engine 3.5.x table would never have returned an unevaluated object.) An object-valued property can be in an unevaluated state when the server cannot determine whether a value exists for that property. Any code that traverses all properties of a query result row might need to be updated to handle unevaluated properties.

Storage

StoragePolicy Class

Content Engine 4.x provides the StoragePolicy class only, whereas Content Engine 3.5.x also provides the StoragePolicy subclasses DatabaseStoragePolicy and FileStoragePolicy. Beginning in the 4.0 release, objects retrieved from the server (for example, when retrieving the StoragePolicies property of an ObjectStore object) will always be of the base class, and neither a DatabaseStoragePolicy nor a FileStoragePolicy instance can be created. This will generally have no impact on applications that simply enumerate the available policies and allow one to be selected as the policy for a new document.

File Stores

Beginning in Content Engine 4.0, a file store is defined to be a file storage area, and a hybrid file store is defined to be a fixed storage area. StorageArea is a new abstract class representing a physical content storage location. It has three concrete subclasses: DatabaseStorageArea, FileStorageArea (replacing FileStore) and FixedStorageArea (replacing a hybrid FileStore). FixedStorageArea can be further subclassed for fixed-content device-specific (such as IS or Snaplock) subclasses.

StorageRepositoryType Property Not Supported

As of the 4.0 release, because a storage policy no longer (in general) references a single storage area, it does not identify a particular storage repository type. Therefore, the StorageRepositoryType property on the StoragePolicy class and subclasses is no longer supported.

Moving Document or Annotation Content

In releases prior to 4.0, the targetPolicyId attribute for a MoveContentAction element specified the ID of a StoragePolicy object. Beginning in the 4.0 release, you must specify the ID of a StorageArea object.

Fixed Content Devices

Content Engine 3.5.x supported Hitachi, Tivoli, and IBM IICE fixed content devices on Microsoft Windows platforms. However, Hitachi and Tivoli fixed content devices are not supported in Content Engine 4.x. If a Content Engine 3.5.x object store uses one of these devices, the 4.x upgrade cannot succeed unless the content on these devices is first moved to a file store or to a fixed content device supported by Content Engine 4.x. In addition, the following Content Engine classes are no longer supported:

Changed FixedContentDevice Properties

In releases prior to 4.0, the FixedContentDevice (FCD) ConfigurationParameters property was a single XML string defining all of the FCD parameters used to configure the various FCD devices. This XML string has been split into separate properties. Each of the FCD-specific properties are on the specific type of FCD (for example, the IS FCD has IS-specific parameters). Additionally, some of the remaining FCD property names have been renamed to be more accurate.

Retrieving an ObjectStore's ClassDescription

In 3.5.x, you could return the ClassDescription object for the ObjectStore class via ObjectStore.GetObjects() or Domain.GetObjects(). Beginning in 4.0, only Domain.GetObjects() will work; ObjectStore.GetObjects() will return an error.

In addition, in releases prior to 4.0, if you retrieved the ClassDescriptions property for an ObjectStore object, the ClassDescription object for that ObjectStore object would be included in the collection. Beginning in 4.0, this is no longer the case. However, as in 3.5.x, you can continue to retrieve the ClassDescription object for an ObjectStore object by retrieving the ClassDescription property on the ObjectStore object.

ObjectStore DatabaseType property

In 3.x, the DatabaseType property was a string, giving the name of the OLEDB provider for the type of database. Beginning in 4.0, this is replaced by an integer property of the same name, with a value indicating the database type as follows:

Content Type

In releases prior to 4.0, when an application did not supply a content type value for a ContentReference or ContentTransfer object, the 3.x Content Engine used file extension mappings in the Windows registry along with Microsoft APIs to examine document content. As of the 4.0 release, the Content Engine identifies the content type based on a fixed listing of file extensions.

Because Content Engine 4.x uses a set listing of file extensions to identify the document content type, the resulting (identified) content type can be different from that identified by Content Engine 3.5.x. To ensure that an object's content type is identified properly, explicitly specify the ContentType property for existing Content Engine 3.5.x applications when creating or updating a content element.

Creating an Addon

Any 3.5.x Content Engine Web Service application that creates an AddOn requires code changes to work with a Content Engine 4.x server. In particular, you must set the ImportData property (of type ContentData) instead of setting the XMLManifest property (of type SingletonString). Note that these code changes are required only for code that creates an AddOn and not for code that installs an AddOn. In addition, the PreImportScript and PostImportScript properties were of type String, but beginning in the 4.0 release are of type ContentData.

IsPersistent Property

Releases prior to 4.0 included the IsPersistent property on the PropertyDefinition and PropertyDescription classes. Beginning in the 4.0 release, this property has been renamed to PersistenceType for these classes. (For the ClassDefinition and ClassDescription classes, the property name remains IsPersistent). Although the server will convert IsPersistent to PersistenceType during property template creation, any existing code that attempts to retrieve the IsPersistent property for PropertyDefinition and PropertyDescription objects must be changed to retrieve the PersistenceType property.

Document Lifecycles

Document Lifecycle Actions

Content Engine 3.5.x supported Microsoft ActiveScript technology for document lifecycle actions. As of the 4.0 release, lifecycle actions must be Java-based. Furthermore, the Java class must be located on the server; it cannot be on a client and streamed to the server for execution as for CE 3.5.x. Any DocumentLifecycleAction objects that your application uses must be modified to use a Java class instead of a script. In addition, note the changes in the following DocumentLifecycleAction properties:

Cannot Delete Default DocumentLifecyclePolicy

In releases prior to 4.0, you could delete any DocumentLifecyclePolicy object as long as the DocumentLifecyclePolicy object was no longer being referenced by one or more Document instances. Beginning in the 4.0 release, you cannot delete a DocumentLifecyclePolicy if it is being referenced by one or more Document instances or if it is the default policy for a Document class.

Document Classification

COM-based Plug-ins Not Supported

Content Engine 3.5.x supported COM-based plug-ins for document classification actions. As of the 4.0 release, classification actions must be Java-based. Furthermore, the Java class must be located on the server; it cannot be on a client and streamed to the server for execution as for CE 3.5.x. Any DocumentClassificationAction objects that your application uses must be modified to use a Java class instead of a COM class. For information on how to create a document classification action, see Understanding automatic document classification in the Help for Content Engine Administration. In addition, note changes in the following DocumentClassificationAction properties:

XMLPropertyMappingScript Algorithm

In 3.5.x, the algorithm used by the XMLPropertyMappingScript object was as follows:

  1. Search for a Processing Instruction named FileNetDocClass:
    1. If it exists, use its value.
    2. Otherwise, search for a DTD with an external specifier:
      1. If it exists, use the value of the SYSTEM attribute (which usually contains a URL).
      2. Otherwise, use the name of the root element.

Beginning in the 4.0 release, the algorithm is as follows:

  1. Search for a Processing Instruction named FileNetDocClass:
    1. If it exists, use its value.
    2. Otherwise, get the expanded QName of the root element in the form of
      {RootElementNamespaceURI}RootElementLocalName. (The system looks for this in the XMLDocumentType property.)

If your existing application uses a FileNetDocClass Processing Instruction node in the XML content, no change is required for 4.x. Otherwise, you need to modify the value of the XMLDocumentType property of the XMLPropertyMappingScript object to use the new format: {RootElementNamespaceURI}RootElementLocalName. For example:

If the root element is: <claim xmlns="http://www.filenet.com/claimSchema">, then the expanded QName is: {http://www.filenet.com/claimSchema}claim.

GUID Strings

In the 3.5.x release, operations that convert a GUID from a String to the internal form ignored any data after the closing } (brace). For example, the boldface text after the closing brace below would have been ignored:

{1321358E-DD13-4913-A44C-B57659A05C1E}, brown, filenet;cemp:t3: //localhost:7001/ FileNet/Engine;null

Beginning in the 4.0 release, this is no longer the case; any applications relying on this behavior must be updated.

Type Property on Domain Class Not Supported

Beginning in the 4.0 release, the Type property on the Domain class is no longer supported. The Type property was meant to indicate the type of IBM FileNet P8 domain (private, public, or workgroup), but public was the only type the Content Engine COM API ever supported.

GCD Changes

In previous releases, the GCD (Global Configuration Data) was stored in the local file system. As of the 4.0 release, the GCD is generally stored in a separate database instance, leveraging the RDBMS used by Content Engine.

During the upgrade operation from IBM FileNet P8 3.5.x, the DateCreated and Creator properties for the following objects are replaced with the date of the upgrade and the name of the user performing the upgrade, respectively:

The DateCreated and Creator properties are not changed by the upgrade operation for objects that reside within an object store (such as Documents, Folders, and CustomObjects).