How to test BOF (TBO/SBO) code changes without re-deployment

Documentum Business Object Framework (BOF) version 2.0 implies deploying of all modules implementation into the repository, as jar artifacts. These jars are downloaded and cached on demand, when the corresponding module is being called.
The need of re-deployment of BOF modules (TBOs or SBOs) each time we make a change in the code might cause important delays in the development process: recompiling composer project, installing it, restarting JMS each time consumes a lot of time.
Is there a way to test the BOF code fast, without redeploying it? Yes, it is!
You can cheat the DFC client and replace the cached jars with a newer versions. Here's how you can do it.
After having called the BOF module (to ensure it's cached), go to the BOF cache folder: its location on the client machine can be specified in dfc.properties file, in the dfc.cache.dir property (default is cache subdirectory of dfc.data.dir). Inside you'll find a folder structure like this: [DFC_VERSION]/bof/[DOCBASE_NAME]. In the docbase folder you'll find more jars having the name [DMC_JAR_OBJECT_ID].jar. You have to locate the one containing your BOF code. For this, you can run the DQL command:
select r_object_id from dmc_jar where object_name='[JAR NAME]'
Or, you could also change the property dfc.bof.cache.append_name property so that the cached jars names will contain also their object names (on next caching).

Once you locate your jar, you have 2 options:
a) replace the cached jar with the new one, built in your IDE, keeping original name
b) open the jar (like a common archive) and replace only the modified class(es)
Remember to stop your DFC client to unlock the cached jars, otherwise you can't modify them.
Now start your DFC client and test your changes.

Code fast, test faster!

Custom job method DFC code sample

Implementing a custom Documentum job method requires writing some non trivial DFC code. Below you'll find a sample using an abstract class which can be extended and re-used for any implementation of a job method.
Connection/helping methods are encapsulated into the AbstractJobMethod abstract class, so you can write custom classes that extend it. The only method to be implemented is execute(), where you have an active session (handled by the abstract class) and can perform the required actions against the repository.
The abstract class uses the CustomJobArguments, which is an extension of standard DfStandardJobArguments, providing some additional methods to access the passed job arguments.
Check How to create a custom job in Documentum for details on creation of custom job and method.

public class SomeCustomMethod extends AbstractJobMethod {
  public int execute() throws Exception {
    DfLogger.debug(this, "Started custom method implementation with user: " + session.getLoginUserName(), null, null);
    // custom method logic goes here
    return 0;
  }
}
////
public abstract class AbstractJobMethod implements IDfMethod, IDfModule {
// for BOF 1.0 the class must implement only the IDfMethod interface, the jar is deployed on JMS
// for BOF 2.0 it implements also IDfModule because it will be deployed into the repository and will run as a BOF module

  protected CustomJobArguments jobArguments;
  protected IDfTime startDate;
  protected IReportWriter reportWriter;
  protected IDfSession session;
  protected IDfSessionManager sessionManager;
  protected IDfClientX clientx;
  protected IDfClient client;

  public int execute(Map args, PrintWriter writer) throws Exception {
    setup(args, writer);
    try {
      int retCode = execute();
      printJobStatusReport(retCode);
      return retCode;
    } catch (Exception e) {
      DfLogger.error(this, "", null, e);
      reportWriter.emitLine("Error encountered: " + e.getMessage());
      reportWriter.closeOut(false);
      throw e;
    } finally {
      if (reportWriter != null)
      reportWriter.close();
      if (session != null)
        sessionManager.release(session);
    }
  }

  // the only method to be implemented in concrete subclasses
  public abstract int execute() throws Exception;

  public void setup(Map args, PrintWriter writer) throws DfMethodArgumentException, DfException, Exception {
    startDate = new DfTime();
    jobArguments = new CustomJobArguments(new DfMethodArgumentManager(args));
    setupMethodFactory(writer);
    String username = jobArguments.getUserName();
    String password = jobArguments.getString("password");
    String domain = jobArguments.getString("domain");
    String docbase = jobArguments.getDocbaseName();
    setupSessionManager(username, password, domain, docbase);
  }

