Tutorial

Build and deploy custom analytics functions in Maximo Monitor

Create, test, and register Python-based functions to process data in Maximo Monitor

By Peter Kohlmann, Jaydeep Ravat, Radhika Surani, Sonali Suthar

Maximo Monitor is an application and monitoring solution in Maximo Application Suite that provides near real-time visibility, root-cause troubleshooting, anomaly detection, and AI-driven alerts at scale. The platform enables organizations to monitor and analyze their operational data with sophisticated analytics capabilities.

With Maximo Monitor, you can:

Visualize data using customizable dashboards that show both current and past trends for better visibility into operations.
Drill into data by setting up hierarchies and exploring from a high-level view down to individual devices.
Use analytics to process data and display results in value cards, tables, graphs, images, and alert views.
Detect issues with built-in tools that spot anomalies such as outliers, data gaps, or flat lines.
Set up alerts based on data conditions and create service requests in Maximo Manage directly from alert views.

Adding custom functions to Maximo Monitor

Maximo Monitor includes many built-in analytics functions, but sometimes you need to perform custom calculations or data changes that are not available by default. In such cases, you can create your own custom functions.

This tutorial shows you how to build a custom function called MultiplyByFactor. You will learn how to write the function, test it locally, and deploy it to your Maximo Monitor environment.

By the end, you will know how to extend Maximo Monitor with custom logic that fits your specific business needs.

Learning objectives

By the end of this tutorial, you will know how to:

Write a custom function using the IoT Functions framework
Save your function in a GitHub repository
Test the function locally
Register it with Maximo Monitor
Use it with a device type in your environment

Time required

Approximately 60 minutes

What you need before starting

Prerequisites

Make sure that you have:

Python 3.11.x installed
Git installed
pip3 (Python package manager)
A code editor (PyCharm is recommended)
A GitHub account
Access to Maximo Monitor with the right permissions

Software to install

Python 3.11.x
Git
pip3 (comes with Python)
PyCharm Community Edition

Set up your project

Create a folder.

mkdir maximo-custom-function cd maximo-custom-function

Download the starter package.

git clone --branch starter_package https://github.com/ibm-watson-iot/functions.git@9.1.x
cd functions

Check that the folder structure looks like this:

├── setup.py
├── scripts/ │
    └── local_test_of_function.py
├── custom/ │
    ├── functions.py │
    ├── __init__.py

Update the setup.py file.

Open the setup.py file
Change the name to something like customJD (use your initials instead of JD)

Make sure the IoT Functions version matches the one used in your Maximo Monitor

Example:

#!/usr/bin/env python
from setuptools import setup, find_packages
setup(
  name='customJD',
  version='0.0.1',
  packages=find_packages(),
  install_requires=[
    'iotfunctions@git+https://github.com/ibm-watson-iot/functions.git@9.1x'
  ]
)

Set up PyCharm

Open PyCharm and open the folder that you cloned.

Create a virtual environment by running:

python3 -m venv venv-cust
cd venv-cust/bin
source activate

Set the virtual environment in PyCharm.
- In PyCharm, go to Preferences > Project > Python Interpreter.
- Click the gear icon and choose Add.
- Select your project folder.
- Choose Python 3.11.x as the base interpreter.

Install the IoT Functions package. Run the following command:

pip3 install git+https://github.com/ibm-watson-iot/functions.git@9.1.x --upgrade

Make sure that the version matches your Maximo Monitor setup.

Note: If you encounter errors that are related to IBM_DB on a Mac, check the section Mac setup tips.

Step 1. Define your calculation requirements

Example scenario

A robotics company is testing new robotic arms. Their tools cause delays that affect speed and travel time readings. The operations manager wants to adjust these values by multiplying them by 2, with the option to change the factor later.

Solution

Create a custom function called MultiplyByFactor that can:

Take multiple input values.
Multiply each by a factor that you can change.
Output the new values.
Be used in different calculations.

Formula: output = input × factor

Step 2. Create your custom function

Set up GitHub

Create a private repository on GitHub for your custom function.
Add a file like README.md to set up the main branch.
Copy the repository URL. You will need it later.

Create your function file

