Chapter 6: Testing, Cutover, and Quality¶

Phases 2 through 5 delivered the building blocks -- assessment inventories, OM merge decisions, infrastructure deployment, custom code repackaging, and integration auth migration. This chapter turns those building blocks into an executable playbook. You will find a three-pass testing strategy with templates for each test type, phase-by-phase migration checklists that synthesize the entire guide into step sequences, a gate-based cutover runbook with rollback procedures, and UAT templates organized by migration area. This is the chapter you will have open during the engagement.

1. Testing Strategy¶

MREF migration testing is not traditional upgrade regression testing. The application layer carries over intact via the database -- your BOs, workflows, forms, and reports are the same objects. What changes is the infrastructure underneath: pod-based agents, operator-managed properties, OpenShift networking, and MAS-centralized auth. Focus testing effort on the seams between your application and the new infrastructure, not on re-verifying every OOTB workflow.

1.1 Three-Pass Approach¶

IBM recommends three migration attempts before production go-live. Each pass serves a distinct purpose, and skipping any of them introduces compounding risk. Verified¹

Pass 1: Initial Test Migration

Your first attempt against a copy of the production database. Purpose: discover environmental issues, validate procedures, and identify documentation gaps. Expect failures -- this is a learning exercise, not a dress rehearsal. Document every issue, every deviation from the planned sequence, and every step that took longer than expected.

Pass 2: Dress Rehearsal (Dry Run)

Your second attempt with full timing measurement. Every step in the cutover sequence (Section 3) is timed. The timing data from this pass becomes your production cutover schedule. Run the dress rehearsal in an environment as close to production as possible -- same database size, same integration endpoints (or realistic stubs), same team.

Tip

The dress rehearsal timing +20% buffer is your production cutover window. Without it, you are guessing.

Pass 3: Production Cutover

Final execution using the refined runbook from the dress rehearsal. No surprises -- every step has been rehearsed, timed, and documented. The cutover runbook in Section 3 is your working document for this pass.

Warning

Do not skip the dress rehearsal. Teams that go directly from test migration to production cutover consistently exceed their maintenance window.

1.2 Environment Model¶

The recommended environment progression for MREF migration testing:

Dev: OM merge testing (Phase 3 decisions), initial ClassLoader and Customization Archive deployment (Phase 5 procedures). This is where you validate that your merge decisions and custom code repackaging work.
QA: Integration testing with migrated auth, regression testing across business-critical processes. If budget allows, run the initial test migration (Pass 1) here.
UAT: Business user validation using the scenario-based templates in Section 4. This is where consultants and client SMEs verify that migrated functionality matches expectations.
Prod: Final cutover using the dress-rehearsal-validated runbook (Section 3).

At minimum, you need Dev + UAT. QA is recommended but often combined with Dev in smaller engagements. Do not skip UAT -- business users catch issues that technical testing misses.

1.3 Functional Verification¶

Scope: Custom workflows, customized forms, custom reports, and custom queries from your Phase 2 inventory. You are NOT exhaustively testing every OOTB workflow -- Phase 5 Section 3 provides the workflow verification methodology and risk-based sampling approach. This section extends that methodology to forms, reports, and queries.

Pass/fail criteria: Each item either functions identically to the source environment or has a documented reason for the difference (e.g., an intentionally adopted MREF baseline change from Phase 3).

Gotcha

UX metadata (perceptive apps) can be deleted by OM import if not in the incoming package. Verify custom UX components explicitly -- do not assume they survived the merge. Verified²

Functional Verification Template

ID	Artifact Type	Artifact Name	Source Behavior	Notes
FV-01	Custom Workflow	triWorkTask - Custom Route to FM	Routes work tasks to FM based on building code lookup	Risk category: Business-Critical
FV-02	Customized Form	triLeaseForm (12 custom tabs)	All custom tabs render, field validations fire on save	Retained in Phase 3 merge
FV-03	Custom Report	Monthly Space Utilization (BIRT)	Generates PDF with correct square footage calculations	Verify BIRT rendering in container

1.4 Integration Testing¶

Scope: Every integration from your Phase 2 inventory, grouped by auth type (API key, OIDC, AES-encrypted). Each integration was migrated in Phase 5 Section 2 -- this section validates end-to-end functionality.

Test each: Authentication succeeds, data flows in both directions (or the expected direction), error handling works as designed.

Pass/fail criteria: Integration returns expected data within acceptable latency; auth tokens are valid and not expired.

Gotcha

Every Integration Object must have the ReMap action run after OM migration (Phase 5 Section 2.3). If ReMap was skipped, integration field mappings are stale and tests will fail with incorrect data -- even though authentication succeeds. Verified³

Warning

Stale OSLC ETags: external consumers caching ETags from the source TRIRIGA environment will get HTTP 412 errors. They must perform fresh GETs post-migration. Verified⁴

Integration Testing Template

ID	Integration Name	Auth Type	Source Endpoint	MREF Endpoint	Notes
IT-01	Work Order Sync	API Key	https://tririga.example.com/ws/...	https://workspace-tririga.mas.example.com/ws/...	Outbound HTTP POST to ServiceNow
IT-02	SSO Portal	OIDC	N/A (redirect-based)	N/A (redirect-based)	Verify OIDC token exchange via Okta
IT-03	Legacy SOAP Feed	AES-encrypted	https://tririga.example.com/soap/...	https://workspace-tririga.mas.example.com/soap/...	Verify vault_secret decryption works

1.5 Regression Testing¶

Scope: Core business processes across all modules (Real Estate, Facilities, Capital Projects, Workplace Services). This is NOT exhaustive -- focus on business-critical workflows identified in your Phase 2 assessment.

Pass/fail criteria: Business process completes end-to-end in MREF with the same outcome as the source environment.

Tip

