Maximo Application Framework, piece by piece: Graphite, role-based apps, bundles, Maximo Mobile and where React fits

Part 1The names, untangled

Start with one sentence that holds them all. A role-based application, such as Technician, is described in an XML file; the Maximo Application Framework turns that description into a React web application drawn with IBM's Carbon components; the result is packed into a bundle and stored in Manage; a browser runs it directly, and the Maximo Mobile app on a phone downloads the same bundle and runs it offline. Graphite is the engineering name of the framework, and it is the word you meet in addresses, pod names and package names.

Part 2Role-based applications: what is installed

The quickest way to see what "role-based application" means on your own system is the first page of the Application Configuration tool. On the system used here the list has 44 entries.

The columns say more than they seem to:

Sixteen of the 44 are mobile. The rest are the desktop side of the same framework: dashboards, administration pages, and the shell that hosts them.

Any of them opens in a browser at https://<manage host>/maximo/oslc/graphite/<app name in lower case>/index.html.

Part 3Anatomy of an application

Open Technician in the tool, search the Navigator for one page, and the structure of every Graphite application is on the screen at once.

Three lines from the screenshot show the pieces working together. They are the start of the Work order page:

XML<page id="workOrderDetails" title="Work order" controller="WorkOrderDetailsController">
  <states id="x947_">
    <state name="canLoadWoDetailResource" value="true" type="boolean" id="xdv7y"/>
  </states>
  <maximo-datasource id="woDetailResource" default="true"
      can-load="{page.state.canLoadWoDetailResource}"
      object-structure="mxapiwodetail"
      where="wonum=&quot;{page.params.wonum}&quot; and siteid=&quot;{page.params.siteid}&quot;"
      controller="WorkOrderDataController" item-url="{page.params.href}" page-size="1">

Read it slowly. The page has an ID, a title and a controller class. It owns a state called canLoadWoDetailResource. Its data source reads the object structure mxapiwodetail, which is the same integration object the REST API uses, and it loads only when that state is true. The work order number and site come from the page's address. So one screen is three things tied together by names: a state, a data source and a controller.

IBM documents these ideas in Basic Graphite concepts and the topics linked from it: data sources, the page component, dialog components, applying configurations, the mobile master schema and the preloaded database. That page also shows a detail worth knowing early: the required attribute works both on an input component and on a schema attribute.

XML<text-input value="{page.state.name}" required="true"
    invalid="{page.state.nameInvalid}" invalid-text="{page.state.nameInvalidText}"/>

Part 4Where React and Carbon come in

Nobody writes React by hand for a Maximo app, yet every Maximo app is a React app. The build step reads app.xml and writes one React component for each page, dialog, drawer and list. The proof is in any built workspace. This is the top of a generated file from a Permit to Work app on the same system:

JavaScript// Generated File - Do not edit
import React, { Component, useEffect, useState } from 'react';
import { observer, Provider, inject } from 'mobx-react';
import { Datasource, JSONDataAdapter, Application, Page, Dialog } from '@maximo/maximo-js-api';
import { Button, Box, Label, Field, SmartInput, Tabs, Tab, Tag, BorderLayout } from '@maximo/react-components';
import AppController from './AppController';
import PagePtwList from './PagePtwList';
import PagePtwDetails from './PagePtwDetails';
import PTWDetailsController from './PTWDetailsController';
import DialogChgStatusDialog from './DialogChgStatusDialog';
import SlidingDrawerAssetLookup from './SlidingDrawerAssetLookup';

(The import lines are grouped here for reading; the generated file has one per line.) The names tell the story:

Carbon is the open-source IBM design system underneath the components: github.com/carbon-design-system/carbon. It matters to an administrator for one practical reason. A design system is software with versions, and its security policy states which major versions receive fixes (at the time of writing, 11.x and 10.x) and how to report a vulnerability privately. When a security scanner flags a front-end package inside a Maximo bundle, that policy and IBM's own fix packs are where the answer comes from. You do not patch Carbon inside a bundle yourself.

Part 5The bundle

A bundle is what the build produces and what the system stores: one zip per application. This is the inside of the Technician bundle taken from this system, 10.6 MB:

Listingtechmobile bundle (145 entries)
  index.html          the page a browser loads
  assets/             104 files: the built JavaScript and styles, split into chunks
  js/                 2 files
  i18n/               29 files: the labels, one per language
  data/               4 files
  build.json          version 9.2.110, application ID, title, and the routes
  manifest.json       name, icon and "standalone" display, as for any installable web app
  loader.css, favicon.svg
  app-source.zip      the source this bundle was built from

The last line is the one people miss. Every bundle carries its own source. Unzip app-source.zip and you have a complete project:

