I have now worked on many migrations from 7.6 to MAS. It has been a nice change of pace from the same old 7.6 patch. However, as part of moving to MAS, we also move where the file storage lives for DOCLINKS. You can now use Persistent Volume Claims (PVCs) or S3. We now host DOCLINKS using S3. Moving to S3 means we have to modify DOCLINKS. In doing this, I have learned a lot about modifying DOCLINKS and how to do it safely, without breaking all your stored attachments.
‍

Before getting into explaining the process of best practices. I want to be sure you know the important pieces that control DOCLINKS. The core tables are DOCINFO and DOCLINKS. You also need to understand that the physical attachment lives in the PVC, or the S3 bucket and not in the database itself.

DOCINFO

This stores the attachment metadata. Key columns:

• DOCINFOID
  
  • Unique ID
  • Relationship to DOCLINKS
• URLNAME
  
  • Actual file path
• URLTYPE
  
  • FILE or URL
• DOCTYPE
  
  • Attachment, Image, etc.
  • S3 - This is a metadata tag with no impact on where files are stored currently.
  • Folder: This can be used as a child folder (or separate folder structure) and separates the attachments.

DOCLINKS

This links the document to a Manage record. Key columns:

• OWNERTABLE
  
  • Shows which Object the DOCLINKS lives on
  • Example: workorder
• OWNERID
  
  • Unique ID for the column of the table
  • Used to find which record the DOCLINK is on; used in relationships to join the table with attachments
• DOCINFOID
  
  • Relationship to DOCINFO

Best Practices

System Backup

Any time you are going to make a change to DOCLINKS, DOCINFO, or honestly anything related to data, do a backup of your system. Do the changes in a non-prod environment first. You can also run SQL to create a DOCINFO table backup so you don’t lose it and drop the table once you are done to easily revert the DOCINFO table.

SQL

SELECT * INTO DOCINFO_BACKUP FROM DOCINFO;
DROP TABLE DOCINFO_BACKUP;

DB2

CREATE TABLE DOCINFO_BACKUP AS (SELECT * FROM DOCINFO) WITH DATA; 
DROP TABLE DOCINFO_BACKUP; 

Oracle

CREATE TABLE DOCINFO_BACKUP AS SELECT * FROM DOCINFO; 
DROP TABLE DOCINFO_BACKUP; 

Start with One Attachment

Narrow down any changes you make to one file first. You may have many different URLNAMEs that need updated. If you try to do them all at once, you may mess up all URLs. Take your time and investigate what is needed to change first.
‍

NOTE: the only updates we will need to do are to the DOCINFO table and not the DOCLINK table. You should not need to update DOCLINKS through this whole process.

URLTYPEs of FILE

I only focus my energy on URLTYPEs of FILE. These are the documents that are stored within the attachment storage you are using.

Blanket Change

Often you’ll want to do a blanket change like below; it’s close to a good change, but missing some information:
‍

UPDATE DOCINFO SET URLNAME = REPLACE(URLNAME,'\\OLD','\\NEW')

This is a mistake that could lead to multiple issues:

• Case sensitivity could be off
• You could update all of your records
• You could make it an invalid UNC path

DOCLINKS Pattern

Find a pattern for your DOCLINKS and use it to create a update statement. You can start with SQL like:
‍

SELECT URLNAME FROM DOCINFO WHERE URLTYPE = 'FILE' 

If all DOCLINKS have a similar Path like \\server\DOCLINKS\ you can create a blanket statement. However, I still recommend testing just one document using something like this:

‍

UPDATE DOCINFO SET URLNAME = 
REPLACE(URLNAME,'\\OLD_SERVER\DOCLINKS','\\NEW_SERVER\DOCLINKS') 
WHERE URLNAME = '\\OLD_SERVER\DOCLINKS\[TEST.TXT]' AND URLTYPE=’FILE’

Verification

Verify the one attachment you change works in the front-end UI.

Controlled Replace

Using a controlled Replace allows you to be sure you only update DOCLINKS that match what you want to replace:

‍

UPDATE DOCINFO SET URLNAME = 
REPLACE(URLNAME,'\\OLD_SERVER\DOCLINKS','\\NEW_SERVER\DOCLINKS') 
WHERE URLNAME LIKE '\\OLD_SERVER\DOCLINKS%' AND URLTYPE=’FILE’

Repeat

Do this for all unique URLNAMEs you need to until all your DOCINFO records point to your new file storage.

‍

Not all DOCINFO issues necessarily need an update like this to the URLNAME. However, changing file storage solutions will require these URL changes. They also will require some updates to a few configurations in System Properties. You may need to update the following properties:

• mxe.DOCLINK.doctypes.defpath

• mxe.DOCLINK.doctypes.topLevelPaths

• mxe.DOCLINK.path01

• mxe.attachmentstorage

• mxe.DOCLINK.securedAttachment

‍

If you are using S3, you will also need to give Manage access to the bucket by updating these system properties:

• mxe.cosendpointuri

• mxe.cosaccesskey

• mxe.cossecretkey

• mxe.cosbucketname

‍

Finally, you will want to review your doctypes. After making all these changes, the DOCTYPES table will still reference your old storage system. You will want to update that to your new storage system:

‍

UPDATE doctypes SET defaultfilepath = ‘[NEW Default Path]’

‍

The most common cause of broken attachments in Maximo environments isn't corruption; it's well-intentioned administrators updating DOCLINK paths without understanding how DOCINFO and DOCLINKS interact.
‍

Current clients: when upgrading to MAS, this is handled for you as part of the upgrade. If you are thinking of joining Naviam’s cloud, we handle these changes for you as part of the implementation. You won’t even have to worry about this for your system.