Regression testing is most efficient when run by the same consultants who performed the Phase 2 assessment -- they already know the customer's critical processes.

Regression Testing Template

ID	Module	Business Process	Steps	Expected Outcome	Actual Outcome	Status
RT-01	Real Estate	Lease creation through payment calculation	Create lease > add terms > trigger payment calc > verify amounts	Payment amounts match source system within rounding tolerance
RT-02	Facilities	Work order creation through completion	Create WO > assign > complete > verify status transition and notifications	WO reaches Completed status; FM receives email notification

1.6 Performance Testing¶

Measure these metrics in the source TRIRIGA environment before migration, then rerun identical tests post-migration. Acceptable threshold: within 110% of pre-migration baseline (industry standard for infrastructure migrations).

Metrics to Baseline

Page load time: Appserver response time for key pages (lease form, work order form, dashboard)
Workflow execution time: Business-critical workflows timed in source vs target (lease payment calculation, work order routing)
Agent throughput: Workflow agent processing rate (tasks processed per minute)
Report generation time: BIRT reports with production-like data volumes
Integration round-trip time: API call through the OpenShift route vs legacy direct connection
Database connection latency: Performance Monitor in Admin Console -- must return green Verified¹⁰

Baseline approach: Run Performance Analyzer in the legacy environment on core business processes. Document metrics. Post-migration: rerun identical tests. Compare against baseline.

MREF-Specific Performance Gotchas

Warning

WF_INSTANCE_SAVE: Full recording degrades performance 50%+. Must be ERRORS_ONLY in production. MREF enforces a 1,000 instance/day hard limit regardless of setting. Use DATA_LOAD for bulk loads, which bypasses instance saving entirely. Verified⁵

Gotcha

JVM auto-sizing: MREF calculates heap at 75% of pod memory request (min) and 75% of pod memory limit (max). Setting javamax above 75% of pod memory limit = OOMKilled by Kubernetes. Use auto-sizing defaults and adjust pod memory limits instead. Verified⁶

Gotcha

maxconnpoolsize: Default 100 per pod. Tune based on appserver replica count -- if running two appserver pods, each gets its own pool of 100 connections. Total database connections = pool size x pod count. Likely⁷

Warning

REPORT_MEMORY_USAGE_LIMIT: Unfiltered reports with large result sets can OOMKill appserver pods. Cap at 1-2 GB. If users run unfiltered reports against production data volumes, the pod will crash. Likely¹⁰

Gotcha

CLEANUP_AGENT_RECORD_BATCH_SIZE: Tune to 10,000-50,000 for database transaction manageability. Larger batches risk transaction timeouts; smaller batches extend cleanup duration. Likely¹¹

Tip

Agent timing jitter: WF_AGENT_SLEEPTIME randomly varies 4500-5500ms. This is not a bug -- it prevents database lock-stepping across agent pods. Do not attempt to eliminate the jitter. Verified⁸

Key Takeaway

Focus testing on the seams between your application and the new MREF infrastructure: integrations with migrated auth, custom Java in ClassLoader records and Customization Archives, scheduled workflows in the pod-based agent model, and performance under container resource limits. Use the three-pass approach (test migration, dress rehearsal, production cutover) and the 110% baseline threshold for performance validation.

2. Phase-by-Phase Migration Checklists¶

These checklists synthesize the procedures from all five prior chapters into actionable step sequences. Each row references the specific chapter and section where the full procedure lives -- use the Source column to navigate to detailed instructions.

2.1 Phase 1: Foundation and Scoping¶

Step	Action	Source
1	Confirm this is an MREF migration (not TAS replatforming or TRIRIGA version upgrade)	Chapter 1, Section 1
2	Verify source environment is on Application 11.5/11.6 + Platform 4.5/5.0; if not, plan prerequisite upgrade	Chapter 1, Section 4
3	Confirm AppPoints licensing model understood; identify Self-Service/Limited/Base/Premium tier definitions	Chapter 1, Section 2
4	Identify deployment model: SaaS (IBM-hosted), customer-managed, or partner-hosted	Chapter 1, Section 3
5	Complete the Engagement Scoping Checklist (8 questions)	Chapter 1, Section 1
6	Assess complexity drivers: custom Java outside ClassLoader pattern, version distance, AES dependencies	Chapter 1, Section 7

2.2 Phase 2: Assessment and Inventory¶

Step	Action	Source
1	Run OM tool comparison and generate Reports 1-3 against MREF baseline	Chapter 2, Section 2
2	Complete standard artifact inventory template (BOs, workflows, forms, reports, queries, navigation, UX apps)	Chapter 2, Section 2
3	Classify each artifact as Carries Over / Reconfigure / Repackage using the three-tier system	Chapter 2, Section 2
4	Complete custom Java inventory template; classify each as ClassLoader Record or Customization Archive	Chapter 2, Section 3
5	Audit file system for undocumented JAR drops (legacy practice, invisible to admin console)	Chapter 2, Section 3
6	Complete integration inventory template; group by auth type (API key, OIDC, AES)	Chapter 2, Section 4
7	Audit AppPoints consumption per integration service account; strip unnecessary high-tier access	Chapter 2, Section 4
8	Complete system properties assessment; classify each as Retained / Moved / Removed	Chapter 2, Section 5

2.3 Phase 3: Object Mapping and Configuration Merge¶

Step	Action	Source
1	Cross-reference Report 1 vs Report 3 to categorize each object: Retain (Report 1 only), Adopt (Report 3 only), Merge Candidate (both)	Chapter 3, Section 3.1
2	Apply merge direction heuristic to each merge candidate (Report 2 changes vs Report 3 changes)	Chapter 3, Section 3.2
3	Resolve conflicts using the 7 named patterns (Field Addition, Form Layout Collision, Workflow Logic Divergence, etc.)	Chapter 3, Section 4
4	Validate feature parity for adopted MREF objects; check for deprecated features	Chapter 3, Section 5
5	Generate Report 4 (post-merge validation) and cross-reference against Report 2	Chapter 3, Section 2
6	Execute OM merge in dev environment first; validate before promoting to QA/UAT	Chapter 3, Section 3.6
7	Complete decision log template with rationale per object for client sign-off	Chapter 3, Section 3.5

