Skip to content

Chapter 1: Foundation and Platform Context

A Note on This Guide

MREF is new. This guide reflects current IBM documentation and early practitioner experience as of early 2026. MREF capabilities and migration tooling continue to evolve -- verify specific procedures against your target MREF version before each engagement.

1. Scope Boundaries

This guide covers migration from standalone TRIRIGA to MREF on MAS. It does not cover TAS replatforming or TRIRIGA-to-TRIRIGA version upgrades. If you are here to upgrade within TRIRIGA (e.g., 11.2 to 11.5 on the same infrastructure) or to move to TAS without MAS Core, you need a different playbook.

Three-Way Scope Distinction

Dimension TRIRIGA Upgrade TAS Replatforming MREF Migration
Infrastructure VMs / bare metal, WebSphere Liberty manually installed OpenShift pods, decentralized admin OpenShift pods, MAS Core centralized admin
Administration Legacy TRIRIGA admin (System user, internal user mgmt) Still internal to TRIRIGA product Centralized in MAS Core (user auth, SSO, lifecycle mgmt stripped from TRIRIGA)
Licensing Traditional named-user / fixed-seat / Enterprise TAS licensing MAS AppPoints: Self-Service (0 pts), Limited (5 pts), Base (10 pts), Premium (15 pts)
Workload Distribution Agent tables (AGENT_REGISTRY, AGENT_STARTUP) Agent tables Automated pod scaling (agent tables must be truncated)
Custom Java File system drops to /lib File system restricted ClassLoader records (workflow tasks) or Customization Archives (servlets, web.xml, 3rd party libs)
Key Difference Same infra, version bump Containerized but decentralized admin Containerized + MAS Core admin; one-off architectural transformation

Even if a customer is already running TAS on OpenShift, transitioning to MREF is still a migration engagement because licensing and administrative control must shift to MAS Core. Do not assume "already containerized" means "already done." Verified1

Engagement Scoping Checklist

Use these questions in your first client meeting to determine if you have an MREF migration engagement and what it will involve:

  1. Is the customer currently on TRIRIGA Application 11.0-11.6? If no, this guide does not apply.
  2. Is the target MREF on MAS 9.x? If no, different engagement type.
  3. Is this a move to MREF, not a TAS replatforming or TRIRIGA version upgrade? If no, different guide needed.
  4. What are the current TRIRIGA Application and Platform versions? Determines if a prerequisite upgrade to 11.5/11.6 is needed -- see Section 4: Version Considerations.
  5. Does the customer have in-house Red Hat OpenShift expertise? Dictates SaaS vs customer-managed vs partner-hosted deployment model.
  6. Are there custom Java classes for workflow tasks, or middleware modifications (servlets, web.xml)? Defines ClassLoader/Customization Archive effort. See Phase 5.
  7. Do any Integration Objects rely on AES reversible encryption? Hard technical gate -- see Section 3: The Infrastructure Shift.
  8. How many concurrent users at peak, and what modules do integration service accounts touch? Needed for AppPoints mapping via UMT.

Key Takeaway

If you answer "yes" to questions 1-3, you have an MREF migration engagement. Questions 4-8 determine complexity and prerequisites.

2. What MREF Actually Is -- Platform Context

MREF is TRIRIGA repackaged inside MAS -- not a rebuild on the Maximo platform. The entire TRIRIGA application layer -- business objects, workflows, forms, reports, queries, navigation, security groups, UX framework components, and builder tools -- carries over intact via the database. What changes is everything below and around the application layer: the infrastructure it runs on, the administration model that wraps it, and the deployment patterns for custom code and integrations.

Common Misconceptions

  1. "MREF is Maximo with a TRIRIGA skin." -- Wrong. MREF is TRIRIGA running inside the MAS container. Your BOs, workflows, forms, and builder tools are unchanged.
  2. "We need to rebuild our workflows for MREF." -- Wrong. All workflows (synchronous and asynchronous) carry over intact. No decomposition needed.
  3. "MREF is just TAS with a new name." -- Wrong. TAS keeps admin decentralized in TRIRIGA. MREF centralizes user management, auth, SSO, and lifecycle management in MAS Core.
  4. "Our custom reports will need to be rewritten." -- Wrong. BIRT reports and custom reports carry over with the database. Verified2
  5. "The System user will still work for admin login." -- Wrong. The System user is repurposed as an internal service account only. Human administrators must use MAS admin accounts. Verified31

