> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Examples

To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your data sources page. Find the integration in the list of data sources and click on it to open the playground.

Project​

Project blueprint (Click to expand)
{
  "identifier": "jiraProject",
  "title": "Jira Project",
  "icon": "Jira",
  "description": "A Jira project",
  "schema": {
    "properties": {
      "url": {
        "title": "Project URL",
        "type": "string",
        "format": "url",
        "description": "URL to the project in Jira"
      },
      "totalIssues": {
        "title": "Total Issues",
        "type": "number",
        "description": "The total number of issues in the project"
      }
    }
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Integration configuration (Click to expand)

The project kind has a selector property, expand that specifies additional fields to be included in the response. It accepts a comma-separated string that allows you to include more fields in the response data that can be used in the mapping configuration. Possible values are description, lead, issueTypes, url, projectKeys, insight.

If not specified, it defaults to "insight".

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: project
    selector:
      query: "true"
      expand: "description,lead,issueTypes,url,projectKeys,insight"
    port:
      entity:
        mappings:
          identifier: .key
          title: .name
          blueprint: '"jiraProject"'
          properties:
            url: (.self | split("/") | .[:3] | join("/")) + "/projects/" + .key
            totalIssues: .insight.totalIssueCount

User​

User blueprint (Click to expand)
{
 "identifier": "jiraUser",
 "title": "Jira User",
 "icon": "User",
 "description": "A Jira user account",
 "schema": {
   "properties": {
     "emailAddress": {
       "title": "Email",
       "type": "string",
       "format": "email", 
       "description": "User's email address"
     },
     "displayName": {
       "title": "Display Name",
       "type": "string",
       "description": "User's full name as displayed in Jira"
     },
     "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)"
     }
   }
 },
 "mirrorProperties": {},
 "calculationProperties": {},
 "aggregationProperties": {},
 "relations": {}
}
Integration configuration (Click to expand)
- kind: user
  selector:
    query: "true"
  port:
    entity:
      mappings:
        identifier: .accountId
        title: .displayName
        blueprint: '"jiraUser"'
        properties:
          emailAddress: .emailAddress
          displayName: .displayName
          active: .active
          accountType: .accountType

Team​

Team blueprint
{
"identifier": "jiraTeam",
"title": "Jira Team",
"icon": "Users",
"description": "A team within the organization",
"schema": {
    "properties": {
    "organizationId": {
        "title": "Organization ID",
        "type": "string",
        "description": "Unique identifier for the parent organization"
    },
    "teamType": {
        "title": "Team Type",
        "type": "string",
        "description": "Type of team (e.g., MEMBER_INVITE, OPEN)",
        "enum": [
        "MEMBER_INVITE",
        "OPEN"
        ]
    },
    "description": {
        "title": "Description",
        "type": "string",
        "description": "Team description"
    }
    }
},
"relations": {
    "members": {
    "target": "jiraUser",
    "title": "Users",
    "description": "The Jira users belonging to this team",
    "required": false,
    "many": true
    }
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {}
}
Integration configuration
- kind: team
  selector:
    query: "true"
    includeMembers: true
  port:
    entity:
      mappings:
        identifier: .teamId
        title: .displayName
        blueprint: '"jiraTeam"'
        properties:
          organizationId: .organizationId
          teamType: .teamType
          description: .description
        relations:
          members: if .__members != null then .__members | map(.accountId) else [] end

Issue​

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"
      },
      "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"
      },
      "labels": {
        "items": {
          "type": "string"
        },
        "title": "Labels",
        "type": "array"
      },
      "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"
      },
      "resolutionDate": {
        "title": "Resolved At",
        "type": "string",
        "description": "The datetime the issue changed to a resolved state",
        "format": "date-time"
      }
    }
  },
  "calculationProperties": {
    "handlingDuration": {
      "title": "Handling Duration (Days)",
      "icon": "Clock",
      "description": "The amount of time in days from issue creation to issue resolution",
      "calculation": "if (.properties.resolutionDate != null and .properties.created != null) then ((.properties.resolutionDate[0:19] + \"Z\" | fromdateiso8601) - (.properties.created[0:19] + \"Z\" | fromdateiso8601)) / 86400 else null end",
      "type": "number"
    }
  },
  "mirrorProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "target": "jiraProject",
      "title": "Project",
      "description": "The Jira project that contains this issue",
      "required": false,
      "many": false
    },
    "parentIssue": {
      "target": "jiraIssue",
      "title": "Parent Issue",
      "required": false,
      "many": false
    },
    "subtasks": {
      "target": "jiraIssue",
      "title": "Subtasks",
      "required": false,
      "many": true
    },
    "assignee": {
      "target": "jiraUser",
      "title": "Assignee",
      "required": false,
      "many": false
    },
    "reporter": {
      "target": "jiraUser",
      "title": "Reporter",
      "required": false,
      "many": false
    }
  }
}
Integration configuration (Click to expand)
- kind: issue
  selector:
    query: "true"
    jql: "(statusCategory != Done) OR (created >= -1w) OR (updated >= -1w)"
  port:
    entity:
      mappings:
        identifier: .key
        title: .fields.summary
        blueprint: '"jiraIssue"'
        properties:
          url: (.self | split("/") | .[:3] | join("/")) + "/browse/" + .key
          status: .fields.status.name
          issueType: .fields.issuetype.name
          components: .fields.components
          creator: .fields.creator.emailAddress
          priority: .fields.priority.name
          labels: .fields.labels
          created: .fields.created
          updated: .fields.updated
          resolutionDate: .fields.resolutiondate
        relations:
          project: .fields.project.key
          parentIssue: .fields.parent.key
          subtasks: .fields.subtasks | map(.key)
          assignee: .fields.assignee.accountId
          reporter: .fields.reporter.accountId

