Skip to main content

Check out Port for yourself 

Change status and assignee of Jira ticket

Overview​

This guide will help you implement a self-service action in Port that allows you to change the status and assignee of Jira tickets directly from Port. This functionality streamlines ticket management by enabling users to update tickets without leaving Port.

You can implement this action in two ways:

  1. GitHub workflow: A more flexible approach that allows for complex workflows and custom logic, suitable for teams that want to maintain their automation in Git.
  2. Synced webhooks: A simpler approach that directly interacts with Jira's API through Port, ideal for quick implementation and minimal setup.

Prerequisites​

  • Complete the onboarding process.
  • Access to your Jira organization with permissions to manage tickets.

Set up data model​

If you haven't installed the Jira integration, you'll need to create a blueprint for Jira issues and Jira user.
However we highly recommend you install the Jira integration to have these automatically set up for you.

Create the jira issue blueprint​

  1. Go to your Builder page.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose "Edit JSON".

  4. Add this JSON schema:

    Jira Issue Blueprint (Click to expand)
    {
      "identifier": "jiraIssue",
      "title": "Jira Issue",
      "icon": "Jira",
      "schema": {
        "properties": {
          "url": {
            "title": "Issue URL",
            "type": "string",
            "format": "url",
            "description": "URL to the issue in Jira"
          },
          "status": {
            "title": "Status",
            "type": "string",
            "description": "The status of the issue"
          },
          "issueType": {
            "title": "Type",
            "type": "string",
            "description": "The type of the issue"
          },
          "components": {
            "title": "Components",
            "type": "array",
            "description": "The components related to this issue"
          },
          "assignee": {
            "title": "Assignee",
            "type": "string",
            "format": "user",
            "description": "The user assigned to the issue"
          },
          "reporter": {
            "title": "Reporter",
            "type": "string",
            "description": "The user that reported to the issue",
            "format": "user"
          },
          "creator": {
            "title": "Creator",
            "type": "string",
            "description": "The user that created to the issue",
            "format": "user"
          },
          "priority": {
            "title": "Priority",
            "type": "string",
            "description": "The priority of the issue"
          },
          "created": {
            "title": "Created At",
            "type": "string",
            "description": "The created datetime of the issue",
            "format": "date-time"
          },
          "updated": {
            "title": "Updated At",
            "type": "string",
            "description": "The updated datetime of the issue",
            "format": "date-time"
          }
        }
      },
      "calculationProperties": {},
      "relations": {}
    }

  5. Click "Save" to create the blueprint.

