Skip to main contentMAF Configuration Practices

FAQ

Table of Contents

User & Application Context

How to collect details about the current user

In AppCustomizations.js you can capture the userInfo object from app.client and use it to query different details about the user and their access.

// Get user information from the app client
this.app.client.userInfo

See Also:

How to check when application is running on a mobile device

The platform provides an instance called Device, which can be captured by getting implementation or using the reference stored in the main app object. Among many properties and methods, there is the isMaximoMobile that can be used to determine the platform.

// Using Device.get()
Device.get().isMaximoMobile


// Or using app reference
this.app.device.isMaximoMobile

See Also:

How to know if my app has any configuration/customization

Often, as part of the case triage process, it is necessary to determine whether a customization or configuration is in place before beginning to investigate the issue.

In the context of MAF, there is a consolidated dashboard that displays the installed applications and their current application revision. Up to MAF version 9.1, the dashboard only shows active versions.

The revision also serves as an indicator of configurations added to installed applications. Maximo Manage applications are stored in the MAFAPPDATA table, which includes the application ID, binary file, version, revision, checksum, as well as information about who deployed it and when. The version is extracted from the build.json file within the application binary, while the revision and checksum are calculated when the binary is uploaded. Each time a new application record is inserted—whether via UpdateDB, maxdev-cli upload-app, or the Configuration Application (through a publish)—a new revision is created and set to ACTIVE.

To retrieve revisions directly from the database, use the following SQL statement:

SELECT 
    m.APPID, 
    m.DEPLOYBY, 
    m.DEPLOYDATETIME, 
    m.STATUS, 
    m.VERSION, 
    m.REVISION, 
    m.ISMOBILE 
FROM MAFAPPDATA AS m

For customization in CSS (Cascading Style Sheets is code that defines the visual appearance of the user interface), on the Suite administration page, from the side navigation menu, click Configurations and then click User interface customization. On the CSS customization tab, check toggle button that enables CSS customization.

See Also:

Customization & Development

How to replace or add logic into existing method

Replacing or adding logic to a particular controller’s method is a common request however there are differences and best practices to do so. When a controller is bound to the application, page, or datasource, the controller class can handle any events that are dispatched. If the controller has a function that matches the event name, it will be invoked to handle the event.

Replacing a Method

By replacing a method you can ensure the sequence of steps to be executed. The idea behind this practice is to use the initialize event of the object where the controller is associated with, store the method out-of-the-box in a variable so you can opt for using it later, and re-assign the reference of the old method to a new one. You can find more details and sample here.

Adding Logic to a Method

Adding new steps to a method requires the creation of method with the same name at AppCustomizations.js file. The sequence the methods to be executed cannot be enforced, all methods with the same name are subscribed to that event dispatched and the order is not guaranteed by the platform mechanisms. You can find an example here.

Warning: Modifying out-of-the-box controllers requires manual merging with every release. Only modify AppCustomizations.js for supported customizations.

See Also:

How to handle events with no alias

Most events from component lifecycle have alias. For instance, originally, onBeforeLoadData event in fact is emit as before-load-data but for sake of simplicity and language pattern. Usually events have its alias with “on” prefixed and gets converted from dash case (kebab case) into camel case.

However, a couple of events do not have an alias (for now), this is the case of events like:

  • before-invoke-action
  • after-invoke-action
  • field-warning

In those cases, the raw name can be used to capture those events, but due to dash chars the name should be wrapped in quotes.

Method 1: Direct Method Declaration

// In AppCustomizations.js
class AppCustomizations {
    applicationInitialized(app) {
        this.app = app;
    }