Release​

Release blueprint (Click to expand)
{
  "identifier": "jiraRelease",
  "title": "Jira Release",
  "icon": "Jira",
  "description": "A Jira project version (release)",
  "schema": {
    "properties": {
      "description": {
        "title": "Description",
        "type": "string",
        "description": "A description of the version"
      },
      "released": {
        "title": "Released",
        "type": "boolean",
        "description": "Indicates whether the version has been released"
      },
      "archived": {
        "title": "Archived",
        "type": "boolean",
        "description": "Indicates whether the version has been archived"
      },
      "releaseDate": {
        "title": "Release Date",
        "type": "string",
        "format": "date",
        "description": "The release date of the version"
      },
      "overdue": {
        "title": "Overdue",
        "type": "boolean",
        "description": "Indicates whether the version is overdue"
      }
    }
  },
  "relations": {
    "project": {
      "target": "jiraProject",
      "title": "Project",
      "description": "The Jira project this version belongs to",
      "required": false,
      "many": false
    }
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {}
}
Integration configuration (Click to expand)
- kind: release
  selector:
    query: "true"
  port:
    entity:
      mappings:
        identifier: .id | tostring
        title: .name
        blueprint: '"jiraRelease"'
        properties:
          description: .description
          released: .released
          archived: .archived
          releaseDate: .releaseDate
          overdue: .overdue
        relations:
          project: .__projectKey

Worklog​

The worklog kind ingests time tracking entries logged against Jira issues. Each worklog is enriched with the key of its parent issue via __issueKey, enabling a direct relation to jiraIssue in Port. Live events (worklog_created, worklog_updated, worklog_deleted) are supported.

Worklog blueprint (Click to expand)
{
  "identifier": "jiraWorklog",
  "title": "Jira Worklog",
  "icon": "Jira",
  "schema": {
    "properties": {
      "timeSpent": {
        "title": "Time Spent",
        "type": "string"
      },
      "timeSpentSeconds": {
        "title": "Time Spent (Seconds)",
        "type": "number"
      },
      "started": {
        "title": "Started",
        "type": "string",
        "format": "date-time"
      },
      "created": {
        "title": "Created",
        "type": "string",
        "format": "date-time"
      },
      "updated": {
        "title": "Updated",
        "type": "string",
        "format": "date-time"
      },
      "authorAccountId": {
        "title": "Author",
        "type": "string"
      },
      "authorDisplayName": {
        "title": "Author Name",
        "type": "string"
      },
      "authorEmail": {
        "title": "Author Email",
        "type": "string",
        "format": "email"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "issue": {
      "target": "jiraIssue",
      "title": "Issue",
      "required": false,
      "many": false
    }
  }
}
Integration configuration (Click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: worklog
    selector:
      query: 'true'
      jql: updated >= -1w
    port:
      entity:
        mappings:
          identifier: .id
          title: .author.displayName + " - " + .started
          blueprint: '"jiraWorklog"'
          properties:
            timeSpent: .timeSpent
            timeSpentSeconds: .timeSpentSeconds
            started: .started
            created: .created
            updated: .updated
            authorAccountId: .author.accountId
            authorDisplayName: .author.displayName
            authorEmail: .author.emailAddress
          relations:
            issue: .__issueKey

Component​

The component kind ingests project components from Jira. Each component is enriched with its parent project key via __project.key for the project relation, and exposes issueCount, assigneeType, and lead directly from the Jira API. The ari property is populated for Compass-linked components and is null for standard Jira components.

Component blueprint (Click to expand)
{
  "identifier": "jiraComponent",
  "title": "Jira Component",
  "icon": "Jira",
  "schema": {
    "properties": {
      "description": {
        "title": "Description",
        "type": "string"
      },
      "assigneeType": {
        "title": "Assignee Type",
        "type": "string",
        "description": "How new issues assigned to this component are routed.",
        "enum": [
          "PROJECT_DEFAULT",
          "COMPONENT_LEAD",
          "PROJECT_LEAD",
          "UNASSIGNED"
        ],
        "enumColors": {
          "PROJECT_DEFAULT": "blue",
          "COMPONENT_LEAD": "green",
          "PROJECT_LEAD": "purple",
          "UNASSIGNED": "lightGray"
        }
      },
      "issueCount": {
        "title": "Issue Count",
        "type": "number"
      },
      "ari": {
        "title": "ARI",
        "type": "string",
        "description": "Atlassian Resource Identifier. Present only for Compass-linked components."
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "title": "Project",
      "target": "jiraProject",
      "required": false,
      "many": false
    },
    "lead": {
      "title": "Lead",
      "target": "jiraUser",
      "required": false,
      "many": false
    }
  }
}
Integration configuration (Click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: component
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .name
          blueprint: '"jiraComponent"'
          properties:
            description: .description
            assigneeType: .assigneeType
            issueCount: .issueCount
            ari: .componentBean.ari // null
          relations:
            project: .__project.key
            lead: .lead.accountId // null

Component mapping configuration options​

Controls which components are returned. Defaults to jira to return only standard project components. Set to compass to return only Compass global components linked to the project, or auto to return both.

- kind: component
  selector:
    query: 'true'
    componentSource: compass

Worklog mapping configuration options​

The worklog kind exposes five optional selector fields.

Scopes which issues are scanned for worklogs. Defaults to issues updated in the last week to avoid re-fetching the full worklog history on every resync. Set to an empty string to fetch worklogs for all issues.

- kind: worklog
  selector:
    query: 'true'
    jql: "project = PORT AND updated >= -1w"
Performance

On large Jira instances, combine a tight jql filter with startedAfter to minimise the number of issues scanned and worklogs fetched per resync.

Backlog​

Backlog blueprint (click to expand)
{
  "identifier": "jiraIssue",
  "title": "Jira Issue",
  "icon": "Jira",
  "schema": {
    "properties": {
      "url": {
        "title": "Issue URL",
        "type": "string",
        "format": "url"
      },
      "status": {
        "title": "Status",
        "type": "string"
      },
      "issueType": {
        "title": "Type",
        "type": "string"
      },
      "priority": {
        "title": "Priority",
        "type": "string"
      },
      "labels": {
        "title": "Labels",
        "type": "array",
        "items": { "type": "string" }
      },
      "components": {
        "title": "Components",
        "type": "array",
        "items": { "type": "string" }
      },
      "creator": {
        "title": "Creator",
        "type": "string"
      },
      "created": {
        "title": "Created At",
        "type": "string",
        "format": "date-time"
      },
      "updated": {
        "title": "Updated At",
        "type": "string",
        "format": "date-time"
      },
      "resolutionDate": {
        "title": "Resolution Date",
        "type": "string",
        "format": "date-time"
      },
      "storyPoints": {
        "title": "Story Points",
        "type": "number",
        "description": "The story point estimate for this issue"
      },
      "team": {
        "title": "Team",
        "type": "string",
        "description": "The team this issue is assigned to"
      },
      "sprint": {
        "title": "Sprint",
        "type": "string",
        "description": "The most recent sprint this issue belongs to"
      },
      "sprintHistory": {
        "title": "Sprint History",
        "type": "array",
        "items": {
            "type": "string"
        },
        "description": "All sprints this issue has been part of, oldest to newest. An issue appearing in multiple sprints indicates carry-over."
      },
      "dueDate": {
        "title": "Due Date",
        "type": "string",
        "description": "The due date of the issue"
      }
    }
  },
  "relations": {
    "project": {
      "target": "jiraProject",
      "title": "Project",
      "required": false,
      "many": false
    },
    "parentIssue": {
      "target": "jiraIssue",
      "title": "Parent Issue",
      "required": false,
      "many": false
    },
    "board": {
      "target": "jiraBoard",
      "title": "Board",
      "required": false,
      "many": false
    }
  }
}
Integration configuration (click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: backlog
    selector:
      query: 'true'
      jql: statusCategory != Done
    port:
      entity:
        mappings:
          identifier: .key
          title: .fields.summary
          blueprint: '"jiraIssue"'
          properties:
            url: (.self | split("/") | .[:3] | join("/")) + "/browse/" + .key
            status: .fields.status.name
            issueType: .fields.issuetype.name
            priority: .fields.priority.name
            labels: .fields.labels
            components: '[.fields.components[]?.name]'
            created: .fields.created
            updated: .fields.updated
            resolutionDate: .fields.resolutiondate
            creator: .fields.creator.accountId
            dueDate: .fields.duedate
            storyPoints: .fields.customfield_10026 // null
            team: .fields.customfield_10001.name // null
            sprint: .fields.customfield_10020 | if . != null and length > 0 then .[-1].name else null end
            sprintHistory: '[.fields.customfield_10020[]?.name] | if length > 0 then . else null end'
          relations:
            project: .fields.project.key
            parentIssue: (.fields.parent // null) | if . != null then .key else null end
            board: '.__boardId | tostring'
            jira_user_assignee: .fields.assignee.accountId // null
            jira_user_reporter: .fields.reporter.accountId // null

Backlog mapping configuration options​

The backlog kind exposes four optional selector fields.

Filters which issues are returned from each board's backlog. Defaults to recently updated or incomplete issues to avoid re-ingesting the full backlog history on every resync. Set to an empty string to fetch all backlog issues.

- kind: backlog
  selector:
    query: "true"
    jql: "statusCategory != Done"  # Only fetch incomplete issues
agile/1.0 deprecation

Atlassian deprecated all rest/agile/1.0 issue listing endpoints on May 1, 2026, with removal scheduled for November 1, 2026. This includes the board backlog, sprint, epic, and board issue endpoints. Keep useSoftwareApi set to true (the default) so the integration uses the replacement rest/software/1.0 endpoints. See Atlassian's deprecation notice for the full list of affected endpoints and their replacements.

Board​

Board blueprint (Click to expand)
{
  "identifier": "jiraBoard",
  "title": "Jira Board",
  "icon": "Jira",
  "schema": {
    "properties": {
      "type": {
        "title": "Board Type",
        "type": "string",
        "description": "The type of the board — scrum, kanban, or simple",
        "enum": ["scrum", "kanban", "simple"]
      },
      "isPrivate": {
        "title": "Private",
        "type": "boolean",
        "description": "Whether the board is private"
      },
      "projectKey": {
        "title": "Project Key",
        "type": "string",
        "description": "The key of the primary project this board belongs to"
      },
      "projectTypeKey": {
        "title": "Project Type",
        "type": "string",
        "description": "The type of the project (e.g. software, business)"
      },
      "adminUsers": {
        "title": "Admin Users",
        "type": "array",
        "items": { "type": "string" },
        "description": "Account IDs of users with admin access to this board"
      },
      "adminGroups": {
        "title": "Admin Groups",
        "type": "array",
        "items": { "type": "string" },
        "description": "Names of groups with admin access to this board"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "project": {
      "title": "Projects",
      "description": "The Jira projects associated with this board",
      "target": "jiraProject",
      "required": false,
      "many": true
    }
  }
}
Integration configuration (Click to expand)
- kind: project
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .key
          title: .name
          blueprint: '"jiraProject"'
          properties:
            url: (.self | split("/") | .[:3] | join("/")) + "/projects/" + .key
            totalIssues: .insight.totalIssueCount
- kind: board
selector:
  query: "true"
port:
  entity:
    mappings:
      identifier: .id | tostring
      title: .name
      blueprint: '"jiraBoard"'
      properties:
        type: .type
        isPrivate: .isPrivate
        projectKey: .location.projectKey // null
        projectTypeKey: .location.projectTypeKey // null
        adminUsers: '[.admins.users[]? | select(.accountId != null) | .accountId] | if length > 0 then . else null end'
        adminGroups: '[.admins.groups[]? | select(.name != null) | .name] | if length > 0 then . else null end'
      relations:
        project: '.__projectKeys // null'

Boards mapping configuration options​

The board kind exposes two optional selector fields that control which boards are fetched from Jira.

Filters boards by type. Accepted values are scrum, kanban, and simple. When omitted, all board types are fetched.

- kind: board
  selector:
    query: "true"
    boardType: scrum  # Only fetch scrum boards
Performance

On large Jira instances with hundreds of boards, using boardType and projectKey together significantly reduces the number of boards fetched and the number of subsequent API calls made to enrich each board with its associated projects. If you only care about a specific project's boards, always set projectKey.

Sprint​

Sprint blueprint (Click to expand)
{
  "identifier": "jiraSprint",
  "title": "Jira Sprint",
  "icon": "Jira",
  "schema": {
    "properties": {
      "state": {
        "title": "State",
        "type": "string",
        "description": "The current state of the sprint",
        "enum": ["active", "closed", "future"]
      },
      "startDate": {
        "title": "Start Date",
        "type": "string",
        "format": "date-time",
        "description": "The date the sprint started"
      },
      "endDate": {
        "title": "End Date",
        "type": "string",
        "format": "date-time",
        "description": "The date the sprint is scheduled to end"
      },
      "completeDate": {
        "title": "Complete Date",
        "type": "string",
        "format": "date-time",
        "description": "The date the sprint was completed. Null if not yet closed."
      },
      "goal": {
        "title": "Goal",
        "type": "string",
        "description": "The sprint goal"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "board": {
      "title": "Origin Board",
      "description": "The board this sprint was created on",
      "target": "jiraBoard",
      "required": false,
      "many": false
    }
  }
}
Integration configuration (Click to expand)
  - kind: board
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .name
          blueprint: '"jiraBoard"'
          properties:
            type: .type
            isPrivate: .isPrivate
            projectKey: .location.projectKey // null
            projectTypeKey: .location.projectTypeKey // null
          relations:
            project: '.__projectKeys // null'

  - kind: sprint
    selector:
      query: "true"
      sprintState:
        - active
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .name
          blueprint: '"jiraSprint"'
          properties:
            state: .state
            startDate: .startDate // null
            endDate: .endDate // null
            completeDate: .completeDate // null
            goal: .goal // null
          relations:
            board: .originBoardId | tostring

Filtering sprints with selectors​

The sprint kind exposes an optional sprintState selector that controls which sprints are fetched per board. Accepted values are active, closed, and future, and multiple states can be provided as a list. When set to a single state, only sprints in that state are fetched from each board.

- kind: sprint
  selector:
    query: "true"
    sprintState:
      - active        # Only fetch active sprints (default)
- kind: sprint
  selector:
    query: "true"
    sprintState:
      - active
      - future        # Fetch active and future sprints
- kind: sprint
  selector:
    query: "true"
    sprintState:
      - active
      - closed
      - future        # Fetch all sprint states
Fetching all sprint states

You can also omit sprintState entirely or set it to null to fetch all sprints regardless of state:

- kind: sprint
  selector:
    query: "true"
    sprintState: null  # Fetch all sprints — active, closed, and future
Performance

sprintState defaults to ["active"] to protect large Jira instances from excessive API calls during resync. On mature Jira instances, closed sprints accumulate over years and can number in the hundreds per board. Fetching all states across hundreds of boards multiplies resync time significantly. Opt in to closed or future sprints explicitly when you need them.

Epic​

Epic blueprint (click to expand)
{
  "identifier": "jiraEpic",
  "title": "Jira Epic",
  "icon": "Jira",
  "schema": {
    "properties": {
      "name": {
        "title": "Name",
        "type": "string",
        "description": "The epic name. Falls back to the Jira issue key (e.g. PORT-6459) when the name is not set."
      },
      "summary": {
        "title": "Summary",
        "type": "string",
        "description": "The epic summary"
      },
      "done": {
        "title": "Done",
        "type": "boolean",
        "description": "Whether the epic is completed"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "board": {
      "title": "Board",
      "description": "The Jira board this epic appears on",
      "target": "jiraBoard",
      "required": false,
      "many": true
    }
  }
}
Integration configuration (click to expand)
  - kind: board
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .name
          blueprint: '"jiraBoard"'
          properties:
            type: .type
            isPrivate: .isPrivate
            projectKey: .location.projectKey // null
            projectTypeKey: .location.projectTypeKey // null
          relations:
            project: '.__projectKeys // null'

  - kind: epic
    selector:
      query: "true"
      done: "false"
    port:
      entity:
        mappings:
          identifier: .id | tostring
          title: .name // .key
          blueprint: '"jiraEpic"'
          properties:
            name: .name // .key
            summary: .summary
            done: .done
          relations:
            board: .__boardId | tostring
Title fallback

If an epic's name field is empty, the integration uses the issue key (for example, PORT-6459) as the value for both title and name.

Filtering epics by status​

The epic kind exposes an optional status selector that controls which epics are fetched per board. Accepts "incomplete", "complete", or both.

Fetch only incomplete epics (default):

- kind: epic
  selector:
    query: "true"
    status: ["incomplete"]

Fetch only completed epics:

- kind: epic
  selector:
    query: "true"
    status: ["complete"]

Fetch all epics regardless of status:

- kind: epic
  selector:
    query: "true"
    status: ["incomplete", "complete"]
Performance

status defaults to ["incomplete"] to protect large Jira instances from fetching their full epic history on first install. Completed epics accumulate over years and can number in the hundreds per board. Opt in to completed epics explicitly when you need them.

Slack notifications​

Using Port's automation capabilities, you can set up real-time Slack notifications when issues are created or updated in Jira.

Automation for new bug reports (click to expand)
{
  "identifier": "jira_new_bug_notification",
  "title": "Notify Slack on New Jira Bug",
  "icon": "Slack",
  "description": "Sends a Slack notification when a new bug is created in Jira",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "ENTITY_CREATED",
      "blueprintIdentifier": "jiraIssue"
    },
    "condition": {
      "type": "JQ",
      "expressions": [
        ".diff.after.properties.issueType == \"Bug\""
      ],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "YOUR_SLACK_WEBHOOK_URL",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "text": "🐛 New Bug Reported\n\n*Issue:* {{ .event.diff.after.title }}\n*Project:* {{ .event.diff.after.relations.project }}\n*Status:* {{ .event.diff.after.properties.status }}\n*Priority:* {{ .event.diff.after.properties.priority }}\n\n<{{ .event.diff.after.properties.url }}|View in Jira> | <https://app.port.io/jiraIssueEntity?identifier={{ .event.context.entityIdentifier }}|View in Port>"
    }
  },
  "publish": true
}
Automation for high-priority tasks (click to expand)
{
  "identifier": "jira_high_priority_task",
  "title": "Notify Slack on High-Priority Jira Task",
  "icon": "Slack",
  "description": "Sends a Slack notification when a high-priority task is created or updated in Jira",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "ENTITY_UPDATED",
      "blueprintIdentifier": "jiraIssue"
    },
    "condition": {
      "type": "JQ",
      "expressions": [
        ".diff.after.properties.priority == \"Highest\" or .diff.after.properties.priority == \"High\"",
        ".diff.before.properties.priority != \"Highest\" and .diff.before.properties.priority != \"High\""
      ],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "YOUR_SLACK_WEBHOOK_URL",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "text": "⚠️ High-Priority Issue Alert\n\n*Issue:* {{ .event.diff.after.title }}\n*Type:* {{ .event.diff.after.properties.issueType }}\n*Priority:* {{ .event.diff.after.properties.priority }}\n*Status:* {{ .event.diff.after.properties.status }}\n\n<{{ .event.diff.after.properties.url }}|View in Jira> | <https://app.port.io/jiraIssueEntity?identifier={{ .event.context.entityIdentifier }}|View in Port>"
    }
  },
  "publish": true
}
Slack webhook URL

Replace YOUR_SLACK_WEBHOOK_URL with your actual Slack incoming webhook URL. For information on creating Slack webhooks, see the Slack API documentation.

These automations allow your team to receive immediate notifications in Slack when bugs are reported or issues are updated with high priority, making your project management workflow more efficient.