Create the jira user blueprint​

  1. Go to your Builder page.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose "Edit JSON".

  4. Add this JSON schema:

    Jira User Blueprint (Click to expand)
    {
      "identifier": "jiraUser",
      "description": "A Jira user account",
      "title": "Jira User",
      "icon": "User",
      "schema": {
        "properties": {
          "emailAddress": {
            "title": "Email",
            "type": "string",
            "format": "email",
            "description": "User's email address"
          },
          "active": {
            "title": "Active Status",
            "type": "boolean",
            "description": "Whether the user account is active"
          },
          "accountType": {
            "title": "Account Type",
            "type": "string",
            "description": "Type of Jira account (e.g., atlassian, customer)"
          },
          "timeZone": {
            "title": "Time Zone",
            "type": "string",
            "description": "User's configured time zone"
          },
          "locale": {
            "title": "Locale",
            "type": "string",
            "description": "User's configured locale"
          },
          "avatarUrl": {
            "title": "Avatar URL",
            "type": "string",
            "format": "url",
            "description": "URL for user's 48x48 avatar image"
          }
        },
        "required": []
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "aggregationProperties": {},
      "relations": {}
    }

  5. Click "Save" to create the blueprint.

Implementation​

You can update a Jira issue by leveraging Port's synced webhooks and secrets to directly interact with the Jira's API. This method simplifies the setup by handling everything within Port.

Add Port secrets

Existing secrets

If you have already installed Port's Jira integration, these secrets should already exist in your portal.
To view your existing secrets:

  1. Click on the ... button in the top right corner of your Port application.
  2. Choose Credentials, then click on the Secrets tab.

To add these secrets to your portal:

  1. Click on the ... button in the top right corner of your Port application.

  2. Click on Credentials.

  3. Click on the Secrets tab.

  4. Click on + Secret and add the following secrets:

    • JIRA_API_TOKEN - Your Jira API token

    • JIRA_USER_EMAIL - The email of the Jira user that owns the API token

    • JIRA_AUTH - Base64 encoded string of your Jira credentials. Generate this by running:

      echo -n "your-email@domain.com:your-api-token" | base64

      Replace your-email@domain.com with your Jira email and your-api-token with your Jira API token.

      One time generation

      The base64 encoded string only needs to be generated once and will work for all webhook calls until you change your API token.

Set up self-service actions

Due to limitations of the Jira API, we will need to create two separate self-service actions:

  1. One action to change the status of a Jira issue
  2. Another action to change the assignee of a Jira issue

Follow these steps to create the self-service actions:

  1. Head to the self-service page.

  2. Click on the + New Action button.

  3. Click on the {...} Edit JSON button.

  4. Copy and paste the appropriate JSON configuration into the editor.

    Change Jira Ticket Status Action (Click to expand)
    {
      "identifier": "jiraIssue_change_status_webhook",
      "title": "Change Jira Ticket Status",
      "icon": "Jira",
      "description": "Update a Jira ticket's status using a synced webhook",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {
            "status": {
              "icon": "DefaultProperty",
              "title": "Status",
              "type": "string",
              "description": "Select the status to transition the issue to",
              "enum": [
                "To Do",
                "In Progress",
                "Done",
                "Code Review",
                "Product Review",
                "Waiting For Prod"
              ],
              "enumColors": {
                "To Do": "lightGray",
                "In Progress": "bronze",
                "Done": "green",
                "Code Review": "darkGray",
                "Product Review": "purple",
                "Waiting For Prod": "orange"
              }
            }
          },
          "required": [
            "status"
          ],
          "order": [
            "status"
          ]
        },
        "blueprintIdentifier": "jiraIssue"
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://<JIRA_ORGANIZATION_URL>/rest/api/3/issue/{{.entity.identifier}}/transitions",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "Authorization": "Basic {{.secrets.JIRA_AUTH}}",
          "Content-Type": "application/json"
        },
        "body": {
          "transition": {
            "{{ if .inputs.status == 'To Do' then 'id' else 'none' end }}": 11,
            "{{ if .inputs.status == 'In Progress' then 'id' else 'none' end }}": 21,
            "{{ if .inputs.status == 'Done' then 'id' else 'none' end }}": 31,
            "{{ if .inputs.status == 'Code Review' then 'id' else 'none' end }}": 41,
            "{{ if .inputs.status == 'Product Review' then 'id' else 'none' end }}": 51,
            "{{ if .inputs.status == 'Waiting For Prod' then 'id' else 'none' end }}": 61
          }
        }
      },
      "requiredApproval": false
    }
    Change Jira Ticket Assignee Action (Click to expand)
    {
      "identifier": "jiraIssue_change_assignee_webhook",
      "title": "Change Jira Ticket Assignee",
      "icon": "Jira",
      "description": "Update a Jira ticket's assignee using a synced webhook",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {
            "jira_user": {
              "type": "string",
              "title": "Jira user",
              "description": "Select the Jira user to assign the ticket to",
              "blueprint": "jiraUser",
              "format": "entity"
            }
          },
          "required": [
            "jira_user"
          ],
          "order": [
            "jira_user"
          ]
        },
        "blueprintIdentifier": "jiraIssue"
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://<JIRA_ORGANIZATION_URL>/rest/api/3/issue/{{.entity.identifier}}/assignee",
        "agent": false,
        "synchronized": true,
        "method": "PUT",
        "headers": {
          "Authorization": "Basic {{.secrets.JIRA_AUTH}}",
          "Content-Type": "application/json"
        },
        "body": {
          "accountId": "{{.inputs.jira_user.identifier}}"
        }
      },
      "requiredApproval": false
    }

  5. Click Save for each action.

Now you should see both the Change Jira ticket status and Change Jira ticket assignee actions in the self-service page. 🎉

Configure your Jira url and status values

Replace <JIRA_ORGANIZATION_URL> in the webhook URL with your Jira organization URL (e.g., example.atlassian.net).

Ensure the status names are mapped to Jira transition IDs as done in the action definitions above:

  • "To Do" → 11
  • "In Progress" → 21
  • "Done" → 31
  • "Code Review" → 41
  • "Product Review" → 51
  • "Waiting For Prod" → 61

Make sure to update these mappings to match your Jira workflow's transition IDs. You can find your workflow's transition IDs by calling:

curl -X GET "https://example.atlassian.net/rest/api/3/issue/{issueKey}/transitions" \
  -H "Authorization: Basic $JIRA_AUTH" \
  -H "Content-Type: application/json"

The response will contain an array of transitions, each with an id and a name that you can use in your configuration.

Let's test it!​

  1. Head to the self-service page of your portal

  2. Choose either the GitHub workflow or webhook implementation:

    • For GitHub workflow: Click on Change Jira ticket status and assignee
    • For webhook: Click on either Change Jira ticket status or Change Jira ticket assignee

  3. Select the Jira ticket you want to update (In case you didn't install the Jira integration, it means you don't have any Jira tickets or users in Port yet, so you will need to create one manually in Port to test this action)

  4. For status changes: Select the new status from the dropdown For assignee changes: Select a Jira user to assign the ticket to

  5. Click on Execute

  6. Done! wait for the ticket to be updated in Jira

More Self Service Jira Actions Examples​