The Content Engine Web Service (CEWS) supports Microsoft® .NET clients written in C# and Visual Basic. For additional hardware and software requirements, see the IBM® FileNet® P8 Hardware and Software Requirements document for this release. To download this document from the IBM support page, see Accessing IBM FileNet Documentation.
When you set a web reference to CEWS from a Microsoft® .NET client, an accompanying Boolean data type attribute that allows you to specify null values is automatically created for each element attribute of data type Boolean
, DateTime
, Double
or Int32
. This attribute's name is composed of the text "Specified" appended to the name of the attribute to which it is associated and should be set in your client application as follows:
Boolean
, DateTime
, Double
or Int32
to a non-null value, you should also set the value of its associated "Specified" attribute to true
. For example:elemPropFilter.maxRecursion = 1; elemPropFilter.maxRecursionSpecified = true;
Boolean
, DateTime
, Double
or Int32
to null, you should also set the value of its associated "Specified" attribute to false
.Customers building .NET-based CEWS client applications should use the 4.0 WSDL, which supports Message Transmission Optimization Mechanism (MTOM) as the attachment standard, thus allowing them to use Microsoft Visual Studio® 2005 with Web Services Enhancements (WSE) 3.0 as their development environment. Because WSE 3.0 does not support Direct Internet Message Encapsulation (DIME), client applications that are based on WSE 3.0 should not use DIME attachments. Those applications must use either MTOM or SOAP with inline base64 encoding to upload or retrieve content data. Because MTOM allows for more efficient sending of binary data than SOAP with inline, base64 encoding, it is the preferred method for transmitting content data.
Client applications using the 4.0 WSDL have the option to retrieve content using a GetContent
request instead of using the Content
pseudo-property in conjunction with a GetObjects
request. With a GetContent
request, an application has the advantage of being able to retrieve portions of the content and at a specific offset.
The use of the DIME standard to upload and retrieve content is deprecated and support for DIME attachments will be dropped in a future P8 release. Because DIME support is deprecated in the 4.0 WSDL, the DIMEAttachmentReference
and DIMEContent
elements are also deprecated. Therefore, any .NET client applications using DIME should be ported to work with the 4.0 endpoints and use either MTOM or SOAP inline base64 encoding for content upload and retrieval.
For a 4.0 WSDL-based application, you can upload and retrieve content data with either MTOM or SOAP 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.
CEWS accepts the WS-Security UsernameToken
security token, which allows clients to provide their username and password security credentials to authenticate with the application server via your directory service. For more information, see Soap Headers. The following C# code example demonstrates how to set this token using Microsoft Visual Studio 2005 with WSE 3.0 installed:
using Microsoft.Web.Services3; using Microsoft.Web.Services3.Security.Tokens; using Microsoft.Web.Services3.Design; // Create the WSE-enabled service and set credentials FNCEWS40ServiceWse wseService = new FNCEWS40ServiceWse(); UsernameToken token = new UsernameToken("username", "password", PasswordOption.SendPlainText); wseService.SetClientCredential(token); Policy MyPolicy = new Policy(); MyPolicy.Assertions.Add(new UsernameOverTransportAssertion()); wseService.SetPolicy(MyPolicy); wseService.Url = "http://localhost:9080/wsi/FNCEWS40MTOM/wsdl"; // Assign CEWS URL
For Kerberos single sign-on (SSO), a .NET client can authenticate using the KerberosToken2
security token instead of the UsernameToken
security token if the Content Engine is configured for Active Directory authentication (LDAP is not supported). This form of SSO is equivalent to integrated logon as supported by the Content Engine and is implemented within the built-in extensible authentication of the Active Directory authentication provider.
The KerberosToken2
security token is constructed with a principal name that is derived from the bind URL by extracting the host name portion and prefixing "FNCEWS/" as shown in the following code example:
SecurityToken token = new KerberosToken2 ("FNCEWS/seattle.westcoast.local");
The host name can be a simple NetBIOS or DNS name, but it cannot contain a localhost or an IP address.
Alternatively, you can construct the KerberosToken2
security token with the Windows account name of the service under which the target Content Engine object store is operating; typically, “<domain name>\FNCE_<machine name>“ or “FNCE_<machine name>”. However, because the account name cannot usually be derived from the bind URL, this approach is not recommended.
The following C# code example demonstrates how to prepare a binding using a KerberosToken2
security token:
using Microsoft.Web.Services3; using Microsoft.Web.Services3.Security.Tokens; using Microsoft.Web.Services3.Design; // Create the WSE-enabled service and set credentials FNCEWS40ServiceWse wseService = new FNCEWS40ServiceWse(); SecurityToken token = new KerberosToken2 ("FNCEWS/seattle.westcoast.local"); wseService.SetClientCredential(token); Policy MyPolicy = new Policy(); MyPolicy.Assertions.Add(new UsernameOverTransportAssertion()); wseService.SetPolicy(MyPolicy); wseService.Url = "http://localhost:9080/wsi/FNCEWS40MTOM/wsdl"; // Assign CEWS URL
Use the Localization
element's Locale
element to specify the name of the locale and its Timezone
element to specify the local time zone offset from UTC.
For sample code written in C# and Visual Basic on the Microsoft .NET platform (Microsoft Visual Studio 2005 with WSE 3.0), see the following zip files. Note that this sample code does not support uploading content data that is over 100 MB:
To download these zip files from the IBM support page, see Accessing IBM FileNet Documentation