Overview

This plugin integrates Hudson with Dimensions, the Serena SCM solution.The plugin allows a Hudson job to be associated with a Dimensions Project or Stream, automatically updating the Hudson workspace with content from the Dimensions repository.

Please note - the maintainer for this plugin is no longer myself (TPayne), but is being changed. Until it has been updated, please forward any issues to Paul Caruana (pcaruana@serena.com).

The plugin currently supports

• Polling
• Checkout
• Build change log reporting
• Tagging
• Artifact Upload
• Tag Deployment
• Launching Tagged Builds via Dimensions Builder

Plugin Information

Pre-requisites

This plugin primarily supports Dimensions CM 2009 R1.x and R2. The plugin uses the Dimensions Java client API to interface against a specified Dimensions server installation and so requires that the Hudson installation be updated with a number of JAR files from the Dimensions installation as documented below.

The plugin requires Hudson version 2.0 or above. It may not work correctly with earlier versions.

Installation

To run this plugin against a Hudson installation, the following steps need to be taken:-

• The plugin needs to be installed and enabled using the Hudson plugin manager using the Available tab in the usual manner. The name of the Dimensions plugin to select and install is Dimensions SCM plugin.
• The following Dimensions Java client API JAR files need to be placed into the Hudson class path or dropped into the <Hudson_Home>/WEB-INF/lib directory. These JAR files can be copied from the <DM_ROOT>/java_api/lib/ and <DM_ROOT>/AdminConsole/lib/ directory of your Dimensions server installation.
  • darius.jar
  • dmclient.jar
  • dmfile.jar
  • dmnet.jar

Failure to follow the above steps will mean the plugin will not operate correctly.

Configuring the Plugin

The plugin can be configured to work with Dimensions at both the System level and at the individual job definition level.

System Configuration

Configuring the plugin at the system level allows you to define a default Dimensions installation which can be used as the default for every job. This default installation can be configured by opening the Manage Hudson->Configure system configuration page and looking for the Dimensions configuration pane shown below.

Dimensions Login Details

The standard Dimensions login details need to be provided in the above fields. This is the Dimensions login that will be used by Hudson to connect to the Dimensions repository and retrieve any updated files. A Check Connection... button is provided for your convenience to ensure the connection details you have specified are correct and can be used by Hudson.

---

---

Checking the Use update toggle will get the plugin to automatically populate your Hudson workspace with content from Dimensions. If the checkbox is not selected, then the plugin will not automatically populate your workspace.

Advanced Options

The Advanced... tag shown below allows you to specify if the Dimensions server installation is running in a different time zone than the current Hudson installation. This is useful if you are running in a geographically distributed environment.

---

---

The Advanced... tag also allows you to specify an optional Dimensions Web client installation that can be used to directly access files in Dimensions to perform Dimensions operations on them via the Web client.

Job Configuration

When you create a new Hudson job, you need to configure the Dimensions stream or project that this job will be monitoring. This can be done using the standard job Configure. page.

Using the Source Code Management pane, select the Dimensions option and fill in the details shown below with the Dimensions project that this job will use.

---

---

The Project Name must refer to the Dimensions project or stream that this job will monitor. This is a mandatory field.

The Folder Name refers to a specific folder name in the Dimensions project or stream that the job can monitor. This should be specified in UNIX format and represent the high-level folder from which files will be monitored. If you leave this field blank or specify '/', then all the contents of the project/stream will be monitored. You can specify multiple folders to monitor or just leave it blank to monitor everything.

The Workspace Location specifies a particular workspace location to which Dimensions will put any updated files. If this field is left blank, then the default Hudson-provided workspace will be used. (Note: As of release 0.7.7, this option has been removed from the GUI and is now ignored. You can configure a custom workspace location using the Hudson Advanced Project Options).

A number of options are provided that can be used to control the behavior of the plugin. These are:

• Clear the contents of the workspace – checking this option will delete the full contents of the workspace before using Dimensions to repopulate it. The use of this option is not recommended for very large projects as it can significantly increase the build time
• Always force a build to occur – checking this option will ignore any errors or file conflicts reported by the plugin and always force the build to be started. If this option is not selected, then any errors or conflicts reported by the plugin will automatically abort the build.
• Overwrite any locally modified files in workspace – checking this option will automatically overwrite any files that may have been modified in the local workspace with files that come from Dimensions. The use of this option is not recommended if you are using Hudson to build workspaces that have content that might conflict with that stored in the Dimensions repository.

An Advanced... tag allows you to override any of the default Dimensions installation details specified in the system configuration. The options provided are the same as document in the System Configuration section above. Options are also provided to control the permissions on files that are checked out into the Hudson workspace and specify if item header substitution is to be used.

Job Build Options

In version 0.6 onwards of the plugin, enhanced support has been added for release builds that provide tighter control over the content that goes into a Hudson build. Options have been added that allow you to:

• Lock a project or stream while a build is in progress
• Tag a successful build such that a baseline is automatically created in the Dimensions repository on build completion
• Use a parametrized build to specify a baseline to build, rather than a project
• Use a parametrized build to specify a list of requests to build, rather than a project.

These options are described in the following sections below.

Locking a Project while a build is running

It is now possible to lock a Dimensions project or stream while a build is being run, such that no changes maybe made to that project (or stream) until the build has finished. This option is provided so that long running builds can be assured that the state of the Dimensions project that they are building does not change while the build is in progress. This option should be set if the build process interacts with Dimensions once the initial checkout is complete and the state of the project needs to be consistent with the assets being built.

An example of this might be if the build process does a deployment or release step from Dimensions as part of the build.

This option can be enabled or disabled via the Lock Dimensions project while the build is in progress flag under the Build Environment options.

(Note - This option must be set if you intend to tag a successful build. Failure to do so will automatically fail that build).

Tagging a Successful build in Dimensions

It is now possible to tag a successful build in Dimensions, such that a baseline is automatically created to represent the state of the project or stream that was just built. This option is provided so that release or checkpoint builds can automatically be tagged in Dimensions to have an asset that represents that build.

This option can be enabled or disabled via the Tag successful builds in Dimensions as a baseline flag under the Post-build Actions options.

An Advanced... tag is present that allows you to change the type of baseline that is created by the tagging process. By default, the tagging process will create a project baseline, but support is also present for creating template driven baselines as well. The options that are currently supported are:

• Owning baseline part - This is the name of the Dimensions part that will own the baseline
• Baseline template - This is the name of the baseline template which will be used to create the baseline. Currently, only item templates are supported. Other template types maybe added in a future release.
• Baseline Scope - This states the type of baseline to be created - either a part scoped, project scoped or revised baseline. Currently, you should only use baseline templates and owning parts with part scoped baselines. Project driven baselines do not support templates or owning parts and specifying these options will be ignored by the plugin. Revised baselines will only work if you have setup your build to be parametrized and provide DM_BASELINE and DM_TARGET_REQUEST as input into the build. DM_BASELINE will be used as the source baseline and DM_TARGET_REQUEST will be used as the list of requests that are used to create the new revised baseline.
• Baseline Type - This is the name of the user defined baseline type against which the baseline will be created. The default is baseline.

Using Parametrized Builds

It is now possible to use a Hudson build project to build both baselines and requests using parameters that are provided to each build when it is being run. This functionality has been added to allow a common build configuration to be used for repeated release and patch type builds if necessary, rather than using a named project which may also contain other unwanted changes. This functionality can be enabled by adding the following parameters to a Hudson project using the This build is parameterized option:

• DM_BASELINE - this string parameter will allow you to specify a Dimensions baseline which will be used as the source for the build, rather than the usual project. Specifying this option will override any project sources that might have been defined, all other options however will be honored as per usual. This option should be used if you intend to perform a release build from a known baseline of code.