What Changes -- and What Doesn't

Your application layer carries over completely: BOs, workflows, forms, reports, queries, navigation, security groups, UX framework components, portals, dashboards, and builder tools all transfer intact via the database. Db2 constraint: you must maintain the exact same schema name and database username. Verified3

What does not carry over:

Item What Happens Migration Action
Traditional Licensing Retired -- MAS AppPoints replaces named-user/fixed-seat/Enterprise Run User Migration Tool (UMT) to map users to AppPoints tiers
User Management Stripped from TRIRIGA, centralized in MAS Core Create FACILITIESADMIN user on first MREF login. Update high-tier users to "Authorized" post-migration.
Human "System" User Login Repurposed as internal service account only Assign MAS administrator privileges
Agent Tables Replaced by automated OpenShift pod scaling Truncate AGENT_REGISTRY and AGENT_STARTUP before connecting DB
File System Access Only userfiles, config, log persistent Route all file operations to persistent directories
Custom Java via /lib Unsupported -- immutable containers Migrate to ClassLoader records or Customization Archives. See Phase 5.
Integration Auth (AES Keystores) Must be migrated before activation Extract credentials, recreate as OpenShift Secrets. Hard gate. See Phase 5.
RMI Permanently deprecated Rebuild using Maximo REST APIs
Manual System Properties Overridden by operator via ConfigMaps/Secrets Modify only via persistent config directory; restart pod to apply. See Phase 4.

Gotcha

License mapping is not automatic.

  • TRIRIGA Enterprise licenses generally map to MAS Self-Service Verified25
  • Reservation Manager (3023) and Business Connect (3021) must be manually upgraded post-migration to Base (Authorized) inside MAS administration Verified25
  • Email discrepancies for the same User ID between legacy system and MAS will fail UMT batch processing Verified26
  • UMT processes in batches of max 499 via triMASCoreUserMigration background workflow Verified27

Key Takeaway

Everything you built in TRIRIGA -- your BOs, workflows, forms, reports, security -- carries over. What changes is the infrastructure underneath and the administration around it. Plan your migration effort around the "What Happens" column above.

3. The Infrastructure Shift

The move from standalone TRIRIGA to MREF is fundamentally an infrastructure transformation. Your application layer stays the same; the platform it runs on changes completely.

Architecture: Before and After

TRIRIGA Standalone (Before)          MREF on MAS (After)
================================     ================================
| TRIRIGA Application Layer    |     | TRIRIGA Application Layer    |
| (BOs, Workflows, Forms,     |     | (BOs, Workflows, Forms,      |
|  Reports, Builder Tools)     |     |  Reports, Builder Tools)      |
|------------------------------|     |------------------------------|
| WebSphere Liberty            |     | Embedded Liberty              |
| (manually installed)         |     | (operator-managed)            |
|------------------------------|     |------------------------------|
| Java JDK (8 or 11)          |     | Java JDK 17 (Platform 5.0)   |
|------------------------------|     |------------------------------|
| VM / Bare Metal              |     | OpenShift Pod (stateless)     |
| (persistent file system)     |     | (only userfiles/config/log)   |
|------------------------------|     |------------------------------|
| Manual Admin                 |     | MAS Core                      |
| (System user, local user     |     | (centralized auth, SSO,       |
|  mgmt, TRIRIGAWEB.properties)|     |  AppPoints, operator CRs)     |
================================     ================================

Notice the top layer is identical. Everything below it has changed.

What "Stateless and Immutable" Means for You

OpenShift pods can be restarted, scaled, or replaced at any time. Only three directories survive a pod restart: userfiles, config, and log. Everything else is ephemeral:

  • Custom JARs dropped into WebSphere directories will not survive pod restarts Verified4
  • File-based integrations must target the persistent userfiles directory Verified5
  • Configuration changes to TRIRIGAWEB.properties must be placed in the persistent config directory, then the pod must be manually restarted to apply Verified6

Operator-Managed Configurations