Listingapp-source.zip (368 entries)
  package.json        dependencies and build scripts
  src/app.xml         the application description
  src/*Controller.js  about 37 controllers: WorkOrderDetailsController, SchedulePageController, ...
  src/assets/
  public/i18n/        29 label files
  ibm-config/         63 files: IBM's original, kept for comparison

Part 6The Application Configuration tool

Click an application in the list and the editor opens. It takes half a minute, because the tool is unpacking that application's source into its own workspace.

The arrow next to Save opens the actions that move a change through its life:

The question mark at the top right of the tool links to the reference material you will need once you go beyond changing a label: Component Documentation, Developer Documentation and JS API Documentation.

Part 7Life of a customization, with an exercise

The exercise changes one word in Technician and follows it through all six steps. The change is deliberately tiny, so that everything you see is the process and not the change.

Before: use the application

Open Technician. A user needs something to look at, so create a work order with the + button. This is the page woCreateEdit: a form whose fields are components bound to a data source.

After Save, the app goes to the work order's detail page, and the list Work created by me now has one record.

Step 1: edit

In the Application Configuration tool, open TECHMOBILE. Type workOrderDetails in the Navigator search and click page Work order. Switch to the Properties tab. Every attribute of the page is there. Change title from Work order to Work order details and press Tab.

Look at the other properties while you are there, because they are the vocabulary of every page: controller names the JavaScript class, sigoption ties the page to a Maximo security option, hidden can take a binding, and license and feature let a page appear only when the right product is installed.

Step 2: save

Click Save. The tool answers "File was updated" and, if a preview was running, starts rebuilding it.

At this point nothing has changed for any user. Close the browser and come back tomorrow: the edit is still in the tool, and still private.

Step 3: preview

Open the actions menu and choose Start Preview. The status line reads "Preview: Building the application artifacts". When it finishes, the same menu offers Open Preview, which opens the application in a new tab under the tool's own address, /preview/. It is the real application with the real data of the signed-in user. Open the work order again:

Step 4: publish

Choose Publish. A notice warns that publishing can take some time, and the status line walks through three stages.

Step 5: the revision

Go back to the Application list. TECHMOBILE has moved to the top.

Version and revision together answer the question every support call starts with: "is this IBM's application or yours?" Version 9.2.110.0 revision 0 is exactly what IBM shipped. Revision 1 or more means somebody on your side published a change.

Step 6: delivery

Open the application at its normal address on Manage, not the preview:

Browser users receive the new bundle the next time the application loads. Maximo Mobile users receive it when the app next checks for updates and downloads the newer revision; a device that stays offline keeps working with the bundle it already has. That last behaviour was not exercised on a phone for this guide.

Part 8Life of a running application

The second lifecycle is the one that runs every time somebody opens the app. Knowing its order tells you where a problem is and where your own code may step in. These are the calls Technician made, in order, when the preview started:

Listing/maximo/oslc/login                           who is this session
/maximo/oslc/whoami                          user, person, default site and organization
/maximo/oslc/systeminfo                      version of the server
/maximo/oslc/permission/allowedappoptions    which security options this user holds
/maximo/oslc/licenseinfo                     which products are licensed
/maximo/oslc/messages                        text of system messages
/maximo/oslc/os/mxapiwodetail                the first data source loads
/maximo/oslc/os/mxapimaxapp, mxapiorganization, ...   supporting data

Identity first, then permissions and licence, then data. If an app stays blank, the first of these calls that fails tells you which layer to look at.

A customization file using two of them looks like this. It is a pattern, not part of the exercise above:

JavaScript// AppCustomizations.js: your code, kept apart from IBM's controllers
class AppCustomizations {
  applicationInitialized(app) {
    this.app = app;
  }

  // show only work orders of my own organization, whatever list is chosen
  onBeforeLoadData(datasource, query) {
    if (datasource.name !== 'todaywoassignedDS') return;
    const mine = datasource.parseQBE({ orgid: '=' + this.app.client.userInfo.defaultOrg });
    query.qbe = { ...query.qbe, ...mine };
  }

  // warn when the estimated duration is cleared
  onValueChanged({ datasource, field, newValue }) {
    if (datasource.name === 'dsCreateWo' && field === 'estdur' && !newValue) {
      this.app.toast('Estimated duration is empty', 'warning');
    }
  }
}
export default AppCustomizations;

The data source names in it are examples, and the helper calls should be checked against the JS API Documentation linked from the tool. Use the Navigator search to find the real IDs in the app you are changing.

Part 9Three ways to customize, and when to use each

IBM's guidance on applying configurations is short: use the customization file for most changes, extend a controller class for the complex ones, and never edit IBM's base controller files. In practice there are three levels.

The patterns below come up in almost every project. They are written in the app.xml tag language.

Part 10Maximo Mobile: the same apps, offline

Maximo Mobile is one app from the app store that contains no Maximo screens of its own. After sign-in it downloads the Navigator and every application marked Mobile download = true that the user may open, then the data those applications need, and from then on it works without a network.

Part 11Working outside the tool

The browser tool is enough for configuration. For larger work, developers take the project out with Download app src and use the same build the tool runs. The project's package.json shows it plainly:

JSON{
  "dependencies": {
    "@maximo/maximo-js-api": "3.2.803",
    "@maximo/react-components": "3.2.803",
    "mobx": "6.15.4",
    "react": "18.3.1"
  },
  "scripts": {
    "build": "npx @maximo/maxdev-cli build --in ./src/app.xml --out ./build/app/src/ --update-ids --copy",
    "build:production": "yarn build && yarn labels && cd build/app && react-scripts build",
    "labels": "npx @maximo/maxdev-cli localize -i ./src/app.xml -o ./src/i18n/labels.json --format json"
  }
}

Two steps, as in Part 1: maxdev-cli build turns app.xml into React files, then the bundler turns those into the web application. Three facts save time here:

• The @maximo packages are not on the public npm registry. The toolchain ships as the graphite-configuration container image of the suite. Build inside that image, and use the one that matches your release.
• Put the project in source control. The tool keeps one current state per application. Git gives you history, review and a way back.
• Upload file is the way back in. A controller edited and tested outside goes into the tool's project with it, and from there through preview and publish like any other change.

Part 12When it does not work

ValueWho gains what

Everything above is about how the applications are built. This is why an organisation cares.

No figures are promised here. Record your own baseline for each measure before the change, and compare after one quarter.

GlossaryThe words, once more

Run on IBM Maximo Application Suite 9.2 with Manage 9.2.4 on Red Hat OpenShift. Technician was at version 9.2.110.0; the exercise published revision 1. The Maximo Mobile behaviour in Part 10 is described from the product's design and from other systems, and was not exercised on a device for this guide.