Overview of FileNet REST API 2.0

The FileNet REST API 2.0 is a modern and flexible way to interact with IBM FileNet Content Manager repositories using RESTful web services. It allows you to perform CRUD (Create, Read, Update, Delete) operations on documents, folders, and other content management objects, as well as search, security management, and other FileNet-related functions.

The REST API simplifies the integration of FileNet Content Manager with web-based applications, mobile devices, and third-party systems, by allowing them to communicate with FileNet using standard HTTP methods and JSON format.

Key Concepts

1. RESTful Endpoints:

o The REST API exposes a set of HTTP endpoints that can be accessed via standard GET, POST, PUT, DELETE methods.

o Responses are typically returned in JSON format, which is widely supported by modern web and mobile applications.

2. Base URL:

o The base URL for FileNet REST API typically looks like this:

http://<filenet-server>:<port>/api

o The API is hosted by FileNet's Content Engine (CE), and you'll interact with it using endpoints that reflect FileNet's object model (e.g., documents, folders, properties, search).

3. Authentication:

o FileNet REST API uses Basic Authentication or OAuth 2.0 (depending on the configuration) to authenticate users. Basic Authentication requires sending the username and password with the HTTP request.

o For more secure configurations, OAuth 2.0 is used, where tokens are obtained and used for subsequent API calls.

4. Object Model:

o The REST API interacts with the FileNet object model, which includes documents, folders, collections, users, and custom objects. These objects are represented as resources, and their properties are typically accessed and manipulated via the API.

________________________________________

Key Operations with FileNet REST API 2.0

Here’s an overview of the main operations available with the FileNet REST API:

________________________________________

1. Authentication

• Login (Basic Authentication)

o Use HTTP Basic Authentication to authenticate users:

POST http://<filenet-server>:<port>/api/v1/login

Content-Type: application/json

{

  "user": "<username>",

  "password": "<password>"

}

• OAuth Authentication (more secure method, but requires setup in the FileNet server for OAuth)

o First, obtain the OAuth token using the credentials.

________________________________________

2. Create Document

To create a document, you typically POST a JSON payload with the document metadata and content.

• Create Document (Example)

POST http://<filenet-server>:<port>/api/v1/objects/documents

Content-Type: application/json

{

  "properties": {

    "DocumentTitle": "Sample Document",

    "Author": "John Doe"

  },

  "content": {

    "fileName": "sample.pdf",

    "mimeType": "application/pdf",

    "fileContent": "<Base64-encoded file content>"

  }

}

• Explanation:

o properties: Defines the document metadata.

o content: Contains the document's content. The file is uploaded as a Base64-encoded string or as a binary payload.

________________________________________

3. Get Document (Retrieve by ID)

To retrieve a document, use a GET request with the document's ID.

• Get Document by ID

GET http://<filenet-server>:<port>/api/v1/objects/documents/{documentId}

Authorization: Bearer <access_token>

• Response (JSON format) The response will contain the document's properties and metadata:

{

  "id": "{documentId}",

  "properties": {

    "DocumentTitle": "Sample Document",

    "Author": "John Doe",

    "DateCreated": "2025-04-27T12:34:56Z"

  },

  "content": {

    "fileName": "sample.pdf",

    "mimeType": "application/pdf",

    "fileSize": 1024

  }

}

________________________________________

4. Update Document Properties

You can update the properties of an existing document using the PUT method.

• Update Document Properties

PUT http://<filenet-server>:<port>/api/v1/objects/documents/{documentId}

Content-Type: application/json

{

  "properties": {

    "DocumentTitle": "Updated Document Title",

    "Author": "Jane Doe"

  }

}

• Explanation:

o The PUT request allows you to modify the document's metadata (not the content). If you want to update the content, you would need to send the content again in the request.

________________________________________

5. Delete Document

To delete a document, send a DELETE request.

• Delete Document

DELETE http://<filenet-server>:<port>/api/v1/objects/documents/{documentId}

Authorization: Bearer <access_token>

________________________________________

6. Search Documents

The FileNet REST API supports a powerful search feature, allowing you to perform queries using the CMIS (Content Management Interoperability Services) query syntax or FileNet-specific CEQL (Content Engine Query Language).

• Search Documents (using CMIS Query)