Many settings you previously managed in TRIRIGAWEB.properties are now controlled by the MREF operator via the Tririga Custom Resource (CR), ConfigMaps, and Secrets:

  • Workflow Agents: Dedicated workflow agent pods via spec.wfagents array in the Tririga CR Verified7
  • Routing Timeouts: OpenShift routes annotated with 600-second default, overridable via spec.rt.timeout Verified8
  • Database Connection Pools: spec.db.maxconnpoolsize in CR Verified9
  • License Configuration: Suite License Service (SLS) host/port set to read-only in Admin Console; the CR is single source of truth Verified10

Warning

Do not manually alter operator-managed properties in TRIRIGAWEB.properties. The operator will overwrite your changes on the next reconciliation cycle. Verified11

AES Encryption: The Hard Gate

Platform 5.0 introduces mandatory AES encryption for reversible password fields. The AES keystore is managed via the Tririga CRD vault_secret field -- a string value corresponding to an existing OpenShift Secret containing the key password. Verified12

Warning

If a valid secret is not present in the CR, operator reconciliation fails and your MREF instance will not start. Verified13 You must extract third-party passwords from the database and recreate them as OpenShift Secrets before activating MREF, or encrypted data becomes unreadable. This is a hard gate -- there is no workaround after activation.

Integration Authentication Changes

The authentication model for integrations shifts significantly in MREF:

  • Inbound HTTP/SOAP integrations enforce MAS-generated API Keys Verified14
  • REST integrations can use OIDC or API Keys Verified7
  • OIDC SSO configurations supported; OKTA explicitly supported as provider Verified15
  • OAuth profiles streamlined: a single profile can authenticate against multiple UX applications Verified16
  • SSO bypass available via /index.jsp appended to TRIRIGA base URL Verified17
  • RMI is fully deprecated -- rebuild any RMI-dependent integrations as REST APIs Verified18

See Phase 5 for detailed integration authentication migration procedures.

Key Takeaway

Your TRIRIGA application is the same. The box it runs in has changed from a persistent VM you manage to a stateless container the operator manages. Plan around three things: (1) move custom code to ClassLoader records or Customization Archives, (2) move secrets to OpenShift Secrets before activation, (3) stop manually editing operator-managed properties.

4. Version Considerations

Your source environment must be on TRIRIGA Application 11.5 or 11.6 (Platform 4.5 or 5.0) before MREF migration tools can execute. If you are on an older version, a traditional TRIRIGA-to-TRIRIGA upgrade is a prerequisite.

Version Eligibility

Source Version MREF Eligible? Path to Eligibility
11.0-11.1 No Upgrade to 11.2 first, then use cumulative 11.5 OM package
11.2-11.4 No Use cumulative 11.5 OM package directly (includes 11.3-11.5 changes)
11.5 / Platform 4.5 Yes Direct MREF migration
11.6 / Platform 5.0 Yes Direct MREF migration

The 11.5 OM package (TRIRIGA_11_5_CumulativeAfter_11_2_202307051000.zip) is cumulative -- it includes all changes from 11.3, 11.4, and 11.5, and the patch helper automatically executes intermediate versions. Verified16

Lease Accounting Hard Gate (crossing 11.4)

You must follow a strict pre/post-upgrade sequence when crossing the 11.4 threshold. Import the Pre-Process OM package and run patch helper 11.4LeasePreProcess before upgrading. After upgrading, create the required index on T_TRIPAYMENTBREAKDOWNITEMS and run 11.4LeasePostProcess. If this sequence is not followed, payment amounts will be permanently wiped out. Verified19 See Phase 2 for the complete step-by-step procedure.

Key Version Notes

  • 11.2: The Polymer triRoomReservation app is discontinued -- you must manually delete the legacy metadata (Application, Model/View, Web View records). The OM package will not auto-delete it. Verified20
  • 11.4: Microsoft EWS completely unsupported -- migrate all Exchange configs to Graph API. Verified21
  • 11.6: Java JDK 17 mandatory. AES keystore mandatory. Carbon styling enforced. For Db2: append jdbcCollection="NULLIDR1" to properties.db2.jcc in server.xml. Verified17

EOL Timeline

