Documentum Composer: Integrating BOF Development into your workflow

A few colleagues have recently asked me what the current best practice for integrating BOF development into your workflow is, using Composer.

If it isn’t immediately obvious why this is an interesting question then it is because the development of a BOF (Business Object Framework) Module spans the disparate worlds of java development, for the module definition and implementation, and of Composer for the artifacts, for packaging and deployment.  More often than not I observe projects where one IDE is used to develop the modules and another is used for developing the artifacts.  Or worse still some other process is used for creating the Documentum Artifacts instead of Composer, normally involving copious amounts IAPI and IDQL.

So, what I want to do here is describe how you can set up a Documentum Composer project to use an ant builder (and ant script) to package a module implementation and associate it with a jardef artifact thus seamlessly bridging the java and artifact worlds and allowing you to keep all your development under one roof, eclipse in this case.

A Documentum Composer project is obviously the natural home of your artifacts but every Composer project is in fact also a java project. So, with this in mind, let’s dive into the details.

First create (or open) the Composer project that will contain your java and artifacts. In its simplest form, a BOF Module is a module definition associated with a a jar definition. Both are Documentum Artifacts, So, let’s create those.

File->New->Other->Documentum Artifact->Jardef. Name it mymodule_jardef. After the editor opens on your new artifact select this jardef type as Interface and Implementation because our jar will contain both classes and their interfaces.

image

Next create the module definition. Choose File->New->Other->Documentum Artifact->Module. Name it mymodule. After the editor opens on your new module artifact, associate the jardef with the module. To do this make sure the General tab is selected click the Add button associated with the implementation jar panel. Select your mymodule_jardef artifact from the list (if this is a new project it will probably be the only jardef in the list).

Now if you look in your Problems view you’ll probably see a problem marker for you module artifact (if you don’t see any problems its probably because auto-build is off – make sure you build your project and you’ll see it appear). The marker is because we haven’t set the module’s class name but that is because we haven’t got any java yet. Ignore it for now as we’ll add the java in a minute and resolve this after.

Before we can create our java we need to slightly reconfigure the project’s build path. At the moment everything is being built into a bin folder. However, we want to separate the java from the artifacts. You won’t see the bin folder in the Documentum Navigator view but you will if you open another view like Navigator (Window->Show View->Navigator). Right-click on the project and select Properties and then Java Build Path and then select the Source tab. Make sure the “Allow output folders for source folders” checkbox is checked and then edit the output folder for the src folder to point to a classes folder as I have done here. When you click browse you’ll get a change to create the new classes folder:-

image

Once you’ve done that, click OK to close the dialog.

Right click on your src folder and select New->Other->Java->Interface to create an interface called IMyModule in package “my.module”, as follows:-

image

And then give the interface a method declaration:-

package my.module;

public interface IMyModule {
public void sayHello();
}

Next follow the same procedure to create a class this time called MyModule also in package “my.module” and make it implement IMyModule, as follows:-

image

And give it an implementation for the say hello method:-

package my.module;

public class MyModule implements IMyModule {

public void sayHello() {
System.out.println(“Hello World!”);
}
}

So, you should end up with something like this in your Documentum Navigator:-

image

The project’s java builder will take care of compiling this interface and class for us. What we need to do though is package them in a jar so we can associate that jar as the content of the Jardef artifact that we created earlier. To do that we want to add a new (ant) builder to the project that calls an ant script. This will take care of always packaging the java into a jar. Create a file in the root of the project and call it buildJar.xml then cut and paste in the following standard ant script:-

<?xml version=”1.0″ encoding=”UTF-8″?>
<project name=”Jar’s the project” default=”main”>

<target name=”main”>

<delete file=”MyModule.jar” />

<jar destfile=”MyModule.jar” basedir=”classes”/>
<eclipse.refreshLocal resource=”your project name goes here“/>
</target>

</project>

Note that the jar task will jar up all classes in classes folder which should be the one we set as our output folder just now. And also remember to put the name of your project into the resource attribute on the eclipse.refreshLocal task otherwise your jar might not show up your view after it is created.

Next, add the new ant builder to your project. Right-click the project and select Properties->Builders. Click the New… button and then select Ant Builder. Click OK. This will launch an ant invocation dialog. Give your builder the name Jar Builder. Browse the workspace and select buildJar.xml as the buildfile:-

