Your first MREF app: a Key Register from scratch

The planSix pieces, six tools

An MREF application is not one thing. It is a set of building blocks, each made in its own builder tool, and each published separately. For our Key Register:

For Maximo peopleComing from Maximo? A translation table

MREF is IBM TRIRIGA, renamed and delivered on Maximo Application Suite. That is why IBM's own objects start with tri (triSpace, triKeyManagement, triSave) and why the builder screens look different from Manage. The ideas, however, are very close to what you know:

Getting startedWhere the builder tools are

Sign in as an administrator. The home page of the Application Administrator has an Application Builder panel with all the tools used in this guide: Data Modeler, Form Builder, Association Manager, Workflow Builder, Navigation Builder and Report Manager. The Admin Console (agents, caches, logs) is a separate page at /html/en/default/admin/index.jsp.

The builders are the classic TRIRIGA tools: they open in frames and pop-up windows, and they ask questions with browser alert boxes. That is normal. The last part of this guide shows how we made that easier to work with.

Step 1 · Data ModelerThe business object

The business object (BO) is the record type. It lives in a module, a family of related objects that share fields, associations and behaviour.

The first attempt, and why we threw it away

Our first idea was to keep everything tidy in a new module, cstKeys. Creating it was easy:

The object, form, query and menu item all built and published without a complaint. Then the first Add on the new page failed with a generic error, and the server log showed a database error: SQLCODE -150 on a table that did not exist.

Create the object in triKeyManagement

In the Data Modeler tree, open triKeyManagement, then New → Business Object.

Because it lives in triKeyManagement, the new object already has the module's fields: name, ID, status, description, organization, location and more. You only add what is specific to keys.

Add the fields

Three fields, all in the General section:

The suffix tells everyone the type (TX text, NU number, CL classification, DA date…). That is IBM's convention; keep it.

Name mapping and lifecycle

Mapping tells MREF which field is the record's name (what you see in headers, lookups and links). We map it to triNameTX. The Name row accepts several fields joined by the Delimiter, so this is also where you would build a name such as "Master MK-01" from two fields.

The state transitions (the lifecycle) come from the module: a key is created as Draft, can be activated, reviewed, revised and retired. Each arrow is an action such as triSave or triActivate. Remember triSave: the workflow in Step 5 listens to it.

Finally Publish BO. Publishing runs in the background (the ObjectPublishAgent) and you get a notification "Publication of cstKeyItem completed successfully". Wait for it before going on.

Step 2 · Association ManagerKeys and spaces

An association is a named link between two objects, defined in both directions. A key is Key For a space; a space Has Key. Open the Association Manager, select your module and object, and Add:

Step 3 · Form BuilderThe record screen

Open the Form Builder, pick the module and click New.

Set the business object (cstKeyItem), a name and a label, and tick Default Form. MREF warns you, in an alert box, that changing an object's default form can affect workflows. For a new object that is fine.

Then build the layout: a tab (cstGeneral), a section "Key Details", and the fields from the Components list.

The related-records section

To list the spaces a key opens, add a query section. A query section shows the results of a query from Step 4, so you will come back here once the query exists. In the section properties pick the query, then set Association Type to Key For. That tells the section which link to create when a user picks spaces.

Step 4 · Report ManagerThe queries

In MREF, lists are queries. The Key Register list and the spaces section are both Query-type reports, made in the Report Manager (System Reports tab, so they are not tied to your user).

Query 1: the register list

General: name cstKeyItem - Manager - All Keys, title "Key Register", type Query, then Add Business Object: module triKeyManagement, object cstKeyItem.

Columns: Name, Key Number, Key Type, Copies, Status.

Advanced → Actions: add a System Add action. Without it the list page has no Add link and nobody can create a key.

Query 2: the spaces of this key

Name cstKeyItem - Associated - Spaces, title "Spaces This Key Opens", object Location / triSpace, columns ID, Name, Parent Building, Parent Floor, Area.

Step 5 · Workflow BuilderAutomation

Workflows are MREF's automation: "when this happens to this kind of record, do these tasks". Ours: when a key is saved, copy its Key Number into the standard ID field (triIdTX), so the number shows wherever IDs are listed.

The Start task

Click New. The designer opens with a Start and an End. Click Start to set the workflow properties:

• Name: cstKeyItem - triSave - Copy Key Number to ID. The pattern "object - event - what it does" is IBM's own.
• Concurrence: Asynchronous. Only then does the Event list offer the record actions; with Synchronous we only saw Pre-Create.
• Module triKeyManagement, Object Type cstKeyItem, Event triSave.
• Save Workflow Instances: ticked while you build and test.

Add a Modify Records task

Hover over the New Task bar on the left: a palette opens. Click Modify Records, then click the arrow between Start and End to drop it there. Label it "Copy Key Number to ID".

In the task properties, Map To is the Start record (the key being saved). Click Edit Map. Every field starts mapped to itself, which changes nothing. Change one row: on triIdTX click the magnifier (Attribute Picker) and choose cstKeyNumberTX. The row now reads General::cstKeyNumberTX. Click OK.

