Over the years I have been working with Documentum, I participated in many migrations and/or upgrades. Just like everything else, this obviously builds up some experience but what if you are pretty new to Documentum and it is your first time working on one? Sure, there is the Documentation from OpenText, which is several dozens of pages (~140, depending on versions) of intense fun so prepare a lot of coffee, you will definitively need some. Except for the documentation, there isn’t much information available so I was thinking about writing a rather short blog to list some key things to absolutely look at if you don’t want to lose all your work or worse. This is obviously not going to be an exhaustive list, it’s not really possible, else it would be in the documentation directly.
The definition of a migration and an upgrade can be found on the documentation. If these two keywords aren’t clear to you, you should definitively go take a look because it can be very confusing, especially some elements of the definition from OpenText. Alright so here are a few key takeaways:
- Read the documentation. Yeah, I know it’s annoying and you will have to excuse me but I had to. There is a lot of crucial information in the documentation, so you don’t really have the choice. This will really help.
- Look at the supported versions early (clients included!). A migration or an upgrade, for Documentum, is a rather complex project and the process that you will need to apply to attain your goal will heavily depend on supported versions. The result will obviously always be the same (the repository is migrated/upgraded) but the path to reach it can be very different. It’s not so easy to define the correct & supported path because there are many possibilities and many things to take into consideration. In addition, there might also be version specific requirements. For example if you are planning to upgrade a Content Server to 16.7 or above, then all DFC Clients (xPlore, DA, D2, …) will also need to be 16.7 or above so this needs to come into the picture.
- Think about the data availability. In the migration/upgrade process, you could opt to keep the source system intact and perform the upgrade on a staging environment before moving to the target system: for example to move from a VM to Docker/Kubernetes. Technically, you don’t need the data on the staging to do an in-place upgrade of the repository, all you need is the Database (export the DB from the source and import it into the DB of the staging). However, performing the in-place upgrade on the staging will create some objects in the repository and these objects will therefore have their data created on the staging data folder. Therefore, if the target system isn’t the staging one, you will then be missing some data because it stayed in the staging while the data that you have on the target is the data from the source (or a copy of the data from the source). If you are following me, you can obviously just perform an additional copy of the staging upgraded data (it’s mainly jar, txt and xml files created by DARs installation), that’s simple because you can easily find which data were created by the upgrade. The purpose of the staging is usually to have the binaries for the upgrade so the initial data will be almost empty, most probably still using the folder “content_storage_01/<hexa_id>/80/00/0x” with x usually equal to 3/4/5. While the data created by the upgrade process will have a much higher id (the next available id, based on the source DB) like “content_storage_01/<hexa_id>/80/8d/6x” for example. I didn’t test it so that might just be a wild guess but maybe re-installing the DARs would have the same effect? That would be something to test…
- Think about encryptions. Whether you are using an AEK key or a Lockbox, you will need to take care about the repository encryption (same for data encryption if you have a TCS license). The simpler is usually to copy the original AEK/Lockbox with its associated repository(ies). However, you might not have this luxury, especially if the source is an old version (AEK needs to be upgraded?).
- Think about passwords (can also be seen as related to the point about encryption). You can change all passwords if you want between the source and the target but that will obviously add an overhead. It’s usually simpler to change passwords (if required) once the migration/upgrade is completed but for that, you will probably want to first copy the AEK/Lockbox. That reminds me of blogs I wrote several years ago about password changes on various Documentum components/layers, like for the Lockbox.
- Think about the Global Registry Repository. In case of migration, the GR doesn’t really need to be migrated, that is only if the Repository that you want to migrate isn’t the GR, obviously ;). However, there might be some data specific for the normal Repository inside the GR, like D2 Keystore information (D2 4.7+) for example. It’s usually faster to just recreate the needed objects/configurations on the target system, compared to the need to duplicate all efforts to migrate another repo (the GR).
- Use the same docbase id. This might sound silly but I prefer to say it, to be sure. If your process involves a different target system, then you will need to install an empty repository on it. It’s not strictly mandatory to use the same docbase id because you can always manually create the needed folder structure on the target system (log folders, data folders, aso…) as well as the needed files (server.ini, dbpasswd.txt, start/stop scripts, ServerApps/ACS config for the repository, aso…). However, doing this manually would take a lot of time to make sure nothing is forgotten while creating the repository, in silent at least, just needs one command to be executed and that’s it. Since you are going to create a repository anyway, you might as well just use directly the correct docbase id from the source. Starting with the CS 7.3, if you want to change the docbase id of a Repository, that’s possible. You don’t have to remove it completely, you can just use the “MigrationUtil” utility (See this blog for an example).
- Make sure there are no locked objects. As far as I remember, the documentation only specify that the dm_server_config objects must not be locked. In reality, you must really check all dm_sysobject. It’s not a problem if some user’s documents are locked since the migration/upgrade process will not update them but Documentum OOTB objects shouldn’t otherwise some steps might fail, even sometimes silently which is then pretty hard to detect. I’m saying this for the dm_ objects but it also applies to other types of objects. For example, if you have a d2_dictionary_archive object locked, then running a D2 Config Import will fail and this is just one of many many cases so better be safe than sorry.
- Look for version specific steps. I already gave an example above about the CS 16.7+ that needs all DFC clients to be 16.7+ as well but there are other things. For example, if you are trying to upgrade to 16.7+ and if you are using a Lockbox, you will first need to extract the AEK Key from the Lockbox since it has been deprecated (See this blog for guidance).
- Verify the components and the logs after. That’s another point that sounds silly but it’s so important… Documentum is a very complex software and there are so many things happening. I have seen so many times things that apparently went well (even according to the main logs) and when you actually start digging into it (looking into Repository objects, looking into sub-logs generated by sub-methods and such), you start seeing a whole new world. Some examples:
- DARs missing or not installed at all (don’t forget the preserve_existing_types=F during upgrades)
- Duplicate ACS & JMS objects
- Lockbox not upgraded (corrupt) (new parameter in 16.4 binaries upgrade)
- Wrong target_server for the dm_DataDictionaryPublisher job
- Locked Castor objects due to bug in EBS (introduced in previous patch)
- JMS or ACS URLs reset to http://localhost
- JMS that lose its HTTPS configuration
- Stay patient and open-minded. Don’t worry, the migration/upgrade will probably fail but that’s OK, you are here to fix it ;).
These are just some key points I like to keep in mind. If there are some you would like to share, feel free and I can also add them to the list.