Jira

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

Prerequisites

Create the following blueprint definition and webhook configuration:

Jira issue blueprint

{
  "identifier": "jiraIssue",
  "description": "This blueprint represents issues from Jira",
  "title": "Jira Issue",
  "icon": "Jira",
  "schema": {
    "properties": {
      "summary": {
        "type": "string",
        "title": "Summary"
      },
      "description": {
        "type": "string",
        "title": "Description"
      },
      "lastChangeType": {
        "type": "string",
        "title": "Last change type",
        "description": "The type of the latest change made to this issue"
      },
      "changingUser": {
        "type": "string",
        "title": "Changing user",
        "description": "The user that madet the latest change"
      },
      "issueUrl": {
        "type": "string",
        "title": "Issue URL",
        "format": "url",
        "description": "URL to the issue"
      },
      "issueType": {
        "type": "string",
        "title": "Type",
        "description": "The type of the issue"
      },
      "status": {
        "type": "string",
        "title": "Status",
        "description": "The status of the issue"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}

Jira issue webhook configuration

{
  "identifier": "jiraMapper",
  "title": "Jira mapper",
  "description": "A webhook configuration to map Jira issues to Port",
  "icon": "Jira",
  "mappings": [
    {
      "blueprint": "jiraIssue",
      "entity": {
        "identifier": ".body.issue.key",
        "title": ".body.issue.key + \" - \" + .body.issue.fields.summary",
        "properties": {
          "summary": ".body.issue.fields.summary",
          "description": ".body.issue.fields.description",
          "status": ".body.issue.fields.status.name",
          "lastChangeType": ".body.issue_event_type_name",
          "changingUser": ".body.user.displayName",
          "issueUrl": "(.body.issue.self | split(\"rest\") | first) + \"browse/\" + .body.issue.key",
          "issueType": ".body.issue.fields.issuetype.name"
        }
      }
    }
  ],
  "enabled": true,
  "security": {}
}

Create the Jira webhook

1. Log in to Jira as a user with the Administer Jira global permission;
2. Click the gear icon at the top right corner;
3. Choose System;
4. At the bottom of the sidebar on the left, under Avanced, choose WebHooks;
5. Click on Create a WebHook
6. Input the following details:
   1. Name - use a meaningful name such as Port Webhook;
   2. Status - be sure to keep the webhook Enabled;
   3. Webhook URL - enter the value of the url key you received after creating the webhook configuration;
   4. Description - enter a description for the webhook;
   5. Issue related events - enter a JQL query in this section to filter the issues that get sent to the webhook (if you leave this field empty, all issues will trigger a webhook event);
   6. Under Issue - mark created, updated and delete;
7. Click Create at the bottom of the page.

tip

In order to view the different payloads and events available in Jira webhooks, look here

Done! any change you make to an issue (open, close, edit, etc.) will trigger a webhook event that Jira will send to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.