Rename the custom folder to customJD (replace JD with your initials).
Inside that folder, create a new file named multiplybyfactorJD.py.

Add the following code, replacing placeholders such as YOUR_TOKEN, YOUR_USERNAME, and YOUR_REPO with your actual GitHub details.

import logging
import pandas as pd
from iotfunctions.base import BaseTransformer
from iotfunctions import ui

logger = logging.getLogger(__name__)

PACKAGE_URL = 'git+https://YOUR_TOKEN@github.com/YOUR_USERNAME/YOUR_REPO@starter_package'

class MultiplyByFactorJD(BaseTransformer):
    """
    Multiply input values by a given factor.
    """

    def __init__(self, input_items, factor, output_items):
        self.input_items = input_items
        self.output_items = output_items
        self.factor = float(factor)
        super().__init__()

    def execute(self, df):
        df = df.copy()
        for i, item in enumerate(self.input_items):
            df[self.output_items[i]] = df[item] * self.factor
        return df

    @classmethod
    def build_ui(cls):
        inputs = [
            ui.UIMultiItem(
                name='input_items',
                datatype=float,
                description="Choose the input values to multiply",
                output_item='output_items',
                is_output_datatype_derived=True
            ),
            ui.UISingle(
                name='factor',
                datatype=float,
                description="Enter the multiplication factor"
            )
        ]
        outputs = []
        return (inputs, outputs)

Step 3. Set up your credentials

You need a credentials.json file to connect to Maximo Monitor for local testing.

Go to your starter package folder.
Find the credentials.json template file.
Open it and complete your details like username, password, host, and API keys.

Example:

{
  "tenantId": "main",
  "db2": {
    "username": "db2inst1",
    "password": "your_db2_password",
    "databaseName": "BLUDB",
    "port": 32183,
    "host": "your-db2-hostname.containers.appdomain.cloud",
    "security": false,
    "certificate_file": null
  },
  "iotp": {
    "asHost": "main.api.monitor.your-environment.ibmmasmonitor.com",
    "apiKey": "your_api_key",
    "apiToken": "your_api_token",
    "certificate_file": null
  }
}

Security setup

To enable secure connections:

For Db2, set "security": true and add the path to your Db2 cert: "certificate_file": "/path/to/your/db2-cert.pem"
For the Monitor API, add the cert path under the iotp section: "certificate_file": "/path/to/your/monitor-cert.pem"

Important: Do not add credentials.json to your GitHub repo. Add it to your .gitignore file to keep it private.

Step 4. Push your code to GitHub

Set up repository

Open a terminal in your project folder
Check the current remote:

git remote -v
Set your GitHub repo as the origin:

git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
Add the IBM Functions repo as upstream:

git remote add upstream https://github.com/ibm-watson-iot/functions.git

Commit and push your changes

In PyCharm, right-click your custom{your_initials} folder.
Go to Git > Add.
Then, select Git > Commit.
Add a message and click Commit.
Go to Git > Repository > Push.
Click Push.

Check your GitHub repo to confirm the changes appear in the starter_package branch.

Step 5. Install your custom function locally

Run the following command in your terminal to install the package.

pip3 install git+https://YOUR_TOKEN@github.com/YOUR_USERNAME/YOUR_REPO@starter_package --upgrade

Replace YOUR_TOKEN, YOUR_USERNAME, and YOUR_REPO with your actual GitHub token, username, and repository name.

Step 6. Test your function locally

Create the test script

In the scripts folder, create a file named test_my_custom_function.py.

Add the following code. Update the placeholder values with your actual details.

import datetime as dt
import json
import pandas as pd
import numpy as np
from sqlalchemy import Column, Integer, String, Float, DateTime, Boolean, func
from iotfunctions.base import BaseTransformer
from iotfunctions.metadata import EntityType
from iotfunctions.db import Database
from iotfunctions import ui

# Load credentials
with open('credentials.json', encoding='utf-8') as F:
    credentials = json.load(F)

db_schema = None
db = Database(credentials=credentials)

# Import your custom function
from customYourInitials.multiplybyfactoryourinitials import MultiplyByFactorYourInitials

fn = MultiplyByFactorYourInitials(
    input_items=['speed', 'travel_time'],
    factor=2,
    output_items=['adjusted_speed', 'adjusted_travel_time']
)

