Documentum Exporter Version 2.X

1 Requirements

This section provides information about usage requirements for running the Exporter Tool.

1.1 Compatibility

The Exporter Tool supports the following Documentum environments as source System. If you need support for an earlier version of Documentum prior to version 5.3 please contact your Gimmal support contact.

Supported Server Versions:

• Documentum 5.3+

• Documentum 6.0

• Documentum 6.5

• Documentum 6.7

• Documentum 7.0

• Documentum 7.1

• Documentum 7.2

• Documentum 7.3

• Documentum 16.X

1.2 Client Software Prerequisites

Prerequisites for the Client/Host PC must be satisfied:

• Windows 10 or equivalent OS.

• Admin access to install the application.

Client PC or VM minimum specification:

1.3 Documentum Pre-requisites

Please ensure the following is available:

• DFC is configured and available for use on the Documentum Environment.

  • DFC port is not blocked.

  • Identify the server port # that is being used.

• Documentum Service account with adequate access to source Docbase and Cabinets is required

  • As a best practice to ensure no content is missed – use of a Documentum Superuser account is recommended where possible.

  • User account should have admin or superuser privileges.

  • User account must be a member of Local Users and Groups in Documentum server.

2 Overview and Optimizations

2.1 About

This quick start user guide is intended to provide a quick reference for Users/Administrators.

Gimmal - has provided created this tool as standalone executable exporter tool to allow a correctly permissioned user the ability to access a Documentum environment and extract information to network drives.

The exporter tool specifically performs read only exporting of documents and metadata from Documentum.
Document and metadata from Documentum are not modified in any way with the sole exception of document export operations would be reflected in the respective Livelink audit trail for a document.

The exports from Documentum will allow an organization to extract documents and metadata from Documetum for multiple purposes including:

• Further manipulation and loading to other destination locations

• Long term archival

• Removal of documents from Documentum and storage on network drives (allowing use of a search mechanism to index metadata for searching)

Functions of the Exporter Tool:

Document Export:

• Allow selection of parent folder to export - extract from Documentum (can be from a specific Docbase / repository, or specific Object IDs)

• Specify the export destination network or local file share location

• Document and document name

• Base Documentum metadata / properties

  • Version Object ID

  • Description

  • Created Date

  • Created By

  • Owned By

  • Folder path

  • Version #

  • Chronicle ID

• Document Type properties

  • For each property

    • The attribute name and corresponding attribute value (dependent on data type)

• Produce a master CSV file with a row for each document describing:

  • Documents, versions, folders

  • Base metadata and document type metadata

  • Created and Modified Dates and Users

• Option to export just the master metadata CSV and not the documents

2.2 Overview of Use

The Documentum Exporter Tool

• Is intended to be run on a Client / Host PC

• Requires login credentials to access the source Documentum System

• Follows the default behaviour of DFC (api) access to Documentum

• Provides one way read-only communication with Documentum – only extract, no modification to source documents or metadata

• Requires adequate permissions for user or use of a Documentum service account with full access rights (recommend superuser or admin equivalent)

• Option to not replicate Documentum folder structure on the shared drive to prevent running into folder length name and windows 256 character path limits

• Exports output to network shared drive with adequate capacity

Please note if the Documentum environment is down or unavailable during an export, errors will be reported and export restart required. This tool is not responsible for managing or preventing such outages.
You should aim to have enough disk space on the destination drive for the size of your exports. If you do not have enough disk space your migration will not complete as expected.

Corrupt or zero-byte files are usually prevented from being added to Documentum, but there are unforeseen circumstances where a document is added to Documentum that is corrupted due to some factor. Please note if there are corrupt files in your Documentum environment - attempting to export a corrupted file is unsupported at this time. If you encounter corrupted files in your Documentum environment, you should delete these before running the Exporter Tool.

2.3 Performance Optimization Considerations and Tips

Speed and performance of the Exporter Tool is dependent on many factors.
Gimmal - does not warrant or guarantee the performance of the Exporter Tool in any way.
We outline some tips and considerations for optimization of performance below.

The implementation of optimization considerations and tips is out of scope for this tool and document.

The performance of the exports depends on many factors such as:

• Network latency

• Server location impacts

• Documentum Server configuration and hardware available (load balancing etc)

• DFC configuration or file store speeds

• Local IT environment and architecture

• Dependent on how much metadata exists to be exported from Documentum

  • Factors such as versioning (how many versions for a document on average)

  • Size of documents

  • Amount of metadata attribute fields

• Size and speed of destination location/drive