GET http://<filenet-server>:<port>/api/v1/search

Authorization: Bearer <access_token>

{

  "query": "SELECT * FROM Document WHERE DocumentTitle = 'Sample Document'"

}

• Search Response:

o The result will be returned as a list of document objects in JSON format, including document IDs, properties, etc.

________________________________________

7. Folder Operations

FileNet allows operations on folders as well:

• Get Folder by ID:

GET http://<filenet-server>:<port>/api/v1/objects/folders/{folderId}

Authorization: Bearer <access_token>

• Create Folder (Post Request):

POST http://<filenet-server>:<port>/api/v1/objects/folders

Content-Type: application/json

{

  "properties": {

    "FolderName": "New Folder"

  }

}

________________________________________

Error Handling

The REST API will return HTTP status codes to indicate the result of an operation:

• 200 OK: Successful request (e.g., document retrieved).

• 201 Created: Successful creation (e.g., document created).

• 400 Bad Request: Invalid request (e.g., invalid JSON syntax or missing parameters).

• 401 Unauthorized: Authentication failure.

• 403 Forbidden: Insufficient permissions.

• 404 Not Found: Resource (e.g., document or folder) not found.

• 500 Internal Server Error: Server-side issues.

________________________________________

FileNet REST API 2.0 Features

1. Modern and Lightweight:

o RESTful architecture with JSON responses is lightweight and easier to integrate with modern web applications.

2. Support for Content and Metadata Operations:

o You can perform both content-related operations (like uploading, retrieving, or deleting files) and metadata operations (like updating properties, searching for documents, etc.).

3. Extensive Search Capabilities:

o The API allows using CMIS queries for searching, making it easier to integrate with other systems that also support CMIS.

4. Multi-part Content Handling:

o Supports multi-part uploads for large files (useful for documents that exceed typical payload size).

________________________________________

Conclusion

The FileNet REST API 2.0 is a powerful and flexible way to interact with FileNet Content Manager repositories. It provides a wide range of functionalities for document management, including CRUD operations, search capabilities, and content management. Its simple, modern, and standard HTTP-based interface makes it ideal for web and mobile app integrations, allowing you to integrate FileNet with other enterprise systems.

Here's an example of how you can perform a simple search query on FileNet using the FileNet REST API.

In this example, we'll search for documents with a specific DocumentTitle (e.g., Sample Document), using the CMIS query language, which is supported by FileNet REST API for searching.

Steps to Perform a Simple FileNet Search Query

1. Set Up the API URL and Authorization: The base URL for accessing the FileNet REST API would generally look like this:

http://<filenet-server>:<port>/api/v1/search

For authentication, you would typically use either Basic Authentication or OAuth 2.0. In this example, we'll assume OAuth 2.0 is used, and you have an access token.

2. Search Query Example Using CMIS: The search query uses CMIS Query Language, which is similar to SQL but specific to content management.

Here’s the CMIS query you would run:

SELECT * FROM Document WHERE DocumentTitle = 'Sample Document'

This query retrieves all documents where the DocumentTitle property is equal to Sample Document.

________________________________________

Example of a FileNet REST API Search Request

HTTP Request:

GET http://<filenet-server>:<port>/api/v1/search

Authorization: Bearer <access_token>

Content-Type: application/json

{

  "query": "SELECT * FROM Document WHERE DocumentTitle = 'Sample Document'"

}

Explanation:

• URL: http://<filenet-server>:<port>/api/v1/search

o Replace <filenet-server> and <port> with your actual FileNet server address and port.

o This endpoint triggers the search operation.

• Authorization: Bearer <access_token>

o You'll need an OAuth access token to authenticate the request.

• Content-Type: application/json

o The content is sent and received in JSON format.

• Request Body:

o The query is a CMIS query string, where we search for all documents (SELECT *) where the DocumentTitle property matches 'Sample Document'.

________________________________________

Example Response (Successful Search):

HTTP Response:

HTTP/1.1 200 OK

Content-Type: application/json