Date Event
January 2024 Legacy TRIRIGA part numbers no longer orderable Verified22
September 2027 Standard support ends for ALL legacy TRIRIGA versions Verified23
September 2027 Hard cutoff for legacy TRIRIGA SaaS -- no Extended/Sustained Support Verified22
October 2027 Extended Support begins (on-premise 11.6/5.0 only) Verified24
2032 Sustained Support ends Verified24

Tip

On-premise customers get a 19-month dual entitlement period upon MAS trade-up, extending to approximately April 2029. SaaS customers get 12-month dual support from contract signing. Verified24

Key Takeaway

You must be on 11.5 or 11.6 before MREF tools can execute. If the customer is on an older version, factor in the prerequisite upgrade -- especially the Lease Accounting sequence if crossing 11.4. Standard support ends September 2027 for everyone; SaaS customers have no extensions.

5. The OM Tool in MREF Migration

You already know the Object Migration tool from TRIRIGA version upgrades. In MREF migration, it serves the same role -- generating comparison reports between your customized source environment and the target MREF baseline. The mechanics are identical: import OM packages, run comparisons, review the four standard report types, make retain/adopt/merge decisions per object.

The key difference is volume. MREF introduces significant baseline enhancements -- AI-driven lease abstraction, dynamic space planning, Envizi Connector for ESG/GHG reporting, Maximo Manage synchronization, and Maximo Monitor integration for IoT/Wi-Fi sensor data -- which means a higher obsolescence rate for legacy customizations. Verified32 Treat the MREF OM process as a strategic "reset opportunity": evaluate whether each legacy customization still adds value or whether native MREF capabilities have made it redundant.

See Phase 3 for the full comparison/merge process, including the retain/adopt/merge decision framework and conflict resolution patterns.

Key Takeaway

Same OM tool, same comparison reports (1-4), but against the MREF baseline instead of a TRIRIGA version target. Expect more changes and a higher rate of customization obsolescence.

6. Migration at a Glance

Before diving into the detailed phases, here is a high-level preview of every major migration workstream:

  1. Customization Assessment (Phase 2): Inventory every customization -- BOs, workflows, forms, reports, queries, custom Java, integrations -- and classify each by migration action required.
  2. Object Comparison and Merge (Phase 3): Run the OM tool comparison against the MREF baseline. For each customized object, decide: retain, adopt, or merge.
  3. Infrastructure and Deployment (Phase 4): Prepare the database (purge agent tables, clean environment properties), deploy MREF on OpenShift, migrate system properties to operator-managed configuration.
  4. Custom Code and Integration Adaptation (Phase 5): Repackage custom Java into ClassLoader records or Customization Archives. Migrate integration auth to OpenShift Secrets. Review AppPoints consumption.
  5. Testing and Cutover (Phase 6): Execute migration-specific testing (functional, integration, regression, performance), follow the cutover runbook, and validate with UAT.

Key Takeaway

MREF migration is not a single event -- it is a sequence of workstreams that build on each other. This guide walks you through each one.

7. Complexity Drivers

These factors drive the effort required for an MREF migration engagement. Use them during scoping to set expectations -- but resist the urge to assign time estimates until after the Phase 2 assessment.

Factors That Increase Effort

  1. Heavy Platform Customization Outside the ClassLoader Pattern -- Custom JARs in WebSphere directories or web.xml modifications require Customization Archives. If the archive is incorrectly structured, the container build fails. Verified28
  2. Db2 Schema Naming Constraints -- You must keep the exact same schema name and database username. If your DBA team wants to rename schemas during migration, it will fail unless IBM Support is engaged. Verified6
  3. Complex Integration Postures and AES Encryption -- Must extract legacy AES keystore password and inject into OpenShift Secret before activation. Integration service accounts consume AppPoints concurrently. Verified29
  4. Large Version Jumps -- Upgrading from early 11.x to 11.6/MREF requires a Full Upgrade strategy with parallel source and target environments. Factor in mandatory version-specific sequences (e.g., Lease Accounting when crossing 11.4). Verified30
  5. Lack of In-House OpenShift Skills -- Operations teams must learn Kubernetes CRs and ConfigMaps. If the client insists on customer-managed but lacks RHOCP skills, the infrastructure phase balloons. Verified33

