The Integrity Configuration Management (CM) Plug-in for Jenkins provides the following capabilities:
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.
API (mksapi.jar) Compatibility Note
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.
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. The size of this database is dependent on the number of active Jenkins items (Jobs x Builds). Hence if disk space or performance of this embedded database becomes an issue, it will be necessary that you maintain a limited number of builds.
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
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
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
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:
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:
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.
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:
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:
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.
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
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:
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
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:
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.
The Integrity CM Plug-in supports the workflow-plugin and associated updated core Jenkins APIs. The following screenshot illustrates how a generic checkout step can be scripted using the workflow-plugin's Snippet Generator
Additionally, the Integrity CM Plug-in also supports three additional workflow steps at this time:
Integrity SCM Label Note
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:
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.
Skip to end of metadata Go to start of metadata