PTC Integrity Plugin

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

Plugin Information

Plugin ID integrity-plugin
Latest Release 1.16-h-5
Latest Release Date Apr 1, 2015
Plugin Central Plugin Central 3.2
Sources Github
Support Eclipse Hudson Forum
Issue Tracking Eclipse Bugzilla
Hudson Core (latest) 3.3.3

Overview

The Integrity Configuration Management (CM) Plug-in for Hudson 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 Hudson 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 Hudson, navigate to the “Manage Plugins” page as illustrated below:

And then click on the “Available” tab:

On the “Available” tab, perform a search using the keyword 'integrity'. Check the box beside the “PTC Integrity - Hudson Plugin” and then click 'Install'.

The “PTC Integrity - Hudson Plugin” is dependent on the “Groovy Support Plugin”, so make sure you have it installed as well.

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

Step 2: Validate Successful Plug-in Installation

After you’ve restarted the Hudson server, go back to the main page of Hudson and click on “Manage Hudson” > “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 Hudson 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 Hudson “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 Hudson 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 Hudson 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 Hudson server on the same server as the Integrity Server (not recommended), then you will need to either override the “URL” field or access Hudson using a different URL. Integrity CM links do not work if Hudson and Integrity are running on the same server and/or are accessed with the same URL. Perhaps you can access Hudson 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 Hudson 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, Hudson will poll Integrity CM every five (5) minutes.

At the bottom of the Hudson 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 enter an appropriate value for the “ItemID” 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 Hudson 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 Hudson 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 Hudson 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 Hudson 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 Hudson 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 Hudson 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 Hudson 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:

Labels:

plugin-scm plugin-scm Delete
tier3-hudson-plugin tier3-hudson-plugin Delete
Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.
  1. May 18, 2011

    Christophe Fouque says:

    Hello, Just a question regarding the checkpoint : why setting the checkpoint af...

    Hello,

    Just a question regarding the checkpoint : why setting the checkpoint after the build ?

    It would be interesting to be able to set the checkpoint BEFORE the build, then write the label
    associated to this checkpoint AFTER the build, only if the build is successful. Here, you extract from the checkpoint
    that has just been created then.

    Because setting the checkpoint after the build may induce a delta between what has been extracted for the build and
    what will be checkpointed as far as developpers may submit changes during the build and before the checkpoint is created.
    Finally, in that case, rebuilding from the checkpoint will give different deliverables (because the sources are different).

    What do you think ?