Team Concert Plugin

Note	View this help page on GitHub README.adoc if you encounter issues with link navigation.

Integrates Jenkins with Rational Team Concert source control and build using the richer features of the build toolkit instead of the command line.

With the build toolkit this plugin adds traceability links from a Jenkins build to an RTC build result, workspace and snapshot. It also publishes links to work items, change sets and file contents captured in the snapshot. It leverages the current RTC features and workflows that users are already familiar with such as,mails, toaster popups, reporting, dashboards, etc.

Table of Contents

Documentation
Known Limitations
Known Limitations with fixes in newer releases of RTC
Tutorial
Best Practices
References
Releases
Migrations
- 1.1.9
- 1.1.2
- 1.0.10
Security Warnings
- 1.3.0 or older

Documentation

Product Name Change

As of 7.0 release, Rational Team Concert is now called Engineering Workflow Management. Team Concert Plugin supports RTC releases 6.0 to 6.0.6.1 and EWM releases 7.0 to 7.0.2. In this documentation, wherever you find Rational Team Concert(RTC), you can substitute it with Engineering Workflow Management (EWM)

Rational Team Concert Help Topics

Requirements

Jenkins

Team Concert Plugin v 2.1.0 or later requires Jenkins 2.60.1 or later, Java 8 or later. Jenkins 2.277.1 LTS has been tested with the latest release.
Team Concert Plugin v 1.2.0.5 or later requires Jenkins 1.625.1 or later. Fix for JENKINS-26100 requires Jenkins 2.60 or later, workflow-job 2.12 or later.
Team Concert Plugin v 1.1.9.3 till v 1.2.0.4 requires Jenkins 1.580.1 or later.
Team Concert Plugin v 1.1.2 and later depends on the Jenkins Credentials plugin version 1.10 or later.

RTC

This plugin requires Rational Team Concert Build Toolkit version 6.0 or newer. Older versions of the plugin supports build toolkit versions starting from 3.0.1.5. See the Installing the Build System Toolkit help topic to learn how to install the build toolkit.
For all the supported build configurations - Build Definition, Repository Workspace, Stream and Snapshot - a valid build toolkit should be present on both the master and agent machines and the Jenkins jobs should be configured to use this toolkit.
Some features depend on specific Rational Team Concert build toolkit or server versions. See below.
- Stream configuration works only from build toolkit v 5.0.2 or higher.
- Post Build Deliver for Build Definition configuration introduced in Team Concert Plugin v. 1.2.0.3 depends on Rational Team Concert server version 6.0.4 or higher.
- Support for Load Rules in build definition has some requirements on the version of RTC client used to create the build definition. See Load Rules Support section for more details.
- If you will be fetching workspaces that contain symbolic links, there is some additional symbolic link setup required. See Symbolic Link Support section for more details.
- Version details of build toolkit can be obtained in the build log only if you are using build toolkit version 6.0 and above.

Jenkins Configuration

Add a new Build Toolkit

Navigate to the Jenkins Global Tool configure page (Jenkins > Manage Jenkins > Global Tool Configuration) and find the "RTC Build toolkit" section. This section is used to define one or more build toolkits available to the plugin. If you are using Jenkins 1.x, this will be under (Jenkins → Manage Jenkins → Configure System)
Click the "RTC Build toolkit installations…" button and add a new build toolkit.
1. See the Installing the Build System Toolkit help topic to learn how to install the build toolkit.
2. There can be multiple RTC build toolkits associated with one jenkins instance.
Click the "Apply" button to apply the changes.

Update RTC Global Configuration

Navigate to the Jenkins Global Configuration page (Manage Jenkins → Configure System).
Find the "Rational Team Concert (RTC)" section. This section is used to define global connection settings that will be the defaults for any jobs created with the plugin. If connection settings will be set on each job, then skip this section.
Select a build toolkit
Credentials are managed by the Credentials plugin. The Team Concert plugin supports username and password type credentials. Credentials can be defined within a domain or a folder (if you are using the folder’s plugin). You can use an application password in place of a regular password.
Choose the credentials to use when logging into RTC for polling and accepting/loading the source code.
- If you are using the 1.0.12 (or earlier) version of the Team Concert plugin, instead of credentials, you will need to supply a userId and password or password file.
Click the "Test connection" button to verify the repository connection details.
Click the Save button to save the settings and return to the Jenkins main page.

Job Configuration - FreeStyle job

Note	This section shows how to configure Team Concert Plugin in a freestyle job to load source code from RTC SCM.

Create a new free-style software project and find the Source Code Management section.
Select "Rational Team Concert (RTC)".
If global connection settings were not configured above or do not apply to this job, then check the Override global RTC repository connection check box and enter the connection settings here.
Click the "Test connection" button to verify the repository connection details.
Prior to 1.2.0.0 a job can be configured with RTC SCM only using either a build definition or a repository workspace. From 1.2.0.0 there is support to configure RTC SCM with a SCM stream or SCM snapshot.

Configuring for Build Definition

To benefit most from the integration between this plugin and RTC Build, select "Build Definition" from the Build Configuration dropdown and enter a build definition ID. See the Hudson/Jenkins build engine type help topic to learn how to create a Jenkins build definition. Follow these steps to setup a Jenkins Build Definition and Jenkins Job to avoid a catch-22 situation. A Jenkins job requires a Hudson/Jenkins build definition and a Hudson/Jenkins build definition requires a Jenkins job. RTC actually won’t let you save the build definition without a job selected. However, Jenkins will let you save a job without a build definition. So it is important to configure your build definition and job this way.
1. In Jenkins, create the job first using RTC for source control, but with no build definition. Leave the Build Definition text box blank.
2. Save the Jenkins Job.
3. In RTC, create a Jenkins build engine that connects to the Jenkins server. See Creating a build engine. In RTC, create a build definition that uses the build engine created in step b and select the job created in step a. See Creating a build definition
4. Lastly, in Jenkins, open the Jenkins job and set the Build Definition field with the id of the build definition created in step c.
5. Notice the "Build Configuration" dropdown. This replaces the radio buttons for build definition and build workspace prior to version 1.2.0.0 of the Team Concert Plugin.
6. Click the "Validate" button to verify the RTC build definition exists.

Configuring for Repository workspace

To load a RTC repository workspace into the Jenkins workspace, select "Build Workspace" from the Build Configuration dropdown. See Dedicated build workspaces help topic to learn how to create a build workspace.
Click the "Validate" button to verify the RTC build workspace exists.
To add a "Related Artifact" link to a Jenkins build in all the included work items, select the option Add Jenkins build link to accepted work items option.

Configuring for Snapshot

To load the jenkins build workspace using a snapshot, select "Build Snapshot" from the Build Configuration dropdown. This configuration is mainly intended to be used in builds that capture the current state of the RTC SCM workspace/stream in a snapshot and start downstream builds that would populate the jenkins build workspace from the snapshot created and passed from the upstream builds.
NOTE:To start a downstream snapshot build Parameterized Trigger plugin is required.
The following steps show how to configure a parent Jenkins job to trigger a downstream Jenkins job. The parent job is configured to use Build Definition, Repository Workspace or SCM stream. The downstream job is configured to use SCM snapshot. The parent job triggers the downstream job, passing a snapshot UUID that will be used to load the sources.
1. Consider a parent job that is configured to load from a RTC repository workspace. When the build runs, Team Concert Jenkins plugin creates a snapshot on the build workspace. The snapshot uuid is available as the build environment property team_scm_snapshotUUID.
  1. Add a post build action to trigger parametrized build on other projects.
2. Configure a downstream snapshot build
  1. Create a new job and with a string parameter named rtcBuildSnapshot. You can use any parameter name for this purpose.
  2. Configure Rational Team Concert under Source Control options to build from a snapshot.
3. Now when an upstream build is started and once it is done it will trigger the downstream build with the UUID of the snapshot created on the workspace.
  NOTE: Generation of change log and polling is not supported for Snapshot configuration.

Configuring for Stream

To load the jenkins build workspace using a stream, select "Build Stream" from the Build Configuration dropdown.
Click the "Validate" button to verify the build stream exists.
This configuration supports building from the current state of the specified stream.
Subsequent builds capture the changes made to the stream since the previous build.
In this configuration change log can be chosen to be generated by comparing the current build with the previous successful build. By default this option is unchecked.
NOTE: For this configuration the RTC user configured globally or for this job needs to have permission to attach snapshots to a stream.

Load Options

From 1.2.0.0 some of the load and accept options that were previously configurable only in RTC build definitions, can now be configured for Repository Workspace, Stream and Snapshot configurations.

The directory on the build machine under which the repository files will be loaded can be specified.
Contents of the load directory can be deleted before reloading
Load Policy field, added in 1.2.0.4, can be used to configure the components to load. You can either specify the components to load or choose to use a remote load rule file or dynamic load rules, to determine which components to load.
1. Specify which components to load
2. When specifying components to load you can choose to create folders for components, in which case the load directory would have folders for components at the top level and each of these folders will have the files/folders for that component.
3. You can also choose to exclude some components.
4. Load components by using a load rule file
5. Load using dynamic load rules
  
  Note
  For more details on load rules support and how to configure dynamic load rules, see the Load Rules Support section.

Accept Options

Note	Applicable only to Repository workspace configuration

When loading the jenkins build workspace from a RTC repository workspace, there is an option to configure whether to accept latest changes before loading. By default, this option is selected.

Traceability Options

Note	Applicable only to Repository workspace and Stream configuration

To add a Related Artifact link to a Jenkins build in all the included work items, select the option "Add Jenkins build link to accepted work items" option. This applies to Repository Workspace and Stream configurations.

Build Triggers

Triggering builds by polling for changes

When Poll SCM is selected, builds will be triggered only if Team Concert Plugin detects new changes. The logic for computing of new changes varies for Build Definition, Repository Workspace and Stream configurations. For Build Definition and Repository Workspace, Team Concert Plugin compares the repository workspace against the flow targets. In case of Stream, the snapshot from the previous build is compared against the stream. If the previous build does not have a snapshot, then the build previous to that one is considered.

New changes can be any or all of the following

Changes in the flow target not present in the repository workspace.
Changes discarded in the flow target or changes created in the repository workspace, not delivered to the stream.
Components added in the flow target
Components removed from the flow target.

