Maximo’s attachment architecture has evolved significantly in MAS, and S3‑compatible object storage is now the recommended pattern for storing attached documents. This article walks through the key concepts, required system properties, setup steps, and migration considerations when moving from traditional NFS/file‑based storage to S3.
Why Use S3 for Attachments?
S3‑style object storage offers several advantages over local NFS or file‑system‑based attachment storage:
Scalability: You can grow storage without worrying about local disk limits.
Cost‑effectiveness: Pay‑as‑you‑go models reduce upfront hardware costs.
Resilience and availability: Cloud‑provider S3 or self‑hosted MinIO can provide redundancy and high availability.
Simpler MAS upgrades: Using S3 from the start reduces post‑upgrade storage‑migration work.
In MAS, attachments are stored in an S3 bucket via the COSAttachmentStorage provider, which is also used in Maximo Manage 7.6.1.1+ and MAS‑based deployments.
Core S3 System Properties in Maximo / MAS
To route attachments to S3, you must configure a small set of system properties in the System Properties application.
After setting these, restart the Server(s) so Maximo starts writing new attachments directly to S3.
Setting Up S3 / IBM Cloud Object Storage
For IBM Cloud Object Storage (COS), the typical flow is:
In IBM Cloud, create an Object Storage resource (Standard plan).
Create a bucket with a unique name, region, and storage class (e.g., Smart Tier).
Generate Service Credentials with role
Writerand enable HMAC credentials.From the COS UI, obtain:
access_key_idandsecret_access_key(HMAC).The regional endpoint URI (public HTTPS URL).
You can reuse the same COS instance across multiple MAS/Maximo environments by creating separate buckets per environment (DEV/QA/PROD).
The same pattern applies to Amazon S3 or MinIO‑compatible S3‑style storage; you just plug in the corresponding access key, secret, endpoint, and bucket name.
Migrating from NFS/File‑Based Storage to S3
If you are upgrading from an on‑prem EAM instance using NFS‑based attachments, you must migrate existing files to S3 and update Maximo’s pointers.
Step 1: Prepare the S3 bucket
Create a bucket (e.g.,
maximo-doclinks) in your S3 provider.Ensure Maximo’s S3 credentials have write access to that bucket.
Step 2: Copy files from NFS to S3
On a machine that can access the NFS mount (or directly on the Maximo app server), use the AWS CLI or similar tool:
bashaws configure # Enter accessKey and secretKey when prompted aws s3 cp /nfs_path s3://maximo-doclinks/ \ --endpoint-url http://<minio-host>:9000 \ --recursive
For MinIO or other S3‑compatible endpoints, include --endpoint-url. You can also use aws s3 sync or tools like rclone for incremental or large‑scale migrations.
Step 3: Update MAXIMO.DOCINFO URLs
Once files are in S3, you must change the URL prefix in the MAXIMO.DOCINFO table so Maximo points to the S3‑hosted files instead of the old NFS path.
A typical pattern is to update the URLNAME field from something like:
sqlUPDATE MAXIMO.DOCINFO SET URLNAME = REPLACE(URLNAME, '/nfs_path/', 'cos:DOCLINKS/') WHERE URLNAME LIKE '/nfs_path/%';
Exact SQL depends on your schema and current URL pattern; always test in a non‑production environment first.
Important S3‑Attachment Gotchas
No subdirectories in S3 for new uploads: Maximo’s S3 implementation expects all attachment files at the root of the bucket; subfolders are ignored for new uploads.
Folder structure in Manage is cosmetic: Manage’s “Folders” UI does not map to physical S3 folders; the system still looks for files at the top level.
Migration tooling in MAS: Maximo Manage ships with a
file2s3.shutility that can help convert file‑based attachments to S3, especially useful during MAS upgrades.
