Link Entity to Code Commits | Pull Requests

Overview

This document outlines the process for updating an entity in target work systems by sending requests and code commits to SyncNow DevOps Gate APIs. For the update to work, developers need to mention work system entities in their code commit comments using #{target work system ID}.

We have also provided Groovy scripts for Jenkins, or you can copy and paste cURL commands from our user interface in the DevOps Gate project configuration.

Update Entities From Code Commits with Comment

This process updates entities mentioned in the comments of all commits of a build.

Usage Examples

A comment in a commit might look like the following: "Done some fixes to code #ENT-1, #ENT-2". After the build, entities ENT-1 and ENT-2 will be updated according to the mapping definition.

1. Update an entity with the build or deploy version number.
2. Update an entity if the latest build has failed.
3. Link the build to an entity – the build details and URL are set in the entity comment.

Request

POST /api/v1.0/DevOpsGate/Enrich/{DevOpsProjectID}?action=update

The payload contains the parameters as defined in the DevOps Gate Process and their values. Below are the parameters defined for the example request.

Parameter	Description
Param1…ParamX	Parameters as defined in the DevOps Gate per Entity Type mapping
entityUniqueKey	Optional if it is needed to update an entity without the use of comments
comments	The comments with #{Entity ID}

[
    {
        "fields": [
            {
                "key": "Param1",
                "value": "string"
            },
            {
                "key": "Param2",
                "value": "string"
            },
            {
                "key": "Param3",
                "value": "string"
            }
        ],       
        "comments": "String with entities unique identifiers from the target system to add comments or remote link. For example, this is a comment in some commit. Need to update entities #CLS-3938, #CLS-3933"
    }
]

Response

Parameter	Description
updatedEntitiesID	List of updated entity IDs
systemID	The target system ID where entities were updated
entityKeys	The updated entity keys
Error	Errors that occurred during the update process
Warning	Warnings that occurred during the update process

{
    "updatedEntitiesID": [
        {
            "systemID": "10",
            "entityKeys": [
                "CLS-3933",
                "CLS-3938"
            ]
        }
    ],
    "errors": [],
    "warnings": []
}

Jenkins Script

This Jenkins script collects all comments with entity IDs mentioned in commits, joins them, and adds them as one comment to be updated in the target system. It then uses the SyncNow DevOps Gateway to update all entities in the commit.

@NonCPS
def getCommentsString() {
    def list = []
    def changeLogSets = currentBuild.changeSets
    for (int i = 0; i < changeLogSets.size(); i++) {
        def entries = changeLogSets[i].items
        for (int j = 0; j < entries.length; j++) {
            def entry = entries[j]
            if (entry.msg != null) {
               list.add("""${entry.commitId} on ${new Date(entry.timestamp)}: ${entry.msg.replaceAll("[\n\r]", " ")}""")
            }
        }
    }
    return list.join(',')
}

pipeline {
    agent any

    stages {
        stage('Clone') {
            steps {
                echo 'Clone Code'
            }
        }
        stage('Version') {
            steps {
                echo 'Version'
            }
        }
        stage('Test') {
            steps {
                echo 'Test'
            }
        }
        stage('Build') {
            steps {
                echo 'Build'
            }
        }
        stage('Publish') {
            steps {
                echo 'Publish'
            }
        }
        stage('Notify SyncNow') {
            steps {
                echo 'Notify'
                echo "Job Name is ${JOB_NAME}, Build ID is ${env.BUILD_ID}"
                script {
                    def commits = getCommentsString()

                    def payload = """
                    [
                        {
                            "fields": [
                                {
                                    "key": "Param1",
                                    "value": "string"
                                },
                                {
                                    "key": "Param2",
                                    "value": "string"
                                },
                                {
                                    "key": "Param3",
                                    "value": "string"
                                }
                            ],
                            "comments": "${commits}"
                        }
                    ]
                    """

                    // Create entities and update entities from commit. Result in format for adding attachments
                    def response = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_JSON', httpMode: 'POST', authentication: 'SyncNow', requestBody: "${payload}", url: "https://<SyncNowBaseURL>/api/v1.0/app/DevOpsGate/Enrich/<DevOpsProjectID>?action=update"

                    println("Status: ${response.status}")
                    println("Content: ${response.content}")
                }
            }
        }
    }
}

Step-by-Step Instructions

1. Create a DevOps Gate Process.
2. Add an entity type mapping and set any field mappings to it.

3. Create two entities in the target system that should be updated by the DevOps Gate.

4. Go to the DevOps Gate Process Configuration and press the "How It Works" link.

5. Select "Update Entities from Commits".
6. Copy the cURL command.

7. Paste it into a command line, set the entity keys of the entities created earlier, and execute.
8. Entities will be updated according to the mapping definition.