image

Then select the Targets tab and add main as the target for an autobuild:-

image

Click OK and then select the newly added Jar Builder and move it up in between the Java Builder and the Documentum Artifact Builder:-

image

Click OK. Assuming auto build is on for you, you should see the project build at this point (if it isn’t invoke a build). You’ll see the Jar Builder doing its stuff in the Console window and you should see MyModule.jar appear in your navigator:-

image

image

So now we are ready to hook the jar up to the artifacts. The first thing to do is open your jardef artifact and using the Browse… button associate your jardef with some content. It doesn’t matter what that is, this action just triggers the creation of the relevant elements in your jardef artifact’s XMI. I just selected a jar file that was lying around in my Temp folder. You can choose anything.

image

Save and close the editor. Next re-open the artifact but this time open it with a text editor. Right-click the artifact and choose Open With->Text Editor. You should see something like this:-

<?xml version=”1.0″ encoding=”ASCII”?>
<Artifact:Artifact xmi:version=”2.0″ xmlns:xmi=”
http://www.omg.org/XMI” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:Artifact=”http://documentum.emc.com/infrastructure/12012007/artifact” xmlns:dclass=”http://documentum.emc.com/artifact/12012007/dclass” xmlns:ide=”http://documentum.emc.com/artifact/12012007/jardef” urn=”urn:com.emc.ide.artifact.jardef.jardef/mymodule_jardef?artifactURI=file:/C:/Temp/Eclipse33ScratchWorkspace/DocumentumProject/Artifacts/mymodule_jardef.jardef” categoryId=”com.emc.ide.artifact.jardef.jardef”>
<dataModel xsi:type=”ide:JarDef” objectName=”mymodule_jardef” contentType=”java” jar_type=”Interface and Implementation”>
<objectType xsi:type=”dclass:DClass” href=”urn:com.emc.ide.artifact.dclass/dmc_jar?name=dmc_jar#//@dataModel”/>
<aspectName href=”urn:com.emc.ide.artifact.aspectmoduledef/com.documentum.fc.bof.bootstrap.DfModuleItemChangeMonitor?aspectname=com.documentum.fc.bof.bootstrap.DfModuleItemChangeMonitor#//@dataModel”/>
<resource xsi:type=”ide:JarResource” jarFile=”//@contentStore/@contentEntries.0/@value”/>
</dataModel>
<viewModel xsi:type=”Artifact:DefaultArtifactViewModel”/>
<contentStore>
<contentEntries key=”test.jar”>
<value filePath=”content/48/513126848/test.jar”/>
</contentEntries>
</contentStore>
</Artifact:Artifact>

I’ve bolded the entries that have just been created by importing some content.

The filePath attribute of the value element is actually just a project-relative path so modify this to point to your jar file, as follows:-

<value filePath=”MyModule.jar”/>

And the contentEntries key is arbitrary. Rename this value to MyModule.jar as well. When you view this again through the jardef editor you will see that it looks like it has the right file attached.

Save and close the file again.

That has now associated your jar file with your jardef artifact which bridges the gap between the java and artifact worlds.

Now finally we can resolve that problem marker that appeared earlier. We need to set the module’s class name. Open the module definition editor for your module artifact and choose the Select… button next to the class name field. Highlight my.module.MyModule and click OK. You should know have something resembling this:-

image

Save and close the editor. You should see project rebuild and the problem marker disappear as we have now resolved that issue.

And that’s it. You are now all set. Your module artifact is associated with your jardef artifact which is in turn associated with your jar which packages your java classes. Your Documentum world and your java world are joined. No more dual development or IAPI scripts. You can edit your java to your hearts content from this point forward. If you work with auto build on then this will automatically build your java, package it and have it associated with your jardef so that when you are ready to test your module you can just install the project it into a Repository. Dar (the distributable package that is produced by a Composer project) installation is a completely repeatable process so you can install time and again and the installer will work out what needs adding and what needs upgrading. So, you can modify you java, re-install, test over and over.

Obviously what I have shown here is an integration based on a plain old BOF module. But of course BOF Modules come in many flavours. You can split your implementation and interface jars for example. And then there are the other types of BOF module as well; TBOs, SBOs, behavioural aspects and aspects with attributes. The basic principles that I have explained here will work for them all and give you a seamless & automated workflow.

