Documentum story – Management of DARs and unexpected errors

During a recent project at one of our customers, we often saw the message “Unexpected errors occurred while installing DARs”. In our case, this message happened when installing, migrating or upgrading a docbase on an already existing Content Server. We never saw this message during the first initial phase of installation of our repositories but we started to see it some months later with the first migration/upgrade. In this blog I will show you where does this issue can come from and how DARs are managed by Documentum for new/migrated docbases. In a future blog I will show you a home-made script that can be used to manually install DARs on docbases which tips, aso…

For this blog, let’s use the following:

• Documentum CS 7.2
• RedHat Linux 6.6
• $DOCUMENTUM=/app/dctm/server
• $DM_HOME=/app/dctm/server/product/7.2

Most of the time, these errors are thrown because Documentum isn’t able to install the needed DARs but what’s the reason behind that? First of all, there is one important thing to know: when installing a new docbase, Documentum will check which DARs should be installed by default. This list is dynamically generated based on a file and this file is the following one:

[dmadmin@content_server_01 ~]$ cat $DM_HOME/install/darsAdditional.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<actions>
    <dar name="TCMReferenceProject">
        <description>TCMReferenceProject</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/TCMReferenceProject.dar</darFile>
    </dar>
    <dar name="Forms">
        <description>Forms</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/Forms.dar</darFile>
    </dar>
    <dar name="Collaboration Services">
        <description>Collaboration Services</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/Collaboration Services.dar</darFile>
        <javaOptions>
            <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>
    <dar name="xcp">
        <description>xCP</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/xcp.dar</darFile>
        <javaOptions>
            <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>
    <dar name="bpm">
        <description>BPM</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/BPM.dar</darFile>
        <javaOptions>
            <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>
    <dar name="C2-DAR">
        <description>C2-DAR</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/C2-DAR.dar</darFile>
        <javaOptions>
           <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>
    <dar name="D2-DAR">
        <description>D2-DAR</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/D2-DAR.dar</darFile>
        <javaOptions>
            <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>
    <dar name="D2Widget-DAR">
        <description>D2Widget-DAR</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/D2Widget-DAR.dar</darFile>
        <javaOptions>
            <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>
    <dar name="D2-Bin-DAR">
        <description>D2-Bin-DAR</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/D2-Bin-DAR.dar</darFile>
        <javaOptions>
            <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>
    <dar name="O2-DAR">
        <description>O2-DAR</description>
        <darFile>/app/dctm/server/product/7.2/install/DARsInternal/O2-DAR.dar</darFile>
        <javaOptions>
            <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>
</actions>

Some of the dars inside this file are configured by Documentum directly (BPM & xcp DARs) and some others have been added by us, manually (D2 DARs). If you want to install new DARs for future installations of a docbase, then you can just update this file with a new section using this template:

    <dar name="DAR_NAME">
        <description>DAR_NAME</description>
        <darFile>/ABSOLUTE_LOCATION_OF_FILE/DAR_NAME.dar</darFile>
        <javaOptions>
            <javaOption>-XX:MaxPermSize=256m</javaOption>
            <javaOption>-Xmx1024m</javaOption>
        </javaOptions>
    </dar>

By default Documentum will always put the DARs inside the folder $DM_HOME/install/DARsInternal/ so I would recommend you to do the same, update the xml file and that’s it. Now this *can* also bring some trouble where some DARs aren’t installed anymore with the error shown at the beginning of this blog and the reason for that is – most of time – simply because there is a space in the name of the DAR… Yes from time to time, depending on the DARs, Documentum might not be able to properly manage spaces in the name of the DARs. It doesn’t always happen and that’s the annoying part because I didn’t find any logical behavior.

There is a way to verify which DAR might cause this issue and which one will not: when installing a CS patch, the folder “$DOCUMENTUM/patch/bin” is usually created and inside this folder, there is a file named “repositoryPatch.sh”. This script will be used by the patch to do some work and to install some DARs if needed. The interesting thing here is that this script include a small bug which you can use to find the troublesome DARs and you can also easily fix the script. After doing that, you will be able to use this script for all DARs no matter if they include spaces or not. So let’s take a look at the default file in one of our Content Server:

[dmadmin@content_server_01 ~]$ cat $DOCUMENTUM/patch/bin/repositoryPatch.sh | grep "^dars"
dars="/app/dctm/server/product/7.2/install/DARsInternal/LDAP.dar,/app/dctm/server/product/7.2/install/DARsInternal/MessagingApp.dar,/app/dctm/server/product/7.2/install/DARsInternal/MailApp.dar,/app/dctm/server/product/7.2/install/DARsInternal/Extended Search - SearchTemplates.dar,/app/dctm/server/product/7.2/install/DARsInternal/ATMOS Plugin.dar,/app/dctm/server/product/7.2/install/DARsInternal/VIPR Plugin.dar"

As you can see above, you just need to define the full path of each DAR file separated by a comma. To fix this script for all DARs, a first solution would be to rename the DARs but there is actually a simpler solution: use single quotes instead of double quotes in the dars definition:

[dmadmin@content_server_01 ~]$ cat $DOCUMENTUM/patch/bin/repositoryPatch.sh | grep "^dars"
dars='/app/dctm/server/product/7.2/install/DARsInternal/LDAP.dar,/app/dctm/server/product/7.2/install/DARsInternal/MessagingApp.dar,/app/dctm/server/product/7.2/install/DARsInternal/MailApp.dar,/app/dctm/server/product/7.2/install/DARsInternal/Extended Search - SearchTemplates.dar,/app/dctm/server/product/7.2/install/DARsInternal/ATMOS Plugin.dar,/app/dctm/server/product/7.2/install/DARsInternal/VIPR Plugin.dar'

By doing that, you corrected the bug in the script and now you should be able to execute this script to deploy all DARs to a single repository using:

[dmadmin@content_server_01 ~]$ $DOCUMENTUM/patch/bin/repositoryPatch.sh DOCBASE USERNAME PASSWORD

Note: As always, if you are using the Installation Owner as the USERNAME, then the PASSWORD can be a dummy password like “xxx” since there is the local trust on the Content Server.

This conclude this blog about the principal issue that we can face when installing a DAR, about how to manage the automatic deployment of some DARs in new docbases and finally how to use the script provided by a patch to do that manually. See you!