2.4 Phase 4: Infrastructure and Deployment¶

Step	Action	Source
1	Full database backup (rollback anchor for all subsequent steps)	Chapter 4, Section 1.1
2	Purge `AGENT_REGISTRY` and `AGENT_STARTUP` tables	Chapter 4, Section 1.2
3	Clean `ENVIRONMENT_PROPERTIES` rows (`platform.class.upgrade`, `AgentManagementUpgrade`)	Chapter 4, Section 1.3
4	Verify system user account exists and credentials documented	Chapter 4, Section 1.4
5	Hard gate: Extract AES encryption secrets and create `vault_secret` OpenShift Secret	Chapter 4, Section 1.5
6	Connect database to MREF (BYOD connection or database conversion to Db2)	Chapter 4, Section 2
7	Map system properties to MREF equivalents using the expanded property mapping table	Chapter 4, Section 3
8	Deploy MREF operator; configure FacilitiesWorkspace CR spec fields	Chapter 4, Section 4
9	Configure pod sizing (`spec.env.size`) and persistent storage (PVCs for userfiles/config/log)	Chapter 4, Sections 4.4-4.5
10	Run post-deployment verification: CR status, pod health, route accessibility, agent activity, workflow execution, persistent storage	Chapter 4, Section 5

2.5 Phase 5: Custom Code and Integration Adaptation¶

Step	Action	Source
1	Repackage ClassLoader record JARs: upload to Class Loader (Tools > System Setup > System > Class Loader)	Chapter 5, Section 1.1
2	Build and deploy Customization Archives (ZIP mimicking `/SMP/maximo/` structure)	Chapter 5, Section 1.2
3	Handle hybrid JARs requiring both ClassLoader and Customization Archive paths	Chapter 5, Section 1.3
4	Migrate API key authentication: generate keys in MAS Admin, update external callers	Chapter 5, Section 2.1
5	Configure OIDC authentication: register app, create secrets, import TLS certificates	Chapter 5, Section 2.2
6	Complete AES keystore post-extraction configuration; verify `vault_secret` accessible from pods	Chapter 5, Section 2.3
7	Update endpoint URLs, import certificates, adjust network policies	Chapter 5, Section 2.4
8	Verify AppPoints licensing for all integration service accounts; strip unnecessary access	Chapter 5, Section 2.5
9	Verify workflow carryover using risk-based sampling (Business-Critical > High-Volume > Integration-Triggered > Standard)	Chapter 5, Section 3

Key Takeaway

These checklists are your execution backbone. Print them, assign owners to each row, and track completion during the engagement. The Source column links back to detailed procedures in each chapter -- you should never need to hunt for the "how." If a step fails, the referenced section includes rollback instructions.

3. Cutover Runbook¶

This is your production cutover playbook -- refined through the three-pass approach in Section 1.1. The dress rehearsal timing data populates the Duration Category column. By the time you execute this runbook for production, every step should be familiar and every duration should be measured, not estimated.

3.1 Cutover Sequence¶

Execute these steps in order. The Gate column maps each step to the go/no-go gates in Section 3.2 -- you must pass all gate criteria before proceeding past each gate boundary.

Step	Action	Duration Category	Dependencies	Gate
1	Quiesce legacy TRIRIGA: disable logins, drain active sessions, confirm zero active users	Hours	None	Pre-Cutover
2	Final database backup (rollback anchor)	Hours	Step 1	Pre-Cutover
3	Database restore to target environment (or BYOD connection verification)	Hours-Overnight	Step 2	Infrastructure Ready
4	Purge `AGENT_REGISTRY`, `AGENT_STARTUP` tables + `ENVIRONMENT_PROPERTIES` cleanup	Minutes	Step 3	Infrastructure Ready
5	Deploy AES `vault_secret` to OpenShift namespace	Minutes	Step 4	Infrastructure Ready
6	Activate MREF operator (FacilitiesWorkspace CR)	Hours	Step 5	Infrastructure Ready
7	Verify pods running (no CrashLoopBackOff), routes accessible (HTTP 200)	Minutes	Step 6	Infrastructure Ready
8	Execute User Migration Tool (UMT)	Hours	Step 7	Platform Live
9	Import OM packages	Hours	Step 7	Platform Live
10	Run ReMap on all Integration Objects	Minutes	Step 9	Platform Live
11	Verify system properties (spot-check critical properties from Chapter 4 mapping table)	Minutes	Step 7	Platform Live
12	Execute smoke test: login, navigate, trigger one workflow	Minutes	Steps 8-11	Platform Live
13	Re-point integrations to MREF endpoints	Hours	Step 12	Business Validated
14	Execute UAT scenarios (Section 4 templates)	Hours	Step 13	Business Validated
15	Update Base/Premium users from "concurrent" to "authorized" access type	Minutes	Step 8	Business Validated
16	Update DNS/load balancers to MREF	Minutes	Step 14 pass	Business Validated

Warning

Step 15 (user access type update) is frequently missed. All users migrate as "concurrent" via UMT. Base and Premium users must be manually updated to "authorized" in MAS Admin Portal, or licensing violations occur. Verified⁹

Tip

Steps 8-11 can run in parallel once pods are verified in Step 7. This is the largest time savings opportunity in the cutover window.

3.2 Go/No-Go Gates¶

Four gates extend the Pre-check/Verify pattern from Chapter 4. Each gate must pass before proceeding to the next phase of the cutover.