• Network traffic and relation to time of day the exports are run

• Memory available on client/host machine (where you are running the Exporter Tool)

We recommend that you work with your local IT to review the considerations outlined above and to ensure performance optimizations are realized.

Performance Tip 1:

Running the tool in the same network and ensure minimal network latency for fastest migration/export speeds.

Performance Tip 2:

Another technique would be to split the document loads into smaller chunks and run on multiple clients to achieve parallel exporting. You would need to ensure the exports do not overlap both from the source data and destination location.

In this case the limiting factor would be the Documentum servers’ capability to handle the additional load, as well as destination network drive speed and capacity considerations.

Performance Tip 3:

Please ensure the client/host has adequate amount of RAM memory (minimum 8 GB).

Performance Tip 4:

If possible, having a Documentum environment that is performant or load balanced from which you are exporting from. If the environment is unhealthy or unstable this will directly impact the tools ability to extract content from the source system.

Performance Tip 5:

When exporting Link Folders or Link Documents you may wish to ensure that you select the option – “Export Only from Selected Node”. When this option is chosen the Link Folder or Link Document will only be exported as part of the current Selected Node structure (hierarchical or flat). If you choose “Export from All Locations” the tool will export all occurrences of the Link Items from all locations that it occurs, this could result in a big performance hit since you are retrieving all such instances.

Performance best practice:

When exporting items for archive or migration into another system we recommend that you try to keep a single export / migration job to under 90,000 objects. This ensures that you balance migration speeds against the case that there is an error and you need to re-migrate or address an issue. If you conduct an export that is larger than say 100,000 objects – it will begin taking a long time as well as harder to address any potential migration related errors or issues.

As such we recommend the maximum export size to be kept under 90,000 objects where possible. Based on experience 50,000 is a good objects is a good limit for best practices, and maximum of 90,000 objects. You can go higher than 90,000 objects but it becomes difficult to address or remediate any issues.

3 Using the Documentum Exporter Tool

3.1 Installation

The Gimmal Documentum Exporter Tool has all the libraries required for Documentum connectivity embedded in the installer, so all that is required is to run the DMInstaller.msi file

Accept the End-User License Agreement and click Next (If you decline the license terms, you cannot proceed with the installation)

Choose the Setup Type (we recommend you choose “Complete”) and Install

To finish the installation after completion and exit the install wizard, click Finish.
If you wish to launch the application upon exit, click on the Launch Documentum Bulk Exporter checkbox.

Note: The Documentum Exporter when installed will be pre-configured to access Documentum from within the tool itself. In the case that you intend to access Documentum from your web browser on your Client PC / VM that you installed the Documentum Exporter on – you may need to work with your IT Administrator to configure your PC to work with Documentum. This may require configuration of Java Run Time environment to browse and access content in Documentum from your web browser. This is out of scope for this document since it is specific to your version of Documentum, web browser and Windows build.

3.2 Activation

Please note a valid activation code is required on first use of the Documentum Exporter Tool, required for very Client PC that it is run on.

Upon purchase of the tools, you would have been provided details on how to obtain the necessary activation codes for your requisite Client PC use.

When first running the Migration Tool you will be required to specify a unique license key to register the product for use. You can enter the provided License Key in the “About” tab and by clicking the “Register” button. The registration will occur one time and will activate the software for use, no further activation will be required.

If you require assistance or would like to obtain additional activation codes for additional Client PC use within your environment, please contact your Gimmal support contact.

If your organization is behind a firewall or proxy and cannot validate your license across the internet – please contact your Gimmal support contact to obtain a firewall/proxy key. Once you have the proxy key you can register your software using the steps below.

• Browse to: InstallDrive:\Program Files (x86)\Gimmal\Documentum Bulk Exporter\config.

• Edit appsettings.properties.

• Add separate line at the end of the file for overrideKey=PROVIDED_PROXY_KEY.

• Save the appsettings.properties and close the file.

• Close and reopen the Documentum Exporter – it should now automatically use the proxy key and no longer prompt for a valid license key for registration.

3.3 Credentials and Login

The user must provide the source Documentum System login credentials as displayed in the screenshot below.

• You will be prompted to specify the:

• User ID and Password

  • Credentials for your Documentum user or service account

• Docbase name

  • The Documentum repository name

• Server Name or IP Address

  • Referencing your Documentum Server environment

• Server Port

  • Default DFC server port (usually 1489)

Note: Requires adequate permissions for user or use of a Documentum service account with full access rights (recommend superuser or admin equivalent)

The user id and password provided must be in the context of the source Documentum System you have specified.