{

  "objects": [

    {

      "id": "1234567890",

      "properties": {

        "DocumentTitle": "Sample Document",

        "Author": "John Doe",

        "DateCreated": "2025-04-01T12:34:56Z"

      },

      "content": {

        "fileName": "sample_document.pdf",

        "mimeType": "application/pdf",

        "fileSize": 1024000

      }

    },

    {

      "id": "9876543210",

      "properties": {

        "DocumentTitle": "Sample Document",

        "Author": "Jane Doe",

        "DateCreated": "2025-03-15T08:22:10Z"

      },

      "content": {

        "fileName": "sample_document_v2.pdf",

        "mimeType": "application/pdf",

        "fileSize": 2048000

      }

    }

  ]

}

Explanation of the Response:

• 200 OK: The query was successfully executed.

• objects: An array of documents matching the search criteria.

o Each document in the response contains:

 id: The unique identifier for the document.

 properties: Metadata of the document, including properties like DocumentTitle, Author, DateCreated, etc.

 content: Information about the document content, including fileName, mimeType, and fileSize.

In the example above, two documents with the title Sample Document are found.

________________________________________

Error Handling

If the query is invalid or there is some other issue, you might get an error response.

Example Error Response:

HTTP/1.1 400 Bad Request

Content-Type: application/json

{

  "error": {

    "code": "INVALID_QUERY",

    "message": "The query is invalid. Please check the syntax."

  }

}

Conclusion

With the FileNet REST API, you can easily search for documents based on their properties using CMIS queries. This simple example demonstrated how to search for documents with a specific title using a RESTful query. Depending on your requirements, you can extend the query with more complex conditions or additional fields (such as dates, authors, etc.).

In IBM FileNet P8 5.5.x, Custom Event Handlers refer to custom Java code that is executed in response to repository events, such as document creation, update, deletion, or other operations on objects like folders or custom classes. These handlers are often part of event subscriptions and are commonly used to implement custom business logic that cannot be achieved through standard configuration.

________________________________________

🔧 What Are Custom Event Handlers in FileNet?

• Custom Event Handlers are Java classes that implement the com.filenet.api.engine.EventActionHandler interface.

• They are triggered by events (like OnCreate, OnCheckIn, OnDelete) defined in event subscriptions.

• The logic in these handlers runs on the Application Engine or Content Engine, depending on configuration.

________________________________________

🧠 Typical Use Case

Use Case: Automatically Set Metadata When a Document Is Created

Suppose you want to automatically populate a custom property (Department) when a document is created, based on the folder it was added to.

________________________________________

🖥️ Example: Java Custom Event Handler

Step 1: Implement the EventActionHandler

package com.example.filenet.handlers;

import com.filenet.api.engine.EventActionHandler;

import com.filenet.api.core.Document;

import com.filenet.api.core.Factory;

import com.filenet.api.core.Folder;

import com.filenet.api.core.ObjectStore;

import com.filenet.api.engine.ExecutionContext;

import com.filenet.api.property.Properties;

public class AutoSetDepartmentHandler implements EventActionHandler {

    @Override

    public void onEvent(ObjectChangeEvent event, ExecutionContext context) {

        try {

            ObjectStore os = event.getObjectStore();

            Document doc = (Document) event.get_SourceObject();

            Folder folder = (Folder) doc.get_FoldersFiledIn().nextElement();

            String folderName = folder.get_Name();

            Properties props = doc.getProperties();

            props.putValue("Department", folderName); // Set the custom property

            doc.save(RefreshMode.NO_REFRESH);

        } catch (Exception e) {

            e.printStackTrace();

        }

    }

}

________________________________________

⚙️ Step 2: Deploy and Configure

1. Compile and package the Java class as a JAR.

2. Deploy it to the FileNet Content Engine classpath.

3. Register it in the FileNet Event Action using ACCE (Administrative Console for Content Platform Engine).

4. Create an event subscription for OnCreate on the desired class (e.g., Document), and associate the custom handler.

________________________________________

✅ Benefits

• Automates back-end logic securely and consistently.

• Runs on the server side, so users don't need to trigger anything manually.

• Keeps the repository intelligent and self-managing.

Migrating from IBM Case Manager (ICM) to IBM Business Automation Workflow (BAW) involves transitioning from a legacy case management platform to a modern, unified workflow and case management solution. IBM BAW combines capabilities from BPM, Case Manager, and Content Platform Engine into a single product.

Here’s a step-by-step outline of the migration process:

________________________________________

🚀 High-Level Migration Steps from ICM to BAW

1. Assessment and Planning