To configure polling,

Find the Build Triggers section.
Check the Poll SCM check box to poll for new changes.
Enter a schedule. Click the help button beside the "Schedule" field to get help with the syntax.
Click the Save button to save the settings and return to the job page.

Note	For pipeline jobs, set `poll` boolean attribute to true in the `checkout` step, in addition to configuring a polling interval mentioned in the above steps.

Triggering builds on a schedule

You can configure the job to build at a specific time, irrespective of whether there are new changes in the source code.

Find the Build Triggers section.
Check the Build Periodically check box.
Enter a schedule. Click the help button beside the "Schedule" field to get help with the syntax.
Click the Save button to save the settings and return to the job page.

Configuring Jenkins job for Post Build Deliver (Build Definition configuration only)

Note	From 1.2.0.3, Post Build Deliver is supported for Build Definition configuration. The RTC server version should be 6.0.4 or higher.

To configure for Post Build Deliver,
. Configure the RTC Build Definition with Post Build Deliver configuration.
. In the Jenkins Freestyle job configuration, add the RTC Post Build Deliver post build action. Select Fail on Error, if you want the build to fail if post build deliver fails.
. In a Pipeline job, add the following snippet before the end of the script to perform post build deliver as the last step of the build.

step([$class: 'RTCPostBuildDeliverPublisher', failOnError: true])

Job Configuration for Pipeline jobs

Generating Pipeline Snippet for Team Concert Plugin from Snippet Generator for RTC SCM and Post Build Deliver

For pipeline jobs, you can generate the snippet for Team Concert Plugin using the Pipeline snippet generator. See the help documentation for more information on how to create a snippet. In the snippet generator,

For RTC SCM snippet,
- Click the Sample Step dropdown and select checkout. Then select Rational Team Concert from the dropdown.
- For configuring the remaining options, refer to Job configuration Freestyle jobs.
- Click Generate Snippet.
For Post Build Deliver snippet,
- Select step in the Sample Step dropdown and select RTC Post Build Deliver
- To fail the build if the step fails, click "Fail on Error".
- Click Generate Snippet.

Best practices when using Snippet Generator

Remove references to serverURI, credentialsId if you choose to use the Team Concert Plugin’s global configuration (in Jenkins→Settings) in your pipeline snippet.

Even if you do not choose to override global configuration for Team Concert Plugin defined in System Settings, the snippet generator will copy the values for serverUri, credentialsId and buildtoolkit copied from the global configuration in the snippet. If you copy this snippet into your pipeline script, it can create maintenance issues when you intend to change the global server URI, credentials and build toolkit. If you intend to use the global settings for RTCScm configuration, then remove the following attributes in the snippet

serverURI
credentialsId
timeout
buildTool
overrideGlobal

and then copy the resulting snippet into your pipeline script.

Using Pipeline Script from SCM

Team Concert Plugin supports Pipeline Script from SCM but does not support lightweight checkout. Some of the ways to use this pipeline feature with RTC SCM are captured in Using Team Concert Plugin with Pipeline from SCM

Considerations when using Pipeline Script from SCM and a declarative pipeline in Jenkinsfile

If you are using declarative pipeline, then every agent directive will cause a checkout to happen in that agent using the same configuration as Pipeline Script from SCM. When using a build definition, stream or workspace configuration, this will cause an accept to happen in each of those cases, leading to different content being loaded in each agent. In the case of build definition, an additional build result will be created if the build is triggered from Jenkins. This may or may not be what you want. If you want to prevent the extra checkout for every agent directive, add a options directive below the agent directive with the value skipDefaultCheckout(true)

options {skipDefaultCheckout(true)}

Master/Agent Configuration

Master and agent configurations are supported by this plugin. See the Jenkins documentation on distributed builds for more information. The RTC build toolkit home path is required for the master to be able to test connections and build artifacts.

Navigate to the Computer page (Jenkins > Manage Jenkins > Manage Nodes) and click the "New Node" link.
Enter a name and create a new node.
In the node configuration page, find the Node Properties section and check the Tool Locations check box.
From the list of tool locations, select the build toolkit you want to define for the node, and set the value in the Home field.

Note	If you do not wish to override the tool location, then Team Concert Plugin will try to locate the toolkit at the same location specified in Global Tool configuration

Build toolkits can also be installed automatically on agents. And labels can be used to match build toolkits to agents. However, a valid toolkit is required in the master node to perform connection tests to build artifacts and perform polling.

RTC Log

You can capture logs from the Team Concert plugin to debug any problems that you may encounter.

Configuring Java Logging for Team Concert Plugin

Navigate to the Jenkins Log page (Jenkins > Manage Jenkins > System Log) and click the Add new log recorder button.
Provide a name, for example RTC Log and click the Add button to add a logger.
Enter a logger for com.ibm.team.build and set the log level to FINER.
Click the Save button.
Return to this log if a problem is ever experienced using this plugin. The log will help to identify the problem.
Logging on Agents
1. On the agent, while messages are logged at level FINER, the logs never come back.

Configuring logging in the build console log

There is support for a debug flag which will result in the debug output going into a build’s console log
The environment variable com.ibm.team.build.debug with the value true will activate the debug logging on a agent.
To configure on a single agent with the debug flag for all builds,
1. Go to Jenkins > Manage Jenkins > Manage nodes.
2. Hover over the link of the node to configure. Choose Configure from the popup context menu.
3. In the Node properties section, select and check the Environment variables checkbox
4. Click the Add button beside the List of key value pairs.
5. Supply com.ibm.team.build.debug as the name and true as the value
6. Click the Save button.
Alternately to configure the debug flag on master and all agents
1. Jenkins > Manage Jenkins > Configure System
2. In the Global Properties section, select and check the Environment variables checkbox
3. Click the Add button beside the List of key value pairs.
4. Enter com.ibm.team.build.debug as the name and true as the value
5. Click the Save button.
To configure debugging for a single job, add com.ibm.team.build.debug as a parameter to the job and set its value to true.

The debug flag currently only logs information relating to the class loader setup. The rest of the logic should not be affected by running on a master or an agent so if you need those logs, consider running on the master to get the detailed logs.

Logging the version of build toolkit

If you have turned on the variable com.ibm.team.build.debug, either through the environment variables or as a job parameter, then the version of build toolkit used in the master and agent for that build will appear in the build log.

You should see messages such as the following in the build log.

Version of build toolkit "<buildtoolkit-name>" on master is "6.0.4".
Version of build toolkit "<buildtoolkit-name>" on "<agent-name>" is "6.0.4".

Configuring Java Logging for the Build Toolkit

Configuring logging for Team Concert plugin does not enable log messages from the build toolkit to appear in the Jenkins log recorder.

To enable log messages from build toolkit to be output to a file on the Jenkins controller or any agent, refer to the steps in the wiki Capture log messages from EWM Build Toolkit on the Jenkins controller

Collecting Metronome Logs for different build configurations

Configuring for Build Definition

Add the following build property to the build definition.
1. Name - team.build.reportStatistics
2. Value - true
Open the build definition editor in RTC Eclipse or RTC Web UI, click Properties tab and add the property.
From the Jenkins console, run a build.
Open the build result associated with the Jenkins build.
Click the Logs tab.
You should see two files statistics-<timestamp>.log and statisticsData-<timestamp>.log

Configuring for Repository Wokspace, Stream and Snapshot

Add the following String Job property to the Jenkins job.
1. Name - team.build.reportStatistics
2. Value - true
From the Jenkins console, run a build.
In the machine that hosts the Jenkins master, go to <jenkins config dir>/jobs/<jobname>/builds/<build number>/teamconcert/diagnostics
You should see two files statistics-<timestamp>.log and statisticsData-<timestamp>.log

RTC Build Properties available during Jenkins build

The following properties can be accesssed as environment variables in the build after Rational Team Concert source control step is completed.

property	description
team_scm_changesAccepted	The number of changes accepted or discared during the build.
team_scm_snapshotUUID	UUID of the snapshot created after accepting changes. Not set if no snapshot was created.
team_scm_workspaceUUID	The UUID of the Repository workspace used in the build. Only set if the build is using a build definition.
buildResultUUID	UUID of the build result. Only set if the build is using a build definition
RTCBuildResultUUID	UUID of the build result. Only set if the build is using a build definition
requestUUID	UUID of the build request. Only set if the build is using a build definition.
buildDefinitionId	UUID of the build definition being used by the build. Only set if the build is using a build definition.
repositoryAddress	Address of the RTC repository.
buildEngineId	Name of the build engine associated with the build request/result (if there is a build result). An RTC build engine is not actually running, but some ant tasks need the engine id.
buildEngineHostName	Host name of the Jenkins master or agent that the build is running on.
buildRequesterUserId	User id of the RTC user that requested the build be started. Only set if the build is using a build definition
personalBuild	True if the build is a personal build (requested from RTC), otherwise, not set
rtcTempRepoWorkspaceName	The name of the temporary Repository Workspace created during a build using Stream configuration
rtcTempRepoWorkspaceUUID	The UUID of the temporary Repository Workspace created during a build using Stream configuration

Apart from these built-in properties, when using Build definition configuration, all the build properties set in the build definition and potentially modified when requesting the build will be available as environment variables in the Jenkins build after the Team Concert plugin runs.

Accessing RTC properties in a Freestyle job

In a freestyle job, after Team Concert Plugin completes downloading the source code to the Jenkins workspace, you can access the properties exported by Team Concert Plugin with the following syntax.

On Windows

%<propertyname>%

On Unix/Linux

$propertyname

Team Concert Plugin exports some standard properties and user defined build properties(only for Build definition configuration). For a list of builtin properties, refer to this section.

Accessing RTC properties in a Pipeline job before checkout step - Build Definition only

In a build definition configuration, if the Jenkins build is started from RTC, you can access build properties set in the RTC build result in a pipeline build even before the checkout step runs. These properties can be any of the RTC built-in properties set in the build result or user defined build properties.

To access the RTC Build property from a Build Definition, you must create a String parameter in the Jenkins job with the same name as the RTC build property. The actual value will be set by the RTC build result that starts the Jenkins build. You can supply different values to the user defined RTC build properties when requesting the RTC build.

