This plugin integrates the Serena Dimensions CM SCM with Jenkins.
Questions can be asked in the comments section of this wiki page or you can contact Serena Support (email@example.com).
The plugin allows a Jenkins job to be associated with a Dimensions CM stream or project, automatically updating the Jenkins workspace with file content from the Dimensions CM repository.
The plugin currently supports
In new releases of this plugin, we test with the two most recent major versions of Dimensions CM, currently 12.2.x and 14.1.x. The plugin should also work fine with Dimensions CM versions 2009 R1.x, 2009 R2.x and 12.1.x (and older plugins that have been tested with older Dimensions servers are still available to install). This plugin uses the Dimensions CM Java client API to communicate with a specified Dimensions CM server installation and so requires that the Jenkins installation be updated with a number of JAR files from the Dimensions CM installation as documented below.
To add this plugin to a Jenkins installation, the following steps need to be taken:
Failure to follow the above steps will mean the plugin will not operate correctly.
The plugin can be configured to work with Dimensions at both the System level and at the individual job definition level.
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 Jenkins->Configure system configuration page and looking for the Dimensions configuration pane shown below.
The standard Dimensions login details need to be provided in the above fields. This is the Dimensions login that will be used by Jenkins 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 Jenkins.
Checking the Use update toggle will get the plugin to automatically populate your Jenkins workspace with content from Dimensions. If the checkbox is not selected, then the plugin will not automatically populate your workspace.
The Advanced... tag shown below allows you to specify if the Dimensions server installation is running in a different time zone than the current Jenkins 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.
When you create a new Jenkins 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 Jenkins-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 Jenkins Advanced Project Options).
A number of options are provided that can be used to control the behavior of the plugin. These are:
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 Jenkins workspace and specify if item header substitution is to be used.
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 Jenkins build. Options have been added that allow you to:
These options are described in the following sections below.
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).
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:
It is now possible to use a Jenkins 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 Jenkins project using the This build is parameterized option:
This section lists other build options that are available in this plugin.
It is now possible to automatically deploy a tagged baseline from the plugin as the last stage of the Jenkins 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).
It is now possible to automatically action a tagged baseline from the plugin as the last stage of the Jenkins 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.
It is now possible to automatically launch a build in Dimensions Builder using the tagged baseline as part of the last stage of the Jenkins build process. This will initiate a baseline build in Dimensions Builder using build parameters setup in the Jenkins 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:
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.
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.
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.
In version 0.6.8 of the plugin onwards, you can specify the following advanced options when checking in a file
This setting can be configured in the Advanced tab of the job configuration.
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
All file and subdirectory patterns specified should be made relative to the workspace root. For example, if your workspace root is /usr/jenkins/project/build/ and you want to save files from /usr/jenkins/project/build/src/include, then specify a pattern like src/include/.*\.h (this regular expression will only match such files on UNIX machines).
Regular expressions for uploading artifacts should use a directory separator character appropriate for the operating system of the machine where the workspace is located. If the workspace is on a Windows machine then \ is the directory separator character (not /), but \ is also the escape character in regular expressions, so you will need to double up the backslash in your regular expression (like \\) to match a single \ directory separator.
Alternatively you can use the sub-pattern [/\\] to match either the \ or / directory separator character. For example, src[/\\]include[/\\].*\.h means all .h files under the src\include\ or src/include/ directory in the workspace (so will work on both UNIX and Windows machines); and (.+[/\\])?test[/\\]helloworld\.dat means the file helloworld.dat in a subdirectory named test somewhere in the workspace (on either UNIX or Windows). Regular expression matching is very powerful, but can also be very complicated to use correctly, so do find some good documentation and maybe an online regular expression testing tool to check that they actually match the files you expect them to.
Ant-Style Pattern Matches
In version 0.8.5 of the plugin onwards, you also have the option to use Ant-style pattern matches for saving assets to Dimensions. As with the Java style regular expressions, this option allows you to enter a number of patterns based on Ant-style pattern matches. Ant-style patterns can be considerably easier to use correctly than regular expressions (and handle differences in directory separator characters on different operating systems for you).
Inclusion and Exclusion Patterns
As of version 0.8.6 of the plugin onwards, you can now also specify file exclusions as well as inclusions to apply to the files selected for upload.
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 Jenkins 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.
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
This setting can be configured in the Advanced tab of the job configuration.
In version 0.6.7 onwards of the plugin, support has been added for using the distributed build facilities within Jenkins. There are two main capabilities that the plugin provides which can potentially be run on a remote node. These are
To use these distributed capabilities, each remote Jenkins node must have a Dimensions client installation available and in the path. The remote Jenkins support is provided through dmcli, so that remote node must be a platform against which Dimensions is natively supported. If you wish to run Jenkins 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 Jenkins), 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.
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:-
This limitation is resolved in version 0.7.1 of the plugin.
The following are a list of possible future changes to the plugin
Warning: Upgrading to this version means you will have to reconfigure any job which uses the check in artifact functionality.
(Acknowledgments - many thanks to Keith for all his contributions to the above features. His help was much appreciated!)
Skip to end of metadata Go to start of metadata