It is also a one-time only gig as well and once set up you can share it with all the other engineers by placing the project in your source control system.

Happy composing!

Advertisements

25 thoughts on “Documentum Composer: Integrating BOF Development into your workflow

  1. This is the best article on the web about Composer usage.

    It is also sad that this is the best article.

    You can not find any information for free about Documentum. Documents downloaded from Powerlink is not enough by theirselves.

    There is nothing to give you a solid start without buying EMC Courses. I think the end of Documentum will come because of this reason.

  2. Many thanks for your very kind comment Bekhan.

    I apologize that there isnt more information out there. I personally am a fan of delivering documentation via wiki and I would love to see our own technical publications delivered via this medium.

    Is there somethings in particular that you are struggling with? Perhaps I can help?

    In the meantime I will pass your comments onto the Composer team.

  3. Well, I’m trying to implement the BOF code example in DFC_6_development.pdf Chapter 5 with no luck.
    I created the java code, type, modules, jar definitions in Composer.
    But I can not understand if I have to add a Ant builder to convert *.class files to Jars.
    “Documentum_Composer_User_Guide.pdf” does not say anything about it.
    I think Jars should be somehow created by Composer itself but I can not achieve it.
    When I deploy my project (Using Application builder, explained in DFC_6_development.pdf ) it simply does not run. type is there, my new property is there but BOF code is not working (it does not show any error, or writes something to log files)

  4. Hi Berkhan,

    You have it exactly. You need to add a custom ant builder to the project that hosts your java interfaces and implementation. Its responsibility is to package these classes into a jar (or two jars if you are separating API and implementation).

    Then, one time only, you need to associate your jardef (which is just a docbase object wrapper around a jar) with the jar that you ant builder produces.

    You can play about with the targets of your ant builder to see what works for you. The default clean and build settings are probably optimal as the DarInstaller will force a full clean build before installing and therefore your jar will always be re-packaged just prior to install ensuring it is up-to-date.

    Hope that helps

  5. Paul,

    Really good coverage of Composer and something that is truly useful. Although Documentum’s getting better about documentation they missed the mark on Composer’s handling of how to create Modules – very slim section in “Documentum Composer User Guide”

    Question – though. I followed the install very closely and it installed some items in Documentum but NOT the .jar file. I’m new to TBO’s, SBO’s and modules but shouldn’t MyModule.jar have been installed into repository? I see MyModule folder under \System\Modules. A file called “mymodule_jardef” is in that folder. There’s also a new empty folder (Systems\Applications\name of project) but no .jar file. Ant DID create jar file OK…I can see MyModule.jar in root of project near buildJar.xml.

    I could have gone wrong here & I plan to repeat and see if it makes a difference…
    a. when you do this…File->New->Other->Documentum Artifact->Jardef. Name it mymodule_jardef. It places jardef in Jar Definitions folder in Composer.

    2. then you create module but if you don’t watch out it places module in Jar Definitions folder. I would expect module to be placed into Modules folder in Composer. Don’t know if this matters but I’ll redo the whole project and see if it matters – maybe that will install the jar file into Documentum as expected.

  6. Hi Steve,

    Many thanks.

    The short answer is yes. But these get placed in different folders depending on the type of module you are installing; TBO, SBO, etc.

    If you make sure logging is turned on (Windows->Preferences->Documentum->Logger) then you can check the log (should be in your java.io.tmpdir folder) after the install to ensure everyhting installed OK and where. You should see something like this in your log:-

    [INFO] FolderTree Structure
    + VirtualFolder : System (V)
    +*VirtualFolder : Modules (V)
    +*ModuleDef : newmodule
    -*JarDef : newjardef
    -*RuntimeEnvironment : RuntimeEnvironment.xml
    +*ModuleSubFolder : Miscellaneous
    +*ModuleSubFolder : External Interfaces
    +*VirtualFolder : Applications (V)
    +*VirtualFolder : Test (V)
    -*DarDef : Test

    and then you can of course double check this against the repository. Standard modules should be installed into /System/Modules/.

    I would be surprised if you are seeing different behaviors when installing through the UI versus Ant. Both interfaces are just thin wrappers onto the installer API so it is the same code that being executed in both cases.

    Let me know if you need more assistance.

  7. Thanks for such a good article on the startup of BOF Module.

    I would like to add one thing over here.

    For the ANT builder, in composer it might not be by default added for all of them ( was not for me).In order to this you have to set ANT HOME in the composer and this can be done as below:

    Go to Windows –> Preferences –> Ant –> Runtime, here select your ANT Home and basically it is \Composer\plugins\org.apache.ant_1.7.0.v200706080842.After this follow the steps as above and enjoy composing!.

    Regards
    Deepak

  8. Hi Paul,
    very interesting article!
    Could you please post some suggestions on how to move TBO development from BOF1.0 to BOF2.0?
    Altough no more supported, dbor.properties has the advantage that it has got an easy development process:
    – create dbor.properties on developer workstation
    – compile, DEBUG (within an IDE!), test on developer workstation
    – deploy only when code is ready on every server

    I would like to be able to use all of the IDEs debugger features also while developing TBOs with BOF20.
    The only way I have found is a non documentum way: put all of the business logic related to a tbo in an helper class that does not need to be deployed on repository and call that class from the TBO.
    Is there a documentum way?

    thanks, A.

  9. Hello Paul,

    I am using Eclipse 3.4 with the Composer 6.5 plugins/features (as outlined in a previous blog entry), plus I am using the Subclipse plugin to access a Subversion repository.

    When performing a custom build using an Ant script (as per the process outlined above), I have found that the DAR packager is not collecting my latest custom JAR file (containing, in this case, a TBO class). Rather it is using a cached copy held in “content/96/775401696”. This cached JAR file is only updated when the user removes/adds a JAR file to the JAR definition via the JARDEF editor.

    This becomes a little more awkward too, because the Subclipse plugin watches the custom JAR resource in the “content” folder and sometimes complains about read/write access when the JARDEF editor attempts to replace the file. My only workaround is to perform the build, manually update the latest custom JAR in the “content” folder, perform another build to ensure the DAR file contains the latest custom JAR, then install the DAR. Not much fun and error prone.

    From all this, a few questions do flow …

    Have you seen this kind of behaviour ? Is there a workaround ?

    Should the “content” folder be stored in source control (eg. SVN repository), or is it a temporary resource folder ?

    Is a better TBO/SBO integration in the pipeline for the Eclipse/Composer world ?

    Thanks.

    – Tim

    • Hi Tim,

      Apologies for the very long wait for a reply. Unforgiveably I completely missed this comment.

      Many thanks for your comment. I think you raise an excellent point with the source control issue. Let me try and answer your questions.

      Firstly, I do think replacing the existing “managed” content file, as opposed to pointing the jardef artifact at a new copy, is a simpler approach overall.

      As per this post you can place the content folder under source control.

      Typically these content files are not derived and therefore you must place then under version control.

      However, in this case the jar truely is derived so it is really up to you. If do dont it will get created/built when the project itself is built. But if you go this route you must make sure the project does get built.

      If you do then I would also modify the build script to checkout the content file prior to replacing it. This should get rid of your read/write access errors and also lend itself to your standard version control workflow; i.e. the content file will be in the change set along with all your other modified files.

      We know this is a hot topic. My hope is that we will productize some internal plugins to provide “BOF projects” and a much better BOF development model. I also hope that in the fullness of time we will also revisit how artifact content is managed and make this more user-oriented and inline with standard eclipse “file link” behaviors so that it can handle derived as well as non-derived use cases.

      HTH
      _Paul

  10. Hi Paul,

    First of all, Thanks for this great howto on integrating the BOF java stuff in Composer. I really think this will greatly help development of Documentum systems.

    Secondly, one big issue rises for me in using Composer and this is that it’s not possible (I think?) to install just a single artifact in the repository. Perhaps there are some ant tasks floating around that I could use to install just one artifact (one object type for example, or one module) but I didn’t find a solution yet. Would you happen to know of a solution for this problem? I don’t want to have an IDE where I have to install the complete solution in the repository every time I make a little change to one artifact.

    Thanks again for your posts, they’re really helpful and informative!

    Regards,

    Kees van Bemmel.

  11. Paul,

    Loved this post. I hope you don’t mind, but I’ve linked to this and a few other posts from my new article, Introduction to Documentum Composer, which was recently published to the Blue Fish website.

    Looking forward to more great posts…

    -Jason

  12. Hi Kees,

    It is definitely not possible to install just a single artifact, unless of course you put it in it’s own project.

    Rest assured this is something we are considering. I may post a blog on the alternative to elicit the communities feedback.

  13. Paul,

    We are trying to take advantage to Composer and Subversion to manage our Business Process. We created the process using BPM and then pulled it into Composer so that it can be added to Subversion. However when we checkout the project on the test machine there are errors when we open the Composer project.

    We’re not exactly sure which files to check into Subversion. As Tim Telcik asked in his comment on Oct 6, do we need the content/xx/xxxxxx files? Composer is storing the definition for the custom activity in this directory. Your example above for the jardef changed the location to help bridge the gap between BOF and Workflow. Is there a similar bridge for BPM and Workflow?

    • Hi Craig,

      The rule of thumb is that you check in all source files but ignore all “derived” files. One tip here is that derived files (and folders actually) should be checked as such if you view their properties. Another useful tip when deciding what needs placing under source control is to view the project using the Navigator view so you can see everyhting, rather than some filtered view.

      Artifacts source files (*.type, *.jardef, *.module, *.lifecycle etc), content attached to artifact source files (i.e. content/xx/xxxxxxxx), project model files (i.e. all the dot files at the root of your project) need to be checked in. And also don’t forget the two “managed” source files in the /dar folder too.

      All derived files; /bin/*, /bin-dar, classes, etc can be ignored.

      I will try to document this more thoroughly in an up-coming post. Thanks for the great question.

  14. I just read your post and was trying to implement your suggestions for our Documentum projects. But i discovered some strange behaviour with Composer 6.5SP1. I can change the output folder for Project/src. Default was Web-Services/bin/classes. I can change it to Project/classes, klick ok, but when editing the entry again, it was reset to to Web-Services/bin/classes. I was only able to solve this problem by using a plain ganymede eclipse installation, change the output folder there and then change back to Composer

    • Hi Jorg,

      Thanks for your comments. You appear to be seeing some strange behavior “out-of-the-box” there. A new project should build /src to /bin and /Web Services/src to /Web Services/bin/classes. So, I am not sure how you ended up with different build targets?

      Anyhow, the real problem is that the artifact builder builds its artifacts into /bin which is not right and sadly cant be configured either (yes I have been on at the team about this for months). As-is you would end up with artifacts in your jar! So the easiest solution to this is to build /src to a different target and then jar that up.

      That is all that step really attempts to achieve. There are a few ways to achieve it and it sounds like you managed another way.

      HTH to clarify the situation.
      _Paul

  15. Hi Paul,

    Great article – it gave me the courage to start using Composer. Its been an interesting ride up to now, but with the advent D6.5 SP1, we’re going to take the plunge with a production implementation.

    One thing thats been a rather major irritation to our developers is precisely what Tim Telcik describes above. Do you know if this is being addressed? We had a great deal of fun this week when a old BOF jar was repeatedly being uploaded. It only takes one person to forget to relink the jardef.

    I’ve tried modifying the jardef artifact xml to pick up the original JAR file rather than the copy, but that causes the builder to fail since something is keeping a file handle open.

    Keith

    • Hi Keith,

      Many thanks for taking the time to comment. I am delighted that you are going to give Composer a shot. There is nothing more satisfying for me than user-adoption. I hope that you will find the later release of Composer “less interesting” and more inline with your initial expectations. If it is not then you know where I am.

      I realized that I had not replied to Tim’s comment which I have now done. Please see this comment.

      I do think that replacing the original content file (as opposed to pointing the jardef artifact at a new copy) is a simpler approach. And I’m hoping that adding the “checkout” step to the script will sort out your file handle issue. Please do let me know.

      Many thanks
      _Paul

  16. Hi Paul,
    thank you for a great article: I did manage to implement this integration between Java and Documentum in our first Composer project.
    I also am having the same problem with setting output
    for classes as Jorg described, when the path keeps reverting from Project/classes back to Web-Services/bin/classes as soon as I close the window.

    We, new Composer users, need more documentation on Composer, so please keep doing your great job writing new articles.

    Rima

    • Many thanks Rima. I am glad my article has proved useful to you.

      Just to confirm the problem Jorg originally reported is a regression starting in 6.5 SP1. It has been logged and the engineering team will be addressing it as soon as possible.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s