The following built-in properties are available to the Jenkins build even before the checkout step runs.

property	description
buildResultUUID	UUID of the build result. Only set if the build is using a build definition
requestUUID	UUID of the build request. Only set if the build is using a build definition.
buildDefinitionId	UUID of the build definition being used by the build. Only set if the build is using a build definition.
repositoryAddress	Address of the RTC repository.
buildEngineId	Name of the build engine associated with the build request/result (if there is a build result). An RTC build engine is not actually running, but some ant tasks need the engine id.
buildEngineHostName	Host name of the Jenkins master or agent that the build is running on.
buildRequesterUserId	User id of the RTC user that requested the build be started. Only set if the build is using a build definition
personalBuild	True if the build is a personal build (requested from RTC), otherwise, not set

For instance, consider the scenario where you want to know if the RTC build result that started this pipeline build is a personal build or not.

First create a Job parameter "personalBuild" type is String in the Jenkins pipeline job and set the default value to false.

2. Request a personal build in the RTC build definition associated with the Jenkins job.

3. In your pipeline script, you can check whether the RTC build is a personal build or not as follows

if ("${env.personalBuild}" == "true") {
   // Do something } else {   // Do something else}
}
// or

if ("${personalBuild}" == "true") {
   // Do something } else {   // Do something else}
}

4. To access the buildRequesterUserId property in your script, define a new String parameter called "buildRequesterUserId" to the Jenkins job and set the default value to an empty string.

5. Back in your pipeline script, you can access the property as

"${env.buildRequesterUserId}"
// or
"${buildRequesterUserId}"

Note

This is different from accessing personalBuild property after the checkout step runs. In that case, the personalBuild property will be reset by the checkout step and can be accessed only through the ${env} variable. Here, the property is set by the RTC when starting the Jenkins build, even before the checkout step runs.

Accessing RTC Properties in a Pipeline Job after checkout step

Prop checkout step now returns a map that is populated by Team Concert plugin. For instance, you can store the return value from the checkout step into the scmvars variable and access them using the syntax "$\{scmvars.<rtc environment variable>}". For a list of built-in properties exported to the environment, see this section

checkoutstep

def scmvars = checkout([$class: 'RTCScm'...])

This feature is available when you use Team Concert Plugin version > 1.2.0.5, Jenkins version > 2.60, workflow-cps version > 2.40. Refer to Issue 26100 for the related issue.

Accessing RTC Properties in a pipeline job using env object

You can access RTC Environment properties after the checkout step runs using the env object. You will need to use workflow-cps plugin version > 2.40.

As an example, after every checkout, you can save the snapshot UUID value into a separate variable as follows

echo "${env.BUILD_NUMBER}"

 node {
   checkout([$class: 'RTCScm'...])
   // At this point, env contains RTC related environment variables from the first checkout
   def snapshotUUID1 = "${env.team_scm_snapshotUUID}"
   echo "${snapshotUUID1}"

   checkout([$class: 'RTCScm' ....])
   // At this point, env contains RTC related environment variables from the second checkout. The environment variables contributed by the first checkout are overwritten.
   def snapshotUUID2 = "${env.team_scm_snapshotUUID}"
   echo "${snapshotUUID2}"
 }

References

Note

The issue reported in Defect 370979 - Environment variables for snapshot, build result UUID are null if env object is accessed before running teamconcert checkout step, in a pipeline script and the issue reported in this jazz.net forum post would be fixed indirectly if you use the new workflow-cps plugin.

Accessing RTC properties through RTCBuildResultAction object

If you are using workflow-cps < 2.40, follow the workaround mentioned below.

In a pipeline job the environment variables published by the Team Concert Jenkins plugin is null if the env object is accessed once before the RTC SCM checkout step. For instance, the following script would return the UUID of the snapshot published by the Team Concert plugin.

node('master') {
    // run teamconcert scm step
    echo "${env.team_scm_snapshotUUID}"
 }

But in the script given below the env object is accessed once before running the checkout step and hence accessing the snapshot UUID from the env object returns null

echo "${env.BUILD_NUMBER}"
node('master') {
    // run teamconcert scm step
    echo "${env.team_scm_snapshotUUID}"
 }

Though the Team Concert plugin publishes the environment variables when checkout is invoked, in pipeline scripts the env object once constructed is not refreshed with any of the environment variables, published later.

If you run into issues accessing the environment variables published by the Team Concert plugin, the suggested work around is to access the RTCBuildResultAction object that is added to the build by the Team Concert plugin. The following code returns the build properties stored in RTCBuildResultAction object. This can be used in a pipeline script to obtain snapshot UUID.

def action = currentBuild.build().getAction(com.ibm.team.build.internal.hjplugin.RTCBuildResultAction.class)
def buildProps = action.getBuildProperties()
println(buildProps['team_scm_snapshotUUID'])

If you invoke RTC SCM multiple times, then there will be that many RTCBuildResultActions in the build. Therefore, currentBuild.build().getActions(com.ibm.team.build.internal.hjplugin.RTCBuildResultAction.class) should be used. The action added by the last invocation of RTC SCM should be available at the end of the list. For instance, if there are two RTCScm checkouts, the second RTCBuildResultAction can be accessed as follows.

def actions = currentBuild.build().getActions(com.ibm.team.build.internal.hjplugin.RTCBuildResultAction.class)
def buildProps = actions.get(1).getBuildProperties()
println(buildProps['team_scm_snapshotUUID'])

Note	Your Jenkins administrator should whitelist these methods to access them in a pipeline script. You should consider adding these methods to Global Shared Library. This is explained in the next section.

Wrapping the code to access RTCBuildResultAction in a Global Shared Library

The above code cannot be directly used in a pipeline script without an administrator whitelisting the APIs in Jenkins. You can wrap this code inside a method and add it to a Global Shared Library. You can then call the method from your pipeline script.

If you are already using a Global Shared Library in your environment, add the following code in a file called rtcutils.groovy and place the file under the vars directory,

 def getSnapshotUUID(actionNum) { // The n'th RTCBuildResultAction.
    def actions = currentBuild.build().getActions(com.ibm.team.build.internal.hjplugin.RTCBuildResultAction.class)
    if (actions != null && actions.size() > 0 && actionNum > 0 && actionNum <= actions.size()) {
        def buildProps = actions.get(actionNum-1).getBuildProperties()
        return (buildProps['team_scm_snapshotUUID'])
    }
    return null
}

Then, in your pipeline script, you can write the following to get the snapshotUUID of the checkout step.

@Library('your-shared-library')_

node {
   checkout([$class: 'RTCScm'...])

   // pass 2 or greater if the shared library is fetched from RTC, otherwise pass 1.
   // If the library is fetched from RTC, then there is one RTCBuildResultAction corresponding to that checkout.
   // Hence you need to pass 2 or more depending on how many EWM (RTC) checkouts have been called after @Library directive.
   def snapshotUUID = rtcutils.getSnapshotUUID(2)
   echo "${snapshotUUID}"
}

If you do not have Global Shared Library that is defined in your environment, see Extending with Shared Libraries for creating and accessing a shared library in your pipeline script. Note that if you use RTC for hosting the Global Shared Library, then there will be a checkout of the source code from RTC. A RTCBuildResultAction will be added to the build at the point where the library is checked out into the pipeline script.

Symbolic Link support

Note	Symbolic links works out of the box from Java version 7 and greater. The following information is retained for older Java versions.

RTC support for symbolic links requires one or two additional libraries (.dll/.so files).

RTC file system natives
Eclipse file system natives

The reason is Java 6 and earlier doesn’t have support for creating/looking at properties of symbolic links. Java 7 has symbolic link support that works on linux, but on Windows there are some limitations when creating links (if the target has not yet been created the type is defaulted to file which is not good if its a directory). If you are running Linux and can use Java 7 you only need the Eclipse natives. Otherwise, you will need both the RTC and Eclipse natives.

In the Build engine directory (<your RTC build install directory>\buildengine\eclipse\plugins), look for (or equivalent jars for your platform/release).

com.ibm.team.filesystem.client_3.1.600.v20130415_0257.jar (RTC file system natives)
org.eclipse.core.filesystem.win32.x86_1.1.201.R36x_v20100727-0745.jar (Eclipse file system natives)

From the com.ibm.team.filesystem.client jar you want to extract +winfsnatives.dll+ (+libfsnatives.so+ on linux). Take all the .dll/.so files from the org.eclipse.core.filesystem jar. Place them directly in a directory (eg. c:\natives\winfsnatives.dll).

When you start Jenkins, we need to tell java about the directory so that it can load the libraries from it. To this, you can add the directory to the search path.

Change the PATH variable on Windows or the +LD_LIBRARY_PATH+ variable on linux prior to starting Jenkins. Alternatively, you can also specify it when starting Java through the +-Djava.library.path+ setting.
eg.

java -Djava.library.path="c:\natives;%Path%" -jar jenkins-1.509.1.war

If you are running on Windows, you need to be sure that you have permission to create symbolic links. The Symbolic links article in the jazz.net library describes how.

Note	If you are running your jenkins builds on agents and the symbolic links fail to load, then the native libraries should be included in the JVM library path of the agents too.

Load Rules Support

When a jenkins build is configured with an RTC build definition, the component load rules specified in the RTC build definition, if any, will be applied when loading the jenkins build workspace. Component load rules in builds describes how to specify load rules in a build definition.
When a jenkins build is configured with an RTC repository workspace, stream, or snapshot load rules can be specified by setting the load policy field to "Load components by using a load rule file".
To configure load policy in a pipeline build, set the "loadPolicy" field to one of - "useComponentLoadConfig", "useLoadRules", or "useDynamicLoadRules".
1. When loadPolicy is set to useComponentLoadConfig, you can either choose to load all components or exclude some components by setting the value for "componentLoadConfig" to either "loadAllComponents" or "excludeSomeComponents".
The load policy field for RTC build definition can be set only using the 6.0.5 RTC client.
Component load rules can also be specified through dynamic load rules extension. For more details refer to DynamicLoadRulesJenkinsPlugin. Dynamic load rules feature is supported across all build configurations
- build definition, repository workspace, stream, and snapshot.
In build definition configuration, when load rules are configured in the build definition and dynamic load rules are also provided, dynamic load rules take precedence over the component load rules.

