At 14:20 a technician finishes a statutory inspection on a pressure reducing station, photographs a corroded pipe support on the handset, attaches four images to the work order in IBM Maximo Mobile and closes the record. Eleven months later an inspector asks to see the photographs. The work order opens, the attachment rows are listed against it, and two of the four links fail to resolve. Nothing in the work management process went wrong. The two missing files were written to a pod filesystem path that no volume was mounted on, and the pod has since been replaced. Maximo attached documents behave exactly as the deployment configured them to, which is why the repository decision belongs in the architecture pack rather than in an administrator’s first week.
One attachment writes a record and a file, on separate lifecycles
An attachment in Maximo Manage produces two database rows and one binary object. The document record (DOCINFO) holds the pointer in URLNAME, the type in URLTYPE and the library folder in DOCTYPE. The link row (DOCLINKS) ties that document to its owner record, a work order or an asset, through OWNERTABLE and OWNERID. The file itself sits wherever URLNAME says: a mounted filesystem path, an S3-compatible bucket, or a Microsoft Azure blob container, all three of which IBM documents as supported storage for attached documents.
The consequence is a backup boundary. A nightly database dump captures every DOCINFO and DOCLINKS row and not one photograph. A restore therefore reinstates pointers, and the repository has to be recovered to the same point in time for those pointers to resolve. A recovery test that opens an attachment, rather than counting DOCINFO rows, is where an estate finds out whether its two backup schedules agree.
The repository is set at deployment, on the ManageWorkspace custom resource
For file-based storage on OpenShift, the persistent volume is declared in the deployment.persistentVolumes block of the ManageWorkspace custom resource: an accessModes value of ReadWriteMany, a mountPath such as /DOCLINKS, a lowercase RFC-1123 pvcName, a size and a storageClassName. ReadWriteMany is the load-bearing entry, because several server bundle pods read and write the same folders. The same claim can be entered from Manage Admin under Administration, Workspace, Manage, Update Configuration, which suits an estate whose platform team does not hand out cluster editor rights.
The object storage route replaces the mount with a bucket: mxe.attachmentstorage selects the handler, the mxe.cos properties carry bucket, endpoint and credentials, and the doclink paths take a cos: prefix. Maximo Manage ships a tool to convert file-based attachments to S3 attachments, which is one reason to settle the route before go-live rather than after it.
| Route | Platform team owns | Manage team owns | Where the decision bites later |
|---|---|---|---|
| Persistent volume | RWX storage class, PVC size, snapshot schedule | Mount path agreement, folder defaults | Growth: resizing a claim is a platform change request |
| Object storage (S3, COS, Azure blob) | Bucket, lifecycle rules, key rotation | Handler and path properties per environment | Credentials: a rotated key stops uploads estate-wide |
The doclink properties have to agree with the mount
Three properties decide where a new file lands: mxe.doclink.doctypes.defpath for the default folder, mxe.doclink.doctypes.topLevelPaths for the roots, and the mxe.doclink.path01 series for the folder mappings. When a PVC is in use, the Attachment Library folders (Attachments, Images, Diagrams) save under the mount path, so the properties and the mountPath value in the custom resource are one decision expressed twice. A property that names a directory inside the container rather than the mounted volume accepts uploads happily and loses them when the pod restarts, which is what happened at 14:20.
Two operating habits keep that alignment: the doclink properties are captured in the environment build record alongside the mount path, and every server bundle pod is restarted after the properties change, not only the pod an administrator happens to be attached to. Where an estate runs separate server bundles for UI, integration and cron workloads, the restart list is the full set.
Volume is governed at the handset
The volume question is settled by field behaviour long before it reaches a storage class. Take 40,000 work orders a year, three photographs each at 2 MB: roughly 240 GB a year of attachments, and both figures are illustrative rather than measured. IBM’s PVC example in the doclinks support guide uses 2Gi, an example value rather than a sizing recommendation, and an estate that copies it will be raising a resize request inside a month.
Three controls decide how much arrives. mxe.doclink.doctypes.allowedFileExtensions sets the accepted file types, and IBM’s documented default list already includes mp4, mov and wmv, so a 90-second video from a handset is admissible before anyone has discussed it. mxe.doclink.maxfilesize caps a single upload and is documented with a default of 10 MB. From Maximo Manage 9.2, IBM documents an image upload quality setting that compresses image attachments before they leave the device, with a technician override for full resolution when the defect genuinely needs it. Set the default compression on, name the roles allowed to override, and the volume curve flattens without anyone being told to take fewer photographs. This is a decision for whoever owns the Maximo Mobile rollout, because it changes what a technician sees at the point of capture.
Retention belongs to a records owner, by document type
No doclink property deletes a photograph. That makes DOCTYPE the retention instrument: a folder per evidence class, so a statutory inspection photograph carries the regulator’s retention period and a general job photograph carries a shorter one. Without that separation, retention has to be argued document by document across a library nobody has counted since go-live.
Each DOCTYPE carries a retention period and an owner on the records or compliance side, and deletion runs on that owner’s approval rather than on a system administrator’s judgement. Evidence attached to a statutory finding sits under the same discipline as the finding itself, which is why inspection findings belong on the asset record rather than in a shared drive.
Non-production environments inherit production pointers
A production database restored into test arrives with URLNAME values pointing at the production path or bucket. Test users then read production evidence, and a test upload can write into the production repository if the properties were never re-pointed. The control is a step in the environment refresh runbook: rewrite the doclink properties and the URLNAME prefix, use a separate bucket or claim per environment, and issue distinct credentials so a test handler cannot authenticate against production storage. The refresh is not finished until an attachment opened in test resolves to a test object.
What stays hard
Point-in-time alignment between a database backup and an object store under lifecycle rules stays a reconciliation problem, and somebody has to own the report that lists DOCINFO rows with no object behind them. Where files sit on the mounted volume, the Manage pods that serve interactive users also stream every attachment download, so a print-all-attachments habit at a busy site is a capacity conversation for whoever owns that bundle. Upgrades from Maximo 7.6.1 carry a third cost: files sitting on a traditional application server path have to be moved and every URLNAME rewritten, and the duration is set by volume rather than by logic.
The position
The attachment repository is estate architecture: one storage route chosen at deployment, doclink properties that match the mount, compression set at the handset, and a retention period per DOCTYPE with a named owner. Ask for those four at the design review, and ask the hosting team which backup restores the files rather than the pointers. Estates that leave Maximo attached documents at default values keep their inspection evidence somewhere nobody has agreed, and learn which files are missing when an inspector asks for them.