Gate 1: Pre-Cutover Readiness

Pre-check

[ ] Legacy TRIRIGA fully quiesced (no active sessions)
[ ] Final database backup complete and verified
[ ] AES encryption secrets extracted (Chapter 4 Section 1.5)
[ ] OpenShift cluster ready (nodes healthy, storage provisioned)
[ ] Cutover team assembled with contact list

Decision: All items checked = PROCEED. Any unchecked = DO NOT PROCEED, resolve first.

Gate 2: Infrastructure Ready

Pre-check

[ ] Database restored/connected to MREF environment
[ ] Agent tables purged, ENVIRONMENT_PROPERTIES cleaned
[ ] AES secret deployed to OpenShift namespace
[ ] MREF operator activated, pods running (no CrashLoopBackOff)
[ ] OpenShift routes accessible (HTTP 200 on health endpoint)

Decision: All items checked = PROCEED. Pod failures = check logs, fix, re-verify. Persistent CrashLoopBackOff = ABORT cutover, reschedule.

Gate 3: Platform Live

Pre-check

[ ] Login successful with FACILITIESADMIN user
[ ] All agents active in Admin Console
[ ] OM packages imported successfully
[ ] User migration (UMT) complete -- verify user count matches source
[ ] Critical system properties verified (spot-check 5 from Chapter 4 mapping table)

Decision: All items checked = PROCEED. Partial failures: evaluate severity. Fixable within cutover window = fix and re-verify. Systemic (multiple agents down, OM import failed) = ROLLBACK.

Gate 4: Business Validated

Pre-check

[ ] Smoke test passed (login, navigate, trigger workflow)
[ ] Critical integration tests passed (per Section 1.4 template)
[ ] UAT scenarios passed (per Section 4 templates)
[ ] Performance baselines within 110% of source (per Section 1.6)
[ ] Base/Premium users updated to "authorized" access type

Decision: All critical items passed = GO LIVE. Isolated failures in non-critical integrations = GO LIVE with known issues documented. Systemic failures (multiple business processes broken) = ROLLBACK.

3.3 Timing Framework¶

Use relative durations only -- every environment is different. Populate the Duration column with actual times from your dress rehearsal.

Tip

Populate the Duration column with actual times from your dress rehearsal. Add 20% buffer for production. This is the most reliable scheduling method.

Step Category	Typical Duration	Variables
Legacy quiesce + backup	Hours	Database size, session drain time
Database restore	Hours-Overnight	Database size, network speed, BYOD vs restore
Agent/env cleanup	Minutes	Fixed -- quick SQL operations
Operator activation + pod startup	Hours	Image pull speed, cluster capacity, operator reconciliation
User migration (UMT)	Hours	User count (batches of 499)
OM package import	Hours	Customization volume
Integration re-pointing	Hours	Number of integrations, per-integration testing
Smoke test + UAT	Hours	Scenario count -- cannot compress

Warning

The longest single step is usually database restore. For large databases (500GB+), this can be overnight. Plan accordingly -- this is the step that most often blows the cutover window.

3.4 Rollback Decision Framework¶

The hardest decision during cutover is not HOW to rollback -- it is WHEN. Establish rollback criteria before the cutover begins, not in the moment.

Decision tree by gate:

Gate 1 or Gate 2 fails: ABORT. No data has moved to the target environment. Reschedule. This is the lowest-risk rollback -- nothing to undo.
Gate 3 fails (platform issues): EVALUATE. Can the issue be fixed within the remaining cutover window? If yes, fix and re-verify gate. If no, ROLLBACK. Key question: "Will fixing this take longer than the remaining maintenance window?"
Gate 4 fails (business validation): HARDEST DECISION. Fix-forward if failures are isolated (one integration, one non-critical workflow). Rollback if failures are systemic (multiple business processes, performance degradation, data integrity concerns).

Gotcha

The Gate 4 decision is where most teams struggle. The sunk cost of a long cutover creates pressure to push forward. Establish the rollback decision criteria BEFORE the cutover begins -- not in the moment.

3.5 Rollback Procedures¶

Three key procedures, ordered from fastest/safest to most involved. The side-by-side deployment model is your greatest rollback asset -- legacy TRIRIGA stays intact throughout.

Procedure A: DNS/Network Re-pointing (safest, fastest)

Re-point DNS records and load balancers back to legacy TRIRIGA VMs
Revert any user-facing URL changes
Legacy environment is intact -- this is a routing change only
Duration: Minutes (DNS propagation may take longer)

Procedure B: Integration Auth Rollback

Revert middleware configuration to previous TRIRIGA endpoints
Re-enable legacy Basic Auth / OAuth credentials
Disable new MAS API keys/OIDC tokens
Duration: Hours (per-integration, must verify each)

Procedure C: Database Revert (for next attempt)

On the MREF side: delete/revert the FacilitiesWorkspace CR and deployment secrets Needs Validation (no public citation located)
Restore MREF target database to pre-cutover state (from the backup taken in Step 2)
This prepares the target environment for the next migration attempt
Duration: Hours-Overnight (depends on database size)

Warning

IBM explicitly states: do NOT decommission legacy TRIRIGA VMs immediately after cutover. Maintain them through a defined stabilization period (typically 2-4 weeks) as your rollback safety net. Verified¹

Tip

The side-by-side deployment model is your greatest rollback asset. Legacy TRIRIGA stays intact throughout. Rollback at any gate means re-pointing traffic, not rebuilding an environment.

Key Takeaway

The cutover runbook has four gates. Gates 1-2 (infrastructure) are low-risk to abort -- nothing to undo. Gate 3 (platform) requires a time-boxed evaluation. Gate 4 (business validation) is the hardest decision -- establish pass/fail criteria before the cutover starts. Your dress rehearsal timing +20% is the production schedule. And do not decommission legacy until the stabilization period is complete.