Please click “Test Connection” to verify that you have specified valid credentials and a valid connection to your Documentum environment. If you are unable to connect please work with your Document system administrator to ensure you have the proper settings and Documentum is configured as per the prerequisites of use. Clicking “Save” will save your login values for future use.

3.4 Running an Export

The Documentum Export Settings tab allows the User to export Document and metadata from Documentum source system to the destination export location (local or network drive).

3.4.1 Choose Source

Select Source Items for Export from one of the options below:

• From the Documentum Content Server Repository (Docbase) tree view - browse to the cabinet or folder area for the content to be exported.

  • You may select any number of folders to be exported – please use caution to ensure that you select folders that occur at the same level

  • When you select a folder – the selected folder and its children will be included in the export, you do not need to enable its children for exporting

  • Likewise, if you select the child folders you do not need to select the parent folder

• Use Text File of Object IDs - provide a preprepared list of Documentum Object ID’s to be exported.

  • Each Object ID should be separated by a new line and in a text readable format

  • The Object IDs will be taken for processing in the sequence provided

  • You can specify Object ID of folders but if you do so you would have to enable the option to Export Contents of Containers.

  • If you specify versions, the corresponding versions will be in scope for the export

  • NOTE: there should be no spaces before or after the list of IDs (if there are extra spaces it will cause problems with the reading of the list)

As a Recommendation – splitting out areas to be exported is recommended: as doing so will minimize potential for error conditions and allows for parallel processing and generally makes migrations / exports more manageable as they are in smaller chunks.

3.4.2 Links

Links – Documents and Folders

Link Folders

A Documentum folder can be in more than one location, but destinations such as SharePoint do not support this behavior. Select the option of exporting the link folder from the selected node only or from all locations to which the folder is linked to (in the latter case, the folder, and the items underneath it will be duplicated in each location in which the folder appears).

Link Documents

An item or an object other than a folder can be in more than one folder. Again, such behavior is not supported in destinations such as SharePoint. The selection chosen (Links – Documents and Folders) will export the file either from the selected node or from all locations (the item will be duplicated in each location in which it appears).

If a hierarchical structure is chosen for export, the links will be exported along with their folder structure so items may appear multiple times in different locations within the same export.

If a flat export is selected, items will only be exported once in a flat structure directly under the ‘Export’ folder, but the metadata will preserve their locations from Documentum so when items are migrated to SharePoint, that folder structure can be rebuilt based on the information from the Metadata.csv file.

The recommended setting for exporting Link Folders or Link Documents is to choose option to “Export Only from Selected Node”. We recommend using this setting to avoid duplication of exporting Link Folders and Link Documents. In this case the Link Items will be created in the current structure only and will not be exported from all Link locations. If you choose Export from All Locations this will export the Link Item from all of the original locations that it is found in. The Link could be existing in many locations so use care when using this option. If you choose to Export from All Locations this will also have an impact on performance depending on how and where the Link Folders or Link Documents exist and frequency.

Export Only from Selected Node option

• All the Link folders are exported with their content within the selected node

• The documents/files that just have their CURRENT version linked will be exported as such (individual items/documents that represent the current version of that document)

• The link versions of documents that do not have the CURRENT version linked along with them in the new location but have the same mime-type as their CURRENT version will be exported together with their CURRENT version (same mime-type) from the original location (this is important for the migration to SharePoint where a current version is needed to migrate the associated versions as well.)

• The link versions of documents that do not have the CURRENT version linked along with them in the new location but have a DIFFERENT mime-type than their CURRENT version are exported with their MOST RECENT VERSION OF THE SAME MIME-TYPE from the original location even if that MOST RECENT VERSION OF THE SAME MIME-TPYE is not linked together with the said version.

Export from All Locations option

• All the Link folders will be exported with their content within the selected node AND within ALL the other folders or cabinets that contain those link folders.

• The link CURRENT documents will be exported as such in all locations with the paths of their linking.

• The original documents (these are not link documents even if they are inside a link folder) are exported as such onto all locations (paths) of their linking.

• The link versions of documents that do not have the CURRENT version linked along with them in the new location but have the same mime-type as their CURRENT version will be exported/saved together with their CURRENT version (same mime-type) from the original location. In the hierarchical structure, the export locations of the CURRENT version that has not been linked together with the non-current version will be the same containers/folders that contain the (linked) non-current version.

