Skip to main contentMAF Configuration Practices

Overview

Welcome to MAF Configuration Practices

IBM’s Maximo Application Framework (MAF) supports the creation of Maximo Mobile and Role-based applications within Manage. This documentation provides practical examples and best practices for configuring and customizing MAF applications.

The MAF Configuration application enables implementers to configure IBM-provided applications (or duplicates of those applications) built with MAF. Other MAS applications, such as Health and Monitor, provide MAF applications that can also be configured using the MAF Configuration application.

What You’ll Find Here

This guide provides practical examples of configurations that can be used, extended, adapted, and combined to achieve your desired customizations. The documentation is organized into two main sections:

Simple Practices - Configuration-focused examples including:

  • Adding attributes to cards
  • Updating saved queries for lookups
  • Modifying UI elements
  • Basic field configurations

Complex Practices - Advanced customizations using JavaScript including:

  • Lifecycle event handling
  • Custom business logic in AppCustomizations.js
  • Advanced datasource manipulation
  • Complex validation scenarios

Recommended Learning Path

🎯 For Beginners

Start here if you’re new to MAF configuration:

  1. Overview - Understand MAF basics (you are here)
  2. Basic Concepts - Learn core MAF concepts
  3. Datasources Guide - Master data management fundamentals
  4. Debug UI - Learn how to troubleshoot
  5. Simple Practices - Start with configuration-only examples:

🚀 For Intermediate Users

Once comfortable with basics, explore:

  1. FAQ - Common questions and solutions
  2. More Simple Practices - Build your configuration skills
  3. Introduction to Complex Practices:
  4. Replace Existing Method - Advanced techniques

💡 For Advanced Users

Ready for complex customizations:

  1. Complex Practices - Advanced JavaScript customizations
  2. Restrict Complete Status - Complex validation example
  3. Performance Mobile Doclinks - Optimization techniques
  4. Combine multiple techniques - Build sophisticated solutions

Quick Reference

Essential Resources

External Resources

General Tips & Best Practices

XML Tag Order

The order of XML tags is important. Although XML is a markup language, the MAF build process considers the declaration order throughout the file.

Best Practice: Declare datasources before using them in lookups or other components.

Logging

Use consistent logging to track progress during customization. Create a tag prefix to identify all code paths.

AppCustomizations.js:

// Add at the first line of the file
const TAG = 'CustomFeature';


// Use throughout your code
this.app.log.d(TAG, 'Processing started');
this.app.log.e(TAG, 'Error occurred', error);

Server Logs:

Access server logs from your Manage (MAS) instance using this URL format:

https://(mas-manage-host)/maximo/oslc/service/logging?action=wsmethod:streamLog

Debug Mode

Enable debug or trace logs in a deployed Role-based Application by adding a query parameter to the URL:

?_graphite_logLevel=[level_option]

Available log levels:

  • trace - Extremely detailed logging
  • debug - Detailed logging
  • info - Informational logging
  • warn - Only log warnings
  • error - Only log errors

Example:

http://localhost:3000/?quickReport=false&_graphite_logLevel=trace#/createwo

AppCustomizations.js Template

Basic template for AppCustomizations.js:

/**
 * Custom Application Logic
 * This file contains customizations for [Application Name]
 */
const TAG = 'CustomApp';


class AppCustomizations {
    /**
     * Called when application is initialized

CSS Customization

Starting in Maximo Application Suite 9.0, you can customize the user interface appearance using CSS.

To enable CSS customization:

  1. Open the Suite administration page
  2. Navigate to side navigation menu
  3. Click Configurations → User Interface Customization
  4. Go to the CSS Customization tab
  5. Enable CSS customization by toggling the switch

Learn more about updating the user interface

Feature Requests

If a customization isn’t possible due to framework limitations or unexposed processes, submit an idea through the IBM Ideas Portal rather than opening a bug report.

Support

What’s Supported

We support modification of:

  • ✅ XML files (app.xml)
  • ✅ AppCustomizations.js

What’s Not Supported

  • ❌ Modifying out-of-the-box controllers (requires manual merging with each release)
  • ❌ Direct framework modifications
  • ❌ Unsupported versions (< 8.10)

Getting Help

L3 RBA Configuration Queue

The support queue handles issues with:

  • Application behavior during configuration
  • Connecting to datasources
  • Creating or altering functions
  • UI layout modifications
  • Page routing
  • Maximo business rules adherence

Important Notes:

  • Same support policies apply to configuration
  • Customers on older/unsupported versions of RBA and Mobile (< 8.10) don’t have access to configuration support
  • Issues traced back to unsupported code configuration won’t be supported, though we’ll provide guidance when possible

Opening a Support Case

When opening a case, include:

  1. Files created/updated:

    • app.xml
    • AppCustomizations.js
    • app.delta.xml (automatically generated from app.xml changes)

  2. Clear reproduction steps:

    • Step-by-step instructions
    • Expected vs actual behavior
    • Environment access information (if possible)

The app.delta.xml file is crucial for fast triage as it highlights all configurations applied.

Learn more about delta files

Edit this page on GitHub
Page last updated: 13 January 2026
Previous
Home
Next
Basic concepts: Basic concepts