4. UAT Templates¶

These templates cover the migration-specific scenarios that UAT should validate. They are organized by migration area, not by business process -- you are testing that each migration workstream (workflows, integrations, custom code, forms, scheduled jobs, user access) functions correctly in MREF. Customize with customer-specific business processes, but use these pre-filled scenarios as your starting framework.

4.1 Workflows¶

Cross-reference Phase 5 Section 3 for the risk-based verification methodology. These UAT scenarios validate end-to-end behavior from the business user's perspective.

ID	Scenario	Preconditions	Steps	Expected Result
UAT-WF-01	Synchronous workflow triggered by form save	Work order record exists in MREF	Open work order > change status to "Assigned" > save	Status change triggers routing workflow; FM receives notification
UAT-WF-02	Asynchronous scheduled workflow	Scheduler agent pod running; overnight batch configured	Wait for scheduled trigger time; verify batch processing log	Batch workflow completes; all records processed within expected window
UAT-WF-03	Workflow with custom Java task (ClassLoader record)	ClassLoader record uploaded per Chapter 5 Section 1.1	Trigger workflow that invokes custom task class	Custom task executes; no ClassNotFoundException in pod logs

4.2 Integrations¶

ID	Scenario	Auth Type	Preconditions	Steps	Expected Result
UAT-INT-01	Inbound HTTP integration with API key auth	API Key	API key generated in MAS Admin; external system configured	External system sends POST to MREF endpoint with x-api-key header	Data received and processed; HTTP 200 response
UAT-INT-02	Outbound REST integration with OIDC auth	OIDC	OIDC secrets deployed; external API accessible	Trigger outbound integration from MREF	Token exchange succeeds; data sent to external API; confirmation received
UAT-INT-03	Integration using AES-encrypted credentials	AES	`vault_secret` deployed; ReMap action completed	Trigger integration that uses stored encrypted password	Decryption succeeds; integration authenticates and exchanges data
UAT-INT-04	OSLC API consumer	API Key / OIDC	External consumer updated to new MREF endpoint	External system performs GET on OSLC resource	Fresh ETag returned (no HTTP 412); resource data correct

4.3 Custom Code¶

ID	Scenario	Deployment Type	Preconditions	Steps	Expected Result
UAT-CC-01	Custom workflow task via ClassLoader record	ClassLoader	ClassLoader record uploaded and active	Trigger workflow containing custom task	Task executes; workflow completes; correct output
UAT-CC-02	Custom servlet via Customization Archive	Customization Archive	Archive deployed; pod rebuilt	Navigate to servlet URL (e.g., /maximo/custom/report)	HTTP 200 response; servlet renders correctly
UAT-CC-03	3rd party library via Customization Archive	Customization Archive	Library JARs included in archive /lib/	Trigger functionality that depends on 3rd party library	No NoClassDefFoundError; library functions correctly under Java 17 runtime

4.4 Forms, Reports, and Documents¶

ID	Scenario	Preconditions	Steps	Expected Result
UAT-FR-01	Customized form with added fields and sections	Form retained/merged in Phase 3	Open record using customized form	All custom tabs, fields, and sections render; field validations fire on save
UAT-FR-02	BIRT report with custom parameters	Report carried over via database	Navigate to report > set parameters > generate	Report generates with correct data; PDF/Excel export works
UAT-FR-03	Document management	Persistent storage configured (PVC)	Upload document > restart appserver pod > access document	Document persists across pod restart; download and view work correctly
UAT-FR-04	UX perceptive app	OM import completed with UX metadata	Navigate to UX application	App loads; all components present (not deleted by OM import)

4.5 Scheduled Jobs¶

ID	Scenario	Preconditions	Steps	Expected Result
UAT-SJ-01	Reserve SMTP agent (inbound email)	SMTP NodePort manually configured per Chapter 5 Section 3.4	Send test email to reserve mailbox	Email processed; reservation created or updated
UAT-SJ-02	DataConnect scheduled job	File paths point to persistent storage (`userfiles` only)	Trigger DataConnect job or wait for schedule	Job completes; data imported from file in persistent directory
UAT-SJ-03	Cleanup agent	`CLEANUP_AGENT_RECORD_BATCH_SIZE` tuned (10,000-50,000)	Wait for cleanup agent cycle	Agent completes without timeout; stale records purged

4.6 User Access and Licensing¶

ID	Scenario	Preconditions	Steps	Expected Result
UAT-UA-01	Base user login	User migrated via UMT; access type updated to "authorized"	Log in as Base user	Login succeeds; Base-level module access available; 10 AppPoints consumed
UAT-UA-02	Premium user with full module access	User migrated via UMT; access type updated to "authorized"	Log in as Premium user; access all modules	All modules accessible; 15 AppPoints consumed per session
UAT-UA-03	Self-Service user	User migrated via UMT	Log in as Self-Service user	Login succeeds; limited access scope; 0 AppPoints consumed
UAT-UA-04	Integration service account	Service account migrated; security groups reviewed per Chapter 5 Section 2.5	Authenticate via API; check AppPoints	AppPoints tier matches reviewed security group assignment

Gotcha

All users migrate as "concurrent" access type via UMT. If UAT is conducted before updating Base/Premium users to "authorized," licensing test results will be inaccurate. Update access types before running UAT-UA scenarios.

Key Takeaway

These UAT templates cover six migration areas: workflows, integrations, custom code, forms/reports/documents, scheduled jobs, and user access/licensing. The pre-filled scenarios address the most common MREF migration failure points -- ClassNotFoundException from missing ClassLoader records, stale Integration Object mappings, deleted UX metadata, silent SMTP failures, and incorrect AppPoints consumption. Customize with customer-specific scenarios, but do not skip the pre-filled ones.

