FileNet was founded in 1982 and released one of the first commercially successful document imaging solutions. At the time, the solution required custom software and hardware. Over the years, it has evolved into more of a software-based solution that today contains much more than just document imaging. FileNet was acquired by IBM in 2006 and has retained the FileNet moniker for the software product line. In its most recent form, it is called the IBM FileNet P8 4.0 Platform (FileNet P8 for short, but I’ve used FileNet and FileNet P8 interchangeably throughout this article).
FileNet P8 is a suite of enterprise software that is known for enabling businesses to integrate process and content management in one solution. The suite also contains products such as records management, electronic forms, and compliance management, just to name a few. As an example of the flexibility and integration capabilities provided, the IBM FileNet Business Process Framework provides a user interface that is built on a highly extensible and configurable framework that incorporates the core products in FileNet P8.
This article will focus on the core FileNet P8 functionality of business process and content management. Both products provide a mixture of thick-client and Web-based user interfaces to configure and use. Most standard uses of the software can be handled through this out-of-the-box functionality. However, a key feature of FileNet is the capability to access its functionality through APIs for Java, .NET, or XML Web services. This opens up the capability to create standalone applications (Web or desktop based) that use FileNet as the foundation.
Initially, the FileNet API may seem large and complex but through this article I’ll cover the basic steps needed to connect to both the process and content management products using the FileNet Java API. This will serve to help navigate the APIs for those new to FileNet and also help veterans get started connecting to FileNet P8 4.0 quickly.
FileNet P8 Architecture
Before you dive into the API code, it is helpful to understand the basic architecture for FileNet P8 4.0. The two main core components that yu’ll focus on are the FileNet Content and Process Engines.
Figure 1: High-level FileNet Architecture (Image from Reference 1)
The FileNet Content Engine (CE) stores content and its metadata as part of business objects that are classified by Document Classes. These classes can define different objects such as images, documents, search templates, custom objects, workflow objects, and many others. They are organized by folders in an Object Store. The CE is able to store these items in a variety of storage mediums, including the file system, a relational database or external devices.
The CE runs as a J2EE application that enables web service access. Configuration is mainly done in a thick-client application called FileNet Enterprise Manager (FEM) that allows configuration of the Object Stores and Document Classes. Once this main configuration is done, the fine tuning can be done either in FEM or the web-based FileNet Workplace application.
Figure 2: High-level Content Engine Architecture (Image from Reference 2)
The FileNet Process Engine (PE) drives the cqpability to create and simulate business processes in Workflows. These Workflows are stored as content in the CE and can be configured through Workplace. The PE relies heavily on the CE for access to certain resources such as Directory Services, and communication between the two is handled over IIOP.
Figure 3: High-level Process Engine Architecture (Image from Reference 2)
FileNet P8 4.0 takes advantage of a combination of the J2EE application server, JAAS, and directory services to establish authentication. Because PE resolves its authentication through the CE, Directory Services only need to be configured once for the CE. Authorization is provided on many levels and can be as broad as an LDAP group or as specific as a particular user. This concept applies to both CE and PE elements.
When IBM released FileNet P8 4.0, it introduced major architectural changes from previous versions. By incorporating more J2EE standards, it allowed FileNet P8 4.0 to be run on operating systems other than Windows as long as it is installed on a J2EE Application Server. Old FileNet API code is still compatible with FileNet P8 4.0, but it is highly recommended to switch to the 4.0 APIs.
One of the key changes was the transport methods for connecting to CE and PE. Previously, the communication used Content Engine Web Service (CEWS) transport based on the SOAP protocol. This has been upgraded with the capability to use an EJB protocol along with added benefits such as using JAAS for security.
Uses of FileNet Outside of an Application Server
FileNet Workplace is the out-of-the-box Web-based application that is usually deployed along with FileNet CE and PE. It allows users to organize documents, create workflows, and lots more. However, there may be cases where unique requirements aren’t solved in Workplace or FileNet may need to be integrated seamlessly into an existing application. This is where the flexibility of the FileNet API comes into play. It enables you to do pretty much everything that Workplace can while allowing you to add in your own custom logic and functionality. This is an easy way to create robust custom applications that are backed by enterprise-level content and business process management.
These custom applications can be online or offline applications and be built in .NET or Java. In any case, the ability to test custom code using the FileNet API is crucial to fast development and a quality product. To do this, you’ll want to be able to connect to FileNet outside of an application server. However, there are some things that need to be set up first to connect to FileNet through the API. An example is CE is deployed as a J2EE application and some libraries from the application server that CE is deployed on will need to be included. The rest of the article will serve as a tutorial for getting started using the FileNet API and connecting to a FileNet environment.
Setting Up the Environment
A working FileNet 4.0 environment needs to be configured before running the sample code presented in this article. Because my FileNet environment runs on a WebSphere 6.1 application server and uses Java 1.5, this is the base that I will be using throughout the article. If you are running FileNet on a different platform, minor changes in the VM Arguments and JAR files are needed to match the application server you are using. These differences are talked about later in the article.
I’ll be using the EJB transport protocol along with JAAS for authentication. Before the sample code is run, it is necessary to configure the CE and PE elements to retrieve in your sample code. This includes but is not limited to Domain, Object Store, Document Classes, Isolated Region, Roster, and Queues. Refer to your FileNet documentation for more information on configuring these items.
Setup Tasks
For the sample code to use the correct JAAS stanza, the line shown in Listing 1 needs to be included in the JAAS configuration file:
Listing 1: JAAS Stanza
FileNetP8 {
com.ibm.ws.security.common.auth.module.WSLoginModuleImpl
required;
};
If you aren’t using JAAS currently, you can create a blank text file containing the stanza and save it to your application configuration folder.
There are a couple WebSphere specific files that are used as well. To establish a connection to CE residing on WebSphere, the proper Secure Association Service (SAS) file must be configured. This file resides in this folder:
{WebSphere Root}IBMWebSphereAppServerprofiles
{Profile Name}properties
Copy the sas.client.props file to the configuration folder. If SSL is also needed, copy the ssl.client.props file as well.
The following lines need to be modified in the sas.client.props file you just copied:
Listing 2: sas.client.props File Changes
...
com.ibm.CORBA.securityServerHost={CE Server DNS or IP}
com.ibm.CORBA.securityServerPort={CE Server Port}
...
com.ibm.CORBA.loginSource=none
...
If you are using SSL, nothing needs to be changed in the ssl.client.props file you copied over.
The following FileNet-specific JARs must be added to run the sample code. They can be found in the lib directory within the Workplace application.
- Jace.jar (Contains the CE API)
- pe.jar (Contains the PE API)
The following WebSphere 6.1-specific JARs also need be added to run the sample code:
- com.ibm.ws.admin.client_6.1.0.jar ({WebSphere Root}IBMWebSphereAppServerruntimes)
- j2ee.jar ({WebSphere Root}IBMWebSphereAppServerlib)
Additionally, these libraries need to be added as well:
- Log4j 4.x
- JUnit 4.x
FileNetConnectionTest.java
Once the environment is set up, you can start looking into the FileNetConnectionTest.java code. The FileNet API is organized by packages for the Content Engine (com.filenet.api.*) and Process Engine (filenet.vw.api.*). In the sample code, the goal is to connect successfully to both CE and PE, and retrieve a list of Document Class properties and Queues.
FileNetConnectionTest.java (Download)
Static Variables
There are a few static application parameters that you will use in the sample code.
FILENET_USERNAME
The Login ID for the user that you want to connect to FileNet with. Any content or workflows updated will be attributed to this user.
FILENET_PASSWORD
The password for the user
A simple test to see whether a user has sufficient rights to do certain functions via the API is to log in to Workplace and attempt to do the functionality that you are trying through the API. An example is, if you are trying to get a list of Document Classes through the API, you should be able to do the same in Workplace.
FILENET_URI
The URI that the application should use to connect to FileNet. This URI is used by both the CE and PE, and should point to the CE server. Because I’m using WebSphere with the EJB transport, the URI is in the format of “iiop://[server]:[port]/FileNet/Engine”. Adjust the URI according to your platforms EJB syntax.
CE_DOMAIN
The Domain represents a logical grouping of physical resources. A single Domain may contain multiple Object Stores.
CE_OBJECTSTORE
An Object Store represents a location in which CE folders and content are managed on the server. The Object Store name can be found in FEM or by logging into Workplace and looking at the list of Object Stores on the left side.
Each Object Store has its own set of Document Classes that can be defined. There is a default Document Class called ‘Document’ that serves as the base Document Class.
PE_CONNECTION_POINT
Connection Points have replaced the Routers from FileNet 3.5 and enables connection to a PE Isolated Region. The PE Isolated Region is like the CE Object Store in that it holds PE queues, rosters, and other workflow configurations. Connection Points can be managed through FEM.
Main Code
In this section, I’ll break down the main test method in the sample code and explain the API calls being made. The sample code starts off by logging into the CE first.
Connection ceConnection = Factory.Connection.getConnection(FILENET_URI);
The CE API contains Factory.* classes to create CE objects. To establish a Connection object, call the Factory.Connection class to create one by passing in the URI. This Connection object represents a logical connection to a FileNet Domain.
Subject ceSubject =
UserContext.createSubject(ceConnection, FILENET_USERNAME,
FILENET_PASSWORD, null);
Next, to use JAAS, you create a Subject object. You pass in the username and password you want to use. The third parameter is for the JAAS stanza. Passing in ‘null’ means you want to use the default FileNet JAAS stanza, which is called ‘FileNetP8’. The server authenticates the user and returns the JAAS subject.
UserContext.get().pushSubject(ceSubject);
Before running any further CE API calls, it is necessary to push a Subject object onto the UserContext stack. This sets the user pushed as the active user for subsequent CE API calls.
Domain ceDomain = Factory.Domain.fetchInstance(ceConnection, CE_DOMAIN, null);
Now that you have a valid Subject on the stack, you can retrieve objects from the FileNet server. In this case, you call a fetch* to retrieve a Domain from the FileNet server by passing in the Connection object you created earlier and the Domain name that you want to retrieve. The third parameter represents a PropertyFilter object; it controls what properties should be returned. For the sample, I’ve left this as null so that all non-object properties are returned by default.
ObjectStore ceObjectStore =
Factory.ObjectStore.fetchInstance(ceDomain, CE_OBJECTSTORE,
null);
Because the Domain is a container for CE resources, you now can retrieve your Object Store. You use the same type of call as retrieving the Domain, but instead you pass in the Domain object and the Object Store name. Once again, you pass in a ‘null’ for the PropertyFilter.
Once you get a valid Object Store object, you are now logged in and ready to use the rest of the CE API.
The next couple lines show how you would retrieve the properties of a Document Class.
ClassDefinition classDef =
Factory.ClassDefinition.fetchInstance(ceObjectStore,
"Document", null);
A Document Class is represented by the ClassDefinition interface. To retrieve a specific instance of a Document Class, you fetch it by passing in the Object Store object and the Document Class name you want. The “Document” document class is provided by default and serves as the base class for other document classes.
PropertyDefinitionList properties = classDef.get_PropertyDefinitions();
Now that you’ve fetched the Document Class, you can call a get* to retrieve the properties on the Document Class. It returns a PropertyDefinitionList, which is an iterable collection of PropertyDefinition objects.
for (Iterator propertyIter =
properties.iterator(); propertyIter.hasNext();) {
PropertyDefinition property =
(PropertyDefinition) propertyIter.next();
System.out.println("Property: " + property.get_DisplayName());
}
For each PropertyDefinition you can get a lot of metadata, including the display name and symbolic name. Here, you iterate the properties and output the display name to the console.
UserContext.get().popSubject();
Lastly, you pop the Subject off because you are done making CE API calls. This makes the next Subject on the stack the active user.
VWSession peSession = new VWSession(); peSession.setBootstrapCEURI(FILENET_URI);
The FileNet PE login starts by creating a VWSession object. The VWSession object is the starting point for most of the PE API calls. With the VWSession object, you can query rosters and queues, and process any items found. In this test code, you’ll log in to the PE and retrieve a list of all Process Queues that are configured.
peSession.logon(FILENET_USERNAME,
FILENET_PASSWORD,
PE_CONNECTION_POINT);
Once you have the VWSession object, you set the CE URI onto the object so that it can perform the login and authentication. Once this method executes successfully, you will be logged into the PE.
String[] queueNames = peSession.fetchQueueNames(VWSession.QUEUE_PROCESS);
From here, you can call fetchQueueNames to retrieve the Queues. The static value you pass in says that you want only the Queues that will be processing Workflow items. There are also other options, such as only system queues or user queues.
for (String queue : queueNames) {
System.out.println("Queue: " + queue);
}
The fetchQueueNames method returns an array of Strings for the name of the Queues. You simply print out the names of the Queues for verification.
Although you’ve covered the basic API calls to login to CE and PE and perform simple queries, this serves as the basis for more complicated API calls. The full API and developers guide are documented within the FileNet ECM Help site, whose link can be found off of Workplace.
Running the Sample Code
Now that you’ve explored what is in the sample code, it is time to try running it in your environment. I used Eclipse and JUnit to run the sample code, but any Java IDE or command line will work as well. Before executing the sample, some VM arguments need to be set so that the configuration files are located properly.
I’ve set mine in the ‘Run Configurations…’ window in Eclipse.
Figure 4: Configuring JUnit VM Arguments in Eclipse
Listing 3: VM Arguments
-Djava.naming.factory.initial="com.ibm.websphere.naming.
WsnInitialContextFactory"
-Djava.security.auth.login.config=file:"{JAAS file location}"
-Dcom.ibm.CORBA.ConfigURL=file:"{sas.client.props location}"
-Dcom.ibm.SSL.ConfigURL=file:"{ssl.client.props location}"
The SSL line is needed only if WebSphere was configured with SSL enabled. The other three lines are mandatory to connect to WebSphere.
Executing the sample code will print the initialization logs to the console. From there, it will output any fatal exceptions. If the sample code runs successfully, the CE Document Class properties and PE queues you have configured will be shown in the console.
Figure 5: Output of Successful CE login and Retrieval of Document Properties
Figure 6: Output of Successful PE login and Retrieval of Queues
Different Platforms
The different libraries and VM arguments required for running the sample code on another application server can be found in the FileNet ECM Help documentation under:
- CE: http://{ECM Help}/nav/dev_ce_start.htm?../developer_help/content_engine_api/guide/gs_concepts.htm#gs_requirements
- PE: http://{ECM Help}/nav/dev_pe_start.htm?../developer_help/process_java_api/guide/misc/install_pde.htm
Conclusion
I hope that this article has introduced you to the core elements of the IBM FileNet P8 4.0 Platform and its API. From here, you can become more familiar with the API and the flexibility it offers by exploring the ECM Help documentation.
References
- IBM BPM Article
- Wikipedia FileNet entry
- FileNet 4.0 System Overview
- ECM Help: This documentation is usually installed as a separate application on the same server as Workplace (http://{Workplace server}:{Workplace port}/ecm_help
About the Author
Anthony Lee is a Senior Consultant at Crowe Horwath. He has worked extensively with both Java and FileNet, and is a certified developer for both.
