Skip to content
Blackbird docs

Jira

View on Github

Jira is a widely used project management and issue tracking tool developed by Atlassian. It provides teams with a platform to plan, track, and manage tasks, projects, and software development processes, helping to streamline collaboration and improve project visibility. This Jira app primarily focuses on issues management.

Before setting up

Before you can connect you need to make sure that:

Enable webhooks

If you want to use Jira webhooks, you need to:

  • Log in as a user with Administer Jira global permission.
  • In top right corner choose Settings > System. Under Advanced, select WebHooks.
  • In top right corner choose Create a WebHook.
  • In URL field specify https://bridge.blackbird.io/api/webhooks/jira.
  • Make sure that Status is Enabled.
  • Select everything under Issue related events > Issue.
  • Scroll to the bottom of the page and click Create.

Selecting events

Adding custom fields

To create custom fields, follow this guide. Once the custom fields you need are created, you need to:

  • Choose Settings > Projects in top right corner.
  • For the project you are interested in, select More > Project settings.
  • Select Issue types from the left panel.
  • Click on issue type to which you want to add created custom fields.
  • Locate Search all fields search bar in the right panel.
  • Search for the field you are interested in and drag it to issue’s fields.
  • Click Save changes button.

Note: this app currently supports only short text (plain text only) custom fields.

Connecting

  1. Navigate to apps and search for Jira. If you cannot find Jira then click Add App in the top right corner, select Jira and add the app to your Blackbird environment.
  2. Click Add Connection.
  3. Name your connection for future reference e.g. ‘My organization’.
  4. Fill in the base URL to the Jira site you want to connect to. The base URL is of shape https://<organization name>.atlassian.net. You can usually copy this part of the URL when you are logged into your Jira instance.
  5. Click Authorize connection.
  6. Follow the instructions that Jira gives you, authorizing Blackbird.io to act on your behalf.
  7. When you return to Blackbird, confirm that the connection has appeared and the status is Connected.

Connecting

Actions

Issues

  • Get issue returns the details for an issue (summary, description, status, priority, assignee, project).
  • List recently created issues returns issues created during past hours in a specific project.
  • List attachments returns a list of files attached to an issue.
  • Download attachment returns the contents of an attachment.
  • Create issue.
  • Add attachment adds attachment to an issue.
  • Update issue. Specify only the fields that require updating.
  • Append to issue description appends text to the description of an issue. Doesn’t brake formatting, useful for adding text to the end of the description.
  • Delete issue.
  • Add labels to issue adds labels to an issue. Returns the updated issue.

Issue custom fields

  • Get custom text field value returns the value of a custom string field (e.g., plain text or URL) for a specific issue.
  • Set custom text field value sets the value of a custom string field for a specific issue.
  • Get custom dropdown field value returns the value of a custom dropdown field for a specific issue.
  • Set custom dropdown field value sets the value of a custom dropdown field for a specific issue.
  • Get custom date field value returns the value of a custom date field for a specific issue.
  • Set custom date field value sets the value of a custom date field for a specific issue.
  • Get custom multiselect field values gets the selected values of a multiple choice select list custom field for a specific issue.

User Actions

  • List users: Lists a predefined number of users (up to 20 by default) from Jira.
  • Get user: Retrieves detailed information about a specific user identified by their account ID.
  • Delete user: Deletes a user from Jira based on their account ID. This action is irreversible.
  • Create user: Creates a new user in Jira with the specified details.
  • Get groups: Retrieves the groups associated with a specified user.
  • Get user email: Fetches the email address for a specified user.
  • Get user columns: Gets the column configuration for a specified user.
  • Reset user default columns: Resets the column configuration to default for a specified user.
  • Set user columns: Sets the column configuration for a specified user.
  • Bulk get users: Retrieves information for a bulk list of users based on their account IDs.

Issue Comment Actions

  • Get sssue comments: Fetches comments for a specified issue. It can retrieve comments for multiple issues if IDs are provided.
  • Get issue comment: Retrieves a specific comment from a specified issue.
  • Delete issue comment: Deletes a comment from a specified issue.
  • Add issue comment: Adds a new comment to a specified issue.
  • UpdateIssue comment: Updates an existing comment on a specified issue.

User Properties Actions

  • Get user properties: Retrieves all properties for a specified user. This can include a variety of user-specific settings and data stored in Jira.
  • Get boolean user property: Fetches the value of a specific boolean property for a given user. Useful for true/false user settings.
  • Get string user property: Retrieves the value of a specific string property for a specified user. This can include text-based user settings or information.
  • Get integer user property: Gets the value of a specific integer property for a user. Ideal for numeric user settings such as limits or thresholds.
  • Get dateuser property: Fetches the value of a specific date property for a user. Useful for date-based settings or milestones related to the user.
  • GetArray user property: Retrieves the values of a specific array property for a user. This can be used for lists of user settings or preferences that are stored as arrays.
  • Set user property: Sets the value of a specified property for a user. This method allows for the dynamic updating of user properties based on provided input.
  • Delete user property: Deletes a specified property for a user. This action removes the selected property from the user’s profile in Jira.

Events

  • On issue updated is triggered when an issue is updated. If you want a bird to be triggered when specific issue is updated, specify the issue parameter. Otherwise, you can specify project parameter if you are interested in specific project’s issues.
  • On issue created is triggered when an issue is created. If you want a bird to be triggered when an issue is created in specific project, fill the project parameter.
  • On issue assigned is triggered when an issue is assigned to specific user. You can specify project parameter if you’re interested in specific project.
  • On issue with specific type created is triggered when an issue created has specific type (for example, a bug) or an existing issue was updated to have specific type. Optionally, you can specify project parameter.
  • On issue with specific priority created is triggered when an issue created has the specified priority or an existing issue was updated to have the specified priority.
  • On issue deleted is triggered when an issue is deleted. If you want a bird to be triggered when an issue is deleted in specific project, fill the project parameter.
  • On file attached to issue is triggered when a file is attached to an issue. If you want a bird to be triggered when a file is attached to specific issue, specify the issue parameter. Otherwise, you can specify project parameter if you are interested in specific project’s issues.
  • On issue status changed is triggered when issue status is changed. If you want a bird to be triggered when specific issue’s status is changed, specify the issue parameter. Otherwise, you can specify project parameter if you are interested in specific project’s issues. You can also limit the event to trigger only on certain statusses.

Optional inputs

We may provide two options for inputting one property to filter results:

  1. Manual:

    • Description: Allows the user to manually enter value without the assistance of a dropdown list.
    • Use Case: This option is ideal when the user knows the exact value they want to use or when the dropdown may not be effective due to the large number of values available through the API.

  2. Dropdown selection:

    • Description: Allows the user to select a value from a dropdown list.
    • Use Case: This option is suitable when there are fewer labels, making it convenient for users to select from a predefined list. However, this approach can be less effective if the number of labels is very large, potentially leading to timeout errors during data retrieval.

Why do we use this approach?

This approach ensures flexibility by providing two methods for inputs, accommodating both situations where the user may need to manually enter specific values and where selecting from a predefined list is more practical. The ‘manual’ option is particularly useful when dealing with a large number of labels, which could otherwise lead to performance issues when retrieving values from the API.

Example

example

This example bird fetches newest issues and assigns those with highest priority to a specific assignee.

example_2

This example shows how to create new TMS (Phrase) projects from issues.

Missing features

In the future we can add actions for:

  • Projects
  • Dashboards

Let us know if you’re interested!