• DM_REQUEST - this string parameter will allow you to specify a list of Dimensions requests (comma separated) which will be used as the source for the build, rather than the usual project. Specifying this option will override any project or baseline sources that might have been defined, all other options however - with the exception of folder filters - will be honored as per usual. This option should be used if you intend to apply a patch or list of patches to an existing area or are building specific controlled features that have been controlled by requests. Dependency relationships between requests will automatically be processed and any child requests be included in the build. When using this option, the Dimensions project specified in the job configuration will be used to select those in-response-to items that are relevant. If a request has changed files related to it that are not in the Dimensions project, then these changes will be ignored. Note - If you are using this functionality against a Dimensions 10.1.3 server, then the functionality that is offered by this parameter is limited to the capabilities present in Dimensions 10.1.3. For example, refactoring support is not offered, files will always be checked out as read-only and if you specify multiple requests to process, then each request will be checked out separately which might cause file versions to conflict with each other. If you wish to use this functionality, it is strongly suggested that you upgrade to Dimensions 2009 R1+.

• DM_TARGET_REQUEST - this string parameter will allow you to specify a list of Dimensions requests (comma separated) which will be used to relate any assets against that get checked into Dimensions as a result of a build. This refers primarily to build steps that use Dimensions Builder and post build actions such as building a tagged baseline and loading assets into Dimensions.

Other Job Build Options

This section lists other build options that are available in this plugin.

Deploying Tagged Baselines in Dimensions

It is now possible to automatically deploy a tagged baseline from the plugin as the last stage of the Hudson build process. This will initiate a deployment of the contents of the baseline to all the deployment nodes associated with a deployment stage and the running of any deployment pre/post scripts. The plugin does this by running the Deploy Baseline command (DPB) and returning any results that this command generates.

This option can be enabled or disabled via the Automatically deploy the baseline flag under the Post-build Actions options. This option will only be presented if the Tag successful builds in Dimensions as a baseline flag is checked.  You will also be able to specify the stage you want the baseline to be deployed to. If you do not specify a stage, then the next one will be used automatically.

(Note - For the deployment to succeed the project being used as a source for the build must be configured to allow baseline deployment).

Actioning Tagged Baselines in Dimensions

It is now possible to automatically action a tagged baseline from the plugin as the last stage of the Hudson build process. This will action the tagged baseline to a given lifecycle state in Dimensions. The plugin does this by running the Action Baseline command (ABL) and returning any results that this command generates.

This option can be enabled or disabled via the Automatically action the baseline flag under the Post-build Actions options. This option will only be presented if the Tag successful builds in Dimensions as a baseline flag is checked.  You will also be able to specify the lifecycle state you want the baseline to be actioned to. If you do not specify a state, then the next one will be used automatically.

Launching Dimension Builder with Tagged Baselines

It is now possible to automatically launch a build in Dimensions Builder using the tagged baseline as part of the last stage of the Hudson build process. This will initiate a baseline build in Dimensions Builder using build parameters setup in the Hudson job configuration. The plugin does this by running the Build Baseline command (BLDB) and returning any results that this command generates.

This option can be enabled or disabled via the Automatically build the baseline flag under the Post-build Actions options. This option will only be presented if the Tag successful builds in Dimensions as a baseline flag is checked.  You are also able to specify -

• the Dimensions Build area you want to use
• the Dimensions Build configuration to use
• the Dimensions Build options
• the Dimensions Build targets
• if to run the build in background mode
• if to perform a clean build
• if to capture build outputs and build dependencies under Dimensions.

This option should be selected if you want to use Dimensions Builder within your build process. For example, to perform multi-platform release builds for the tagged baseline under strict Dimensions control.

Saving Build Artifacts into Dimensions

It is now possible to save assets that have been created as a result of a build process into Dimensions. This option can be enabled or disabled via the Load any build artifacts into the Dimensions repository flag under the Post-build Actions options.

Activating this checkbox will give you the opportunity to enter a series of Java style regular expression patterns that will be used to determine which files in your workspace you want to consider for saving into Dimensions. For example, patterns like

• .*.obj - will consider all .obj files
• .*.h - will consider all .h files
• src/.*.h - will consider all .h files in the src/ subdirectory (UNIX).

