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

Plugin Information

Plugin ID integrity-plugin Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.31 (archives)
Feb 16, 2015
1.546
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Cletus D'Souza (id: cdsouza)
Usage Installations 2014-Feb 188
2014-Mar 207
2014-Apr 199
2014-May 217
2014-Jun 220
2014-Jul 217
2014-Aug 215
2014-Sep 239
2014-Oct 239
2014-Nov 237
2014-Dec 239
2015-Jan 258

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

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. However, an option exists to connect to an Integrity Client as a Server Integration Point. Refer to Integrity's Integrations Builders Guide for more details on Integrity API configuration options. Furthermore, this plug-in packages the mksapi.jar (4.13.5479) within the install package.

Step 1: Enable the Plug-in

On the main page of Jenkins, navigate to the “Manage Plugins” page as illustrated below:

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” configuration block under the “Configure System” page:

You can setup a list of default Integrity Server connection profiles which can be selected later when you configure a build job or when you enable other post build actions like the “Integrity - Workflow Item” action. The advanced button contains the default configuration for the API Integration Point and SSL settings. Make sure you test the connection prior to proceeding to save your connection information.

The Integrity plugin uses an embedded derby database to store cache information about an Integrity SCM Project. Since there is no way of knowing when Jenkins jobs have been purged and hence a possibility of the embedded database growing larger than expected, you can clean up the cache associated with deleted projects by clicking on the Clear Inactive Cache button which can be found under the “Integrity Cache Management” section of the Jenkins “Configure System” page

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” option to configure the settings for the Integrity plug-in

For the “Server Configuration” parameter, choose the appropriate connection profile you setup earlier in 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 the 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 “Checkpoint Label” field to define a Groovy pattern for the Integrity CM Checkpoint Label. The “Checkpoint Label” 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. If you've configured your build job to use parameters (example Integrity Item ID), then click on “Build with Parameters” as illustrated below

If you intended to check-in artifacts from the build back into Integrity, then the ItemID parameter must specify how you are authorized to update the Integrity Project.

Valid values for the ItemID parameter include:

:none    // Indicates no change packages are used for check in
:bypass  // Assumes that the user has administrative privileges to bypass change package policies configured for the Integrity Project
0        // Same as :none above
12345    // An actual valid Integrity Item ID that the plugin will use to create a change package

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, it is important to note that the 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”. The following characters are not allowed within a “Checkpoint Label”:

$
,
.
:
;
/
\
@

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:

If the “Integrity - CM Checkpoint” Post-build Action is configured for a build configuration or if the Jenkins job is configured for a pre-build checkpoint, then the post-build action simply labels the project and no new checkpoint is attempted. 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 4:46 PM and found a total of 4 changes (which includes adds/updates/drops).

Also notice, in the left side “Build History” window for new builds that will get kicked off as a result of a poll.

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 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 configure a "Log Record" for the Integrity plugin as illustrated below:

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

Plugin for Unsupported Configurations

With the release of integrity-plugin 1.29, versions older than Integrity 10.5 are no longer supported. A special one off version 1.31-4.10.9049 has been created for users who want to take advantage of the recent fixes but need more time to migrate from Integrity 2009 SP6, SP7, 10, 10.1, 10.2, 10.3 and 10.4. There will be no more fixes provided for configurations older than Integrity 10.5.

Change Log

Version 1.31 (Feb 16, 2015)

  • Resolved JENKINS-26770 - 'Apply' doesn't work in version 1.29 of the plugin
  • Implemented JENKINS-26906 - Re-introduce the ability to override the username/password at the specific job
  • Resolved JENKINS-26910 - Null pointer exception if host/port/user is changed in global configuration page
  • Fixed issue with SSL (secure connection) setting not getting saved in configuration
  • Eliminated unique 'Configuration Name' check in favor of migration path from pre-1.29 to latest
  • Fixed issue with creating APISessions in parallel checkout executions

Version 1.30 (Feb 05, 2015)

  • Transitioned from several db instance (one per build) to a single db for the entire Jenkins instance. As a result the following issues are resolved:
    • JENKINS-25228 - Using the integrity-plugin together with concurrent builds causes SQL Exceptions
    • JENKINS-14675 - Schema 'DBUSER' does not exist error in integrity plugin
    • JENKINS-25450 - Unexpected behavior of Jenkins Integrity plugin after SQL Exception inside plugin (no error returned to build job).
  • Upgraded to Apache Derby 10.11.1.1
  • The overall build status is marked failed if any of the related post build actions (Checkpoint, Delete Non-Members, Check-in and Item Workflow) encounter a failure
  • Eliminated the much contested 'Configuration Name' parameter from configuration page. It is now calculated as a GUID and saved under the covers
  • IMPORTANT - Please create new Jobs, if you are upgrading from a version older than 1.29. If you are upgrading from 1.29, then simply re-save and re-build all jobs.

Version 1.29 (Feb 03, 2015)

  • IMPORTANT - This version is not backward compatible! Please create new Jobs.
  • JENKINS-22066 - PTC plugin has massive memory leak if scm names are not unique
  • JENKINS-23369 - Unable to check-in using bypass mode
  • JENKINS-25629 - Checkpoints are done against wrong project!
  • Fixed bug with line terminator option not persisting in Integrity SCM configuration page
  • Improved handling of user and password credentials for multiple Integrity Servers
  • Switched logging from Apache Commons Logging (SimpleLog) to java.util.logging.logger
  • Removed previous limitation introduced with JRE 1.7 u40 by upgrading to Integrity API 4.13.5479 (10.5)

Version 1.28 (Oct 09, 2014)

  • Fixed JENKINS-25068: uncaught null pointer exception during SCM polling

Version 1.27 (Oct 08, 2014)

  • Fixed API compatibility issue when running Integrity item integration for Build/Test Management against Integrity 10.6
  • Added catch exception to CmdRunner.release() in APISession terminate function per JENKINS-24849

Version 1.26 (Sep 04, 2014)

  • Resolved JENKINS-23638: Error in Checkin not failing job
  • Added feature JENKINS-23369: Unable to check-in using bypass mode. Pass in keyword :bypass for the ItemID build parameter. Example - http://server/job/myjob/buildWithParameters?token=TOKEN&ItemID=:bypass
  • Moved from deprecated AbstractBuild.getTestResultAction() (changes contributed by Jesse Glick)

Version 1.25 (Jun 11, 2014)

  • Fixed 'JENKINS-23404 - NullPointerException when running IntegrityCheckpointAction' with a more descriptive error message
  • Fixed 'JENKINS-23319 - Unable to override Advanced Parameters in Checkpoint Step'‏

Version 1.24 (May 20, 2014)

  • Fixed specific serialization issue reported - java.io.NotSerializableException: hudson.scm.IntegrityCheckinAction
  • Added serialization to Checkpoint, Delete Non Members, and Item Actions
  • Suppressing 'unbuffered entity error' on checkout
  • Added additional debug logging for JUnit Test Execution in IntegrityItemAction

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