• Inventory existing ICM assets:

o Solutions

o Roles

o Pages

o Case Types

o Task Flows

o Document Classes

o Custom scripts/widgets

• Determine:

o Complexity of case models

o Custom integrations

o Use of legacy components (e.g., Dojo-based widgets)

• Decide on target BAW architecture: traditional (on-prem), containerized (CP4BA), or cloud.

________________________________________

2. Prepare the Environment

• Install IBM BAW (v19.x or later) with:

o Content Platform Engine (CPE)

o Business Automation Studio (for low-code modeling)

o Workflow Server (replaces BPM and ICM workflows)

o Case Client (modern Case UI)

• Ensure access to:

o Case Manager Builder

o BAW Design Tools (BA Studio, Workflow Center, etc.)

________________________________________

3. Export ICM Artifacts

• Use ICM Deployment Tool to export:

o Case Solutions

o Case Type Definitions

o Pages and Roles

o Task Settings

• Capture solution definition XML, security settings, and content model.

________________________________________

4. Transform Models for BAW

• There is no automatic tool to directly import ICM solutions into BAW. You'll need to recreate solutions in BAW:

o Use Business Automation Studio or BAW Designer.

o Rebuild:

 Case types with properties and stages

 Tasks (manual, automatic, BPMN)

 UI pages (via Coaches or Case Pages)

 Document classes and metadata

o Use Content Navigator Extensions if custom widgets need porting.

________________________________________

5. Integrate with Content Platform

• Map BAW case types to FileNet document classes.

• Reuse existing object stores or define new ones as needed.

• Configure document storage and security policies.

________________________________________

6. Migrate Content and Data

• If needed, use FileNet Export/Import tools, or custom scripts to:

o Migrate document data

o Re-link to new case instances

• Optionally, archive or leave legacy content in read-only mode.

________________________________________

7. Test End-to-End Scenarios

• Validate:

o Case creation, task execution, document handling

o Security and role access

o UI rendering and behavior

o Integration points (e.g., email, external systems)

________________________________________

8. Deploy and Train

• Deploy migrated BAW solutions to Production.

• Provide training for end-users and administrators.

• Monitor for issues using BAW logs and dashboards.

________________________________________

✅ Tips for Success

• Use BAW's low-code tools to speed up rebuild.

• Modernize UI and process logic instead of doing a 1:1 rebuild.

• Retire unused case types or components during migration.

• Start with pilot cases before a full cutover.

IBM Business Automation Workflow (BAW) integrates with IBM FileNet Content Manager to provide a seamless platform for combining business process management (BPM), case management, and enterprise content management (ECM).

This integration allows processes and cases in BAW to manage, access, and store documents and metadata in FileNet — enabling robust, content-centric applications.

________________________________________

🔗 How BAW Integrates with FileNet

1. Content Platform Engine (CPE) Integration

• BAW connects directly to FileNet's Content Platform Engine (CPE) via CE APIs.

• Allows BAW to:

o Access document classes

o Create and manipulate documents

o Link documents to cases and tasks

o Use FileNet security and storage policies

2. Object Stores

• BAW is configured to use one or more FileNet Object Stores.

• Each case solution in BAW is tied to a specific object store that holds:

o Case folders

o Case metadata (properties)

o Attached documents

3. Document Classes and Case Types

• Each BAW case type is backed by a FileNet document class.

• Properties defined in the case model are mapped to FileNet properties.

• BAW manages metadata and documents via this mapping.

4. Case and Document APIs

• BAW uses:

o Case REST APIs to manage case lifecycles and metadata

o Content Engine Java/REST APIs to manage documents and folders

• This allows workflows or UI components (Coaches) to create, fetch, or route documents stored in FileNet.

5. IBM Content Navigator (ICN) Integration

• BAW’s case UI often embeds or extends IBM Content Navigator (ICN).

• ICN is the standard viewer and editor for FileNet content.

• Users can:

o View and upload documents

o Launch workflows or tasks from within ICN

o Use custom widgets or plug-ins for specialized functions

6. Security Integration

• BAW respects FileNet document- and folder-level security, including:

o Role-based access

o ACLs (Access Control Lists)

• Single Sign-On (SSO) via LDAP or WebSphere helps unify access control.

________________________________________