Load Rules behaviour in Team Concert Plugin version >= 1.2.0.4

From 1.2.0.4, the behavior of load rules in Jenkins builds is at par with RTC SCM (in Eclipse client or SCM CLI). So, only those components for which load rules are specified will be loaded, according to those rules; all the other components for which load rules are not specified will not be loaded. To maintain backwards compatibility in Jenkins builds configured with an RTC build definition, old load rules behavior will be enforced unless the load policy field in the build definition is set to use load rules. You can change the load policy by migrating your old build definitions from the Eclipse client to use the new load format.

Load Rules behaviour in Team Concert Plugin version < 1.2.0.4

Before 1.2.0.4, the behavior of load rules in Jenkins builds, when using the component load rules specified in RTC build definition or the load rules generated by the dynamic load rules extension, is different from how eclipse client enforces the load rules. Say, you have a load rules file that loads some but not all of the components in a workspace. This load rules file when used to load a workspace in the eclipse client, will result in loading of only those components specified in the load rules file. When the same load rules file is configured in an RTC build definition, all components from the workspace, including those not specified in the load rules file, are loaded; those components for which load rules are specified are loaded according to the specified load rules, all the other components are loaded as is. Components to exclude option, in the RTC build definition can be used to restrict which components are loaded during the build - for more details refer Creating RTC build definitions.

Advanced Pipeline capabilities

Perform polling only and generate changelog while skipping downloading the sources in the Jenkins build

You can configure a pipeline job to poll on a RTC build definition or a repository workspace but skip downloading the sources when the pipeline build runs by using the option polling-only. Optionally, you can provide a snapshotUUID to generate a changelog for the Jenkins build. The snapshot should be owned by the repository workspace configured in the build definition.

To enable the polling-only option, add the text "pollingOnly: true" to the checkout step. If you prefer to use the snippet generator to generate a checkout step with the polling-only option, follow the steps below:

Open the Jenkins Web UI.
Navigate to the pipeline job.
In the left pane, click "Pipeline Syntax".
Under Steps, select checkout from the Sample Step dropdown list.
Under SCM, Select Rational Team Concert (RTC).
Change the Build Configuration to Build Definition or Repository Workspace.
For Build Definition configuration, enter the ID of the Build Definition.
For Repository workspace configuration, enter the name of the Repository Workspace.
Click Advanced.
Select "Perform polling but do not accept or load the repository workspace.
To generate a changelog, enter the variable that references the snapshot UUID. For example, ${ret.snapshotUUID}.
1. To retrieve Jazz SCM snapshot details from the build result, use the "Get SCM Snapshot" task.
Click Generate Pipeline script.

Note

All values in the generated script are enclosed in single quotes. If single quotes are used, then a value like ${ret.buildResultUUID} is interpreted literally by the pipeline build. To expand such values, modify the script to enclose the value within double quotes, for example "${ret.snapshotUUID}".

rtcBuild Step

rtcBuild is a pipeline step to interact with RTC Build from a pipeline job. The step provides the following tasks

Request Build
Wait for Build
List logs
List artifacts
Download log
Download artifact

Request build

To request a RTC build from a pipeline job, use the "Request Build" task. Once the build request is successfully created, the step returns the build result UUID in an object that is available in pipeline script. To retrieve the build result UUID from the object, use the syntax ${obj.buildResultUUID}, where obj is the name of the object.

To generate the pipeline snippet for requesting a build, perform the following steps

Open the Jenkins Web UI.
Navigate to the pipeline job.
In the left pane, click "Pipeline Syntax"
Under Steps, select rtcbuild from the Sample Step dropdown list.
Select a Build toolkit.
Enter a value for RTC server URI or accept the default.
Select the appropriate credentials or accept the default.
Select "Request Build" from the Task dropdown list.
Enter a Build Definition ID.
To delete properties while requesting a build, check "Delete Properties".
1. Click "Add Property" and enter the name of the property to delete.
To add a new property or override the value of an existing property when requesting a build, select "Add or Override Properties".
1. Click "Add Property" and add the name and value of the property to add to or override in the build request.
To insert a link of the build result associated with the build request to the Jenkins pipeline build, select "Insert EWM(RTC) build link to Jenkins pipeline build"".
Click Generate Pipeline Script.

Note

All values in the generated script are enclosed in single quotes. If single quotes are used, then a value like ${ret.buildResultUUID} is interpreted literally by the pipeline build. To expand such values, modify the script to enclose the value within double quotes, for example "${ret.buildResultUUID}".

The following snippet requests a build and prints the build result UUID after the step completes requesting a build in RTC

def ret = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildDefinitionId: '<build-definition-id>', name: 'requestBuild'], timeout: 480], timeout: 480
  echo "${ret.buildResultUUID}"

The following snippet requests a build with one new property and a few deleted properties and prints the build result UUID after rtcBuild step completes requesting a build in RTC.

  def ret = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildDefinitionId: '<build-definition-id>', name: 'requestBuild',
  addOrOverrideProperties: true, propertiesToAddOrOverride: [[propertyName: 'addProp', propertyValue: 'newValue']],
  propertiesToDelete: [[propertyName: 'deleteProp1'], [propertyName:'deleteProp2']]
 ], timeout: 480], timeout: 480
  echo "${ret.buildResultUUID}"

The following snippet requests a build, prints the build result UUID after rtcBuild step completes requesting a build in RTC and adds a link of the build result to the Jenkins pipeline build.

  def ret = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildDefinitionId: '<build-definition-id>', name: 'requestBuild',
linkEWMBuild: true], timeout: 480], timeout: 480
  echo "${ret.buildResultUUID}"

Wait for Build

To make the pipeline build pause until a RTC build to change state or a timeout expires, use the Wait for Build task. Once the step completes successfully, one of the following is true:

The timeout has expired.
The RTC build has reached one of the required states.

The following argument must be provided for waiting on a build.

Build result UUID.

The following arguments are optional.

Build states to wait for
- The different states of the build result on which the step will wait. If the build result enters into one of the states, then the step returns from execution. By default, the step does not complete until the build result enters the COMPLETED or INCOMLPETE state. The build enters an INCOMPLETE state when it is abandoned.
Wait Timeout
- The time in seconds up to which this step will wait. By default, the step waits forever to reach the specified build states. For longer builds, it is recommended to wait for a shorter timeout and use looping constructs available in pipeline script to retry.
Wait Interval
- The time in seconds up to which the rtcBuild step waits before polling to check the specified build states. The polling is done at regular intervals until it reaches the value mentioned in the Wait Timeout property. The Wait Interval property value should be less than the Wait Timeout property value.

The step returns the following values.

The status of the build - either OK, ERROR, WARNING, or INFO.
The state of the build - either COMPLETE, INCOMPLETE, IN_PROGRESS, CANCELED, or NOT_STARTED.
Whether or not the step timed out. If this value is false, then the status of the build is one of the build states that the step waited on.

To generate the pipeline snippet for waiting on a build, perform the following tasks

Open the Jenkins Web UI.
Navigate to the pipeline job.
In the left pane, click "Pipeline Syntax".
Under Steps, select rtcBuild from the sample step dropdown list.
Select a Build toolkit.
Enter a value for RTC server URI or accept the default.
Select the appropriate credentials or accept the default.
In the Task dropdown list, select "Wait for Build".
In the Build Result UUID text box, enter a value. This value is usually a parameter which is obtained from requesting a build. For example, to refer to the build result UUID obtained from a "Request Build" task, enter ${ret.buildResultUUID}.
In the Build States to wait for text box, enter the states to wait for separated by a comma. The default values are COMPLETED and INCOMPLETED. Other values are IN_PROGRESS, CANCELED, and NOT_STARTED.
In Wait timeout (in seconds) text box, enter the wait timeout in seconds. This value should be greater than zero. The default value is -1 which makes the step wait until the build result enters into the specified states.
Click Generate Pipeline Script.

Note

All values in the generated script are enclosed in single quotes. If single quotes are used, then a value like ${ret.buildResultUUID} is interpreted literally by the pipeline build. To expand such values, modify the script to enclose the value within double quotes, for example "${ret.buildResultUUID}".

In the following snippet, the "Wait for Build" task uses the build result UUID from "Request Build" task to wait for the build result to enter into COMPLETED or INCOMPLETE state for 120 seconds. Once the step completes, it prints the following fields from the return value.

* buildState
* buildStaus
* timedout

  def ret1 = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildDefinitionId: '<build-definition-id>', name: 'requestBuild'], timeout: 480
  echo "${ret.buildResultUUID}"

  def ret2 = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildResultUUID: "${ret.buildResultUUID}", name: 'waitForBuild', buildStates: 'COMPLETED,INCOMPLETE,CANCELED', waitBuildTimeout: 120], timeout: 480
  echo "${ret2.buildState}"
  echo "${ret2.buildStatus}"
  echo "${ret2.timedout}"

List Logs

Use the "List Logs" task to retrieve the details of the logs from an EWM build result. Logs appear in the "Logs" tab of the EWM build result.

Note

The content of the log can be stored in the EWM repository or in some external storage. This task will retrieve the details of the logs whose content is stored in the EWM repository. Such logs can be uploaded to the build result using the logPublisher ant task in the EWM build toolkit. Log Publisher

To generate the pipeline snippet for list logs from an EWM build result, perform the following steps

Open the Jenkins Web UI.
Navigate to the pipeline job.
In the left pane, click "Pipeline Syntax".
Under Steps, select rtcBuild from the sample step dropdown list.
Select a Build toolkit.
Enter a value for RTC server URI or accept the default.
Select the appropriate credentials or accept the default.
In the Task dropdown list, select "List Logs".
In the Build Result UUID text box, enter a value. This value is usually a parameter which is obtained from requesting a build. For example, to refer to the build result UUID obtained from a "Request Build" task, enter ${ret.buildResultUUID}. This is a mandatory parameter. NOTE: Remember to quote ${ret.buildResultUUID} once the snippet is copied to the pipeline script.
In the File name or pattern text box, enter a file name or pattern to restrict the logs for which details will be retrieved. If no value is specified, then details of all the logs whose content is stored in EWM repository will be retrieved. This parameter is optional.
In the Component name text box, enter the name of the component to restrict the logs for which details will be retrieved. If no value is specified, then details of all the logs belongining to any component or no component will be retrieved. To retrieve details of logs that does not belong to any component, leave this field blank. This parameter is optional.
In the Maximum number of results text box, enter the maximum number of logs for which details will be reterieved. The default value is 512, largest value is 2048. If there are more than 2048 logs in the build result, restrict the result set by providing a file name pattern or component name.
Click Generate Pipeline Script.

