Building a FileNet troubleshooter with IBM Granite and Ollama

Imagine the complexities that come with running a content platform engine for an enterprise-level organization. Enterprise content management systems (ECM) such as IBM® FileNet® P8, securely store millions of critical documents—from contracts and financial records to patient files and engineering plans. For many organizations, that system is not just an object store, but supports many use cases and acts as a highly structured, intelligent library. It comes with many features to accommodate multiple stakeholders as well as controls permissions to manage who can see what and how information flows through the business. It’s powerful, reliable and essential.

But with great power comes great complexity!

It consists of many components such as the application server, workflow, authentication, permissions, SQL databases and an application programming interface (API) as well as LDAP synchronization. These components come with their own dependencies that are time-consuming to support—combing through event logs, reviewing the state of the JVM and looking at disk space. These dependencies are used to help find the root cause of issues and due to their wide use in the enterprise, they usually need to be kept operational with an SLA.

When an error occurs in a system like this, it doesn’t just say “File not found” or “timeout.” Instead, a user might be met with a cryptic error code. This code contains random strings of letters and numbers, for example, ‘FNRCA0117E.’ For the person facing an error such as this, whether they’re a new developer, a junior administrator or someone on the support team, it’s like hitting a brick wall. These cryptic codes create a few major challenges:

• The code tells you what happened, but not why.
• Finding the solution becomes a frustrating time sink.
• This scenario creates a knowledge gap that halts productivity.

This space is where generative AI changes the game. Imagine having a seasoned expert on call, 24 x 7, who can instantly translate that cryptic code into plain English. But it doesn’t stop there. A well-instructed AI can weave a story around the error, suggesting common scenarios where it occurs and, most importantly, providing a clear, step-by-step plan for how to investigate and fix it. Instead of a dead end, the error becomes the starting point of a guided solution.

In this tutorial, we will build the program that will generate the full troubleshooting guide by using the IBM Granite® model.

Granite 4.0 introduces the next-generation family of open, performant and trusted Granite language models (SLMs). These models deliver greater efficiency through high performance and faster inference speeds at lower operational costs compared to similar and larger frontier models.

With a range of compact sizes, Granite 4.0 is built for flexibility to meet different hardware, deployment and cost requirements. It’s designed to scale, offering unconstrained context lengths for extended document processing and complex workflows.

Like previous Granite models, Granite 4.0 models are open source under Apache 2.0, offering extensive transparency into the training data and processes. This design equips developers to customize the models with proprietary data for increased performance.

The Granite 4.0 family consists of multiple small sizes and architectures, offering developers the ability to choose the right model for their use case, while considering specific hardware, deployment and cost requirements.

In this tutorial we will be using Granite 4.0-H-Micro, a 3B parameters hybrid SSM-transformers model

Let’s understand this scenario:

A junior administrator is trying to help a user and sees the error FNRCA0117E pop up. The system tells them this means “The requested action is not authorized.”

Here is where the real problem begins. The administrator is left with a list of frustrating questions: Which action wasn’t authorized? Which user’s permissions are wrong? Is the problem with the user, the document or the folder? The error code is just a clue about the system fault. It cannot provide the solution.

With this program, we can bridge this gap. It will take error code as input and by using an LLM, generate a full guide that answers those follow-up questions, providing a clear path to resolving the issue.

To implement this process, the LLM model needs specific documentation to understand the context. It doesn’t have years of FileNet experience out of the box. We give this data to the LLM in a simple CSV file named filenet-errors.csv.

It contains three columns:

• ErrorCode: The unique identifier, like FNRCA0117E.
• ErrorName:  A short, human-readable title for the error, like “Authorization Failure.”
• ErrorMessage: The short, official description.

For this tutorial you must install the following dependencies and make sure to run them on your computer:

• Ollama : This dependency is essential to run the Granite model on your local machine. If you don’t have it, you can download it from ollama.com. Make sure that the application is running in the background.
• Python : The code is written for Python 3.7 or newer.
• Jupyter Notebook : This notebook is where we’ll write and run our code. If you need to install it, you can run the command: pip install notebook.

The purpose of this tutorial is to demonstrate the power of using the IBM Granite 4.0 Micro model. To use the model with Ollama, we need to run the following command in the terminal to download it locally to our computer

ollama pull ibm/granite4:latest

This command tells Ollama to pull the IBM Granite 4:Micro model and configure to be available for inferencing. Once the command is complete, you can then run the next command