5. Guide Quality Standards¶

This section documents the quality conventions applied throughout this guide and provides a verification checklist for validating guide claims against your specific MREF version. These standards were applied during writing -- they are documented here for transparency and practical use, not as a retroactive audit.

5.1 Source Citation Convention and Bibliography¶

Technical claims in this guide prioritize IBM documentation as the primary source. Claims not directly confirmed are tagged with Likely or Needs Validation confidence levels (see Section 5.2). The citation convention follows two rules:

Inline citations identify the source by topic or document title -- not by URL. This keeps the prose readable while preserving traceability.
URLs are consolidated in the bibliography below, organized by topic. When you need to verify a claim or check for updates, start here.

Good citation: "Agent tables must be truncated before connecting the database to MREF (IBM: Migrating the Application Database). Verified"

Bad citation: "Agent tables should probably be truncated (based on general best practices)."

The good example names the source document, tags the confidence level, and the bibliography below provides the URL. The bad example cites nothing and hedges with "probably" -- if you cannot cite the source, tag the claim Needs Validation and tell the reader why.

Consolidated Bibliography¶

Core Migration Documentation

Source	URL	Chapters Referenced
Upgrading from TRIRIGA to MREF	https://www.ibm.com/docs/en/masv-and-l/cd?topic=upgrading-from-tririga-maximo-real-estate-facilities	1, 4, 6
What's Changed in MREF	https://www.ibm.com/docs/en/masv-and-l/cd?topic=facilities-whats-changed-in-maximo-real-estate	1, 3
Application Upgrade Best Practices	https://www.ibm.com/docs/en/masv-and-l/maximo-ref/cd?topic=application-upgrade-best-practices	3, 4, 5
Post-Migration Tasks	https://www.ibm.com/docs/en/masv-and-l/cd?topic=facilities-post-migration-tasks	4, 5, 6

Database and Customization

Source	URL	Chapters Referenced
Migrating the Application Database	https://www.ibm.com/docs/en/masv-and-l/cd?topic=facilities-migrating-application-database	4
Migrating Customizations (Archives)	https://www.ibm.com/docs/en/masv-and-l/cd?topic=preparing-migrating-customizations-using-customization-archives	5
Object Migration User Guide (PDF)	https://www.ibm.com/docs/en/SSHEB3_5.0/pdf/pdf_tap_obj_migration.pdf	2, 3
OM Overview	https://www.ibm.com/docs/en/tap/5.0.0?topic=objects-object-migration-overview	1, 2, 3

User and License Migration

Source	URL	Chapters Referenced
Migrating Users and Licenses	https://www.ibm.com/docs/en/masv-and-l/cd?topic=facilities-migrating-tririga-users-licenses	6
UMT Download and Install	https://www.ibm.com/docs/en/masv-and-l/cd?topic=licenses-downloading-installing-user-migration-tool	6
License IDs and Names	https://www.ibm.com/docs/en/tap/5.0.0?topic=management-license-ids-names	1, 5

AES Encryption

Source	URL	Chapters Referenced
Migrating AES Reversible Encryption	https://www.ibm.com/docs/en/masv-and-l/cd?topic=facilities-migrating-aes-reversible-encryption	4, 5

Deployment

Source	URL	Chapters Referenced
Deployment and Activation Settings	https://www.ibm.com/docs/en/masv-and-l/cd?topic=facilities-deployment-activation-settings	4
Deployment Size Scenarios	https://www.ibm.com/docs/en/tas/11.5.0?topic=installation-deployment-size-scenarios	4

Support and Planning

Source	URL	Chapters Referenced
TRIRIGA Release Information	https://www.ibm.com/support/pages/ibm-tririga-release-information	1
Reverting Upgraded Platform or Portfolio Versions	https://www.ibm.com/support/pages/ibm-tririga-reverting-upgraded-platform-or-portfolio-versions	6
MAS Performance Wiki (Sizing Guidance)	https://ibm-mas.github.io/mas-performance/mas/sizing/guidance/	4
MREF Launch Central	http://ibm.biz/MREFLaunch	1
MAS SaaS Calculator	https://IBM.biz/MAS_SaaS_Calculator	1

Tip

Bookmark the four "Core Migration Documentation" sources. These pages are your primary reference throughout any MREF engagement and are updated as MREF evolves. Start there when verifying any guide claim.

Additional IBM Documentation

Source	URL	Chapters Referenced
TRIRIGAWEB.properties Reference	https://www.ibm.com/docs/en/tap/5.0?topic=files-tririgawebproperties	2, 4
Custom Classes for Custom Tasks	https://www.ibm.com/docs/en/tap/5.0.0?topic=functions-custom-classes-custom-tasks	2, 5
Adding Customizations (Maximo Manage)	https://www.ibm.com/docs/en/masv-and-l/maximo-manage/cd?topic=customizing-adding-customizations	5
Applying Customization Archives	https://www.ibm.com/support/pages/applying-customization-archive-ibm-maximo-manage	5
Dedicated TRIRIGA Workflow Agents	https://www.ibm.com/docs/en/tas/11.4?topic=configuration-dedicated-tririga-workflow-agents	5
Trusted Certificates in Maximo Manage	https://www.ibm.com/docs/en/masv-and-l/maximo-manage/cd?topic=administering-trusted-certificates	5
Application Not Found Error After Migration	https://www.ibm.com/support/pages/node/7268203	4
MREF Evolution from TRIRIGA	https://www.ibm.com/support/pages/maximo-real-estate-and-facilities-evolution-tririga	1, 2, 3
MREF Component Release (MAS 9.1.8)	https://www.ibm.com/support/pages/ibm-maximo-application-suite-real-estate-and-facilities-component-918	1
IBM Maximo Manage FAQ	https://ibm-mas-manage.github.io/faq/	2, 5
OM Comparison Methods	https://www.ibm.com/docs/en/tap/4.5.0?topic=objects-comparison-methods	2
OSLC Integration Guide (PDF)	https://www.ibm.com/docs/en/SSHEB3_5.0/pdf/pdf_tap_oslc.pdf	5
APAR IV98944 (Reverse Association)	https://www.ibm.com/support/pages/apar/IV98944	3

