Setting selected system properties on IBM FileNet P8 document versions

Answer

The steps to successfully set values for these system properties are not always obvious, so this note will attempt to clarify the conditions and steps necessary, and provide some sample Java code as an example. Similar steps can be performed through the .NET API.

Note: In the code samples that follow, error and exception handling have been ignored in order to focus on the necessary steps. Production code should always include appropriate error and exception handling.

Details

Permissions

The first requirement is for the authenticated user to have the necessary permissions to set these properties. Along with the normal WRITE permission (“Modify all properties”) on the document, the user must also have PRIVILEGED_WRITE permission on the object store where the document will be saved. This permission is seen as “Modify certain system properties” in the object store permissions in FileNet Enterprise Manager.

We can determine whether the authenticated user has the required permission by examining the access granted on the object store interface.


private static boolean hasPrivelegedAccess(ObjectStore objectStore)
{
    boolean hasPrivilege = false;
    Integer accessAllowed = objectStore.getAccessAllowed();
    if ((AccessRight.PRIVILEGED_WRITE_AS_INT &
                           accessAllowed.intValue()) != 0)
        hasPrivilege = true;
   
    return hasPrivilege;
}


Setting Properties on Versions
There are two cases that we will deal with separately. The first is setting values for Creator and DateCreated. The properties are system-defined as SetOnlyOnCreate, which means that there is one opportunity to set values, before the document is created in the object store. For a new document version this is straightforward. Simply create an initial Document object using the Java API, set the values, and save the document. Once the document is saved these values can no longer be set.


private static void createNewDoc(ObjectStore objectStore)
{
    Document version1 =
             Factory.Document.createInstance(objectStore,
                                             "Document");
    version1.getProperties()
                 .putValue("DocumentTitle",
                           "Modify Properties Test");
    version1.set_Creator("Tom");
    version1.set_DateCreated(myCreateDate);
    version1.set_ContentElements(
                  createContent(new File("TestDoc.odt")));
    version1.checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY,
                     CheckinType.MAJOR_VERSION);
    version1.save(RefreshMode.REFRESH);
}


Since the initial object returned by the factory createInstance method has not been saved in the object store, it is not considered “created”, so the SetOnlyOnCreate restriction is not yet enforced.

Many applications will want to set the initial values for LastModifier and DateLastModified to the same values as Creator and DateCreated, respectively. Setting these two properties is addressed next.

Setting these values on a second or subsequent version is a little more complex, as the next version is created as the result of a checkout operation on an existing version. An initial object is not available to set values on before creation. The solution is to provide an additional collection of properties to the checkout method that will be applied to the new version before it is created.


private static void createNextVersion(ObjectStore objectStore,
                                      Document oldVers)
{
    Document newDoc = Factory.Document.createInstance(
                                      objectStore, "Document");
    newDoc.getProperties().putValue("DocumentTitle",
                                    "Next Properties Test");
    newDoc.set_Creator("Tom");
    newDoc.set_DateCreated(myCreateDate);
    Id id = Id.createId();

// this next part looks useless, but we need to re-set
// LastModifier and DateLastModified on the previous version,
// otherwise performing the checkout updates the document being
// checked out.

    String lastModifier = oldVers.get_LastModifier();
    Date lastModified = oldVers.get_DateLastModified();

    oldVers.getProperties()
               .removeFromCache(PropertyNames.LAST_MODIFIER);
    oldVers.getProperties()
               .removeFromCache(PropertyNames.DATE_LAST_MODIFIED);
    oldVers.set_LastModifier(lastModifier);
    oldVers.set_DateLastModified(lastModified);

// we pass newDoc as a collection of properties to be set
// on the version we are about to create...

    oldVers.checkout(ReservationType.EXCLUSIVE, id, null,
                        newDoc.getProperties());
    oldVers.save(RefreshMode.REFRESH);
}


We can also see in the preceeding code the solution to the second case, setting values for the ModifiedBy and DateLastModified properties. A little care must be taken with these properties as the operations to checkout and checkin versions will directly affect them. Specifically, checking out a document version not only creates a new version, but it modifies the previous version to mark that it is checked out and has a reservation. We need to take steps to preserve the values for ModifiedBy and DateLastModified on the previous version while performing the checkout. We do this by gathering the two values in temporary variables, clearing their values from the version, and then setting them again from the saved copies. This rewrites the values in the old version as part of the checkout operation. The removeFromCache calls are needed to prevent enforcement of the read-only restriction on these two values.

We can then proceed with filling in the second version using the steps we used previously...


private static void completeNextVersion(ObjectStore objectStore,
                                        Document oldVersion)
{
    Document reservation = (Document)oldVersion.get_Reservation();

// this looks useless, but we need to re-set LastModifier and
// DateLastModified to preserve them past the checkout.
// Otherwise performing the checkout updates the document
// being checked out.

    String lastModifier = reservation.get_LastModifier();
    Date lastModified = reservation.get_DateLastModified();

    reservation.getProperties()
                   .removeFromCache(PropertyNames.LAST_MODIFIER);
    reservation.getProperties()
                   .removeFromCache(PropertyNames.DATE_LAST_MODIFIED);
    reservation.set_LastModifier(lastModifier);
    reservation.set_DateLastModified(lastModified);

    reservation.set_ContentElements(
                     createContent(new File("TestDoc2.odt")));
    reservation.checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY,
                                         CheckinType.MAJOR_VERSION);
    reservation.save(RefreshMode.REFRESH);
}


Once the checkout operation has completed, we retrieve the resulting reservation as we normally would. The Creator and DateCreated properties have been set as part of the checkout. We perform the same steps for setting LastModifier and DateLastModified as the previous version.

Summary
The code needed to set Creator, DateCreated, LastModifier and DateLastModified are not complex, but they are somewhat different to the code normally used for more common properties. The above steps should allow a developer to set these values when called for.