Development environments often become corrupted and unusable due to the heavy use they undergo as temporary and experimental spaces. Documentum offers housekeeping jobs within the Content Server that, when properly utilized, can prevent development environments from becoming dysfunctional. There are seven essential jobs every developer should know and run regularly in their development environments. These jobs help ensure that your development Docbases remain clean, efficient, and free of referential integrity issues. They also offer valuable insights into the content within the Docbase. This paper outlines these seven jobs, recommends schedules for their execution, and highlights the importance of their capabilities.
Introduction
If you’re like me, you can be pretty tough on your development environment. Whether it’s physical or virtual, it often takes a beating during development. It’s subjected to mass imports and deletions, abandoned workflows, altered and re-altered types and DocApps, failed logic, and unsuccessful rollbacks. Over time, these activities can lead to a messy, inconsistent, fragmented, slow, and sometimes dysfunctional Docbase.
Fortunately, there are simple steps you can take to keep your development environment healthy. One of the easiest is running the housekeeping jobs provided by Documentum. While many developers may view jobs as the responsibility of a Documentum administrator, in a development environment, that responsibility could easily fall on you. Even if it doesn’t, it never hurts to have a good understanding of basic housekeeping.
This paper introduces seven essential jobs that every developer should be familiar with and offers recommendations on how frequently they should be run. The seven jobs are:
There are two key reasons why it’s important not only to know about these jobs but also to understand how to configure and run them:
- Some of these jobs are not automatically configured to run in the out-of-the-box setup. By default, Documentum does not enable jobs that delete objects or require user-defined parameters.
- The jobs that are set to run automatically may do so at times when your development environment is offline, especially if you work in a virtual environment.
The remainder of this paper will cover these seven essential jobs, explaining what they do, how to run them, and why they are critical for your development environment.
About Jobs
Jobs are programs or scripts that run automatically on the Content Server without requiring any user intervention. These programs are typically diagnostic or housekeeping in nature. Jobs can perform a wide range of tasks, from reporting available disk space to synchronizing users and groups with an LDAP server, or from removing orphaned files to replicating content. In general, jobs are scheduled by specifying the desired day, time, and frequency (daily, weekly, monthly, etc.) using the Documentum Administrator (DA) client. A special process within the Content Server, called agent_exec, continually monitors the Docbase for jobs that are ready to execute based on their schedule.
Implementation
In the Content Server, jobs are implemented as two objects: the job (dm_job) and the job method (dm_method). The job object holds the scheduling information and job method parameters, while the method object contains the reference to the code that performs the job’s specific function.
Arguments
window_interval: The window_interval defines a time window (in minutes) on either side of a job’s scheduled execution time during which it can still run. If the Content Server is down at the scheduled time, the agent_exec will attempt to run the job when the Content Server restarts. If the current time falls within the window_interval, the job will execute; if not, it will be rescheduled for the next day, week, or month, depending on the schedule. This variable can be frustrating and confusing, as manually trying to run a job outside its window_interval will prevent it from running. Since we’re discussing a development environment where running jobs is more critical than performance, I recommend setting the window_interval to 1440 minutes (24 hours). This guarantees that the job will run regardless of the time the server is restarted.
Seven Jobs
The following sections introduce the seven essential jobs. Of these, four (DMClean, DMFilescan, Log Purge, and QueueMgmt) focus on deleting obsolete objects from the Docbase to maintain cleanliness. One job (Consistency Checker) runs integrity checks to ensure the Docbase remains referentially sound. Another (Update Stats) updates the statistics for each database table and repairs fragmented tables. The final job, State of the Docbase, generates a snapshot report that highlights the configuration and content of the Docbase.
- DMClean
The first job, DMClean (dm_DMClean), is the workhorse of housekeeping jobs. It searches for and deletes orphaned content objects (dm_sysobject), ACLs (dm_acl), annotations (dm_note), and SendToDistributionList workflow templates. Orphaned objects are those that are no longer referenced by or don’t reference any other objects in the Docbase, effectively cluttering the environment.
By default, the DMClean job is inactive and does not run automatically. In a development environment with a high degree of volatility, it’s crucial to run this job regularly to keep the Docbase clean and uncluttered. I recommend enabling the DMClean job and scheduling it to run weekly. In addition to tidying up the Docbase, running this job helps preserve disk space, which can be especially valuable in development or virtualized environments.
When the DMClean job runs, it generates an API script in the %DOCUMENTUM%/dba/log/<docbase ID>/sysadmin directory named after the job object ID, with a .bat extension. The script is then executed to delete the identified objects. This deletion not only removes content objects from the Docbase but also clears their associated content files from the file system. If preferred, the job can be configured to generate the script without executing it, giving you the option to review the changes before they are applied.
- DMFilescan
The DMFilescan job (dm_DMFilescan) scans the file stores for content files that have no associated objects in the Docbase, essentially orphaned files. Unlike DMClean, which targets orphaned objects, DMFilescan focuses on orphaned files, taking a different approach to achieve a similar outcome. When the DMFilescan job runs, it generates a script in the %DOCUMENTUM%/dba/log/<docbase ID>/sysadmin directory named after the job object ID. The script is then executed to delete the orphaned files. Like other jobs, it can be configured to generate the script without running it, if preferred.
By default, the DMFilescan job is inactive and does not run automatically. In a volatile development environment, it’s important to run this job to keep the file system clean and reclaim valuable space. However, if the DMClean job is run regularly, this job may not need to be run as often, since DMClean should keep most orphaned files in check. Given that development environments are often subject to frequent changes and uncertainty, I recommend enabling this job and scheduling it to run once a month.
3. Log Purge
The Log Purge job (dm_LogPurge) deletes system-generated log files from both the file system and the Docbase that are older than a user-specified age. It specifically removes the following eight types of log files:
By default, the Log Purge job is inactive and does not run automatically. In a development environment, log files can rapidly consume disk space, especially when running heavily instrumented code or traces for debugging. To help reclaim space, I recommend scheduling this job to run at least once a month.
4. Consistency Checker
The Consistency Checker job (dm_ConsistencyChecker) runs a series of 77 checks on the repository, looking for inconsistencies, corruptions, and data integrity issues. While the job does not fix the problems it detects, it generates a report that assigns a unique error number for each issue discovered. The report provides the error number, a brief description of the problem, and an indication of its severity (either Error or Warning).
The specific areas checked and the number of tests run include:
The Consistency Checker job is configured, out-of-the-box, to run automatically every night at 9:40 PM. This is beneficial, as long as your Content Server is up and running at that time. However, if your development environment is virtualized on your local workstation or laptop, and you turn off your computer at night, the Consistency Checker may never get a chance to run. In such cases, it’s important to adjust the execution time to a period when your system is active.
5. Update Statistics
The Update Statistics job (dm_UpdateStats) scans all the database tables used by the repository and updates their statistics. This process helps ensure that the query optimizer has accurate data to improve performance. Additionally, the job will reorganize tables to optimize performance if it detects fragmentation.
For those running Documentum on Oracle or Sybase, the Update Statistics job uses an external file to further fine-tune the query optimizer. This file is located at %DOCUMENTUM%/dba/config/<docbase name>/custom_<database name>_stat.sql. You can add additional commands to this file if you’re familiar with database optimization. However, if not done correctly, modifications can negatively impact query performance.
The Update Statistics job is configured, out-of-the-box, to run automatically once a week at 8:30 PM (originally). This is beneficial, as long as your Content Server is active when the job is scheduled. However, if your development environment is virtualized on your local workstation or laptop, and you turn your computer off at night, the Update Statistics job may never get a chance to run. Note that this job is both CPU- and disk-intensive, so it’s important to schedule it at a time when system resources are available.
Although the job is preconfigured to run, it is set to READ mode by default, which means it only generates a report without actually updating the statistics or reorganizing the tables. To fully benefit from this job, it should be run in FIX mode to perform the necessary updates and optimizations.
Outputs
The Update Statistics job generates a report detailing its activities, which is saved in the Docbase at /System/Sysadmin/Reports/UpdateStats. This report is versioned, allowing you to track and review changes over time.
6. Queue Management
The Queue Management job (dm_QueueMgt) deletes dequeued Inbox items (dmi_queue_item). When tasks in a user’s Inbox are forwarded, completed, or deleted, they are marked for deletion and dequeued. However, the underlying objects in the Docbase are not immediately removed. In a development environment, particularly where workflows and activities that generate Inbox items are frequently tested, the accumulation of undeleted objects can degrade performance.
The Queue Management job deletes queue items based on the age of the objects and a custom DQL predicate passed to it. The job automatically creates a base predicate of delete_flag = TRUE AND dequeued_date = value(<cutoff_days>), and any custom predicate is added to the base predicate using the AND condition.
By default, the Queue Management job is inactive and doesn’t run automatically. I recommend scheduling this job to run at least weekly, or even daily, depending on your application’s use of queue objects. Running this job regularly will help maintain Inbox performance.
7. State of the Docbase
The final job, State of the Docbase (dm_StateOfDocbase), generates a report covering ten key areas of a Docbase’s configuration and status. This report is invaluable for troubleshooting, preparing for migrations, or simply reviewing the overall state of the Docbase. The ten areas covered by the report include:
- Docbase configuration (from the
docbase configobject) - Server configuration (from the
server.inifile) - OS, RDBMS, and environment information
- Registered tables
- Types
- Formats
- Storage information
- Rendition information
- Users and groups
- ACLs
The State of the Docbase job is preconfigured to run automatically every night at 8:45 PM. This is beneficial, provided your Documentum Content Server is up and running at that time. However, if your development environment is virtualized on a local workstation or laptop, and you turn off your computer at night, this job may never get a chance to run. Be sure to adjust the execution time as needed to fit your environment’s schedule.
Conclusion
To recap, there are seven essential jobs that you, as a developer, should configure and run in your development environment. These jobs help maintain a lean and clean Docbase, while also alerting you to potential issues before they escalate.
Four of these jobs—DMClean, DMFilescan, LogPurge, and QueueMgt—focus on removing obsolete objects and keeping the Docbase tidy. The Consistency Checker runs a series of integrity checks to ensure your Docbase remains referentially sound. Finally, the State of the Docbase job generates a snapshot report, providing an overview of your Docbase’s configuration and content.