Click Publish on the Start task's properties bar.

Changing a published workflow

A published workflow cannot be edited. In the list, select it, click List All Revisions, then Revise. That creates a new revision "In Progress"; edit and publish it. The previous one is retired automatically.

When a workflow "does nothing"

This is the part nobody tells you. Our workflow was published, the key was saved, nothing changed and nothing failed. How we found out why, in order:

1. Did Save change anything? Saving an unchanged record may not send the event. Change a field, then Save.
2. Is the event reaching the agent? Asynchronous workflows are run by the WFAgent, often on a separate agents server. The Admin Console → Agents page shows where it runs. In the Database Query Tool, WF_EVENT_HISTORY lists each event with its completion time. Our triSave events were there, completed in 4 seconds.
3. Is the agent using the new workflow? Admin Console → Caches → Workflows For Agent flushes the workflow templates the agents hold.
4. Is there an instance? Workflow Builder → List All Instances. On our system instances are only kept for failed runs, so "no instance" plus "no change" pointed at the task itself, not the engine.
5. Look at the map as saved, not as you remember it. Ours had every field mapped to itself.

After the fix, one Save was enough: the key's ID field held MK-01.

Step 6 · Navigation BuilderThe menu item

Users reach apps through navigation items grouped in navigation collections (menus, home-page panels, quick links). Open the Navigation Builder.

Create the item in the Navigation Items Library:

• Name Master Detail - Key Register, label "Key Register".
• Target Type: Master/Detail Query: a list on top, the selected record's form below. No extra pop-up window.
• Target: module triKeyManagement, object cstKeyItem, report cstKeyItem - Manager - All Keys.
• Form: triKeyManagement / cstKeyItem.

Then open the collection that feeds the administrator's home page (triApplicationAdministrator - Quick Links - Home Application Administration), drag the item in, and Save.

Try itThe Key Register

Back on the home page, click Key Register. Click Add, fill in a key, Save. On the record, the spaces section is empty:

Top right of the list, Inline View / Popup View chooses whether a record opens below the list or in a window. Inline keeps everything on one page.

Click Find in the section, tick spaces, Accept:

Your toolboxThe Admin Console

When something does not work, the Admin Console (/html/en/default/admin/index.jsp) is the first stop.

Working smarterPop-up windows as dialogs, alerts as messages

The classic builders open many pop-up windows: field properties, maps, pickers, association filters, previews. Each is a separate browser window, easy to lose behind the main one. Questions come as browser alert() boxes that freeze the page until you click OK. During this exercise we used a small script, pasted into the browser's developer console, that changes both, only in your own browser tab:

• window.open() → an in-page dialog (an iframe in a blue frame, with a × to close). Dialogs stack, so a picker opened from a dialog appears on top of it.
• alert() → a yellow message strip at the top, which closes itself after 12 seconds or on click, and is also written to the console.
• confirm() questions ("delete this?", "create a new revision?") stay as normal browser boxes on purpose: those you should read.

The script

Open the builder (for example Form Builder), press F12, go to Console, paste, press Enter. Nothing is sent anywhere and nothing changes on the server.