All file and sub-directory patterns specified should be made relative to the workspace root. For example, if your workspace root is /usr/hudson/project/build/ and you want to save files from /usr/hudson/project/build/src/include, then specify a pattern like src/include/.*.h.

All directory and sub-directory references must use native OS directory separators.

Artifacts which have been identified for loading into Dimensions will then be put into the project that the plugin is monitoring using DELIVER or UPLOAD command as appropriate. If you specify files that are already under control and have not changed, then these files will be ignored. If you wish to specify a request to save these changes against, then you should set a project default request using SCWS or use DM_TARGET_REQUEST as commented on above.

(Note - For specifying rules on a Windows system, please refer to the plugin help for how to use '\'. It needs to be protected by doubling the '\' up).

For more information on the capabilities of regular expression pattern matching, please refer to the appropriate help documentation.

In version 0.6.8 of the plugin onwards, you can specify the following advanced options when checking in a file

• Force files to be checked onto the tip - This will force uncontrolled files with the same name as existing Dimensions files to be loaded into the repository and placed onto the tip even if they are completely unrelated to files already present
• Force files to be recorded as merged- This will force files which might contain revision conflicts to be loaded into the repository and recorded as being merged even though no physical code merge has taken place
• Owning part for files - this will put all new files under the Dimensions part specified.

This setting can be configured in the Advanced tab of the job configuration.

Specifying Dimensions Requests to Capture Uploaded Artifacts or Build Assets

If you are loading build artifacts into Dimensions using the Load any build artifacts into the Dimensions repository or Automatically build the baseline options and want to specify Dimensions requests against which to capture these changes, you can now do so by defining a Hudson build parameter called DM_TARGET_REQUEST. When you then start a build, populate this parameter with the comma separated list of requests that you wish to use and these will be passed on to the appropriate Dimensions commands.

Specifying Permissions of Checked Files

In version 0.6.8 of the plugin onwards, it is possible to specify the permissions of the files which are being checked out as part of the job configuration. This includes

• Default permissions - the file's default permissions stored in Dimensions
• Read-only - setting all the files to read only
• Writeable - setting all the files to writeable.

This setting can be configured in the Advanced tab of the job configuration.

Distributed Build Support

In version 0.6.7 onwards of the plugin, support has been added for using the distributed build facilities within Hudson. There are two main capabilities that the plugin provides which can potentially be run on a remote node. These are

• Checking files out of the project/stream being monitored into a workspace, and
• Checking files into the project/stream being monitored from the workspace

To use these distributed capabilities, each remote Hudson node must have a Dimensions client installation available and in the path. The remote Hudson support is provided through dmcli, so that remote node must be a platform against which Dimensions is natively supported. If you wish to run Hudson on an unsupported platform - such as Mac OS - then you can only use that platform as a master node. The master node support is Java based, so as long as that platform supports Java (and Hudson), it should work. However, running the plugin on an unsupported platform in this way is purely at your own risk. No responsibility is taken or implied about how the plugin will behave in these conditions.

Security limitations

If you run in a secure environment, then you need to be aware of one current limitation which is present in the plugin for distributed support. As the plugin is using dmcli on the slave to run Dimensions commands, the login details of the Dimensions user configured in the build job are temporarily written to a parameter file on the slave which is then used to run Dimensions commands. This parameter file is persisted until the job finishes. The location of this parameter file is displayed as the build progresses, so a knowledgeable individual with access to the slave could access this file whilst the job is in progress and obtain these login credentials. If this is a security concern, then it is advised that either:-

• you make the slave machine user's default temporary-file directory inaccessible to unauthorized users
• configure the Dimensions user referenced in the job to have a very limited set of privileges, or
• run the build on the master only

This limitation is resolved in version 0.7.1 of the plugin.

Known Issues

The following are a list of the current known issues and limitations with this plugin

• The plugin has had limited validation in a distributed environment using Windows masters/slaves running Dimensions 2009 R2 only. It has not been validated against Dimensions 10.x or Unix slaves. If there are any issues with these additional configurations, please email the specific details and they will be corrected in the next release.
• The plugin will work against Dimensions 10.x servers, but does require Dimensions Java client API JAR files from a Dimensions 2009+ server installation to work correctly.
• Upgrading between plugin versions may sometimes give an error like FATAL: Unable to run checkout callout - null, when running a job. If this occurs, simply open the job configuration and resave it. This should resolve the issue.
• All Dimensions related operations must be run by users who have the privilege to do that operation. If the user does not have the necessary permissions, then the Dimensions operations will fail.
• The latest version of the plugin now requires Hudson version 2.0 or above. It may not work correctly with earlier versions
• Loading build artifacts into Dimensions will not process controlled files which have been deleted, i.e. the deleted files will not be removed from the repository.
• Earlier versions of the plugin, i.e. 0.7.8/9 are only supported against Hudson 1.389-90. Later versions were found to have intermittent issues.

Hudson & Jenkins - An initial statement of intent

Given the recent fork in Hudson to become Hudson and Jenkins, a number of questions have been asked about which fork this plugin will continue to support. While the situation is still a little unclear about how Hudson and Jenkins will interact with each other and what their associated infrastructures will be, the intention is to continue to support both forks as long as it is practically feasible.

Going by what is currently being said by both camps, the plugin architecture will remain pretty much unchanged, so as long as it is practical - and the code bases do not fork significantly - both will be supported going forward. Of course, this intention will be reviewed on an ongoing basis as the situation between Hudson and Jenkins becomes more clear.

Up and Coming Changes

The following are a list of possible fixes and enhancement(s) to be added to the next version of the plugin

• Documentation: Update the wiki with new screen dumps for improved options and document best practices
• Enhancement: Code diff'ing from the change logs
• Enhancement: Timeout on job polling
• Bugfix: Change-set generation to handle HTTPS
• Bugfix: Compatibility issues with 1.391+
• Enhancement: Check-in artifacts to support ANT regex
• Enhancement: Check-in artifacts to support requests

Version History

0.8.1/2 – Apr, 2010

• Bugfix: Incorporate fix for copying Dimensions plugin information around between jobs
• Enhancement: Support for NOTOUCH option
• Bring code in synch with Jenkins release

0.7.8/9 – Dec, 2010

• Enhancement: Add DM_BASELINE to the baseline id template
• Enhancement: Incorporate EOL changes
• Enhancement: Polling to support 1.345+
• Enhancement: Upgrade Hudson architecture support to latest version
• Bugfix/Enhancement: Allow slave processing to also be run on the master
• Bugfix: Correct command handling on Unix slaves for checkout/checkin tasks, e.g. /TMP invalid qualifier error.

0.7.7 – May, 2010

• Enhancement: Remove "workspace location" text box. It is not needed and just confuses issues. This option has been removed from the GUI and is now ignored. You can configure a custom workspace location using the Hudson Advanced Project Options
• Enhancement: Using a template pattern to allow the customization of the baseline identifier and type that gets created

0.7.6 – April, 2010

• Bugfix/Enhancement: Changes to polling support for monitoring sub-directories.

0.7.5 – April, 2010

• Enhancement: Enable no metadata as an option for checkout

0.7.4 – April, 2010

• Enhancement: Support for revised baselines using DM_BASELINE (source) and DM_TARGET_REQUEST
  (revised with)

0.7.3 – April, 2010

• Enhancement: Enable IHS expansion as an option for checkout

0.7.2 – April, 2010

• Bugfix: Request based download does not work for Dimensions 10.1.3 as there is a command incompatibility. A different mechanism is needed for 10.1.3 servers using FCDI
• Enhancement: Add baseline type parameter for tagging
• Bugfix: When create new job, set update to match what is in the global config on "Save"

0.7.1 – February, 2010

• Bugfix: Remove project baseline references from some help/error tags and call baseline instead
• Enhancement: Mask command parameters where appropriate for DMCLI slave node operations
• Enhancement: If project baseline specified, then ignore invalid parameters when executing the command. Avoids unnecessary build failure. Update help to show this

0.7.0 – February, 2010

• Enhancement: When tagging a project, optionally specify a template, part and scope that could be used

0.6.9 – February, 2010

• Bugfix: Request based checkouts with multiple directory filters does multiple checkouts. It should not as request checkout ignores directories
• Bugfix: Correct issue with config cache when project id changed
• Bugfix: Artifact upload has a compatibility issue with Dimensions 10.1.3, generates
  "FATAL: Unable to load build artifacts into Dimensions - Invalid attribute: -AdmAttrNames.wset_is_stream" error
• Enhancement: Add support for distributed build environments - artifact uploading

0.6.8 – February, 2010

• Enhancement: When checking out from a project allow the permissions on the file to be set to readonly, writable or default
• Enhancement: When checking in from a workspace, allow the check to be forced if file conflicts are detected
• Enhancement: When checking in from a workspace, allow the owning part to be specified rather than the defaults setup in the upload rules

0.6.7 – February, 2010

• Enhancement: Adding Dimensions Builder as a valid build step
• Enhancement: Be more verbose about what steps the plugin is currently doing during checkout process
• Enhancement: Add support for distributed build environments - checkout operations only
• Bugfix: The order of the GUI "Automatically build the baseline" and "Automatically deploy the baseline"in the job configuration needs to be swapped around. The deploy is done before the build and the order in the GUI implies the other order.
• Bugfix: Resolve a problem with the Dimensions connection getting nulled when long jobs are running and polls on that same job are performed in rapid succession resulting in strange exceptions being fired.
• Enhancement: Generate a set of change logs even when the plugin is not being used to update the Hudson workspace.
• Bugfix: Fix spelling mistake with "Files to Montor" in main job config.jelly.

0.6.6 – January, 2010

• Enhancement: When Dimensions post-action fails, fail the build

0.6.4 – January, 2010

• Bugfix: Fix compatibility issue with Maven Integration Plugin.

0.6.3 – January, 2010

• Enhancement: Add integration to Dimensions Build to allow the launching of a Dimensions build on the tagged baseline
• Enhancement: Actioning of baseline in Dimensions

0.6.2 – January, 2010

• Enhancement: Deployment of baseline in Dimensions

0.6.1 – December, 2009

• Bugfix: Don't overwrite change log for build if multiple project directories are being used - append them, so full change list is given for all directories
• Enhancement: Give the ability to upload build artifacts into Dimensions stream/project based on 1:N regex patterns
• Bugfix: If plugins attempted to use with non-Dimensions SCM engine, then abort.

0.6.0 – December, 2009

• Enhancement: Add the ability to checkout a given baseline or request instead of a project/stream
• Bugfix: Report no changes when no changes made in a build rather than Failed to determine log
• Enhancement: Add the ability to lock a project during the build process
• Enhancement: Add the ability to tag a successful build
• Enhancement: For a given build, enhance the change set processing to list the requests that were used to create the new files that went into a build.
• Enhancement: Make the change set reporting use drop down lists rather than static lists. Easier to hide unwanted content.
• Bugfix: Correctly unregister connections from the Dimensions java thread pool.
• Enhancement: Tag all messages from the plugin with the [DIMENSIONS] prefix
• Bugfix: Tidy up output of messages
• Enhancement: When performing an initial build for the first time, cleanup the target workspace so that only assets from the build are present, not other uncontrolled files
• Enhancement: Expand on what update means in the boiler plate

(Acknowledgments - many thanks to Keith for all his contributions to the above features. His help was much appreciated!)

0.5.8 – December, 2009

• Enhancement: Add ability to monitor multiple directories in the repository

0.5.7 – November, 2009

• Bugfix: Fixed broken URL link issue
• Enhancement: Removed unnecessary exception stack printing on Dimensions errors

0.5.6 – November, 2009

• Enhancement: Support added for Dimensions 10.x servers

0.5.4 – November, 2009

• Release of the initial version