  private void setupSessionManager(String username, String password, String domain, String docbase) throws DfServiceException, DfException {
    DfLogger.debug(this, String.format("setupSessionManager-> username[%s] password[%s] domain[%s] docbase[%s]", username, password, domain, docbase), null, null);
    clientx = new DfClientX();
    client = clientx.getLocalClient();
    sessionManager = client.newSessionManager();
    IDfLoginInfo loginInfoObj = clientx.getLoginInfo();
    loginInfoObj.setUser(username);
    if (password != null && !password.equals(""))
        loginInfoObj.setPassword(password);
    loginInfoObj.setPassword(password);
    loginInfoObj.setDomain(domain);
    sessionManager.setIdentity(docbase, loginInfoObj);
    session = sessionManager.getSession(docbase);
  }

  private void setupMethodFactory(PrintWriter writer) throws Exception {
    try {
      IDfId jobId = jobArguments.getJobId();
      ReportFactory reportfactory = new ReportFactory();
      if (writer != null) {
        DfLogger.debug(this, "uso reportFactory", null, null);
        reportWriter = reportfactory.getReport(jobArguments.getDocbaseName(), jobArguments.getUserName(), "", jobArguments.getMethodTraceLevel(), jobId, writer);
      } else {
        DfLogger.warn(this, "writer == null, uso SimpleReportWriter", null, null);
        reportWriter = new SimpleReportWriter();
      }
    } catch (Exception e) {
      DfLogger.error(this, "Failed to create report writer. Error: " + e.getMessage(), null, e);
      throw e;
    }
  }

  private void printJobStatusReport(int retCode) throws Exception {
    reportWriter.emitLineToReport("Return Code-> " + retCode);
    String jobStatus = null;
    IDfTime end_date = new DfTime();
    long min_duration = Utility.timeDiff(startDate, end_date) / 60L;
    if (retCode == 0)
      jobStatus = "Custom Job completed at " + end_date.asString("yyyy/mm/dd hh:mi:ss") + ". Total duration: " + min_duration + " minutes.";
    else if (retCode > 0)
      jobStatus = "Custom job completed with Warnings at " + end_date.asString("yyyy/mm/dd hh:mi:ss") + ". Total duration: " + min_duration + " minutes.";
    else
      jobStatus = "Custom job completed with Errors at " + end_date.asString("yyyy/mm/dd hh:mi:ss") + ". Total duration: " + min_duration + " minutes. Check job report for details.";
    updateJobStatus(jobStatus, jobArguments.getJobId());
    reportWriter.closeOut(retCode >= 0);
  }

  public void updateJobStatus(String sJobStatus, IDfId jobId) throws Exception {
    if (session == null) {
      DfLogger.error(this, "setJobStatus: (session==null)", null, null);
      throw new NullPointerException("setJobStatus: (session==null)");
    }
    try {
      IDfPersistentObject job = session.getObject(jobId);
      if (job == null)
        throw new DfException("Failed to retrieve dm_job object from id '" + jobId.getId() + "'.");
      job.setString("a_current_status", sJobStatus);
      job.save();
    } catch (Exception e) {
      throw e;
    }
  }
}
////
public class CustomJobArguments extends DfStandardJobArguments {

  protected IDfMethodArgumentManager methodArgumentManager;
 
  public CustomJobArguments(IDfMethodArgumentManager manager) throws DfMethodArgumentException {
    super(manager);
    methodArgumentManager=manager;
  }

  public String getString(String paramName) throws DfMethodArgumentException {
    return methodArgumentManager.getString(paramName);
  }

  public int getInt(String paramName) throws DfMethodArgumentException {
    return methodArgumentManager.getInt(paramName).intValue();
  }
}

How to create a custom job in Documentum