• The link versions of documents that do not have the CURRENT version linked along with them in the new location but have a DIFFERENT mime-type than their CURRENT version are exported with their MOST RECENT VERSION OF THE SAME MIME-TYPE from the original location even if that MOST RECENT VERSION OF THE SAME MIME-TYPE is not linked together with the said version. The export locations of these MOST RECENT VERSION of the same mime-type as the versions with mixed mime-types that were linked will be the same containers that contain the non-current mixed-version.

• If in any of the two scenarios above the (CURRENT versions, OR MOST RECENT versions in the latter case) were also linked along with the linked versions, then those locations will already have the right CURRENT versions for export which should meet the requirements of always having a current version (or most-recent) associated with a non-current (or mixed mime-type respectively) version.

Choose Export Type

• Ignore the source folder structure and export as a flat structure (recommended).

  • You would want to use this option if your Content Server structure was deep (paths longer than 255 characters) OR

• Preserve the source hierarchical folder structure

  • Please be advised that there is a Windows 255-character NTFS path restriction.

  • If this option is chosen and a document or folder exceeds the path limitation the object will be logged as an error and the tool will try the next object for export. If it is a folder the contents of the folder will also be skipped.

  • We recommend in most cases to use the flat structure option as the path metadata is preserved in the CSV control file. If choosing hierarchical export most use cases would run into the 255 character NTFS limitation. This option would only be recommended in the cases that the location can be verified that the path limit will not be exceeded.

• You may also wish to choose whether to export to timestamped folder

  • If enabled will create a unique timestamped folder for every export operation

  • If disabled will export documents to the same folder, if duplicates are found they will be skipped

  • We recommend in majority of cases to use timestamped folders to ensure your exports are uniquely identified

Browse to the destination export location – this can be a local, network drive, or OneDrive

• The export location will have an impact on performance due to size and latency considerations

• Please ensure adequate space is available on the destination export location to handle the size of the export

Specify Exported Document Name

• Choose naming of documents

  • Name Document as Object ID (the unique Object ID from the Documentum source system)

  • Name Document as Document Name (the document name/title from the Documentum source system)

    • If you choose this setting and you happen to have collision in the document names across multiple source folders to the single destination folder – the document will be overwritten and replaced by the latest document. Please ensure you take this into account if you enable this option.

  • Name Document as Object ID - Doc Name

    • This option is desired if you are doing a flat export, this ensures that you will never have collision on the document names since the unique Object ID is appended to the front of the document name.

• Note: The original Content Server file name is always preserved as metadata and can be rehydrated as required from your metadata.csv or xml files

Setting for Character Replacement

• Documentum supports many characters that are invalid on a network file share. This setting allows one to replace invalid characters with valid characters in the exported location when it is enabled

• By default, the main common replacement characters are already included in the Character Replacement list

• If you need to add additional character mappings you can add them from the install > config folder – by editing the CharacterReplacementMappings.xml file and adding the corresponding character replacement entry

Hex Code Replacement

• Documentum by default does not allow hex codes in document name or folder name. Sometimes customers have this in their environment due to legacy load processes or prior to upgrading to newer versions of Documentum.

• Documentum does not support the hex code characters and as such it can be a problem for exporting

• The Documentum Exporter will automatically strip out hex codes but maintains UTF8 language characters

Warning: Adding additional char or hex code replacements will have an impact on performance since it takes effort/cycles to do the replacement checks. We recommend only adding the necessary replacement entries to ensure optimal performance is achieved.

Upgrading: When uninstalling an old version of Documentum Exporter Tool then installing new version – if you have custom CharacterReplacementMappings.xml files for char or hex replacements you must copy those files out first - otherwise upon uninstall the files will be lost. Upon install of new version you can copy the corresponding CharacterReplacementMappings.xml files back to replace the default char files which preserves your custom replacement mappings.

Choose versions to export.

• Choose option to export All Document Versions, or just latest.

  • Please note: Choosing all versions has a performance impact since a Document could have many versions

  • Note: if you choose to export versions, you will have a row entry in your metadata.csv for every version of a document.

    • This will preserve the exact version numbers from Documentum as well as created by and modified by dates for those versions.

Versions with Mixed Extensions

• In Documentum Content Server there may be cases where a document / object has multiple mixed extensions

  • This is Content Server behaviour in that a single mime type extension is not enforced on a document

  • It may not be very common but you may encounter from time to time documents with versions that have mixed extension types

• If you try to keep version extensions as is – you will receive a warning during analysis and migration steps:

  • “Version mime type of '.xlsx' is different than that of the latest version's mime type of '.docx'.

• This will cause problems when importing into a new system like SharePoint

  • SharePoint does not allow versions with mixed extensions for the same document