Note

All values in the generated script are enclosed in single quotes. If single quotes are used, then a value like ${ret.buildResultUUID} is interpreted literally by the pipeline build. To expand such values, modify the script to enclose the value within double quotes, for example "${ret.buildResultUUID}".

Once the step completes execution, you can access the information about each log using a for loop.

* fileName
* componentName
* description
* type
* contentId
* size

The following snippet retrieves details of all the logs in the build result and outputs them to the console log using a for loop.

  def ret1 = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildResultUUID: "${ret.buildResultUUID}", name: 'listLogs'], timeout: 480

for(i=0;i< ret1.fileInfos.length;i++) {
         echo "${ret1.fileInfos[i].fileName}"
         echo "${ret1.fileInfos[i].componentName}"
         echo "${ret1.fileInfos[i].description}"
         echo "${ret1.fileInfos[i].type}"
         echo "${ret1.fileInfos[i].contentId}"
         echo "${ret1.fileInfos[i].size}"
}

List Artifacts

Use the "List Artifacts" task to retrieve the details of the artifacts from an EWM build result. Artifacts appear in the "Downloads" tab of the EWM build result.

Note

The content of the artifact can be stored in the EWM repository or in some external storage. This task will retrieve the details of the artifacts whose content is stored in the EWM repository. Such artifacts can be uploaded to the build result using the artifactFilePublisher ant task in the EWM build toolkit. Artifact Publisher

To generate the pipeline snippet for list logs from an EWM build result, perform the following steps

Open the Jenkins Web UI.
Navigate to the pipeline job.
In the left pane, click "Pipeline Syntax".
Under Steps, select rtcBuild from the sample step dropdown list.
Select a Build toolkit.
Enter a value for RTC server URI or accept the default.
Select the appropriate credentials or accept the default.
In the Task dropdown list, select "List artifacts".
In the Build Result UUID text box, enter a value. This value is usually a parameter which is obtained from requesting a build. For example, to refer to the build result UUID obtained from a "Request Build" task, enter ${ret.buildResultUUID}. This parameter is mandatory. NOTE: Remember to quote ${ret.buildResultUUID} once the snippet is copied to the pipeline script.
In the File name or pattern text box, enter a file name or pattern to restrict the artifacts for which details will be retrieved. If no value is specified, then details of all the artifacts whose content is stored in EWM repository will be retrieved. This parameter is optional.
In the Component name text box, enter the name of the component to restrict the artifacts for which details will be retrieved. If no value is specified, then details of all the artifacts belongining to any component or no component will be retrieved. To retrieve details of artifacts that does not belong to any component, leave this field blank. This parameter is optional.
In the Maximum number of results text box, enter the maximum number of artifacts for which details will be retrieved. The default value is 512 and the largest value is 2048. If there are more than 2048 artifacts in the build result, restrict the result set by providing a file name pattern or component name.
Click Generate Pipeline Script.

Note

All values in the generated script are enclosed in single quotes. If single quotes are used, then a value like ${ret.buildResultUUID} is interpreted literally by the pipeline build. To expand such values, modify the script to enclose the value within double quotes, for example "${ret.buildResultUUID}".

Once the step completes execution, you can access the information about each artifact using a for loop.

* fileName
* componentName
* description
* type
* contentId
* size

The following snippet retrieves details of all the artfiacts in the build result and outputs them to the console log using a for loop.

  def ret1 = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildResultUUID: "${ret.buildResultUUID}", name: 'listArtifacts'], timeout: 480

for(i=0;i< ret1.fileInfos.length;i++) {
         echo "${ret1.fileInfos[i].fileName}"
         echo "${ret1.fileInfos[i].componentName}"
         echo "${ret1.fileInfos[i].description}"
         echo "${ret1.fileInfos[i].type}"
         echo "${ret1.fileInfos[i].contentId}"
         echo "${ret1.fileInfos[i].size}"
}

Download Log

To download a log from the build result, use the "Download log" task. You can download a log using the log’s name or content ID.

If you do not know the full name of the log when creating the script, you can retrieve details of all the logs starting with a specific prefix using the "List logs" task. Then, you can use the content id or the file name to download the contents of the log to the Jenkins workspace or any folder in the agent where this task runs.

Note

The content of the log can be stored in the EWM repository or in some external storage. This task will download the content of a log which is stored in the EWM repository. Such logs can be uploaded to the build result using the logPublisher ant task in the EWM build toolkit. This task is similar to the logRetriever ant task in the EWM build toolkit. Refer to Log Publisher and Log Retriever.

To generate the pipeline snippet for download log from an EWM build result, perform the following steps

Open the Jenkins Web UI.
Navigate to the pipeline job.
In the left pane, click "Pipeline Syntax".
Under Steps, select rtcBuild from the sample step dropdown list.
Select a Build toolkit.
Enter a value for RTC server URI or accept the default.
Select the appropriate credentials or accept the default.
In the Task dropdown list, select "Download log".
In the Build Result UUID text box, enter a value. This value is usually a parameter which is obtained from requesting a build. For example, to refer to the build result UUID obtained from a "Request Build" task, enter ${ret.buildResultUUID}. This parameter is mandatory. NOTE: Remember to quote ${ret.buildResultUUID} once the snippet is copied to the pipeline script.
In the File name text box, enter the full name of the log. If the full name of the log is not known at the time of writing the script (for example, the log’s name has a timestamp as a suffix), then use the list logs task to retrieve details of all logs matching a file name pattern and provide the file name attribute as a reference, for example ${ret2.fileName}. If more than one log matches the given file name, then the first match is downloaded. If it is possible for logs to have the same name, then use the content ID attribute as a reference, for example ${ret2.contentId}. Either File Name or Content ID parameters must be provided but not both.
In the Component name text box, enter the name of the component to which this log belongs to. If there are multiple logs with the same name across different components, then providing the component name will download the log under the specific component. This parameter is optional.
In the Content Id field, provide a reference to the contentId attribute from the return value of List logs task. Either File Name or Content ID parameters must be provided but not both.
In the Destination file name text box, provide a name for the file to which the contents will be downloaded to. If a file with the same name already exists in the destination, then a file will be created by appending the destination file name with the current timestamp. This parameter is optional.

Note

All values in the generated script are enclosed in single quotes. If single quotes are used, then a value like ${ret.buildResultUUID} is interpreted literally by the pipeline build. To expand such values, modify the script to enclose the value within double quotes, for example "${ret.buildResultUUID}".

Once the step completes execution, you can access the following fields about the downloaded log.

* fileName - The name of the file on disk. This name is not required to match the name of the log file, if a destination file name was provided in the arguments.
* filePath - The full path to the file on disk.

The following snippet retrieves details of all the logs in the build result whose name starts with "build" and outputs them to the console log using a for loop. It then switches the current working directory to a subfolder in the Jenkins workspace and downloads each log and then prints the name and path of the file on disk.

  def ret1 = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildResultUUID: "${ret.buildResultUUID}", name: 'listLogs', fileNameOrPattern: "build*"], timeout: 480

for(i=0;i< ret1.fileInfos.length;i++) {
         echo "${ret1.fileInfos[i].fileName}"
         echo "${ret1.fileInfos[i].componentName}"
         echo "${ret1.fileInfos[i].description}"
         echo "${ret1.fileInfos[i].type}"
         echo "${ret1.fileInfos[i].contentId}"
         echo "${ret1.fileInfos[i].size}"
}

// Switch to a subdirectory in the Jenkins workspace
dir('downloads') {
   // Download each log using content ID
   for(i=0;i< ret1.fileInfos.length;i++) {

       def ret2 =  rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildResultUUID: "${ret.buildResultUUID}", name:  'downloadLog', contentId: "${ret1.contentId}" ], timeout: 480
      echo "${ret2.fileName}"
      echo "${ret2.filePath}"
  } // end for
}  // end dir

Download Artifact

To download an artifact from the build result, use the "Download artifact" task. You can download an artifact using its name or content ID.

If you do not know the full name of the artifact when creating the script, you can retrieve details of all the artifacts starting with a specific prefix using the "List artifact" task. Then, you can use the content id or the file name to download the contents of the artifact to the Jenkins workspace or any folder in the agent where this task runs.

Note

The content of the artifact can be stored in the EWM repository or in some external storage. This task will download the content of the artifact which is stored in the EWM repository. Such artifacts can be uploaded to the build result using the artifactPublisher ant task in the EWM build toolkit. This task is similar to the artifactRetriever ant task in the EWM build toolkit. Refer to Artifact Publisher and Artifact Retriever.

To generate the pipeline snippet for download artifact task from an EWM build result, perform the following steps

Open the Jenkins Web UI.
Navigate to the pipeline job.
In the left pane, click "Pipeline Syntax".
Under Steps, select rtcBuild from the sample step dropdown list.
Select a Build toolkit.
Enter a value for RTC server URI or accept the default.
Select the appropriate credentials or accept the default.
In the Task dropdown list, select "Download log".
In the Build Result UUID text box, enter a value. This value is usually a parameter which is obtained from requesting a build. For example, to refer to the build result UUID obtained from a "Request Build" task, enter ${ret.buildResultUUID}. This parameter is mandatory. NOTE: Remember to quote ${ret.buildResultUUID} once the snippet is copied to the pipeline script.
In the File name text box, enter the full name of the artifact. If the full name of the artifact is not known at the time of writing the script (for example, the log’s name has a timestamp as a suffix), then use the list artifacts task to retrieve details of all logs matching a file name pattern and provide the file name attribute as a reference, for example ${ret2.fileName}. If more than one log matches the given file name, then the first match is downloaded. If it is possible for artifacts to have the same name, then use the content ID attribute as a reference, for example ${ret2.contentId}. Either File name or Content ID parameters must be provided but not both.
In the Component name text box, enter the name of the component to which this artifact belongs to. If there are multiple artifacts with the same name across different components, then providing the component name will download the log under the specific component. This parameter is optional.
In the Content Id field, provide a reference to the contentId attribute from the return value of List Artifacts task. Either File Name or Content ID parameters must be provided but not both.
In the Destination file name text box, provide a name for the file to which the contents will be downloaded to. If a file with the same name already exists in the destination, then a file will be created by appending the destination file name with the current timestamp.

Note

All values in the generated script are enclosed in single quotes. If single quotes are used, then a value like ${ret.buildResultUUID} is interpreted literally by the pipeline build. To expand such values, modify the script to enclose the value within double quotes, for example "${ret.buildResultUUID}".

Once the step completes execution, you can access the following fields about the downloaded log.

* fileName - The name of the file on disk. This may or may not match the destination file name or the name of the artifact (if destination file name is not provided).
* filePath - The full path to the file on disk.

The following snippet retrieves details of all the artifacts in the build result whose name starts with "build" and outputs them to the console log using a for loop. It then switches the current working directory to a subfolder in the Jenkins workspace and downloads each artfiact and then prints the name and path of the file on disk.

  def ret1 = rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildResultUUID: "${ret.buildResultUUID}", name: 'listArtifacts', fileNameOrPattern: "build*"], timeout: 480

for(i=0;i< ret1.fileInfos.length;i++) {
         echo "${ret1.fileInfos[i].fileName}"
         echo "${ret1.fileInfos[i].componentName}"
         echo "${ret1.fileInfos[i].description}"
         echo "${ret1.fileInfos[i].type}"
         echo "${ret1.fileInfos[i].contentId}"
         echo "${ret1.fileInfos[i].size}"
}

// Switch to a subdirectory in the Jenkins workspace
dir('downloads') {
   // Download each artifact using content ID
   for(i=0;i< ret1.fileInfos.length;i++) {

       def ret2 =  rtcBuild buildTool: '<builtoolkit-name>', credentialsId: '<credentials>', serverURI: '<rtc-server-uri>', task: [buildResultUUID: "${ret.buildResultUUID}", name:  'downloadArtifact', contentId: "${ret1.contentId}" ], timeout: 480
      echo "${ret2.fileName}"
      echo "${ret2.filePath}"
  } // end for
}  // end dir

Get SCM Snapshot

Retrieve the Jazz SCM snapshot details for a given EWM (RTC) build result.

If the build result has a Jazz SCM snapshot contribution, then the task returns the snapshot’s name and UUID. If the build result does not have such a contribution, then the task returns empty values for snapshot name and UUID. This task does not check the state of the build result to see if it is in progress while the task runs. It is left to the caller to ensure that a snapshot has been added to the build result before the task runs. You can use the Wait for build task to wait for a specific amount of time or change of state and then call this task to retrieve snapshot details.

To generate the pipeline snippet for the "Get SCM Snapshot" task, perform the following steps

Open the Jenkins Web UI.
Navigate to the pipeline job.
In the left pane, click "Pipeline Syntax".
Under Steps, select rtcBuild from the sample step dropdown list.
Select a Build toolkit.
Enter a value for RTC server URI or accept the default.
Select the appropriate credentials or accept the default.
In the Task dropdown list, select "Get SCM Snapshot".
In the Build Result UUID text box, enter a value. This value is usually a parameter which is obtained from requesting a build. For example, to refer to the build result UUID obtained from a "Request Build" task, enter ${ret.buildResultUUID}. This parameter is mandatory.

Note

All values in the generated script are enclosed in single quotes. If single quotes are used, then a value like ${ret.buildResultUUID} is interpreted literally by the pipeline build. To expand such values, modify the script to enclose the value within double quotes, for example "${ret.buildResultUUID}".

Once the step completes execution, you can access the following fields about the Jazz SCM snapshot.

* snapshotName - The name of the Jazz SCM snapshot.
* snapshotUUID - The UUID for the Jazz SCM UUID.

Accessing Jenkins build parameters and groovy variables in steps

To access a Jenkins build parameter in place of string value in a pipeline script, use the syntax

"${env.parameter_name}".

The presence of double quotes in the script will cause the groovy interpreter to perform string interpolation.

To access a groovy variable in place of string value in a pipeline script, use the syntax "{$var}". If the variable is an object and you need to use the value of one of the fields of the object, use the syntax

"${var.field_name}"

Known caveats with download log or artifact into the jenkins workspace on an agent

In a pipeline build , if the option "Use groovy sandbox" is unchecked, then Jenkins does not allocate the workspace directory when the build starts. If an attempt is made to create a file or a folder under the workspace directory, it fails since the workspace directory does not exist.

If you use the "Download Log" or "Downalod Artifact" task to download a file into the Jenkins workspace, you must create the workspace directory before running the task. The following snippet shows how to create the workspace directory if it doesn’t exist and then create a subdirectory under the workspace directory to store the logs and artifacts.

    def workspace = "${env.WORKSPACE}"
    echo "${workspace}"
    withEnv(["workspace=${workspace}"]) {
        sh '''
        echo "${workspace}"
        if [ ! -e ${workspace} ]; then
          mkdir -p "${workspace}"
        fi
        '''
    }
    dir('') {
     // Switch to the directory to download the log or artifact
    }

Jenkins does not allocate workspace

Publishing downloaded log or artifact to the Jenkins build

To publish the downloaded log or artifact to the Jenkins build, use the "archiveArtifacts" step. The following snippet publishes all files with the .log extension to the Jenkins build.

archiveArtifacts artifacts: '*.log', followSymlinks: false

Known Limitations

In the version 1.2.0.0, polling is not supported for stream and snapshot build configurations, when "avoid using toolkit on master (experimental)" is checked.
In the version 1.2.0.0 temporary workspaces are created to support loading from a stream and snapshot. Teamconcert plugin deletes the temporary workspaces when the completes. These temporary workspaces could be left behind in case of network issue during the build. The temporary workspaces can be located by searching for workspaces that starts with the prefix "HJP_".
In the version 1.1.9.5, validating the connections when "avoid using toolkit on master (experimental)" is checked is broken. This issue seems to be do with maven dependencies. The issue is tracked in the work item Error shown when validating a connection with avoid using toolkit on master option checked
You may need to recycle Jenkins and agents when updating the Team Concert plugin to a new version, or when automatically installing a new build toolkit.
Following are knows issues with Workflow support
1. Deleting a workflow build does not delete the corresponding RTC build result
2. 365198: [Workflow plugin Using the groovy script generated by snippet generator for TeamConcert step in a workflow job throws NPE in RTCScm]. For a workaround change the generated script from teamconcert([value:"buildDefinition", buildDefinition:"<>")] to teamconcert buildType: [value:"buildDefinition", buildDefinition:"<>"]. For more information on this issue refer to JENKINS-29711
Using com.ibm.team.build.debug to know the RTC build toolkit version in a agent for a particular job doesn’t work in the first build processed by the agent. Subsequent build of the job on the same agent will output the build tooolkit version in use. See 461155: Logging version of build toolkit on the agent doesn’t work in the first build processed by the agent after a agent restart.

Known Limitations with fixes in newer releases of RTC

Issue with RTC 6.0 build tool kit and load rules. Due to a breaking change in the RTC 6.0, load rules will not work when using RTC 6.0 build tool kit. Fix is available in 6.0 Ifix07 build toolkit (work item 362564). Refer to the work item Load rules is broken with Jenkins plugin and RTC 6.0 build tool kit (361926) for more details. If you are using load rules then its recommended to use the RTC 5.0.2 build tool kit and not RTC 6.0 build tool kit. Note that this recommendation if only or the version of the RTC build tool kit and and not for the RTC server. The RTC server can either be 5.0.2 or 6.0, since RTC supports n-1 compatibility (i.e an older client can connect to a later server) a 5.0.2 version of the build tool kit will work with RTC 6.0 server.
Each build request initiated from RTC creates a buildResultUUID parameter in the Jenkins workflow job.
1. This issue is fixed in RTC v6.0.1 or higher and in 6.0 ifix04, 5.0.2 ifix12.
2. For a workaround follow the steps listed below
  1. In the workflow job configuration page, delete all but one buildResultUUID parameters.
  2. Add the following under the <flow-definition> tag in the workflow job’s config.xml
    <actions>
    <hudson.model.ParametersDefinitionProperty>
    <parameterDefinitions>
    <hudson.model.StringParameterDefinition>
    <name>buildResultUUID</name>
    <description>The UUID of the build result in RTC. It is supplied by builds initiated through RTC. For builds initiated through Hudson/Jenkins, no value should be supplied.</description>
    <defaultValue></defaultValue>
    </hudson.model.StringParameterDefinition>
    </parameterDefinitions>
    </hudson.model.ParametersDefinitionProperty>
    </actions>
  3. Click Manage Jenkins→ Reload Configuration from Disk.

Tutorial

jazz.net wiki topic: Integrating with Jazz SCM and Builds from Hudson and Jenkins using the Team Concert Plugin
YouTube video: Team Concert Plugin for Hudson/Jenkins

Best Practices

Refer to the best practices document here.

References

Using the Team Concert plugin in Pipeline jobs - Pipeline Support in Team Concert Plugin
Using dynamic load rules in Team Concert plugin - Using Dynamic Load Rules with Team Concert Plugin

Releases

2.4.4 March 07, 2024

The following defects are fixed:

User with Job/Configure role will now able to configure the toolkit path at Job level.
"Download log" and "Download artifact" steps in rtcBuild pipeline step will now create new file with proper name and format if file exist with same name at destination directory.
waitForBuild step will now log the sleeping logs on each "Wait Time interval" in the build log file only if com.ibm.team.build.debug = true property has been added to the environment or passed as a job parameter. Earlier this could end up flooding the logs for a long running operation.

Note: Team Concert Plugin continues to support LTS versions starting from 2.361.1

2.4.3 October 03, 2023

Upgraded to Jenkins version 2.361.1 and Java 11.
TLSv1.1 protocol is no longer supported in Team Concert Plugin. Users are encouraged to use TLSv1.3 or TLSv1.2 protocol.

Note: Team Concert Plugin continues to support LTS versions starting from 2.361.1

2.4.2 June 06, 2023

The following defects are fixed:

The pipeline jobs that are configured with the Post Build deliver step, when executed in parallel on different nodes or agents, will no longer fail with ConcurrentModificationException. Earlier, they were failing intermittently with ConcurrentModificationException.
Fixed a minor security vulnerability related to permission checks.

2.4.1 January 20, 2022

The following defects are fixed:

Two parallel running pipeline jobs no longer occupy the workspace directory of each other. Previously, the jobs occupy the workspace directory of each other intermittently.
When credential parameters are used in the pipeline job against the credentialsId parameter, post build delivery steps no longer fail with a message that it cannot resolve the credentials.
In the waitForBuild task of the rtcBuild step, the waitBuildTimeout property specifies how long the task should keep checking for the build result status change. The task checks the status every 30 seconds until the time that is specified in the waitBuildTimeout property expires. The polling interval for the waitBuildTimeout property is now configurable by using the waitBuildInterval property where you can add the wait interval time, which was default to 30 seconds earlier.
Previously, if the global settings were modified, it is required to change the serverURI, credentialsId, and buildTool parameter values manually in the pipeline script. From now on, these parameters are added to the pipeline script only when it is required to override them and give specific values other than the global settings. Otherwise, serverURI, credentialsId, and buildTool parameters are not added if the global settings were used.

Note: Team Concert Plugin continues to support LTS versions starting from 2.60.1

GitHub commit - e676523368

2.4.0 June 22 2021

Pipeline job related enhancements to Team Concert plugins
- New pipeline step rtcBuild to interact with EWM Builds introduced.
Compatibility changes to remove common-digester2 and use common-digester3
- Pull request 20. Merged and released as part of 2.4.0.

Note: Team Concert Plugin continues to support LTS versions starting from 2.60.1

GitHub commit - 73cf16eea7

2.2.1 March 30, 2021

Compatibility update for Jenkins 2.277.1 LTS. 524132:Adoption - tables to divs migration for Team Concert Plugin Note: Team Concert Plugin continues to support LTS versions starting from 2.60.1

GitHub commit - 1dcbf3308f3

2.2.0 December 22, 2020

Support for SAML/OIDC app password.
- Work Item 515283
Support for Optimized incremental load when using build definition configuration and load rules with EWM 7.0.2. This feature is supported only when both EWM server and build toolkit version is 7.0.2. For more information, see EWM 7.0.2 New and Noteworthy

2.1.0 July 18,2020

Support for optimized incremental load when using Build Definition configuration with EWM 7.0.1. This feature is supported only when both EWM server and build toolkit version is 7.0.1. For more information, see EWM 7.0.1 EWM 7.0.1 New and Noteworthy
Upgrade to Jenkins version 2.60.1 and Java 8
Remove support for RTC 5.x releases.

GitHub commit - 9a6a46c6ae

1.3.1 January 7,2020

Fixed security issue #1605

GitHub commit - c5a48d1541

1.3.0 May 1, 2019

Note

The default behavior of creating "Related artifact" link to a Jenkins build in all the accepted work items when using Repository Workspace or Stream job configuration (introduced by work item 388795) has changed. In 1.2.0.5, links will be created in all the accepted work items. In 1.3.0, links will NOT be created in all the accepted work items. There is a new option "Add Jenkins build link to accepted work items" in the Job configuration to create these links and is unchecked by default. You must select the option in the Job configuration to create related artifact links to a Jenkins build in all the accepted work items. See work item 461859 for more details.

You can collect metronome information for all build configurations.See Collecting Metronome Logs section for more details.
- See Work Item 438208: Enhance Team Concert Plugin to collect metronome log like JBE
In this release, we have changed the behavior of creating "Related artifact" links to Jenkins builds in all the accepted work items originally introduced by work item 388795. You must choose the option "Add Jenkins build link to accepted work items" in the Jenkins job configuration to create "Related artifact" links to Jenkins builds in all the accepted work items.
- See Work Item 461859: Make the "creation of Jenkins build links to work items in accepted change sets" an opt - in for the users in Repository Workspace and Stream configuration.
We have fixed an incompatibility with Pipeline jobs wherein messages from Team Concert Plugin were not printed in the build log.
- See Work Item 478877: Pipeline builds do not output messages from RTCScm

GitHub commit - 166456d2a65

1.2.0.5 June 15, 2018

Important information : The minimum required version of Jenkins is now 1.625.1. After upgrade, it is recommended to check that the Team Concert plugin (RTCScm) configuration is intact in a few jobs.

In repository workspace and stream build configuration, plugin now creates links to the Jenkins build in the work items attached to the change sets
- See WorkItem 388795: In Team Concert Jenkins Plugin, when using build workspace/stream configuration, create backlinks in included work item (s) to the Jenkins build
You can view the version of build toolkit used in master and agent in the build log by adding com.ibm.team.build.debug = true to the environment or as a job parameter.
- See WorkItem 449539: [Jenkins] Log the version of build toolkit in the build log
You can access the environment variables exported by RTCScm in a checkout step by assigning it to a groovy variable.
- WorkItem 446242: Adopt changes to SCM from [.jira-issue .conf-macro .output-block]# https://issues.jenkins-ci.org/browse/JENKINS-26100 JENKINS-26100] - Getting issue details… STATUS #
Other fixes
- WorkItem 398804: Upgrade parent pom version to 2.x
- WorkItem 448725: Jenkins Build Error: An invalid XML character (Unicode: 0x10) was found
- WorkItem 458158: Move to Java 7 - upgrade minimum required Jenkins version to 1.625.1

1.2.0.4 December 04, 2017

Support for load rules in Jenkins jobs configured with an RTC repository workspace, stream, or, snapshot.
1. https://jazz.net/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/402834[402834:
Per checkout dynamic load rules configuration.
1. 403461: Provide an interface in the Jenkins job configuration to check for dynamic load rules during a run
Fix for 403254: Dynamic load rules should have precedence over load rules from Build Definition
getComponentLoadRules method in dynamic load rules extension is deprecated. Instead dynamic load rules have to be returned by the newly added getPathToLoadRuleFile method. For more information, see DynamicLoadRulesJenkinsPlugin.
https://jazz.net/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/367019[367019:
410454: team_scm_workspaceUUID should be available as an environment variable for Repository workspace based builds.

1.2.0.3 Jun 16, 2017

In Build Definition configuration, Post Build Deliver is supported when using Rational Team Concert server 6.0.4 or higher. You can edit the Build Definition in RTC to include Post Build Deliver configuration. The configuration information will be used by the plugin to perform post build deliver.
1. Improve the Team Concert Plugin for Jenkins to support post-build deliver for build definition configuration

1.2.0.2 Dec 6, 2016

Support for customising the name of the snapshot created during the build. You can use Jenkins job parameters and/or environment variables in the snapshot name. During the build, the parameters will be resolved to their values to construct the snapshot name.
1. 368222: Support customization of the name of the generated snapshot
In Stream configuration, allow check-in and deliver changes using SCM CLI during the build. The temporary Repository Workspace created for loading content is now deleted at the end of the build, thus permitting check-in and deliver operations. The name and UUID of the temporary Repository Workspace created during the build is available as rtcTempRepoWorkspaceName and rtcTempRepoWorkspaceUUID
1. 397202: Ability to check-in and deliver changes in Stream configuration based Jenkins build
Fixes for the following issues

1.2.0.1 Aug 16, 2016

A String parameter can be provided in the text field for Build Definition, Repository Workspace or Stream as ${paramater_name}. Enhancement 324449 https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=324449[- Jenkins Team concert plugin can support parameters for stream,workspace and build definition fields]
A Snapshot can be scoped to a Repository Workspace or Stream. Task 392790 -https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=392790[For build snapshot configuration, provide options to specify the project area/team area and the owner workspace/stream]
A Stream can be scoped to a Project Area/Team Area. Task 391633 https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=391633[- In the build stream configuration, use the project area/team area value, if configured, to resolve the stream specified by name]
Support for configuration level validation instead of validating individual fields in the Rational Team Concert section.
Temporary Repository Workspace created for Snapshot and Stream configuration have a comment of the form "Created by Team Concert Plugin for job in Jenkins server. Task 388924 - Add a comment to the temporary workspace so that it becomes easier to identify it as a build workspace
Link to the Build Definition, Repository Workspace, Stream used in the build now appears in the build page. Task 396340 - Add links to the current configuration used in a build of a Jenkins job

1.2.0.0 April 22, 2016

Enhancement 376827: Support Load Directory and Delete before loading in Jenkins Job
Enhancement 382347: Support RTC BuildDefinition’s Accept Options in Jenkins job
Enhancement 366909: Support for loading from a snapshot
Enhancement 375548: Support for loading from stream
Enhancement 376098: Provide dropdown combo box support for various build configurations
Fixes for the following issues
1. 346653: Jenkins plugin repeatedly resets the "Quiet period"
2. 380220: Rework the Jenkins Plugin messages to display the error trace
3. 388284: Loading a jenkins build workspace with a RTC build definition configuration fails in Jenkins 1.655
4. 383194: Insufficient error handling or error logging for dynamic load rule generation - with this fix, implementations of dynamic load rules can propagate any exceptions to the teamconcert jenkins plugin.
5. 387320: Validating workspace/connection during job configuration fails if the job is created under a folder with global credentials scoped to the folder

1.1.9.9 January 25, 2016

Enhancement 338976 Provide a mechanism to generate and input the Load Rules file in the Jenkins Team Concert plugin. Dynamic Load Rules feature allows users to provide load rules for components during the build. For more information, see DynamicLoadRulesJenkinsPlugin
Fixes for the following issues

1.1.9.8 December 21, 2015

[.aui-icon .aui-icon-small .aui-iconfont-info .confluence-information-macro-icon]# #

Fix for work item 379521- RTC Jenkins plugin leaving .jazzlock file in the workspace, is not available in 1.1.9.8. The issue has been fixed 1.1.9.9

Fixes for the following issues
1. Jenkins Jobs config.xml file broken when upgrading the plugin from 1.1.9.4 to 1.1.9.7
2. Jenkins Plugin v1.1.9.7 doesn’t save the credentials of the global RTC configuration (Manage Jenkins)