IBM Community and GitHub

Source	URL	Chapters Referenced
Welcome to MREF (Kalman Gyimesi, IBM)	https://community.ibm.com/community/user/blogs/kalman-gyimesi1/2025/07/21/welcome-to-maximo-real-estate-and-facilities	1, 3
MREF Installation and Demo Data Discussion	https://community.ibm.com/community/user/discussion/mref-installation-and-demo-data-in-mas91	2
MAS CLI Installation Guide	https://ibm-mas.github.io/cli/guides/install/	4
MAS Ansible DevOps	https://github.com/ibm-mas/ansible-devops	4
MAS/TAS AppConnect Flows	https://github.com/IBM/mas-tas-appconnect-flows	5
TRIRIGA API	https://github.com/IBM/tririga-api	5

Supplementary Sources (Non-IBM)

These practitioner blogs, implementation partner guides, and community resources informed the guide's practical recommendations. They are secondary to IBM documentation and should not be treated as authoritative for MREF-specific procedures.

Source	URL	Type	Topics Informed
EAM360: Oracle to Db2 Conversion	https://eam360.com/blog/maximo-application-suite-convert-oracle-database-to-db-2/	Practitioner blog	Database conversion procedures, DMT limitations (Ch 4)
EAM360: SQL Server/Oracle to Db2	https://eam360.com/blog/navigating-the-transition-from-sql-server-oracle-to-db2-a-perspective-for-maximo-users/	Practitioner blog	SQL dialect conversion effort estimation (Ch 4)
TRM Group: AppPoints Licensing	https://trmgroup.com/resource/ibm-maximo-new-apppoints-licensing-model-explained	IBM partner	AppPoints tier values and licensing model (Ch 1, 2)
eCIFM: Early TRIRIGA-to-MREF Lessons	https://ecifm.com/bridging-platforms-lessons-from-early-tririga-maximo-real-estate-facilities-transitions/	Practitioner blog	Early migration practitioner experience, Dec 2025 (Ch 1)
MaximoDev: MIF/OSLC/REST/JSON API	https://bportaluri.com/2026/02/mif-oslc-rest-json-api.html	Developer blog	Integration API comparison and migration paths (Ch 5)
ebasso: Customization on OpenShift	https://ebasso.net/wiki/index.php?title=IBM_Maximo:_Provide_you_customization_binaries.zip_on_OpenShift	Community wiki	Customization Archive hosting on OpenShift (Ch 5)
TRIRIGAFEEDIA: ClassLoader Mechanics	https://tririgafeedia.wordpress.com/tag/class-loader/	Community blog	ClassLoader record behavior and custom task patterns (Ch 2, 5)
Briwo Solutions: MREF Overview	https://briwosolutions.com/ibm-tririga-mref/	IBM partner	MREF positioning and support timeline context (Ch 1)
ValuD Consulting: Upgrade Best Practices	https://www.valudconsulting.com/blog/best-practices-ibm-tririga-application-upgrade-part-3/	IBM partner	OM upgrade best practices (Ch 3)
Naviam: MAS 9.1 Release Analysis	https://www.naviam.io/resources/blog/maximo-application-suite-9-1-release-in-june-2025-what-to-expect	Analyst	Java 17 requirement, BIRT changes (Ch 4)
Red Hat: MAS and OpenShift	https://www.redhat.com/en/blog/ibm-maximo-application-suite-mas-and-red-hat-openshift	Vendor	OpenShift architecture context for MAS (Ch 4)
IBM 2Q 2025 TRIRIGA Roadmap	https://www.scribd.com/document/890777272/2Q-2025-TRIRIGA-Product-Roadmap-Update	IBM (Scribd)	Product roadmap and timeline context (Ch 1)

5.2 Confidence Level System¶

Three confidence levels are applied inline throughout this guide. Each claim that makes a factual assertion about MREF behavior, configuration, or procedures carries one of these tags:

Verified: Claim confirmed against IBM documentation or tested in a live MREF environment. Highest confidence. Use for IBM-documented procedures, confirmed UI paths, and verified API behavior.
Example from Chapter 1: "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. Verified"
Likely: Claim based on strong architectural reasoning or indirect IBM documentation, but not directly confirmed for MREF specifically. Medium confidence. Use for behavior inferred from TRIRIGA patterns that likely carry over, and configuration values from related IBM products.
Example from Chapter 4: "Merged into userfiles PVC via subPath Likely" -- the config directory persistence mechanism follows the established PVC pattern but the exact subPath implementation was not confirmed in IBM documentation.
Needs Validation: Claim based on early practitioner experience or reasonable inference, but MREF documentation is sparse or absent. Lowest confidence. Use for CR field paths that may change between releases, and features documented for TAS but not yet confirmed for MREF.
Example from Chapter 5: "Configure dedicated workflow agents via spec.wfagents in the TRIRIGA CR (exact JSON format Needs Validation)." -- the feature exists, but the exact CR syntax was not confirmed against current documentation.

Tip

Before each engagement, search the guide for Needs Validation tags and verify those claims against your target MREF version. These are the most likely to change as MREF matures.

5.3 Terminology Usage Rules¶

Chapter 3 Section 1 provides the concept glossary mapping TRIRIGA terminology to MREF equivalents. The following usage rules apply throughout this guide and should be applied in any engagement documentation:

