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. 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.
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.
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.
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
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 “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:
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.
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” (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:
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.
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.
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 following is an excerpt from the log starting from the invocation of this plugin:
Skip to end of metadata Go to start of metadata