PTC Integrity Plugin

Skip to end of metadata
Go to start of metadata

This Jenkins plugin provides SCM integration capabilities to PTC Integrity for Configuration Management.

Overview

The Integrity Configuration Management (CM) Plug-in for Jenkins provides the following capabilities:

  1. Build from any Integrity CM Project configuration (normal, variant, and build)
  2. Tag support with a user defined tag name/pattern. For example:
    ${env['JOB_NAME']}-${env['BUILD_NUMBER']}-${new java.text.SimpleDateFormat("yyyy_MM_dd").format(new Date())}
    

    A “tag” translates to an Integrity CM Project Checkpoint with a project label and without cascading the label to all members

  3. Supports full or incremental workspace synchronization. When a clean option is checked, then the current workspace is deleted and a fresh copy is downloaded from Integrity. If the clean option is left unchecked, then the workspace is updated based on changes found in the Integrity repository
  4. Provides a detailed Change Log of what is different for the current build with integrated SCM Browser Support. Change Log report will link directly into Integrity CM Annotated Member and Differences Views
  5. Polls Integrity CM on a cron schedule to see if there are any changes, if so then automatically kick off a build
  6. Supports distributed/remote build execution. In a clustered Jenkins environment this plug-in is designed to execute the checkout operation on remote slaves
  7. Provides the option to update an Integrity “Build” item with the results of the build including the option to save the log contents to a rich text field
  8. Provides the option to update an Integrity "Test Session" item with the results from a build's automated test execution
  9. Updates Integrity project/sub-project with output from build

Plugin Information

Plugin ID integrity-plugin Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.23
Feb 20, 2014
1.546
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Cletus D'Souza (id: cdsouza)
Usage Installations 2013-Apr 138
2013-May 148
2013-Jun 150
2013-Jul 153
2013-Aug 150
2013-Sep 159
2013-Oct 175
2013-Nov 185
2013-Dec 185
2014-Jan 189
2014-Feb 188
2014-Mar 207

Installation Preparations

Prior to getting started with this installation, you will need to make sure you’ve enabled API connections on the Integrity Server. This plug-in does not use the Integrity Client and uses the API exclusively to communicate with the Integrity Server. Furthermore, this plug-in packages the mksapi.jar (4.11.3238) within the install package. It should be known that mksapi.jar comes with a version of apache http client which might not be compatible with Jenkins or Maven’s apache commons http client packages.

Step 1: Enable the Plug-in

On the main page of Jenkins, click on “Manage Jenkins” as illustrated below:

On the “Manage Jenkins” page, click on “Manage Plugins”:

And then click on the “Available” tab:

On the “Available” tab, scroll down to the section containing the “Source Code Management” plugins. Check the box beside the “PTC Integrity Plugin”

Finally, click “Install” at the bottom of the screen.

Note
You will need to restart the Jenkins server for the plug-in to get installed.

Step 2: Validate Successful Plug-in Installation

After you’ve restarted the Jenkins server, go back to the main page of Jenkins and click on “Manage Jenkins” > “Configure System”

If the installation was a success, you should see the “Integrity CM” configuration block under the “Configure System” page:

You should configure the default connection parameters which will be reused when you configure a build job or when you enable the “Integrity - Workflow Item” action. You will have the option to override the settings for the specific action should you have different servers for Workflow vs. Configuration Management. The advanced button contains the default configuration for the Integration Point and SSL settings.

Step 3: Configure a Build using the Integrity for Configuration Management plug-in

Navigate to any existing Build configuration or create a new build job as needed. Please refer to Jenkins documentation on how to create a new Build job.

On your build configuration page, you should now see a new option under “Source Code Management”:

Click on the “Integrity - CM” option to configure the settings for the Integrity plug-in

Under the advanced settings you will have the option to override the default connection settings which are typically copied from the “Configure System” page

As illustrated in the image above, the question mark icons will provide help on a given configuration field.

