Jenkins

In this example you are going to create a webhook integration between Jenkins and Port, which will ingest job and build entities.

Port configuration

Create the following blueprint definition:

Jenkins job blueprint

{
  "identifier": "jenkinsJob",
  "description": "This blueprint represents a job event from Jenkins",
  "title": "Jenkins Job",
  "icon": "Jenkins",
  "schema": {
    "properties": {
      "jobName": {
        "type": "string",
        "title": "Project Name"
      },
      "jobStatus": {
        "type": "string",
        "title": "Job Status",
        "enum": ["created", "updated", "deleted"],
        "enumColors": {
          "created": "green",
          "updated": "yellow",
          "deleted": "red"
        }
      },
      "timestamp": {
        "type": "string",
        "format": "date-time",
        "title": "Timestamp",
        "description": "Last updated timestamp of the job"
      },
      "url": {
        "type": "string",
        "title": "Project URL"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {
    "jobUrl": {
      "title": "Job Full URL",
      "calculation": "'https://your_jenkins_url/' + .properties.url",
      "type": "string",
      "format": "url"
    }
  },
  "relations": {}
}

Jenkins build blueprint (including the Jenkins job relation)

{
  "identifier": "jenkinsBuild",
  "description": "This blueprint represents a build event from Jenkins",
  "title": "Jenkins Build",
  "icon": "Jenkins",
  "schema": {
    "properties": {
      "buildStatus": {
        "type": "string",
        "title": "Build Status",
        "enum": ["SUCCESS", "FAILURE", "UNSTABLE"],
        "enumColors": {
          "SUCCESS": "green",
          "FAILURE": "red",
          "UNSTABLE": "yellow"
        }
      },
      "buildUrl": {
        "type": "string",
        "title": "Build URL",
        "description": "URL to the build"
      },
      "timestamp": {
        "type": "string",
        "format": "date-time",
        "title": "Timestamp",
        "description": "Last updated timestamp of the build"
      },
      "buildDuration": {
        "type": "number",
        "title": "Build Duration",
        "description": "Duration of the build"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "jenkinsJob": {
      "title": "Jenkins Job",
      "target": "jenkinsJob",
      "required": false,
      "many": false
    }
  }
}

Create the following webhook configuration using Port's UI

Jenkins job and build webhook configuration

1. Basic details tab - fill the following details:

   1. Title : Jenkins Mapper;
   2. Identifier : jenkins_mapper;
   3. Description : A webhook configuration to map Jenkins builds and jobs to Port;
   4. Icon : Jenkins;

2. Integration configuration tab - fill the following JQ mapping:

   [
     {
       "blueprint": "jenkinsJob",
       "filter": ".body.type | startswith(\"item\")",
       "entity": {
         "identifier": ".body.url | sub(\"%20\"; \"-\"; \"g\") | sub(\"/\"; \"-\"; \"g\") | .[:-1]",
         "title": ".body.data.displayName",
         "properties": {
           "jobName": ".body.data.fullName",
           "url": ".body.url",
           "jobStatus": ".body.type | split(\".\") | last",
           "timestamp": ".body.time"
         }
       }
     },
     {
       "blueprint": "jenkinsBuild",
       "filter": ".body.type | startswith(\"run\")",
       "entity": {
         "identifier": ".body.data.fullDisplayName | sub(\" \"; \"-\"; \"g\") | sub(\"#\"; \"\"; \"g\")",
         "title": ".body.data.displayName",
         "properties": {
           "buildStatus": ".body.data.result",
           "buildUrl": ".body.url",
           "buildDuration": ".body.data.duration",
           "timestamp": ".body.data.timestamp / 1000 | todate"
         },
         "relations": {
           "jenkinsJob": ".body.source | tostring | sub(\"%20\"; \"-\"; \"g\") | sub(\"/\"; \"-\"; \"g\") | .[:-1]"
         }
       }
     }
   ]

3. Click Save at the bottom of the page.

Create a webhook in Jenkins

1. Go to your Jenkins dashboard;
2. At the sidebar on the left side of the page select Manage Jenkins and click on Manage Plugins;
3. Navigate to the Available Plugins tab and search for Generic Event in the search bar. Install the Generic Event or a suitable plugin that can notify some endpoints about all events that happen in Jenkins;
4. Go back to your Jenkins dashboard and click on Manage Jenkins at the left side menu;
5. Click on the Configure System tab and scroll down to the Event Dispatcher section;
6. Enter the value of the url key you received after creating the webhook configuration in the textbox;
7. Click on Save at the buttom of the page;

tip

In order to view the different payloads and events available in Jenkins webhooks, click here

Done! any changes to a job or build process (queued, started, completed, finalized etc.) will trigger a webhook event to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.