MREF for the target environment and product; TRIRIGA for the source environment. Never use "new TRIRIGA" or "TRIRIGA on MAS" -- these are ambiguous and cause confusion in client communications.
MAS (not TAS) when referring to the suite; MAS Core for centralized admin functions. TAS refers specifically to the standalone TRIRIGA Application Suite deployment without MAS Core integration -- a different migration path not covered by this guide.
Pod/container (not server/JVM) when discussing MREF runtime infrastructure. The legacy terms imply VM-based architecture that no longer applies. Say "appserver pod" instead of "appserver instance."
Operator/CR (not installer/properties file) when discussing MREF configuration. The deployment model is fundamentally different from legacy TRIRIGA installation. Say "configure the CR" instead of "update the properties file."

5.4 Deliverable Format¶

This guide is authored in markdown as the working format. For client delivery, export to .docx using your preferred conversion tool. The markdown format preserves table structure, callout formatting, and cross-references through standard markdown syntax that survives .docx conversion.

5.5 Per-Chapter Verification Checklist¶

MREF is a new and evolving product. Before each engagement, verify the following version-sensitive claims against your target MREF version. These are the claims most likely to change between releases.

Chapter 1: Foundation and Platform Context

Claim to Verify	Where in Guide	How to Verify
MREF requires Application 11.5/11.6 + Platform 4.5/5.0	Section 2	Check IBM prerequisites page for current version requirements
AppPoints tier values (Self-Service=0, Limited=5, Base=10, Premium=15)	Section 2	Check IBM license documentation for current tier values
Deployment model options (SaaS, customer-managed, partner-hosted) still current	Section 2	Check IBM MREF product page for current deployment options
Support timeline dates (September 2027 standard support end)	Section 5	Check IBM TRIRIGA Release Information page for any date changes

Chapter 2: Assessment and Customization Inventory

Claim to Verify	Where in Guide	How to Verify
OM tool Report 1-3 formats unchanged	Section 2	Generate test reports in current OM version and compare format
ClassLoader approved package prefixes (com.tririga.ps, com.tririga.appdev, com.tririga.custom)	Section 3	Check ClassLoader record creation in current MREF for accepted prefixes
Integration Object auth types and AppPoints model	Section 4	Check current AppPoints documentation for integration licensing

Chapter 3: Object Mapping and Configuration Merge

Claim to Verify	Where in Guide	How to Verify
Concept glossary terminology current	Section 1	Compare glossary terms against current MREF UI labels and documentation
OM Report 4 generation process unchanged	Section 2	Generate test Report 4 in current MREF and verify workflow
Feature parity additions and removals current	Section 5	Review current MREF release notes for new or deprecated features
Reverse association deprecation status	Section 5	Check current MLA documentation for reverse association handling

Chapter 4: Infrastructure and Deployment

Claim to Verify	Where in Guide	How to Verify
Agent table names (AGENT_REGISTRY, AGENT_STARTUP) and purge requirement	Section 1.2	Verify table names in current MREF database schema documentation
CR spec field paths (spec.db., spec.env.size, spec.jvm., spec.storage.*)	Section 4	Check current FacilitiesWorkspace CR documentation for field names
Property mapping table entries (operator-managed vs retained distinction)	Section 3	Verify 5 critical properties against current MREF documentation
Pod sizing defaults (memory request and limit values)	Section 4.4	Check current deployment size scenarios page for updated defaults
BYOD supported database versions and drivers	Section 2	Check current IBM Supported Software page

Chapter 5: Custom Code and Integration Adaptation

Claim to Verify	Where in Guide	How to Verify
ClassLoader record UI path (Tools > System Setup > System > Class Loader)	Section 1.1	Navigate to path in current MREF to confirm it exists
Customization Archive ZIP structure (/SMP/maximo/ layout)	Section 1.2	Check current IBM documentation on archive format requirements
FacilitiesWorkspace CR for archive configuration (vs ManageWorkspace)	Section 1.2	Check current CR documentation for the correct resource name Needs Validation (no public citation located)
WF_INSTANCE_SAVE hard limit (1,000 instances per day)	Section 3	Check current performance documentation for limit changes
SMTP NodePort requirement for reservesmtpagent	Section 3.4	Verify SMTP configuration requirements in current MREF

Warning

Do not skip this verification step. MREF is evolving rapidly. A claim that was Verified when this guide was written may have changed in a newer release. The 15 minutes spent on verification prevents hours of debugging during migration.

Key Takeaway

Chapter 6 completes the migration guide with executable testing, cutover, and quality scaffolding. The three-pass approach (test migration, dress rehearsal, production cutover) is your engagement timeline. The phase-by-phase checklists synthesize Chapters 1-5 into a single migration sequence. The gate-based cutover runbook provides go/no-go decision points with rollback procedures at each stage. Before each engagement, run through the verification checklist (Section 5.5) to confirm guide claims against your target MREF version.

Sources¶

IBM internal migration deck (PDF) ↩↩
IBM TAP Application Upgrade User Guide; IBM Docs: Merge objects; IBM TAP Object Migration User Guide; IBM Docs: Upgrade Process; IBM Docs: UX in Object Migration tool ↩
IBM TRIRIGA Connector User Guide (PDF) ↩
IBM TAP OSLC documentation ↩
IBM Docs: TRIRIGA tuning; IBM TAP Readme ↩
Red Hat: Advanced migration options; IBM MREF vs TAS architecture comparison (PDF) ↩
IBM Docs: Basic configuration ↩
IBM Docs: TRIRIGA tuning; IBM TAP Readme; IBM Docs: System properties; IBM Docs: TRIRIGAWEB.properties ↩
IBM UMT video walkthrough; IBM internal migration deck (PDF) ↩
IBM Docs: TRIRIGA tuning; IBM Docs: System properties ↩↩
IBM TAP Readme ↩