ollama list

You should see the model showing as being available

Here are the steps that you can follow in the Jupyter Notebook to build the FileNet Troubleshooting Guide generator.

To make this tutorial more interactive, you’ll find a special feature. Below each code block, look for an “Explain code” button powered by Granite. Use this button to see a detailed breakdown of each line and understand the code with more depth.

First, we’ll install the essential Python libraries that our project depends on.

Now we will run a quick connection test to confirm our notebook can communicate with the local AI model.

Output:

As we can see, the connection with local model is established successfully. Now, as a next step we will load the filenet-errors.csv file into memory and clean the data to prevent any errors.

Output:

Successfully loaded and cleaned data from ‘filenet-errors.csv’

Cleaned column names: [‘ErrorCode’, ‘ErrorName’, ‘ErrorMessage’]

First 5 rows of data:

Here, we will write the master instruction set, or ‘prompt,’ that tells our AI expert exactly how to behave and what to create.

Our prompt template will:

1. Define a persona: Tell the model to act as an expert IBM FileNet administrator.
2. Provide the input data: Use placeholders ({error_code} ,{error_message}  and others) that we will enter later with our data.
3. Specify the output format: Instruct the model to use Markdown for headings and lists, ensuring a clean, readable output.

Now, let’s create a reusable Python function that acts as the ‘engine’ for our tool, handling the AI generation process.

This function will:

1. Take the details of a specific error (code, message, explanation) as input.
2. Use ourprompt_template to format these details into a complete set of instructions.
3. Send the final prompt to our localGranite 4.0 model with Ollama.
4. Receive the AI-generated response and return it as clean text.

Finally, we will assemble all our previous steps into the final interactive application that a user can operate.

This code block will:

1. Create a continuous loop that keeps the tool running.
2. Prompt the user to enter a FileNet error code.
3. Search our DataFrame for the code the user entered.
4. If the code is found, it will call ourgenerate_guide function and display the detailed, AI-generated guide.
5. If the code is not found, it will provide a helpful message and even suggest similar codes the user might have meant.
6. Allow the user to type exit to quit the tool gracefully.

Output:
--- IBM FileNet AI Troubleshooter ---
Enter a FileNet Error Code to generate a guide.
Type ‘exit’ or ‘quit’ to stop the tool.
-----------------------------------

Found ‘FNRAC1008E’. Generating guide with AI, please wait...
-----------------------------------

Troubleshooting Guide: FNRAC1008E1.

Understanding the Error

As an IBM FileNet P8 senior system administrator, encountering the error code FNRAC1008E with the name ERR_UNABLE_TO_GET_DATA and message Unable to get data from server can be alarming. This error indicates that there is a fundamental issue preventing the application from retrieving necessary data from the server. For a junior administrator, this means one or more of the following might be happening:

The server is down or experiencing connectivity issues.
There are insufficient permissions for accessing specific resources.
The server logs show errors related to data retrieval processes.

Key Points:

Data Retrieval Failure: The core problem lies in the inability to fetch required information from the server, impacting tasks like data manipulation or retrieval operations.
Network/Server Dependency: This error is often network-related, indicating potential issues with connectivity, server load, or resource constraints on the server side.

Common Scenario

Imagine a junior administrator named Alex working in the finance department of an organization that utilizes IBM FileNet P8 for document management and processing. One day, while trying to add a new invoice to the system under the “Invoices” folder, Alex encounters the error FNRAC1008E.

The issue arises because Alex’s account lacks sufficient permissions to perform write operations on certain documents within this specific folder.
This could also be due to server-side issues such as maintenance activities or network latency affecting data retrieval processes at the moment of operation.

Step-by-Step Troubleshooting

1. First Actionable Step: Verify User Permissions in ACCE

Action: Open the Access Control Center Enterprise (ACCE) application and navigate to the relevant folder where Alex is trying to upload the invoice.

Steps:

Log into ACCE using administrative credentials.
Locate the “Invoices” folder within the Document Library or Repository section.
Check the permissions assigned to Alex’s user account under the Access Control tab.

Why It Matters:

Ensuring that Alex has appropriate write and read permissions on the specific documents/folders is crucial. If Alex’s permissions are insufficient, attempts to upload files will result in retrieval errors like FNRAC1008E. This step confirms whether the issue stems from user-level access control settings.