Documentum jobs allow to process some objects automatically, by schedule, according to the business logic. They are pretty similar to scheduled tasks on Operating Systems. When started, the job calls a Documentum method which executes the desired logic. The methods are executed on the Java Method Server (JMS), which is part of the Content Server installation.
A job consists of several items:
 1) Job Method implementation code
 1.1) for BOF 2.0: corresponding implementation jar(s) and module
 2) dm_method object - which holds information about the method, implementation class, etc.
 3) dm_job object - which holds information about job, its schedule, last and next invocation, current status, the method it runs, etc.

Here's how to create all of the required items for the job.

1. Job method implementation code
First of all you have to write the code that will implement the logic the job method will perform. There are 2 approaches of deploying this code: BOF 1.0 or 2.0.
With BOF 1.0 the method classes are deployed manually on the JMS (path: [JBOSS]\server\DctmServer_MethodServer\deploy\ServerApps.ear\DmMethods.war\WEB-INF\lib), while BOF 2.0 requires you to deploy the implementation jars into the repository and associate them with a BOF module.
For both approaches you can find job method implementation classes samples here: Custom job method DFC code sample
When you're done with coding, compile the implementation classes and build the jar.

1.1 Implementation jar(s) and module (for BOF 2.0)
Open Composer and create the follosing artifacts:
a) Jar: the artifact name should be equal to the jar name (to avoid confusion), the jar type is Implementation.
b) Module: the module name must be equal to the full class name (with packages), modul type: Standard Module, choose the implementation jar created at previous step (a), select the class name (equal to module name). In addition specify all the required modules and Java libraries used by your implementation class(es).

2. dm_method object
a) Using Composer
In Composer create a Method artifact, enter the method name, select type: java, Command: module name (equal to implementation full class name), Run Controls: Run Synchronously, check the options: Run as the server, Trace launch, Use method server, Launch directly. If your code is taking considerable time to run, increase the timeout values.

b) Using Documentum Administrator
Open DA and go to Job Management->Methods node level. From menubar select File->New->Method, enter required values and save the method.

c) Using DQL:
create dm_method object
set object_name = 'MyCustomMethod',
set launch_async = false, set launch_direct = true, set method_type = 'java',
set method_verb = 'com.documentum.project.method.SomeCustomMethod',
set run_as_server = true, set timeout_default = 600,
set timeout_min = 300, set timeout_max = 3000, set trace_launch = true,
set use_method_content = false, set use_method_server = true;

3. dm_job object
a) Using Composer
In Composer create a Job artifact, enter job name, Subject, select the Method (created at step 2), set schedule options. In Arguments section you can add custom arguments passed to your method implementation class. Keep in mind that even if you use custom arguments, you should also pass the standard arguments (docbase name, installation owner, job id, etc.) which are used to manage the job. Thus, in order to add custom arguments select Custom Arguments, add desired arguments with values, then switch back to Standard Arguments. Save the job artifact.

b) Using Documentum Administrator
Open DA and go to Job Management->Jobs node level. From menubar select File->New->Job, enter required values and save the job.

c) Using DQL:
create dm_job object
set object_name = 'MyCustomJob',
set title = 'Title', set subject = 'Job description',
set pass_standard_arguments = true, set is_inactive = false,
set start_date = DATE('01/01/2013'), 
set expiration_date = DATE('01/01/2020'), 
set a_next_invocation = DATE('02/01/2013'), set max_iterations = 0,
set method_name = 'MyCustomMethod', set run_mode = 3,
set run_interval = 1, set inactivate_after_failure = true;

Now you have all the required items for you job. Build the composer project, install it into the repository (from Composer, right click the project and choose Install Documentum Project... or take the built DAR from bin-dir folder and install it using DarDeployer/DarInstaller). If you're using BOF 1.0, deploy manually the implementation jar on JMS (usualy in [JBOSS]\server\DctmServer_MethodServer\deploy\ServerApps.ear\DmMethods.war\WEB-INF\lib).
If it's not the first deployment of the DAR, it's better to restart the JMS and clear the BOF cache (mandatory in case of BOF 1.0).