📘 Example Use Case

Insurance Claims Case

• A new claim case is created in BAW.

• The associated documents (e.g., photos, forms) are stored in FileNet.

• Workflow tasks route the claim for review, using document content as decision input.

• A claims adjuster opens the case via Content Navigator, views the claim form stored in FileNet, and completes the task.

________________________________________

✅ Benefits of BAW–FileNet Integration

• Content-centric process automation: Tie business processes to rich document repositories.

• Scalability: FileNet handles high volumes of documents with lifecycle and retention support.

• Security and compliance: Centralized access control and auditability.

• Flexibility: Use case-style workflows or structured BPMN processes.

Migrating an IBM Case Manager (ICM) solution from 5.2.x to 5.5.x is a multi-step process that involves preparing your environment, upgrading the platform, and migrating your case solutions. The 5.5.x version introduces significant improvements and unification with IBM Business Automation Workflow (BAW), so careful planning and testing are essential.

________________________________________

🧭 Migration Overview

🚩 Key Components in Migration:

• Case Manager application and its solutions

• FileNet Content Platform Engine (CPE)

• IBM Content Navigator (ICN)

• Application Engine (if used)

• Optional: Custom widgets, scripts, and services

________________________________________

🔄 Step-by-Step Migration Process

1. Pre-Migration Assessment

• Inventory all case solutions, including:

o Case types, roles, tasks, rules, documents

o Custom widgets or JavaScript

• Confirm compatibility of:

o Operating system

o WebSphere/Liberty versions

o Database

o LDAP & security configurations

📌 Note: ICM 5.5.x requires WebSphere Application Server 9.x or Liberty.

________________________________________

2. Back Up Everything

• Export all case solutions using ICM Deployment Tool or Case Manager Builder.

• Back up:

o FileNet object stores

o ICN configuration

o Application Engine customizations (if any)

o File system (CE configuration files)

o Database

________________________________________

3. Upgrade the Platform Components

🔧 Upgrade Order:

1. FileNet CPE to a supported version (e.g., 5.5.5 or 5.5.9)

2. ICN (IBM Content Navigator) to 3.0.6.x or later

3. ICM to 5.3 first (if coming from 5.2.x), then to 5.3.3, and finally to 5.3.3.0 iFix 7 or later before moving to 5.5.x.

o ICM 5.5.x is a functional successor to ICM 5.3.3.0.

4. Optional: Upgrade Application Engine or move to ICN-based interface

✅ Use the IBM Compatibility Reports to verify supported combinations: IBM Software Product Compatibility Reports

________________________________________

4. Migrate and Deploy Case Solutions

• Use Case Manager Builder 5.5.x to re-import previously exported .zip solutions.

• Alternatively, use the Case Manager Solution Deployment Tool (SDT):

deployCaseSolution -solution <solution.zip> -objectStore <targetOS> -targetEnv <dev/test/prod>

• After import:

o Check and update solution dependencies (e.g., script adapters, custom roles)

o Verify property mappings, tasks, and workflow references

________________________________________

5. Verify and Test

• Open solutions in Case Manager Client (ICN) and test:

o Case creation

o Task execution

o Document upload/view

o Custom widgets or scripts

• Perform regression testing on workflows and business rules.

________________________________________

6. Update Custom Components

• Migrate any Dojo-based widgets to newer ICN plug-in format if needed.

• Validate external integrations (web services, databases, etc.)

________________________________________

7. Move to Production

• Once tested, replicate deployment steps in the production environment.

• Monitor using PE/CE logs, ICN logs, and Case Analytics (if used).

________________________________________

✅ Tips

• ICM 5.5.x is a transitional path to Business Automation Workflow (BAW). Consider planning long-term migration to BAW for full modernization.

• Maintain a rollback plan during the upgrade process.

• Use IBM Fix Central to ensure all components are up to date with recommended interim fixes.

In IBM FileNet P8 5.5.x, the Subscription and Event Action mechanism allows you to automate actions in response to system events (like document creation, update, deletion, etc.). This is part of the event-driven architecture in FileNet, enabling content-centric workflows, audits, or metadata updates without user intervention.

________________________________________

🔄 Overview: Subscription & Event Action Mechanism

🧩 Key Components

Component Description

Event A system-generated signal triggered by an operation (e.g., create, delete).