• This feature allows migration analysts to choose what happens to documents with versions that have mixed extensions / mime types

Versions with Mixed Extensions - Recommendation

The recommended best practice is to use the setting “Do not keep versions with different extensions” where possible. This will ignore all versions with different extensions. This works well when the mixed extensions case is rare and you only care about the newest documents versions anyways - then this is the simplest approach. In the case that you are migrating to SharePoint and MUST preserve all versions only then should you use the setting “Split versions with different extensions to separate files”. This will guarantee that all document versions are exported for SharePoint use and will allow the versions with different extensions to be loaded as separate documents altogether since SharePoint does not support documents with mixed extensions/mimetypes.

Specify Export Metadata options for the content that will be exported.

• Choose option to enable export of metadata

  • If metadata is included they will be generated and stored in a master CSV file

    • Please note – including metadata has a performance impact depending on the amount and type of metadata

    • If choosing master CSV option – the master csv file – “metadata.csv” will be created at the root of the export area

  • If not enabled metadata file(s) are not generated

  • Option to export only metadata and suppress the download of content (folders and documents)

    • This option is useful for customers who wish to review the metadata only prior to exporting the content

    • If you enable this option – in the metadata.csv the source directory column will be invalid since we aren't exporting any of the files

• Please note: most customers will choose export as metadata.csv – since this provides the greatest flexibility in preserving a centralized manifest of all information about the exported content

• If you intend to migrate your content to SharePoint – you will need to ensure the metadata.csv option is chosen as that is used by Gimmal MAPIT for M365

Please note if you choose to export to a CSV master file all metadata will be included in a single file where each row in the file represents each document (related by local source path).

Note about zero-byte files and versions

The Documentum Exporter cannot export files that have no content through the API, so dummy/empty files will be created during the export with the same name and metadata as the original files that exist in the Documentum Content Server. That way, if a non-zero-byte version of a document has a link and the CURRENT version of that document has no content (zero bytes), both versions (CURRENT and link non-CURRENT) will be exported/saved into the proper location on the filesystem. (This is important for a proper migration of items to SharePoint).

Note about naming exported objects on export (Link Items)

When exporting links from All Locations or exporting from a list of IDs, the Document Naming Format option called “Name Document as Document Name” will be disabled to avoid duplicate names and avoid skipping files on export. The metadata.csv file will preserve the original file names that the migrated files to SharePoint will inherit.

Documentum Content Server as Source for SharePoint Destination – Version Notes

The Documentum Exporter will preserve all original Documentum version #’s including major, minor and branched versioning. If you are migrating to SharePoint Online with Gimmal Migrate’s MAPIT for M365 – the original version #’s from Documentum will automatically be preserved in the SharePoint version history comments along. For regular major and minor versioning – this will be reflected one-to-one in SharePoint with the same version #’s. In the case of branched versioning, as SharePoint does not handle branched versioning, the Documentum versioning will be made compatible with the SharePoint versioning. The original branched version # scheme will be shown in the SharePoint version history.

An example of how the Documentum version #’s would be translated to SharePoint automatically by Gimmal tools. The numbers in green represent the SharePoint version #’s and the item highlighted in green is the latest version in SharePoint.

Version Created By

Note: By default, when you using Gimmal Migration Tools to migrate to SharePoint – the original version created by comment will be preserved in SharePoint. Gimmal tools will automatically add the Created By comment into the SharePoint version history comments in case that the user is no longer in Active Directory or does not map to Active Directory.

3.4.3 Run Analyze

Perform Pre-Migration analysis, click “Analyze” button

• This step performs an analysis of your planned export identifying potential issues with your export

• The analyst can review the analysis log to determine if any actions are required to fix issues prior to performing the export

• Summarizes a list of object types that are not supported if discovered in the path

  • A log file is generated that summarizes the results of the analysis.

3.4.4 Run Export

Click “Export” button

• The export will start

  • If timestamp is enabled - a new folder is created in the export location named with a time stamp ex.) YYYY-MM-DD HH-MM-SS

  • The export outputs are contained here (Export1,…)

  • The status bar will indicate the # of item currently processed

  • When completed the status bar will indicate completion

• A log file is generated in the root folder (ExportLog.csv)

  • The log file contains a detailed logging of operations and logs successes or failures

  • The log file can be used as audit / proof of export as well as for validation purposes

• You may interrupt and cancel an export by clicking the “Cancel” button at any time

  • Please be aware if you click the Cancel button the operation is stopped and would need to be restarted -from the beginning