# Run test
df = fn.execute_local_test(db=db, db_schema=db_schema, generate_days=1, to_csv=True)
print(df)
print("Test completed. Results saved to: df_test_entity_for_multiplybyfactoryourinitials.csv")

Run the test

In your terminal, run the script:

python3 test_my_custom_function.py

The script creates sample data and saves the results as a CSV file in the scripts folder. Check the file to make sure that your function runs as expected.

Step 7. Register your function

Create the registration script

Create a file named register_my_custom_function.py in the scripts folder.

import json
from iotfunctions.db import Database
from customYourInitials.multiplybyfactoryourinitials import MultiplyByFactorYourInitials

# Load credentials
with open('credentials.json', encoding='utf-8') as f:
    credentials = json.load(f)

# Connect to the database
db = Database(credentials=credentials)

# Register the function
db.register_functions([MultiplyByFactorYourInitials])
print("Function registered successfully with Maximo Monitor")

Register the function

Run the script to register your function:

python3 register_my_custom_function.py

Your function is now listed in the Maximo Monitor function catalog and ready to use.

Step 8. Create a sample device type

In Maximo Monitor, go to Setup > Devices.
Click the + icon to add a device type.
Choose the Robot sample type template.
Enter a name for your device type.
Click Create.
Select your device type and click Set up device type.
Go to the Data ta.b

Note: Metrics might take a few minutes to appear.

Step 9. Apply your custom function

If your device type doesn't have a distance metric yet, create one first. Refer to the Adding expressions tutorial for steps.

Configure the custom function

From the Data tab:
- For versions earlier than 9.1, click Create metric.
- For version 9.1 and later, go to Calculated metric and click Add calculated metric.
Choose your MultiplyByFactor{YourInitials} function from the catalog.
Set the scope and click Next.
Fill in the parameters:
- Factor: 2
- Input items: Select distance
Click Next.
In the output section:
- Rename the output to adjusted_distance.
Click Create

Check the results

In the data items list, find adjusted_distance.
Wait a few minutes for Maximo Monitor to process the calculation.
Review the values to confirm they look correct.

Next steps

Now that your first custom function is working, try these next:

Build more advanced functions with multiple calculations.
Explore other use cases where custom logic adds value.

Mac setup tips

If you are using a Mac with Apple Silicon, you might run into issues with the ibm_db package. Try the following steps to fix it:

Fix compatibility issues on Apple Silicon

If you see errors with ibm_db==3.2.3 on Apple Silicon, try this:

Clone the functions repo.

git clone https://github.com/ibm-watson-iot/functions cd functions
Update the ibm_db version.
- Open requirements.txt.
- Change ibm_db==3.2.3 to ibm_db==3.2.5.
- Save the file.
Install the updated dependencies.

pip3 install -r requirements.txt

Set up PyCharm for Mac

To run and debug your scripts in PyCharm:

Add the functions repo to your project.
- Go to PyCharm > Project Structure
- Click Add Content Root
- Select the folder where you cloned the functions repo
Create run configurations.
- For testing (Step 6): Add a run config for test_my_custom_function.py
- For registration (Step 7): Add a run config for register_my_custom_function.py
Debug your custom function.
- Add breakpoints in your code
- Run the test script in Debug mode
- Step through the code to fix any issues

This setup makes development and troubleshooting easier.

Troubleshooting common issues

Function not showing in catalog

Make sure the function is registered without errors.
Check whether all required packages are installed.
Confirm that your credentials are correct.

Local test fails

Use Python 3.11.x.
Ensure that all dependencies are installed.
Match the IoT Functions version with your Maximo Monitor version.

GitHub access issues

Make sure that your token has the right permissions.
Double-check the repository URL format.
Confirm that your environment can access the repo.

Summary and next steps

This tutorial showed how to build and use a custom analytics function in IBM Maximo Monitor. You wrote a Python function, tested it locally, and registered it in the Maximo Monitor environment. You created a device type and applied your function to real data.

For more help:

Check the Maximo Monitor documentation.
Explore examples in the IoT Functions GitHub repository.
Reach out to your system administrator for setup issues.

Topics

Languages

Products

Open Source