Second Actionable Step: Check Server Logs

Action: Access the IBM FileNet server and locate the error logs.

Steps:

SSH (or remote desktop) into the P8 server.
Navigate to the log directory, typically /opt/ibm/p8/server/logs.
Open the p8_server_error.log file using a text editor or command-line tool like less or cat.

Keywords to Look For:

Errors related to data retrieval (ERR_UNABLE_TO_GET_DATA, FNRAC1008E).
Network-related errors such as “timeout” or “connection refused”.
Resource exhaustion warnings (e.g., memory limit reached).

Why It Matters:
Server logs often contain detailed error messages that provide insights into why data could not be fetched. Identifying specific error patterns can guide further troubleshooting steps, whether it’s a server overload issue or an internal application bug.
3. Third Actionable Step: Review Class Definitions or Folder Security

Action: If the user permissions check does not resolve the issue, proceed to inspect class definitions and folder security settings.

Steps:

Access the IBM FileNet P8 administrative console.
Navigate to Content Structure > Classes and locate the class associated with invoices (e.g., INVOICE).
Review the Security Tab for this class to ensure that Alex’s user group has necessary read/write privileges.

Additionally, check folder security settings:

Go back to ACCE or directly in the administrative console under Document Libraries, find the specific folder.
Examine the Access Control List (ACL) and verify permissions granted to Alex’s role.

Why It Matters:
Class definitions determine how users interact with particular document types. Incorrect permissions at this level can prevent data retrieval, similar to insufficient user-level permissions identified earlier. Ensuring correct security configurations is vital for seamless operations within IBM FileNet P8.

Summary of Solutions

To effectively resolve the FNRAC1008E error:

Verify User Permissions: Use ACCE to confirm that Alex has appropriate write and read permissions on all relevant folders/documents where data retrieval is attempted.
Check Server Logs: Examine server logs (p8_server_error.log) for detailed error information, focusing on network or resource-related issues.
Review Class Definitions & Folder Security: Confirm class-level security settings in the administrative console ensure that Alex’s role can interact with the targeted document classes and folders.

Likely Solutions:

Adjusting user permissions to grant necessary access rights.
Investigating server performance metrics (CPU, memory) to identify potential bottlenecks.
Correcting folder or class-level security configurations if misconfigurations are identified.

By systematically following these steps, junior administrators like Alex can efficiently troubleshoot and resolve the FNRAC1008E error, ensuring smooth operations within IBM FileNet P8.

-----------------------------------

Exiting the troubleshooter. Goodbye!

This tutorial is about more than just building one program. We learned the fundamental skills needed to create your own specialized AI assistants. We have tamed a powerful yet small large language model, become a prompt engineer and built a practical solution to a real-world business problem.

A note on system resources and configuration

It’s helpful to know the kind of system this tutorial was built on and what you should consider for your own machine.

This tutorial was developed and tested on a MacBook Pro with the following specifications:

• OS: macOS Sequoia
• Memory (RAM): 32 GB
• Storage (Disk) used for project: Approximately 4 GB

Here’s a breakdown of the resources that this project will use:

• Storage: Most of the disk space is used by the AI model file itself. Expect the Granite 4 model l to take up about 2 GB of storage. The code and data files are very small.
• Memory (RAM): This resource is most important for running the AI. When the model is active, it’s loaded into your computer’s RAM. For a smooth experience, a system with at least 16 GB of RAM is recommended. While the tool might function on a machine with 8 GB of RAM, it could be quite slow.

Guidance for Windows users

For those of you working on a Windows machine, the good news is that the process is almost identical. All the tools we’ve used—Ollama, Python and Jupyter—are fully compatible with Windows.

The only minor difference is in the command line interface. Instead of using a “Terminal,” you will use “Command Prompt” or “PowerShell” to run the setup commands like Ollama create. All the commands themselves, and the Python code, are exactly the same.

What you can build next

This tutorial is more than just a FileNet tool; it’s a blueprint for powerful automation. The core components—a reliable model, a defined data source and a smart prompt—can be adapted to countless other challenges, from parsing legal documents to generating code documentation.

Think of the next step in this tool’s evolution: an assistant that you could automatically trigger to enrich IT support tickets that could be turned into a production-ready version of that service to be deployed on an application server for the entire organization. The script that you built today is the foundational building block for these kinds of sophisticated systems. The power to build specialized, private AI assistants is now at your fingertips.