The integration is mostly suitable for the following scenarios:
A: Multiple Teams: when you have multiple teams working in Kanbanize and/or in JIRA and you need to bridge them.
For examplе: Team A, Team B, and Team C are working in JIRA and Team K is working in Kanbanize and receives requests/tasks in the form of JIRA issues.
As the rest of the teams are using JIRA, they report issues within the project located in JIRA and they also expect to receive comments and updates there, while Team K uses the Kanban Method advantages (workflow visualizations and breakdown structures) in Kanbanize.
B: Product Development / Project Management: Using related boards and implementing the Kanban Portfolio breakdown setup facilitate the Product and Project Managers in Kanbanize to monitor the overall work progress at different levels. Once the tasks are broken down for the teams to be executed, they are requested into their systems (JIRA Projects) for execution.
Note: We do not support nor recommend scenarios where the team is expected to be able to work equally between the two systems. Like, half of the team is using only JIRA and the other members are using Kanbanize only. As the systems compliment/enhance each other, there is no possibility for full replication. This is why only basic information is kept in sync to support the scenarios above.
- Bi-Directional Sync of JIRA issues and Kanbanize cards using Webhooks.
- Create cards/issues,
- Update cards/issues
- Add Comments
Note: Make sure the Board Name in Kanbanize has the same name as the Project in JIRA or use the advanced parameters in the webhook to specify where new Kanbanize cards to be created.
- Jira Status to Kanbanize Column Move
Note: Make sure the JIRA Transitions have 1:1 mapping to Kanbanize Column Names.
- Fields mapping for Kanbanize cards and Jira issues:
|Issue Type||<->||Type *|
* Types: In Kanbanize the default type is "None", just a plain card. In Jira, depending on your solution in place, there are several default issue types.
Note: There might be also additional issue types defined by the Administrator. Make sure you have 1:1 mapping between JIRA Issue Types and Kanbanize Types.
The issue type is mandatory for Jira, but not for Kanbanize. So we need to set a default mapping for "None" type in Kanbanize. This is defined during the integration configuration step.
** Assignees: Assignees will work only if the "Usernames" match in the two systems.
*** Priority: In Kanbanize we have 4 options to prioritize the card: Critical, High, Average and Low. In JIRA the priority names can be changed by changing the priority schemes. That is there is no way to cover some custom scenarios and we have a mapping for Kanbanize and Jira Priorities:
All other types of priorities in JIRA are not supported.
1. In Kanbanize -> go to Administration -> click Integrations and enable the Jira integration
- Prepare one Kanbanize user that is to be used for integration purposes.
- Prepare one JIRA user that is to be used for integration purposes.
1. Select a Kanbanize User for the integration.
Click on the arrow and select the user from the dropdown menu. You can use an existing Kanbanize user on behalf of which the sync will work, or you can create a new user for integration purposes.
- We recommend creating a separate user for integration purposes, as it will help you to easily track the changes in the card history.
- Make sure the selected user has all the necessary permissions as described in Section 8.
2. Select the board.
Click on the arrow in the "Board Selector" field and use the dropdown menu to select the board that you want to synchronize with your JIRA project.
- Make sure the user you selected in Step 1 has access to the selected board and all the necessary permissions as described in section N.
- By default, it is: Kanbanize board <-> JIRA Project synchronization, so make sure that the board has the same name as the JIRA Project (Case Sensitive). If you would like to sync your Jira Project with different boards or to create a card in another swimlane, please follow the steps in the section "Optional Webhook Parameters".
3. Specify the JIRA Integration Username.
In order to prevent loops, we need the username of your JIRA integration user. The username should not look like an email address. You should have access to the JIRA "User Management" Panel to create a user and see its username.
4. Specify the JIRA Default Issue Type.
As described in the Section "Abilities", in Kanbanize you create a plain card without any types. There is no way to create an issue in Jira without specifying the Issue Type. That is why we need a default issue type in order to be sure the JIRA issue will always be created. After that, you can change the issue type and all these changes will be synchronized back to Kanbanize (if you enabled bi-directional integration and all issue types should be added to Kanbanize board as card types).
Note: To see all available Issue types in JIRA go to "Project Settings" - "Issue Types" or check it in JIRA Settings - Issues - Issue Types.
5. Authenticate within JIRA Connector.
Once you clicked on "JIRA Connector" button, the system will ask for your username and password for the authentication. Please enter the credentials of JIRA Integration user you created previously.
Note: Please, make sure the integration user has all necessary permissions for your JIRA project.
6. JIRA Webhook Registration.
Once you are authenticated within JIRA connector you can proceed with registration of the Webhook URL in JIRA. In order to add a webhook to JIRA go to "Settings" - under "JIRA Settings" click on "System" - under "Advanced" you can find "Webhooks" section - "Create a Webhook"*. Copy the Webhook URL from the "Webhook" field in Jira Integration settings and paste it to the "New Webhook Listener" (you edit the name of your Webhook listener during the configuration).
In the screenshot below you can see how the default Webhook configuration looks like:
Note: The path to the "Webhooks" section may vary depends on the JIRA software version.
In this particular case, JIRA sends the payload to the Webhook URL if any user creates issues, updates issues or add comments. As you may notice, there are no JQL queries, so JIRA will send the information about the specified types of actions in all your projects. In order to filter to some specific projects, you can use JQL queries as described in the official Atlassian article here. Once you have specified the types of events and JQL queries, you can save the Webhook listener.
7. Optional WebHook Parameters.
The WebHook URL could look like this:
*column and lane names are case sensitive, use "%20" if you have spaces in the names.
**if the card has been moved to another board the update/sync from GitHub to Kanbanize will stop as the integration will not be able to locate the card.
- Kanbanize Integration User
In order to set up the integration correctly, your Kanbanize Integration user should have access to the boards you want to integrate. The Integration user should have a role with the following permissions:
- Create Card
- Move Card
- Card Details - Edit Card Details
- Comments - Add Comments
- Access API
- Create issues
- Assign issues
- Edit issues
- Resolve issues
- Transition issues
- Add comments
- Create epic
- Rename epic
Note: Depends on the solution you have in place, you might need to modify your permissions schemes in order to use the integration.
Create / Update
Upon configuration as per the requirements above, when an issue is created, a new Kanbanize card will be created. Each issue update will be reflected on the cards as follows:
JIRA Issue <-> Kanbanize card
Summary <-> Title
Description <-> Description
Assignee <-> Assignee (names have to match, only one assignee is supported in Kanbanize)
Note: By default, all New Issues/Kanbanize Cards are created in the Backlog of the board matching the JIRA Project name. If you create a Kanbanize Card in some other column, the integration will first create an Issue in Jira Backlog and only after that, the status of the issue will be changed. More about Moving Cards <-> JIRA Transitions you can find in the next section.
Card Moved / Jira Transitions
- Card moved in Kanbanize:
When Kanbanize card is moved from one column to another, the integration is looking for the possible JIRA transitions and statuses with the same name as the target Kanbanize column. That is why it is very important to have columns in Kanbanize with the same names as your workflow stages in JIRA. If there is no transition/status with the same name as Kanbanize Column, the issue will stay in Backlog.
- Jira Issue Transitions/Status changes:
When you change the status of a JIRA issue (for example, from Backlog to To Do or Selected for Development) the integration will work differently than in move the card in Kanbanize. There is an additional step to check for the column. When you change the status of the issue, the integration is looking for the same column name in Kanbanize. If there is such, it moves the corresponding card to the specific column. If there is no such column, the integration is taking JIRA Status Category parameter and compare it with the columns in Kanbanize. If there is a column with the same name, the card will be moved to this column. If no matches found during both iterations, the corresponding Kanbanize card will stay in the original column.
In case you have different resolution states in JIRA (for example, Cancelled or Rejected) and you want to make it work with Kanbanize, you need this resolution states to be available as transitions and statuses, so the integration could access it via API and find the correct Transition ID. If all the resolution states are already available, you need to create a new column with the same name as your resolution states for each state in Kanbanize under the "Done" section.
Note: By default, all JIRA issues are created in the Backlog and there is no way to create cards in some other stages of the workflow (only if you created your own workflow). That is why when you create the issue in JIRA, it will always be created in Kanbanize Backlog without being moved to another column.
Issue CommentsComments are added from both sides by the integration users. The username of the person making the comment is added in front of the comment itself, for example:
Comment by KBIntegration:
john: Hey we need more info here?
If JIRA users want to mention a Kanbanize user, the process is the same as between Kanbanize users and @Username should be added to the comment. More information about how to @mention a user in Kanbanize you can find here.
Note: Markup language is not supported and the text in the comment and the description of the Task/Issue is converted to plain text format.