It's done! Go on with testing: run the new job and check the job report and JMS logs.

How to stop running job

A Documentum job consists of a dm_job object, containing job configuration, name of method to run, as well as process execution information. The job method is executed on the Content Server (if it's a java method - on the JMS). Once the job is started, there's no 'soft' approach to stop it, you can only force it.
Below are the steps to stop properly a running job, reseting also the dm_job object:
1. Get the process id, by running the DQL:
select a_last_process_id from dm_job where object_name='[JOB_NAME]'
2. Using Process Explorer (or similar tool) locate the process by id and kill it. (Or with a command like: taskkill /pid 1234)
3. Run the API command to unlock the job object:
unlock,c,[job_id]
4. Execute the following DQL queries to clear job execution-related attributes:
a) Reset application that uses/locked the job
update dm_job objects set a_special_app='' where object_name='[JOB_NAME]';
b) Reset current status
update dm_job object set a_current_status='FAILED' where object_name='[JOB_NAME]';
c) Prevent job from being run immediately
update dm_job object set run_now=FALSE where object_name='[JOB_NAME]';

Remember to change the schedule or inactivate the job if you don't want it to run automatically after specified period.
If your job is locked in running state, check here how to unlock it: How to unlock a job in running state.

Renaming users - how dm_UserRename job works

In a previous article How to change the user_name of a dm_user we've seen how to rename a Documentum user manually (using Documentum Administrator) and by DFC code.
Let's assume we want to update a set of users, but can't or don't want to write DFC code (it also requires some time to write and run the code). We have an additional option: have the dm_UserRename job rename the users automatically. But how does the dm_UserRename job work?
This job polls a queue: dm_job_request objects. The object has the following attributes which are relevant for the job:
object_name         : UserRename
job_name            : dm_UserRename
method_name         : dm_UserRename
request_completed   : F
arguments_keys   [0]: OldUserName
                 [1]: NewUserName
                 [2]: report_only
                 [3]: unlock_locked_obj
arguments_values [0]: userA
                 [1]: userB
                 [2]: F
                 [3]: F

The jobs read the arguments_keys & arguments_values values and calls the dm_UserRename method with these arguments, so the specified user is renamed with selected options (report_only mode, unlock objects or leave locked). When the operation completes, the request_completed attributed is set to TRUE.
Thus in order to rename a set of users, you need to create a dm_job_request object for each user and run the dm_UserRename job. Note that by default the dm_UserRename job is inactive, so you can either run it manually, or activate it and schedule if you often rename users.

Here's sample DQL to create a dm_job_request object (to rename 1 user):
create dm_job_request object set object_name='UserRename', set job_name='dm_UserRename', set method_name='dm_UserRename', set request_completed=FALSE, append arguments_keys='OldUserName', append arguments_keys='NewUserName', append arguments_keys='report_only', append arguments_keys='unlock_locked_obj', append arguments_values='userA', append arguments_values='userB', append arguments_values=FALSE, append arguments_values=FALSE

How to change the user_name of a dm_user

In a Documentum repository users are uniquely identified by the user_name attribute. Being a key, the user_name value is used in related objects (for example: owner, r_modifier, r_creator, r_lock_owner, etc.) stating that this user performed an action on this object.
In certain cases we need to change the user_name value: for example when we want to create a new user, but an old one (perhaps deactivated) already exists with the same user_name.
Being a key, we can't simply update this value, you won't even be able to modify it on user property screen. Here are the ways to accomplish this:

1. Manual renaming
There's a simple tool called Reassign User which invokes the dm_UserRename job (Renaming users - how dm_UserRename job works explains how this job works):
a. (Optional) Create a new user with the user_name you want to rename the old user to.
b. Open DA, go to Users node in browsertree, find the desired user, right click on it and choose Reassign User. On the opened page enter/select the new user, select the option to run the reassign job now (and change other settings if required).
c. (Optional) As soon as the dm_RenameUser job has completed, you can remove the original (old) user if it's not needed anymore.
Note that you can skip the creation of a new user and just enter the new user_name on the Reassign User page, it will handle the modification of user_name itself.

2. Automatic renaming
If we want to rename many users, the manual approach would be really annoying, so as usual we turn to some DFC coding.
Renaming users in DFC is quite straightforward, it's enough to call the rename method:
 IDfUser user = session.getUser("userA");
 user.renameUser("userB", true, false, true);
 user.save();

Here's the method description from the API:
void renameUser(String userName,
                boolean isImmediate,
                boolean unlockObjects,
                boolean reportOnly)
                throws DfException
    Renames this user. If this is a new user, the attribute value is set. If this is an existing user, this method invokes a job to rename user.
    Parameters:
        userName - user name to be set or renamed to (existing user)
        isImmediate - Detemines if the job should be run immediately or run on schedule.
        unlockObjects - control if the objects should be unlocked when renaming user. If this is a new user, this parameter does not take any effect.
        reportOnly - control if the job created is to report or actual rename. If this is a new user, this parameter does not take any effect.

How to register and unregister types for indexing

Documentum uses fulltext indexing to enable search on all document properties as well as its contents.  How does fulltext indexing work?
Indexing is performed by a dedicated server (FAST, xPlore, etc.) that polls the queue of the fulltext user. In order to index certain (sub)types of documents, you must register certain events of these types for index user. Thus when a registered event occurs on a document of the registered type, a queue item is created in the fulltext user's queue, which consequently is processed by the Fulltext indexing server, by indexing the document. The events to register are those that usually change the object metadata and/or content: dm_save,dm_readonlysave,dm_checkin,dm_move_content,dm_destroy

By default, (in previous versions of Documentum) all dm_sysobject types and its subtypes are registered for indexing. Usually you don't need all the dm_sysobject to be indexed, so before registering your custom types, you should unregister the dm_sysobject first. You can do that by running the following API script, being connected with the fulltext user (dm_fulltext_index_user):
(Note: if you don't know the password for dm_fulltext_index_user you can generate a login ticket by running following API with a superuser: getlogin,c,dm_fulltext_index_user Read more details about this trick in: How to login to the repository with a ticket).

API for unregistering indexing:
unregister,c,[TYPE_ID],dm_save,,F
unregister,c,[TYPE_ID],dm_readonlysave,,F
unregister,c,[TYPE_ID],dm_checkin,,F
unregister,c,[TYPE_ID],dm_move_content,,F
unregister,c,[TYPE_ID],dm_destroy,,F
[TYPE_ID] is the r_object_id of the dm_type object
Note: If you have more Index servers, you should have an index user for each, so run the unregister script for each user.

You can also do that by unchecking the 'Enable Indexing' checkbox on dm_sysobject type properties in DA.

You can register a custom type for indexing in 2 ways:
1. By executing the following API script, with the fulltext user (dm_fulltext_index_user):
register,c,[TYPE_ID],dm_save,,F
register,c,[TYPE_ID],dm_readonlysave,,F
register,c,[TYPE_ID],dm_checkin,,F
register,c,[TYPE_ID],dm_move_content,,F
register,c,[TYPE_ID],dm_destroy,,F

[TYPE_ID] is the r_object_id of the dm_type object
Note: If you have more Index servers, you should have an index user for each, so run the register script for each user.

2. Manually, by using DA: Open Types node in browsertree, find the desired type, open its properties and check the 'Enable Indexing' checkbox.

To check which types are currently registered for indexing, use the DQL:
select name from dm_type where r_object_id in (select distinct registered_id from dmi_registry where user_name='dm_fulltext_index_user')