    // Method name must be quoted due to dashes
    'field-warning'({item, field, warning}) {
        if (warning) {

Method 2: Event Listener Binding

Alternatively, you may bind event listeners during the initialization of the application or page. It is equally important to ensure that these listeners are properly removed once they are no longer needed.

// In AppCustomizations.js
class AppCustomizations {
    applicationInitialized(app) {
        this.app = app;
    }


    pageResumed(page, application) {
        // Get reference to the datasource
        const ds = page.datasources['yourDatasourceName'];

See Also:

Datasources & Data Management

How to filter with datasource

There are a few ways to fetch the right amount of data to the appropriate context:

  • QBE filter (declaration or API)
  • Where clause
  • Saved Query
  • Mobile QBE Filter

The last one is exclusive for mobile apps searching against data previously loaded.

Mobile QBE Filter

Mobile QBE filter is exclusive for mobile apps searching against previously loaded data.

Key Characteristics:

  • Used only when fetching data from local database (on device)
  • Not used when fetching data from Maximo server
  • Only supports filtering on the “top most” object

Important Limitations:

  • Nested properties: Do not work in mobile. Use an alias instead and reference it in the QBE filter
  • Server variables: Variables like SYSDAY are interpreted only on server, so avoid using them

Best Practice:

Saved query should be used to be the least restrictive filter. If there is additional filter criteria, then you would add to the maximo-datasource a where (for web) and mobile-qbe-filter (for mobile) to reduce the dataset.

Lookup datasources for Maximo Mobile need to use the same saved query so it’s important that you implement the filter with where & mobile-qbe-filter.

See Also:

How to make a datasource field available in sort list

In order to make one of those attributes listed in schema part of sort list just set the “sort” attribute of the field to “true” or remove sort attribute and value all together.

<!-- Add sort="true" or remove the sort attribute entirely -->
<attribute name="location.description--locationdesc" searchable="true" id="d_m_3"/>

See Also:

Should I duplicate an object structure to work with a particular app

Short Answer: No, duplicating object structures is discouraged.

Why?

Duplicating object structures may seem like it isolates object usage, but this practice causes issues due to mobile architecture:

  • All data from object structures sharing the same root object get merged
  • This merge operation supplies data in disconnected mode
  • The merge can exclude exclusive attributes from duplicate object structures

Best Practice:

✓ Reuse the same object structure across apps
✓ Apply logic in the app to display only necessary data
✗ Avoid creating duplicate object structures

See Also:

Components & UI

Why should I avoid multiselect component

Even though multiselect component seems to be more appropriate to address a simple selection in input field, this component is not recommended for that task. A few bugs were found in the library that uses it and this might be addressed in the next releases (v9.2).

Instead, we suggest using either data list or lookup. Take a look at one of the cases using lookup, Create Priority Lookup in Techmobile for instance.

See Also:

Troubleshooting

I cannot push changes of my custom object children

All modifications to records—whether initialized or retrieved from a datasource—are automatically tracked, including those originating from child datasources. Persisting these changes is handled by the save() API of the corresponding datasource.

Common Errors

Error: BMXAA10013E - Invalid URI for updating resource

Message: “The URI needs to end with the resource REST id.”

Solution:

Verify that the parent-child datasource relationship is properly established:

  1. Check the Database Object configuration
  2. Verify the relationship in the primary Object Structure source code
Error: BMXAA3761E - Event has failed

Full Message: “Cannot invoke ‘com.ibm.tivoli.maximo.notification.OSEventInfo.isFireEvent(psdi.mbo.MboRemote)’ because ‘eventInfo’ is null”

Solution:

Events from the Notification app may be restricting operations:

  1. Access the Notification app
  2. Check records related to the Object Structure
  3. Delete problematic records
  4. Retry the operation

See Also:

How to determine problems after upgrade

After a version upgrade the customization should be re-tested and here are some steps to triage a customization problem after version upgrade:

  1. Check ID references: Verify that ID references still exist, especially states and datasources declared in XML
  2. Verify version compatibility: Check MAS and MAF versions match using compatibility matrix
  3. Review delta files: Check app.delta.xml for configuration changes
  4. Test customizations: Re-test all custom logic in AppCustomizations.js
  5. Check logs: Review server and client logs for errors

See Also:

Edit this page on GitHub
Page last updated: 06 January 2026
Previous
Troubleshooting: Debugging application code