Event Action A script or handler (often Java-based) that defines what to do when an event occurs.

Subscription Binds an object class (like a Document class) to an event and action.

________________________________________

⚙️ How It Works

1. An Event Occurs

A user or system action (like creating a document) triggers a predefined event (e.g., OnCreateObject).

2. Subscription Matches

FileNet checks if there are subscriptions for the event on that class or object instance.

3. Event Action Executes

The associated Event Action (custom or built-in) is invoked.

4. Result Applied

The handler performs logic like updating metadata, launching a workflow, or notifying users.

________________________________________

🛠️ Setting Up a Subscription

1. Create the Event Action

• Java class that implements com.filenet.api.engine.EventActionHandler

• Must be deployed to the Content Engine classpath

2. Register the Event Action in ACCE

• Open ACCE (Administrative Console for Content Engine)

• Go to Event Actions → New Event Action

• Provide the fully qualified class name

3. Create the Subscription

• In ACCE:

o Go to the document class or object

o Navigate to Subscriptions

o Create a new subscription

o Choose:

 Event (e.g., OnCreateObject)

 Event Action (e.g., AutoClassifyHandler)

 Execution context (Synchronous or Asynchronous)

________________________________________

📘 Example Use Case

Automatically Populate Metadata on Document Upload

• Event: OnCreateObject

• Target: Custom document class InvoiceDoc

• Event Action: Java handler that:

o Reads the file name or folder path

o Sets the "Department" and "Category" properties

o Saves the document

Sample Java Skeleton:

public class AutoTaggingHandler implements EventActionHandler {

    public void onEvent(ObjectChangeEvent event, ExecutionContext ec) {

        Document doc = (Document) event.get_SourceObject();

        String folderName = ((Folder) doc.get_FoldersFiledIn().nextElement()).get_Name();

        doc.getProperties().putValue("Department", folderName);

        doc.save(RefreshMode.NO_REFRESH);

    }

}

________________________________________

🧠 Execution Modes

Mode Description

Synchronous Executes before the user receives confirmation; blocks response.

Asynchronous Executes in the background via Event Queue; suitable for longer tasks.

Use asynchronous mode for long-running or non-critical operations.

________________________________________

✅ Benefits

• Automates content behavior and business logic

• Reduces user errors and manual work

• Improves data consistency and compliance

• Enables event-driven workflows and integrations

The difference between Process Engine (PE) and Workflow Auto-Launch lies in their roles and scope within IBM FileNet P8 / Business Automation Workflow (BAW):

________________________________________

🔍 1. Process Engine (PE)

✅ Definition:

The Process Engine (PE) is the runtime component of FileNet that executes workflows (processes). It manages queues, workflows, steps, participants, and routing.

📦 Key Features:

• Executes workflow definitions (built in Process Designer or Case Builder).

• Manages work items, queues, and participants.

• Handles task assignments, escalations, deadlines, and lifecycle.

• Integrates with Content Engine (CE) for document-related tasks.

💡 Role:

It is the core engine responsible for processing workflow logic. Without PE, no workflow can run.

________________________________________

🔍 2. Workflow Auto-Launch

✅ Definition:

Workflow Auto-Launch is a feature (or configuration) that automatically starts a workflow when a specific event happens — such as when a document is created or a case is filed.

⚙️ How It Works:

• Configured via Event Action or Case Designer.

• Common use: auto-launch a workflow when a document of a certain class is added to an object store or folder.

🔁 Triggers:

• Document creation

• Case creation

• Metadata value change

• Event subscription (OnCreate, OnCheckin, etc.)

________________________________________

🆚 Comparison Table

Feature Process Engine (PE) Workflow Auto-Launch

What it is Core runtime engine for executing workflows A mechanism to trigger a workflow

Role Executes workflow logic Starts workflows automatically upon events

Configured In Process Designer / ACCE Case Designer / ACCE / Event Subscription

Triggered by Manual start or system call System events (e.g., document created)

Scope Full workflow lifecycle Only the start of the workflow

Example Claim approval process Auto-start claim workflow when a claim form is uploaded

________________________________________

🧠 Summary:

• Process Engine is the engine that runs workflows.

• Workflow Auto-Launch is a mechanism to initiate those workflows automatically based on system events.