// MREF / TRIRIGA classic builders: open pop-up windows as in-page dialogs, and show
// browser alert() boxes as an in-page message instead of a blocking box.
// Paste into DevTools console on the builder page. Re-run after a full page reload.
// confirm() questions are left as the normal browser box on purpose.
(function installBuilderHelpers() {
  const top_ = window;
  // Some builders (Report Manager) are a <frameset> page that cannot show anything
  // itself: then put messages and dialogs in its main frame.
  const doc = (top_.document.body && top_.document.body.tagName === 'FRAMESET')
    ? ((top_.frames.frameMain || top_.frames[0]).document) : top_.document;
  const stack = [];                       // open dialogs, last = on top
  const closeTop = () => { const ov = stack.pop(); if (ov) ov.remove(); };

  // 1. alert() -> a message strip at the top of the page (also written to the console).
  const toast = (msg) => {
    console.info('[MREF alert]', msg);
    const t = doc.createElement('div');
    t.textContent = msg;
    t.style.cssText = 'position:fixed;left:50%;top:12px;transform:translateX(-50%);z-index:200000;' +
      'max-width:640px;padding:10px 16px;background:#fff8e1;border:1px solid #f1c21b;' +
      'border-radius:6px;font:14px sans-serif;box-shadow:0 4px 14px rgba(0,0,0,.25);cursor:pointer';
    t.title = 'Click to close';
    t.onclick = () => t.remove();
    doc.body.appendChild(t);
    setTimeout(() => t.remove(), 12000);
  };

  const findFrame = (w, name) => {
    try {
      for (const f of w.document.querySelectorAll('iframe,frame')) {
        if (f.name === name) return f.contentWindow;
        const hit = findFrame(f.contentWindow, name);
        if (hit) return hit;
      }
    } catch (e) {}
    return null;
  };

  // 2. A finished pop-up calls window.close(), sometimes on the top window:
  //    close a dialog, never the tab.
  top_.close = closeTop;

  const hook = (w, ownDialog) => {
    try {
      w.alert = toast;
      w.close = ownDialog
        ? () => { const i = stack.indexOf(ownDialog); if (i >= 0) stack.splice(i, 1); ownDialog.remove(); }
        : closeTop;
      // 3. window.open() -> an iframe in a dialog stacked on top of the page and other dialogs.
      w.open = function (url, name) {
        // window.open(url, 'someFrame') where that frame already exists just means
        // "load into that frame" (Report Manager tabs work this way): do exactly that.
        const existing = name && findFrame(top_, name);
        if (existing) { if (url) existing.location.href = url; return existing; }
        const n = stack.length;
        const ov = doc.createElement('div');
        ov.style.cssText = `position:fixed;left:${3 + n * 2}%;top:${4 + n * 2}%;width:${94 - n * 4}%;` +
          `height:${92 - n * 4}%;z-index:${100000 + n};background:#fff;border:2px solid #0f62fe;` +
          'box-shadow:0 8px 30px rgba(0,0,0,.4)';
        const x = doc.createElement('button');   // manual close, top-right corner
        x.textContent = '×';
        x.title = 'Close this dialog';
        x.style.cssText = 'position:absolute;right:4px;top:2px;z-index:1;border:0;background:#0f62fe;' +
          'color:#fff;font:16px sans-serif;width:24px;height:24px;cursor:pointer';
        x.onclick = () => { const i = stack.indexOf(ov); if (i >= 0) stack.splice(i, 1); ov.remove(); };
        const fr = doc.createElement('iframe');
        fr.name = name || 'pop' + n;
        fr.style.cssText = 'width:100%;height:100%;border:0';
        ov.append(x, fr);
        doc.body.appendChild(ov);
        stack.push(ov);
        // The pop-up talks back to the page that opened it through window.opener: keep that link.
        fr.addEventListener('load', () => { try { fr.contentWindow.opener = w; hook(fr.contentWindow, ov); } catch (e) {} });
        fr.src = url;
        return fr.contentWindow;
      };
      // Builders are built from nested frames: patch every one of them.
      [...w.document.querySelectorAll('iframe,frame')].forEach(f => hook(f.contentWindow, ownDialog));
    } catch (e) { /* cross-origin frame: skip */ }
  };
  hook(window, null);
  top_.__installBuilderHelpers = installBuilderHelpers;   // re-run after a builder panel reloads
  return 'pop-ups open as dialogs; alerts show as a message at the top';
})();

How it works, in plain words

Browsers let a page replace its own window.open, alert and close functions. The builders are made of nested frames, and each frame has its own copies, so the script walks every frame and replaces them all. When a builder asks for a pop-up, the script creates an iframe in a dialog instead, and points the new page's window.opener back at the page that asked, because that is how the pop-up sends its answer back (a picked field, a saved map).

What we learned building it

Wrap-upLessons and checklist

1. Look for an out-of-the-box answer first. MREF already had key management.
2. New objects go into an existing module when Module Level Associations is on. A new module gave us SQLCODE -150.
3. Field and association names are global. Reuse with Find; do not invent a second name for the same thing.
4. Build in order: object → association → form → queries → workflow → menu item, and publish each one.
5. Lists need a System Add action, or users cannot create records.
6. Related-records queries need an association filter on $$RECORDID$$.
7. Record events need an Asynchronous workflow to choose them, and a Modify Records map takes one source per field.
8. Debug with evidence: event history, agents, caches, instances, then the task as saved.
9. Clean up failed attempts: retire and delete the objects, forms, queries and workflow drafts you no longer use, so the next admin is not confused.

GlossaryWords you will hear

MREF / TRIRIGA

Maximo Real Estate and Facilities is the new name of IBM TRIRIGA; objects starting with "tri" are IBM's originals.

Module

A family of business objects that share fields, associations and lifecycle (for example triKeyManagement, Location).

Business object (BO)

A record type, with fields, a name mapping and state transitions. Maximo: an object in Database Configuration.

Publish

Make a new version of an object, form, query or workflow live. Maximo: Apply Configuration Changes, but per piece.

Revise

Open a published item for changes as a new revision; the previous one is retired when you publish.

State transition

An action that moves a record from one state to another, such as triSave or triActivate.

Association

A named, two-way link between records: Key For / Has Key. Maximo: closest to a relationship, but stored as data.

Module Level Associations

A platform mode where each module stores its associations in its own MA_ table.

Query section

A form section that lists related records using a query.

$$RECORDID$$

In a query filter, the record currently open on the form.

Asynchronous workflow

Runs in the background on the workflow agent after the event, not while the user waits.

Agent

A background process such as WFAgent or SchedulerAgent. Maximo: a cron task.

Navigation item / collection

A menu entry and the menu, panel or quick-link list that holds it.

Master/Detail

A page with a list on top and the selected record's form below.

Screens: IBM Maximo Real Estate and Facilities 9.2.2 on IBM Maximo Application Suite, test system with IBM's demo data, signed in as an administrator. Object names starting with cst are ours; everything else is standard MREF. The browser script is a personal convenience, not an IBM tool.