Factors That Decrease Effort

  1. Already on 11.5/11.6 -- Partial Upgrade strategy viable, using IBM "delta" OM packages within a single environment. Verified30
  2. Modern UX Framework Adoption -- UX framework components migrate cleanly. The OM tool automatically packages all UX metadata and Web View files. Verified6
  3. Lightly Configured Environment -- Fewer customizations means fewer comparison/merge decisions and less repackaging work.

Key Takeaway

The biggest effort drivers are custom code outside the ClassLoader pattern, the version distance to 11.5/11.6, and AES encryption dependencies. Assess these three areas first in your engagement scoping.

Sources

  1. IBM Partner Enablement deck (June 2025, PDF); IBM SaaS migration deck (Oct 2025, PDF); IBM Docs: Upgrading from TRIRIGA to MREF; IBM UMT documentation ↩

  2. IBM MREF FAQ; IBM MREF technical content (PDF) ↩

  3. IBM MREF FAQ; IBM Docs: Basic configuration ↩

  4. eCIFM: Early TRIRIGA-to-MREF Lessons; IBM MREF technical content (PDF); IBM SaaS migration deck (Oct 2025, PDF) ↩

  5. eCIFM: Early TRIRIGA-to-MREF Lessons; IBM SaaS migration deck (Oct 2025, PDF); IBM Docs: Basic configuration ↩

  6. eCIFM: Early TRIRIGA-to-MREF Lessons ↩↩↩

  7. IBM MREF technical content (PDF) ↩↩

  8. IBM Docs: Network considerations ↩

  9. IBM Docs: Basic configuration ↩

  10. IBM Docs: Upgrading from TRIRIGA to MREF; IBM MREF vs TAS architecture comparison (PDF) ↩

  11. IBM Docs: MREF TRIRIGAWEB.properties ↩

  12. Technovity: TRIRIGA to MREF migration (domain defunct); IBM MREF technical content (PDF) ↩

  13. IBM Docs: Basic configuration; Technovity: TRIRIGA to MREF migration (domain defunct) ↩

  14. IBM MREF technical content (PDF); IBM MAS/TAS Connector ↩

  15. IBM Docs: Configuring OIDC SSO; IBM MREF technical content (PDF) ↩

  16. IBM TRIRIGA Release Notes for 11.5 and 4.5 ↩↩

  17. IBM TRIRIGA Release Notes for 11.6 and 5.0 ↩↩

  18. IBM Docs: REST API as replacement for RMI ↩

  19. IBM TRIRIGA Release Notes for 11.4 and 4.4; IBM TRIRIGA Release Notes for 11.5 and 4.5 ↩

  20. IBM TRIRIGA Release Notes for 11.2 and 4.2 ↩

  21. IBM TRIRIGA Release Notes for 11.3/11.4/11.5/11.6 ↩

  22. IBM MREF FAQ ↩↩

  23. IBM MREF FAQ; IBM internal migration deck (PDF); IBM SaaS migration deck (Oct 2025, PDF) ↩

  24. IBM MREF FAQ; IBM internal migration deck (PDF) ↩↩↩

  25. IBM Docs: Migrating TRIRIGA users and licenses ↩↩

  26. eCIFM: Early TRIRIGA-to-MREF Lessons; IBM UMT video walkthrough ↩

  27. IBM UMT documentation; IBM UMT video walkthrough; IBM Docs: Migrating TRIRIGA users and licenses ↩

  28. IBM Docs: Customization archive guidelines; TRM Group: Customization Archive ↩

  29. IBM MAS/TAS Connector; Maximo Open Forum: AppPoints efficiency (no longer publicly accessible); IBM Partner Enablement deck (June 2025, PDF) ↩

  30. IBM Docs: Application upgrade best practices ↩↩

  31. IBM Docs: Migrating the application database; eCIFM: Early TRIRIGA-to-MREF Lessons; IBM Docs: What's changed in MREF ↩

  32. IBM Partner Enablement deck (June 2025, PDF); IBM SWMUG presentation: RE&F Roadmap (PDF); IBM MREF technical content (PDF); IBM Docs: Maximo Real Estate and Facilities ↩

  33. eCIFM: Early TRIRIGA-to-MREF Lessons; IBM MREF FAQ; IBM: Running TAS on AWS with Red Hat OpenShift ↩