| June 17, 2022

SCM Integration of HCL Compass with HCL VersionVault Express – (Webhook based)

Introduction:

This Blog covers snapshot of the key steps that are needed to configure SCM Integration of HCL Compass 2.1.0 with HCL VersionVault Express 2.1.0 – using the Webhook based method.
With this integration in place, we can track the Change sets that are done in context of an Activity on the HCL VersionVault Express end that corresponds to a specific Defect or a Record on the HCL Compass end.
In the end of this article we can also see an Example that shows the integration in action, between the HCL VersionVault Express and HCL Compass.

Following is the list of topics that are covered in this article:

Si No:	Topic
1	Prerequisites for the Integration – HCL VersionVault Express and the HCL Compass components and versions needed
2	Installing the SCM Integration Packages on the Compass DB
3	Starting the Rest server
4	Configuring the SSO and SCM on the Compass Schema and DB.
5	Defining the SCM Configurations on Compass
6	Setting up the Webhook on the VersionVault Express end.
7	Final Integration in action

Prerequisites before starting with configuring the integration:
We need the following 2 things already up and running.

a) HCL VersionVault Express 2.1.0 installed and running.

b) Compass 2.1.0 installed with Compass RESTful services installed

2. Start the Compass RESTful services:

Open CMD as administrator (run as administrator) and run the command “start.bat” from the default location of the Rest server

Default path is: C:\Program Files\HCL\Compass\compass-rest-server-distribution\bin>

(unless you have changed it while installation) .

See the below screenshot where it will start the “Springboot” and after few minutes the service wills start and be ready.

Reference: https://help.hcltechsw.com/compass/2.0.1/com.hcl.compass.doc/webhelp/oxy_ex-1/com.ibm.rational.clearquest.oslc_cmrest_api.doc/topics/c_rest_api_introduction.html

3. We will initially be seeing only the Default Record types in this DB if we login in the Compass for the Compass database where we are going to do the integration. In this example we are using a “Defect Tracking” Schema. So we can see the below records.

4. On Compass end, install the “SCM Integration” package on the Schema that you are working with:

4a) Go to Compass Desginer and install the package as shown below:

4b) Select “SCM Integration package” and click “Next”

4c) Select the record type to which the package must be applied. In our current example we will select the “Defect” record types and click “Finish”.

4d) Checkin the Schema Version change done:

4e) Upgrade the User database to apply this Schem change:

4f) Select the new Schema Version “2” and click “Ok”

4g) Now the UserDB has been upgraded to Schema Version “2”

5. Next Run the below commands to configure the SSO and the SCM groups and users on the Compass DB:
5a) cqperl setupSSO.pl <<repository_name>> <<admin_user_name>> <<sso_user_name>>
5b) cqperl setupSCM.pl <<repository_name>> <<admin_user_name>>

Reference:
https://help.hcltechsw.com/compass/2.1.0/com.hcl.compass.doc/webhelp/oxy_ex-1/com.ibm.rational.clearquest.integrations.doc/topics/t_scm_task.html

6. Now if we check the “Compass User administration” of this DB , we will see “SCMIntegration, SSO_USER” users and “SCMIntegrationAdmins” Group being created due to the command that we ran above.

7. We will add the ID that we are using for logging in and configuring to this group “SCMIntegrationAdmins”.
7a) In this example we will add the “admin” ID that we will be using – to the group and upgrade the DB.

7b) Then we can see that the “admin” ID is also part of this group:

8. Then do “Upgrade” of the Database from “DB Action”

9. Now if we check the “New record” section of our database in Compass, we will see the below 3 additional SCM related record types being made available in the list:

10. Next create the Config records for the required SCM in HCL Compass:
10a) in this example we will create for HCL VersionVault Express.

10b) To create “Security” -> Click “New” and it will pop anther form like below:

Enter the Config name same as previously given, and a “Secret” key (I am giving “hello” just for sake of example here, you can choose and give a complex key here).

Then click on “Save and Close”.

10c) The Security will be populated as below, now we can save the Config record and close it:

11. If we query for the “Config” type of records by creating a new query in Compass, then we should see the Config that we created as below:

12. Now let’s configure the Webhooks on the VersionVault Express end for the Compass Integration:

Per stream in VersionVault Express, we have to enter the Webhook payload as below:

Click on “Add Webhook”

Webhook name -> Can be anything of your choice
Payload URL -> This is of the form:
https://<<hostname>>:8190/ccmweb/rest/repos/<<repository_name>>/databases/<<db>>/services/scm/webhooks/<<config_name>

In Our Example:
https://<compassHost>:8190/ccmweb/rest/repos/VVExpInt/databases/SAMPL/services/scm/webhooks/CfgVV

Secret -> Enter the Secret value that we entered in the Compass end. In our example we will give the value “hello” that we gave in Compass end.
Select Events -> Select the Events at VersionVault Express, for which we have to trigger the Payload to Compass
Then click on “Validate”, if all the connections are correct then we should see a success message as below in GREEN as “Accepted”

13. Integration in Action:

Now we must first create a Defect / record in Compass end and take the Record ID.

This Compass Record will be corresponding to the Activity at the VersionVault Express End.
In our example lets say we created a Compass defect with Record ID: “SAMPL00000045”

In VersionVault Express end we will create an Activity where in the Activity name is starting with the Compass record ID that we created.

14. On the Stream we will set into the activity and do all the code changes that we will do from the VersionVault Express end.
So the activity will record the changes as “Change sets” under it:

15. Now by the virtue of the “Web hooks” the event done at the “Activity” end will trigger a payload to the Compass.
And this will be captured as a changeset information in the “SCM Events” section of the Compass record as below.
It will have the ink of the Activity along with the URL of the SCM from where it was triggered. In our example it will have the VersionVault Express instance URL.

16. If we click on that Link URL in the SCM Events section of that activity change set, it will take us to the VVE Activity as below:

Conclusion:

As we can see, from the HCL Compass end – in a given Defect or a Record, we will be able to track what all Changes happened in the Source code at the HCL VersionVault Express end.
These will be captured as the Changesets in the HCL VersionVault Express Activity.
And in the HCL Compass end it will be captured as part of the “SCM Events” section of the HCL Compass record end corresponding to that Activity.

Comment wrap

Avinash Srinivasamurthy

Senior Technical Specialist

Avinash is a Senior Technical Specialist at HCLSoftware. With a Master’s degree in "Software Systems", he has 15 years of experience in the IT industry. A large part of his experience is around Change and Configuration Management, DevOps domain. He has been actively involved in the VersionVault implementations and the Upgrade assistance program for some of the key customers. He has published several articles, Product concept videos on the HCLSoftware channel, delivered Technical sessions and Webinars on product solutions and implementation in the area of CCM.