Projects can be specified using the old convention (full path to project.pj). However, when referencing a development path or a specific checkpoint, you must specify the “Configuration Path” convention.

Configuration Path Note
Please refer to Integrity documentation or contact PTC Customer Support for details on how to obtain the Configuration Path for variant and build configurations

To update an existing Jenkins workspace, you should leave the “Clean Workspace?” field unchecked. Checking 'Synchronize Changed Workspace Files' option will cause the plugin to generate and store checksums for files in the workspace. When a build is executed either manually or due to a polling trigger, then the checksums will be used to synchronize any changed or deleted workspace files.

Synchronize Changed Workspace Files Note
If a polling trigger detects no changes for the Integrity SCM Project in the repository, but some workspace files have been deleted or changed, then the workspace files are not synchronized. This is because the checksum difference calculations are performed on the target file system (or salve). Hence the only time the workspace is actually synchronized is when a build is kicked off, either manually or due to a change in teh Integrity SCM Project

The “URL” field for the “Repository browser” is optional. By default, the plug-in will construct a URL based on the host/port/secure parameters specified. However, should you want to provide a different link for viewing the Annotated Member and Differences View, you may specify the URL in the field provided.

Repository Browser URL Note
If you are running the Jenkins server on the same server as the Integrity Server (not recommended), then you will need to either override the “URL” field or access Jenkins using a different URL. Integrity CM links do not work if Jenkins and Integrity are running on the same server and/or are accessed with the same URL. Perhaps you can access Jenkins with just the hostname, example: http://hostname:8080 and Integrity with the fully qualified DNS name, example: http://hostname.domain.com:7001. Obviously the recommendation is to run the Integrity Server and Jenkins on separate servers or virtual machines.

Optionally, if you’d like to poll Integrity CM for updates to your project, you may specify the schedule under the “Poll SCM” > “Schedule” field. In the following illustration, Jenkins will poll Integrity CM every five (5) minutes.

At the bottom of the Jenkins Job configuration page, you will see a post-build action called “Integrity - CM Checkpoint”. Use the “Tag Name” field to define a Groovy pattern for the Integrity CM Checkpoint Label. The “Tag Name” string will be validated for invalid label characters.

Click “Save” on the bottom of the page to commit your changes:

Step 4: Execute the Build and monitor progress

Click on “Build Now” to immediately kick off the build

In the “Build History” area, click on the build you’ve just kicked off to monitor the progress:

Clicking on the “Console Output” should get you the details of the build in progress:

As highlighted above, when the ‘Clean Workspace?” option is left unchecked, the plug-in will attempt to update the workspace by only downloading any changed files (which includes adds/renames/moves) and dropping any files that are no longer needed (which includes drops/renames/moves). Also, as illustrated below, this plug-in wont attempt to checkpoint Integrity CM Build configurations. Only normal or variant configurations will be checkpointed.

Tagging

A ‘tag’ translates to an Integrity CM Project Checkpoint with a project label and without cascading the label to all members. Integrity CM plug-in supports tagging with a user defined tag name/pattern. For example:

${env['JOB_NAME']}-${env['BUILD_NUMBER']}-${new java.text.SimpleDateFormat("yyyy_MM_dd").format(new Date())}