1.1.9.6 and 1.1.9.7 October 26, 2015

Fixes for the following issues
1. RTCScmStep uses serverUri but RTCScm uses serverURI
2. RTC Jenkins integration for "Recent Changes" does not work properly when a changeset is related to two workitems
Note that 1.1.9.6 and 1.1.9.7 releases are the same, 1.1.9.7 is a respin of the 1.1.9.6 release to fix the error in the release 1.1.9.6.1

1.1.9.6.1 October 26, 2015

Invalid plugin release, do not use

1.1.9.5 September 21, 2015

Fixed multiple issues with supporting WorkFlow projects

1.1.9.4 August 04, 2015

Fixed issue with load rules and RTC 5.x build tool kit Remote load rules not working using Jenkins Team Concert Plugin 1.1.9.3 (364161)

1.1.9.3 July 26, 2015

Implement Quiet period support for FreeStyle project types. work item 362725
Initial implementation for Workflow jobs. 362121: RTC Jenkins plugin - workflow support. Refer to Usage guide and documentation for more details.
Note that this is a initial implementation with some limitations and issues, refer to the the limitation section for know issues and workarounds.

1.1.9.2 June 11, 2015

Translation update and release for RTC 6.0https://jazz.net/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/360197[work item 360197]

1.1.9.1 March 26, 2015

Provide a Group ID in the Team Concert plugin work item 336266
RTC build plugin for Jenkins repeatedly resets the "Quiet period" work item 350379

1.1.9 October 9, 2014

There is a migration impact for this release. See the Migrations section below.

When a Jenkins build is deleted, the corresponding RTC build result(s) (if there are any) are deleted from RTC. The RTC build result will not be deleted it it is flagged as deletion is not allowed. work item 330249
Improve support for "Multiple SCMs" plugin. You can now specify multiple RTC SCM configurations referencing different servers (when builds are started from Jenkins). work item 300164
Support so RTC’s Build Definition editor can warn the user if the Jenkins job doesn’t point to that definition work item 276139
Thread’s context class loader not reset properly + work around for unexpected failure to load LogFactory class work item 322272

1.1.8 July 10, 2014

Main Jenkins configuration page was not showing the chosen Build toolkit work item 320832
Add warning to console log when build workspace has components not visible to the build user work item 203294
When the SCM provider is the "Multiple SCMs" plugin, the detailed changes for a build does not list the change details work item 323307

1.1.2 June 11, 2014

Support for Jenkins credentials has been added which introduced a dependency on the Credentials plugin. If a job is already configured to use user ID and password (or password file) , it will continue to run but these fields are read only. Any changes will require credentials going forward. Using the Credentials plugin offers more flexibility and solves some issues.
1. Multiple credentials can be defined and used in multiple jobs
2. Can use a global user ID and password (or password file) when the RTC URL is overridden issue 21537
3. Improves Security issue 21038 and work item 295009
Work related to starting a build with an RTC build result has been moved from the master to the agent (assuming the job is running on the agent). Work item 306172
When builds are started within RTC, the server will manage the lifecycle of the build result by periodically polling Jenkins to determine if the build is completed. With RTC 5.0, build definitions support the boolean property com.ibm.rational.connector.hudson.queueOnly. When used in conjunction with this release of the plugin, the plugin will terminate the RTC build result when the build completes (just as it does when the build is started in Jenkins). If a lot of builds are started from within RTC, this will be more efficient. Requires RTC version 5.0 or later. Work item 308749
New option to use rest service calls to communicate with the RTC Server when performing configuration, polling and build result management (as opposed to the build toolkit). This means if all the jobs have this configured and run on agents, the toolkit classes will not be loaded on the master. Requires RTC version 5.0 or later.

1.0.12 (and earlier) October 23, 2013

This plugin version does not have any Jenkins specific dependencies.
To authenticate against an Team Concert server a user id and password is required. The password can be supplied directly or it can be placed in a password file.
The RTC build toolkit is used perform build related tasks within Jenkins master and agent processes (as opposed to using a command line client). The RTC related tasks include validating the configuration, polling and working with the RTC build result as well as performing the Accept and Checkout phases of the build.
Support for a simple build workspace
1. Changes are accepted into the build workspace from the stream(s) referenced by the flow target(s)
2. Snapshot of the workspace is created for a build
3. Change log is created
4. Build workspace is loaded
Integrated support for build definitions
1. Traceability links from a Jenkins build to an RTC build result, workspace and snapshot.
2. Publishes links to work items, change sets and file contents captured in the snapshot.
3. Build workspace is identified by the Build definition
4. Changes are accepted into the build workspace from the stream(s) referenced by the flow target(s)
5. Snapshot of the workspace is created for a build
6. Additional SCM configuration options available in the build definition
7. RTC Build result is created for a deeper integration with the work items included in the build
8. Builds (including personal builds) can be started from RTC
9. Environment variables defined in the RTC build definition are available in the build environment

RTC build environment variables are available in the build environment

property	description
team_scm_changesAccepted	How many changes were accepted. Not set if there were no changes.
team_scm_snapshotUUID	UUID of the snapshot created after accepting changes. Not set if no snapshot was created.
RTCBuildResultUUID	UUID of the build result. Only set if the build is using a build definition
requestUUID	UUID of the build request. Only set if the build is using a build definition.
buildDefinitionId	UUID of the build definition being used by the build. Only set if the build is using a build definition.
repositoryAddress	Address of the RTC repository.
buildEngineId	Name of the build engine associated with the build request/result (if there is a build result). An RTC build engine is not actually running, but some ant tasks need the engine id.
buildEngineHostName	Host name of the Jenkins master or agent that the build is running on.
buildRequesterUserId	User id of the RTC user that requested the build be started. Only set if the build is using a build definition
personalBuild	True if the build is a personal build (requested from RTC), otherwise, not set

Migrations

1.1.9

The environment variable buildResultUUID is a parameter that is supplied to the Jenkins job when the build started from RTC. It was sometimes also being updated (contributed by this plugin) even if the build was started in Jenkins. In order to better support building multiple projects with the Multiple SCM plugin, the environment variable will not be updated by this plugin. The build result UUID is still available from the RTCBuildResultUUID regardless of where the build was started from.

1.1.2

Jenkins Credentials Plugin is now used for storing the user ID and password. For an existing global configuration and jobs, the user ID and password (or password file) fields will be read-only. If a job is using a password file and needs to change a password, the password file contents can be replaced. Otherwise, to update the password the job will need to start using credentials. If this not acceptable, the plugin can work in the old mode by setting the system/environment property: com.ibm.team.build.credential.edit=true.

1.0.10

On Linux, a build definition with a load directory starting with "/" (i.e. "/any/folder") used to be interpreted as a relative path, but is now correctly interpreted as an absolute path. So, any build definition relying on the previous behavior need only prefix the load directory with a "." (i.e. "./any/folder").

Security Warnings

1.3.0 or older

Please review the following warnings before using an older version:

Name		Name	Last commit message	Last commit date
Latest commit History 358 Commits
.github/workflows		.github/workflows
.vscode		.vscode
com.ibm.team.build.hjplugin-rtc.tests		com.ibm.team.build.hjplugin-rtc.tests
com.ibm.team.build.hjplugin-rtc		com.ibm.team.build.hjplugin-rtc
com.ibm.team.build.hjplugin		com.ibm.team.build.hjplugin
.gitattributes		.gitattributes
.gitignore		.gitignore
README.adoc		README.adoc

jenkinsci/teamconcert-plugin

Folders and files

Latest commit

History

Repository files navigation

Team Concert Plugin

Documentation

Product Name Change

Rational Team Concert Help Topics

Requirements

Jenkins

RTC

Jenkins Configuration

Add a new Build Toolkit

Update RTC Global Configuration

Job Configuration - FreeStyle job

Configuring for Build Definition

Configuring for Repository workspace

Configuring for Snapshot

Configuring for Stream

Load Options

Accept Options

Traceability Options

Build Triggers

Triggering builds by polling for changes

Triggering builds on a schedule

Configuring Jenkins job for Post Build Deliver (Build Definition configuration only)

Job Configuration for Pipeline jobs

Generating Pipeline Snippet for Team Concert Plugin from Snippet Generator for RTC SCM and Post Build Deliver

Best practices when using Snippet Generator

Using Pipeline Script from SCM

Considerations when using Pipeline Script from SCM and a declarative pipeline in Jenkinsfile

Master/Agent Configuration

RTC Log

Configuring Java Logging for Team Concert Plugin

Configuring logging in the build console log

Logging the version of build toolkit

Configuring Java Logging for the Build Toolkit

Collecting Metronome Logs for different build configurations

Configuring for Build Definition

Configuring for Repository Wokspace, Stream and Snapshot

RTC Build Properties available during Jenkins build

Accessing RTC properties in a Freestyle job

Accessing RTC properties in a Pipeline job before checkout step - Build Definition only

Accessing RTC Properties in a Pipeline Job after checkout step

Accessing RTC Properties in a pipeline job using env object

Accessing RTC properties through RTCBuildResultAction object

Wrapping the code to access RTCBuildResultAction in a Global Shared Library

Symbolic Link support

Load Rules Support

Load Rules behaviour in Team Concert Plugin version >= 1.2.0.4

Load Rules behaviour in Team Concert Plugin version < 1.2.0.4

Advanced Pipeline capabilities

Perform polling only and generate changelog while skipping downloading the sources in the Jenkins build

rtcBuild Step

Request build

Wait for Build

List Logs

List Artifacts

Download Log

Download Artifact

Get SCM Snapshot

Accessing Jenkins build parameters and groovy variables in steps

Known caveats with download log or artifact into the jenkins workspace on an agent

Publishing downloaded log or artifact to the Jenkins build

Known Limitations

Known Limitations with fixes in newer releases of RTC

Tutorial

Best Practices

References

Releases

2.4.4 March 07, 2024

2.4.3 October 03, 2023

2.4.2 June 06, 2023

2.4.1 January 20, 2022

2.4.0 June 22 2021

2.2.1 March 30, 2021

2.2.0 December 22, 2020

2.1.0 July 18,2020

1.3.1 January 7,2020

Packages