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:
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:
Content
pseudo-property (in conjunction with the GetObjects
operation): This is the same method used in 3.5 WSDL-based applications to handle content data. Using MTOM, this is the most efficient way to download content data because a single network trip is guaranteed. However, to obtain maximum efficiency you must have enough contiguous memory available to hold the entire content. GetContent
operation: This a new operation in the 4.0 WSDL and can be used for content retrieval only. GetContent
allows you to retrieve a portion of the content data or to retrieve the content data at a specific offset. Although not as efficient as the Content
pseudo-property, GetContent
is useful if you do not have enough contiguous memory available to hold the entire content data or if you only need a portion of the content data. 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:
Microsoft.Web.Services3
.Microsoft.Web.Services2
in the project with Microsoft.Web.Services3
. This can leave some assembly usages invalid (for example, Microsoft.Web.Services3.Dime
).Microsoft.Web.Services2
.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.FNCEWS35ServiceWse
) with the new name (for example, FNCEWS40ServiceWse
).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)
).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:
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)
DIMEContent
and DIMEAttachmentReference
objects). 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.Binary
property of an InlineContent
object.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:
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;
Binary
property of the InlineContent
object returned as the Value
property of a ContentData
object. For example:
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
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).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.
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.
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:
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.
As of release 4.0, the following classes are no longer supported by the Content Engine:
CbrEngineType
Computer
ContentCacheService
ContentManagerService
FileStore
ObjectStoreService
Transient
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:
.
OIID, in previous releases, this was retrievable only via queries; use This instead.PropertyDescription/PropertyTemplate/PropertyDefinition.
IsPersistent, renamed to PersistenceType.Subscription.
EnableOn*, deprecated in a previous release; use SubscribedEvents instead.ObjectStore.
DatabaseConnectionString, the 4.x Content Engine uses a completely different mechanism for specifying the database for an object store. ObjectStore.
DatabaseName, deprecated in a previous release.ObjectStore.
DatabaseServerName, deprecated in a previous release.ObjectStore.
EnumBatchSize,
DefaultQueryBatchSize,
DefaultQueryRowLimit,
MaxQueryRowLimit; see Query-related ObjectStore Properties.StoragePolicy.
StorageRepositoryType; see StorageRepositoryType Property Not Supported.PropertyDescription.
QueryOperatorDescriptions, deprecated in a previous release; for internal use only.Realm.
Users and Realm.
Groups; use the PrincipalSearch
option of ExecuteSearch
to obtains
lists of users, groups, or both meeting specified criteria.Additional information on removed properties is provided in sections below.
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.
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).
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.
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.
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:
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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:
FSBFixedContentDevice
TivoliFixedContentDevice
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.
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.
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:
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.
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
.
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.
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:
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.
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:
In 3.5.x, the algorithm used by the XMLPropertyMappingScript
object was as follows:
Beginning in the 4.0 release, the algorithm is as follows:
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
.
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.
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.
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:
ObjectStores
MarkingSets
FixedContentDevices
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
).