Tagging is configured in the Jenkins build job under a “Post-build Action” (see page #10 for details). The following characters are not allowed within a “Tag Name”:

$
,
.
:
;
/
\
@

If you’ve configured the “Integrity - CM Checkpoint” Post-build Action correctly, then upon successful completion of a build, you should see an entry in the console output as follows:

Following is the project history view in Integrity CM after the build referenced above completed successfully:

Polling

Based on the polling configuration for the Jenkins build job, you should see a link “Integrity CM Polling Log” in the left side navigation pane. Clicking on this link will give you details about the last poll. In this case, our poll ran at 5:35 PM and found a total of 4 changes (which includes adds/updates/drops).

Also notice, in the left side “Build History” window, a new build has been kicked off and will start in 3.1 seconds.

Change Log and Integrity CM Browsing

This plug-in provides a detailed Change Log of what is different for the current build with integrated SCM Browser Support. Change Log report will link directly into Integrity CM Annotated Member and Differences Views. For example, clicking on the build that was kicked off via our SCM Polling trigger, you’ll notice that the build was started by an “SCM change”. Additionally, the Summary of Changes lists out the details (date and comments) obtained directly from Integrity CM.

Clicking on the “detail view” above will produce a detailed report as follows:

The “Action” column provides an indicative icon about the change (add/update/drop). Additionally, in the case of an update, the Edit Action icon is actually clickable. Clicking on the Edit Action will take you to the Integrity CM - Member Differences View. Similarly, clicking on the “Revision” will take you to the Integrity CM – Annotated Member View.

Drop Member Note
The comments associated with the “drop” action are actually referring to the last member revision in the Integrity CM Project at the time of the drop. Currently, Integrity CM does not capture comments when a file is dropped.

As an example, clicking on the “Edit Action” icon for member Stage.java, produces the Integrity CM - Member Differences View as illustrated below:


Likewise, clicking on the revision link, you will get the Integrity CM - Annotated Member View:


Remote Execution

The Integrity CM Plug-in for Jenkins supports build execution on remote slaves. Currently, the plug-in is designed to only execute the “check-out” step on a remote machine. All other commands are executed from the Jenkins master server.

The remote build execution is virtually transparent from an SCM plug-in point of view. Perhaps the only difference might be a different workspace path as illustrated in the output from the following build executed on a slave machine:

No additional setup is required, so long as the Integrity Server is configured to allow API connections from any machine. If Integrity’s API connections are configured for specific servers, then you will need to ensure the respective Jenkins salve nodes are added to the list of allowed connections on the Integrity Server.

Remote Execution Note
If you switch building from the “Master” to a “Slave” node; or from one “Slave” node to another “Slave” node, then you must check the “Clean Workspace?” option (as described on page #9) in order to obtain a full copy of the source code from the Integrity Server. This does not impact the ability of the plug-in to calculate the “Change Log” or generate the “Summary of Changes” report.

Integrity Workflows & Documents Integration

The Integrity CM Plug-in for Jenkins facilitates end-to-end traceability by capturing build outcomes and automated test execution results.

Simply enable the 'Integrity - Workflow Item' post build action and you will have configuration options for both “Build Management” and “Test Management”. The plug-in is flexible in terms of capturing just build information or just test results or both. If you'd like to use the Test Management integration only, simply leave the 'Query Definition' parameter blank and provide a 'SessionID' parameter to the build. This 'SessionID' is used to find the Integrity Test Cases and based on the 'External ID' field mapping (Test Case Test Name Field), test results are populated in Integrity. The 'External ID' field should reference the JUnit or other Test ID using the appropriate syntax. In the case of JUnit test results, the following are acceptable forms of Test Case IDs:

Default Package Example:  junit/(root)/TestCaseClassName/testCaseName

Package Example: junit/com.ptc.demo/TestCaseClassName/testCaseName

Java Package Example: com.ptc.demo.TestCaseClassName.testCaseName

If you'd like to integrate Build Management with Test Management, then simply define a relationship field between the 'Build' item and the 'Test Session' (Test Session Field). The plug-in first checks for the existence of a build parameter 'SessionID', if not found, then will look for the 'Test Session Field' relationship to determine how to locate a 'Test Session' item. This implies that your build automatically generates test results. If there are no test results for the build, then the 'Test Management' configuration is simply ignored.

Troubleshooting

To troubleshoot this plug-in you can monitor the jenkins.err.log that will give you detailed information on the execution of this plug-in:

Debug Logging Note
The plugin uses the Apache commons logging library. In order to turn up debug logging add the property -Dorg.apache.commons.logging.simplelog.log.IntegritySCM=debug to the startup arguments in jenkins.xml:

  <arguments>-Xrs -Xmx256m -Dorg.apache.commons.logging.simplelog.log.IntegritySCM=debug ... --httpPort=8080</arguments>

The following is an excerpt from the log starting from the invocation of this plugin:

Change Log

Version 1.23 (Feb 20, 2014)

  • JENKINS-21689: SCM occasionally does not write some checked out files to Workspace
  • JENKINS-21587: memory leak in Plugin 1.22 -orphaned Logger Threads (accepted patch from Matthias Rump - thank you!)
  • JENKINS-21479: Poll SCM trigger not functioning during the first execution (incorporated suggestion from Gregory Pierre - thank you!)
  • JENKINS-21260: PTC integrity plugin: version 1.19 instantly triggers new build though corresponding files in repository have not been changed!

Version 1.22 (Jan 24, 2014)

  • Rolled back fix about (java.lang.StringIndexOutOfBoundsException) when moved files are fetched from server. Since this doesn't appear to be an actual move, trapping edge case condition and logging warning.

Version 1.21 (Jan 23, 2014)

  • Contributions from Christian Bürenheide - Thank you!
    • JENKINS-21350: Here we get a NullPointerException when checking out a variant project where the original project has been moved. In my opinion this is a major problem and it would be good to have it fixed in one of the next plugin versions.
    • JENKINS-21351: This is just a nice-to-have. A little inconsistency since Groovy expressions can be used in the main SCM config section but not in the checkin post-build action.
    • JENKINS-21370: The addprojectlabel functionality had been removed with 1.20. This feature has been recovered and extended with the functionality to recurse subprojects for applying checkpoint labels to subprojects as well.
  • Additional fixes:
    • JENKINS-21410: memory leak in Plugin 1.20
    • Fixed issue (java.lang.StringIndexOutOfBoundsException) when moved files are fetched from server

Version 1.20 (Jan 07, 2014)

  • Fixed JENKINS-20751: PTC_Integrity Plugin- file exclude filter not working for multiple entries - thanks to Matthias Rump for patch!
  • Added enhancement JENKINS-20541 expose pre-build checkpoint Number to build environment
  • Fixed potential security issue where Firefox can expose saved passwords in clear text
  • Upgraded to Jenkins 1.546

Version 1.19 (Dec 30, 2013)

  • All fixes/enhancements in this release was contributed by Tyrel Alastair Hunter - Thank you!
  • Fixed JENKINS-21152 Files are now unlocked after checkin even if the file was not updated
  • Fixed JENKINS-21151 Checkin can now be performed when using multiple-scms-plugin
  • Fixed JENKINS-21150 When using the multiple-scms-plugin each scm will have it's own Derby database.

Version 1.18 (Oct 04, 2013)

  • Fixed Integrity API deprecated calls that were deprecated with Integrity 10.4
  • Fixed JENKINS-19791 Workaround for missing 'memberdescription' field in API response - thanks to Joerg Steeg for patch!
  • Fixed JENKINS-19790 There was an issue with locating the previous build - thanks to Joerg Steeg for patch!
  • Added enhancement JENKINS-14705 which allows substitution of Jenkins' built-in variables and other build parameters for Integrity's Config Path parameter
  • Added enhancement JENKINS-14037 which allows the ability to add a checkpoint label to the build prior to synchronizing the workspace
  • Added the ability to filter (include/exclude) Integrity SCM Project to limit the amount of data synchronized in the workspace - thanks to Musa Molla for patch!
  • Added the ability to collect Test Results from Jenkins build and update an Integrity Test Session
  • Upgraded to Jenkins 1.533

Version 1.17 (Jun 10, 2013)

  • Fixed JENKINS-17853 where pending entries (add, rename, move) were creating incorrect configurations - thanks to Martin Bickel for patch!
  • Fixed JENKINS-17292 which was a duplicate of JENKINS-17853 above - thanks to Tobias Weier for patch!
  • Fixed JENKINS-16275 where potential CDATA tags in comments were causing errors in change log reporting
  • Enhanced support for remote build execution and subsequent update of Integrity Item using URL: http://server/job/myjob/buildWithParameters?token=TOKEN&ItemID=1234
  • Added support for updating Integrity project/sub-project based on build output/updates
  • Upgraded plugin to Integrity API Version 4.11.3238 (10.3)
  • Upgraded to Jenkins 1.517

Version 1.16 (Sep 11, 2012)

  • Fixed JENKINS-14871 to resolve an issue when no value is specified for the 'Checkout Thread Pool Size' setting
  • Fixed JENKINS-14844 to resolve missing 'Author' in Change Log - thanks to Ryan Stedman for patch!
  • Upgraded to Jenkins 1.481

Version 1.15 (Aug 10, 2012)

  • Fixed JENKINS-14704 PTC Integrity Plugin throws/catches SQL Exception in case of too long revision number
  • Added thread polling feature for checkout - contribution from Sascha Dais
  • Added feature to clean workspace of non-source controlled files - contribution from Sascha Dais
  • Upgraded to Jenkins 1.477

Version 1.14 (Jul 05, 2012)

  • Fixed issue when 'Clean Workspace' option is checked and files were dropped from the SCM Project
  • Resolved url issues in the plugin's configuration pages when running Jenkins as a Webapp on Tomcat or other Java Webservers
  • Upgraded to Jenkins 1.473

Version 1.13 (May 01, 2012)

  • Improved caching of large Integrity SCM Projects which should prevent Jenkins from crashing due to out of memory errors
  • Added feature to synchronize changed or deleted files in the workspace that originated from an Integrity SCM Project, resolving JENKINS-13221 and JENKINS-12819
  • Added the ability to turn debug logging on/off for the plug-in
  • Upgraded to Jenkins 1.462 and added dependencies to Apache Derby 10.5.3.0_1 (for better cache management), Apache commons-codec 1.6 (for checksum generation)

Version 1.12 (Jan 24, 2012)

  • Included a fix (provided by Brian Krebs) to address Jenkins-11751
  • Included an alternate (provided by Brian Krebs) suggestion to use revision numbers instead of revision dates for determining changes in Integrity CM
  • Upgraded to Jenkins 1.449 and Apache Commons Digester 3.0

Version 1.11 (Oct 10, 2011)

  • Added the option to update an Integrity "Build" item with the status of a build
  • Changed plugin branding from MKS to PTC

Version 1.10 (Sep 23, 2011)

  • Improved checkout performance as author information (si revisioninfo) is obtained only if file revision changed from previous build
  • Converted all 'info' logging into 'debug' in an effort to minimize noise sent to jenkins.err.log
  • Fixed numbering issue with Change Log on "Recent Changes" page

Version 1.9 (Aug 26, 2011)

  • Added the option to use an API Integration Point other than the Integrity Server. Allows for a client to use FSA Proxy cache
  • Added the option to use an alternate workspace directory
  • Added the option to checkpoint before the build. A label is applied after the build was successful
  • Implemented a workaround for the open file handle issue when checking out of a large project
  • Fixed polling to look at the last build vs. the last successful build
  • Updated plugin pom.xml for Jenkins 1.427 dependency

Version 1.8 (May 06, 2011)

  • Added the ability to omit author information from Change Log report
  • Enhanced error handling when attempting to obtain author information for Change Log report

Version 1.7 (Apr 15, 2011)

  • Updated Change Log calculation and Workspace synchronization based on comparison of last build vs. last successful build
  • Fixed a Change Log generation issue when bad xml characters are present in member revision comments/description

Version 1.6 (Apr 01, 2011)

  • Fixed issue with Change Log when dropped files are encountered

Version 1.5 (Mar 17, 2011)

  • Fixed a Null Pointer Exception that occurs when an API session cannot be established with the Integrity Server

Version 1.4 (Mar 04, 2011)

  • Fixed issue with checking out members from shared subprojects

Version 1.3 (Feb 28, 2011)

  • Initial Jenkins release

Labels

Edit
plugin-scm plugin-scm Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment