Integrating CA Software Change Manager with a Java EE application

CA’s Software Change Manager is a tool that we use to manage software and documents.  Although much of our development staff is using GIT, many of our engineers still use SCM (or Harvest as it used to be known).  The primary way our web applications use Harvest is as a version controlled repository for documents.  Our web apps can link directly to the latest versions of documents and can even allow our users to checkout and modify documents through the web.  I’d like to share some of the techniques we’ve used to build a relationship between a Java EE application apps and Harvest.

The obvious choice for using Harvest with java is the JHSDK (Java Harvest SDK).  But through trial and error, I’ve learned that JHSDK fails in Java EE because it’s classes are not thread safe.  At the CA World conference a few years ago, I had the privilege of consulting with the father of Harvest (can’t remember his name) about this problem.  He said that I have two options, make the API thread safe or just make system calls to the command line interface (Harvest CLI).  Not knowing exactly how to make the API thread safe, I chose the latter.  It has never failed us.

Things to consider when designing a Harvest-related web app:

1.  The server on which your app server resides must have a Harvest client installed.   You’re essentially creating an automated Harvest user in your web app.

2.  Because you’re using a CLI instead of JHSDK, you have to retrieve errors and exceptions by reading logs.  Each Harvest command creates its own log file on the server.  So you have to manage log files in real time.  We create a new log file with a new random name with every command.  After the command runs, we check the log messages so that we can send the messages (including errors) back to the browser.  And finally, we delete the log file.  This is handled differently for asynchronous calls (see #5).

3.  Each Harvest command must contain user credentials.  When the user logs in, you could capture his/her username and password, but this isn’t very secure.  Ultimately, you want to use an auth file on the server.  This can be generated with a command using the username and password one time and never again (unless the password changes).  You name the auth file after the user name and then you can reference it anytime you need it.  The svrenc command looks like this:

String[] command = new String[11];
int i = 0;
command[i++] = “svrenc”;
command[i++] = “-f”;
command[i++] = userName+”.auth”;
command[i++] = “-usr”;
command[i++] = userName;
command[i++] = “-pw”;
command[i++] = password;
command[i++] = “-dir”;
command[i++] = siService.getAuthRootPath();
command[i++] = “-o”;
command[i++] = log;

4.  Building commands can be error prone if it’s done in one big String.  Fortunately, Java’s Runtime class takes a String array.  It’s best to build your commands this way. (see above example for building a command)

5.  Commands can be run asynchronously for long-running processes by putting the command into a thread.  As the thread runs it writes the progress of the log file output into the database and the client polls it with AJAX calls.  That way you can show progress on the process.

6.  When the user needs to view a file, it’s easier and quicker to use SQL rather than the hco command to get a blob and stream it out to the browser

7.  When the user needs to checkout a file (hci command), you’re checking it out to the server’s file system then streaming a copy of that file back to the web browser.

8.  To check in a file, upload the file through the web browser to the exact spot where it was checked out to, then run the hco command on it.

9.  Finally, use the documentation.  It comes with your installation and is called “CA Software Change Manager Command Line Reference Guide”.  Everything you can do with the SCM client can be done via the CLI, and therefore can be done in a web app.

Integrating your web apps with CA SCM can be a very powerful asset to your users.  We allow users to list, view, and manage files, promote/demote packages, edit forms, create comments, and approve/deny packages.  We had hoped that CA would be a decent web version of SCM, but it never happened, so we built the parts that we need.  We’ve been very successful, and using CLI calls has been very reliable.

Step 2: Set up a Repository

Before you can load a baseline for your release, you have to set up a place to put it.   In CA SCM, this is called a Repository.   The definition of Repository in the documentation is very simple:

A repository is a collection of items and item paths

You can think of Items as files and item paths as folders.  In truth, an item is  the information about a single Configuration Item.  The file itself, is always a Version of an Item.   So a repository is a collection of Items and their Versions organized with Item Paths.

An administrator can load files into a repository with the admin tool, but the only way a regular user can affect a repository is through Packages in a Life Cycle. What’s really cool is that a Repository can be associated with one or more Life Cycles.   So you might have different kinds of processes that manage change on the same configuration items.   This way, you don’t have to create one MONSTER process to manage everything.  You can design Life Cycles that manage your various processes from Service Desk, to Release Management, to Maintenance, etc.

Steps to Setting up a Repository:

  1. Login to CA SCM Administrator and select the Repositories tab

    CA SCM Administator Repository Tab

    CA SCM Administator Repository Tab

  2. Right-click the broker node and select New Repository

    Right-Click Broker node

    Right-Click Broker node

  3. Give your Repository a unique name.   Ok, this is a good time talk about a choice you need to make.  Will your repository be used over and over again for many iterations and have a long trail of versions?  Or will it retain only the development iterations on a single release?  In my case, I’m focused on the development of a single release, so my repository name will be the name of my release.

    Repository Properties Dialog

    Repository Properties Dialog

  4. Click Apply
  5. Setup Access to your repository.  Click the Access tab of the Repository Dialog.   Note that there are three Access Types in the drop-down field:  Secure Access, Update Access, and View Access.  I’m not sure what Secure Access is.  I just set it to the Administrator group.  Update Access needs to go to your developers.  View Access needs to go to your developers and any other group that needs to view the code.
  6. Click Ok.  Congratulations, you have a place to put your crap.
  7. Load your Baseline into the repository.   If you’re using Eclipse and the CA SCM Plugin, it’s important that you load each entire Eclipse project that you are using to work with your software.  Right-click your Repository node and select Load Repository.  This will bring up the Load Repository Dialog
    Load Repository Dialog

    Load Repository Dialog

    Browse out to your local machine to find the files that will make your baseline.  Check Recursive so that you can get all the files and folders in you projects.  Use “*” in the Files field to get all file types.  If you set up some subfolders in your Repository for this project or that, your can specify them in your Repository Path field.

    NOTE:  You can create a repository by duplicating another repository, so the files from your last release are already loaded.

  8. Click Load and watch it go!

CRUCIAL STEP

Just because you have a place to put your crap, doesn’t mean you have access to it from your Life Cycle.   The key to CA SCM is Association.  This is what gives the tool it’s flexibility.  You must add your repository to the Baseline of your Life Cycle.

  1. Navigate to the Baseline node of your Life Cycle

    Baseline Node

    Baseline Node

  2. Right-click node and select Configure Baseline
    fig35
  3. Add one or more Repositories from the Available Repository/View List

    Configure Baseline Dialog

    Configure Baseline Dialog

Woo Hoo!   Now, this is where it gets fun!