What is Jira?
Jira is a popular project management system developed by Atlassian. In Jira, you can track issues and bugs using agile project management practices.
While an ideation environment, such as Viima, is good for transparent ideation and innovation by a large group of people, a project management system, such as Jira, excels in helping manage the implementation of issues in more detail. These platforms work best in tandem, where the bulk of ideas are collected, developed, and prioritized in the ideation software, and then selected ideas are implemented using a project management system to support this.
What does integrating Viima with Jira do?
With Viima's Jira integration, you can automate the process of sending selected ideas from Viima to Jira for further development.
The integration automatically creates an issue in Jira whenever an idea in Viima is advanced to a certain status. The integration will also keep the idea in Viima updated when the Jira issue is moved forward in the development process.
How does it work?
When your Viima board is integrated with a Jira board, the integration will automatically sync ideas between the two platforms by certain rules. Note, that the integration is one-way, meaning the integration is able to create issues in Jira, but will not create ideas in Viima. In other words, issues created manually in Jira (i.e. not created by the integration) will not appear on the Viima board, but ideas created in Viima will appear on both platforms.
When creating a Jira integration in Viima, you'll notice that your board will get an additional custom field called the Jira issue key. The custom field is responsible for storing the key of the Jira issue to which the Viima idea is linked. If you don't have custom fields enabled on your board, creating a Jira integration will enable them. The integration will not work without custom fields.
Currently, the integration will sync the Viima idea's name, description, and status with a corresponding Jira issue's summary, description, and status and vice versa. When creating the integration, you are required to make status mappings so that the integration knows how to sync statuses between Viima and Jira. For example, if you have an In progress status in Viima and in Jira, you'll probably want them to be linked with each other. The status mappings also indicate when the integration should create new issues in Jira.
Whenever a Viima idea is moved to a mapped status, the integration will try to find a linked Jira issue (by the idea's Jira issue key custom field), and if not found, the integration will create a new issue in Jira in the linked status.
You can also exclude certain categories in Viima from the integration so that ideas in those categories will not be pushed to Jira. By default, all categories are included.
All issues created in Jira by the integration will be set to the default issue type which can be selected from all of the issue types in your Jira project when creating the integration. Subtasks are not supported by this integration.
The integration will sync changes made to Jira issues to Viima every 5 minutes. Every time a Viima idea is created or edited, a sync from Viima to Jira will occur for that idea.
You can have multiple Viima boards integrated with the same Jira project if you want by creating the same integration in each Viima board separately. Additionally, you can also have a single Viima board integrated with multiple Jira projects by creating a new integration for each Jira project. Note, that you can't integrate a single Viima board with multiple Jira boards in the same Jira project. Each new integration must point to a different Jira project.
Current limitations
There are a few limitations considering your Jira board that you should keep in mind when integrating your Jira board into Viima.
Backlog and sprints: If you are using a Next-gen project in Jira and have the backlog enabled, make sure you enable sprints, too. You can disable both the backlog and sprints if you want, but enabling the backlog and disabling sprints might prevent ideas to sync properly.
The integration works only with Jira boards with one backlog.
Issue types: If the integration's default issue type is custom-made in Jira, ensure the issue type has no additional mandatory fields. The integration will only set summary and description fields for issues, so if an issue requires additional mandatory info, the integration cannot create the issue.
Example
Here is an example of an integration using the following Viima and Jira configurations:
Viima board:
Name: Research & Development
Statuses: New Ideas, Planned, In Progress, Done, Archived For Later Use
Jira board:
Name: Dev board
Statuses: To Do, In Progress, Code Review, Testing, Done
Let's assume your company has a Viima board called Research & Development, and a Jira project with a board called Dev Board. A typical case would be that your company gathers all sorts of ideas regarding development in the Viima board and they are all created in the New Ideas status. You probably don't want to push all of the ideas to Jira for further development, but only those which are actually planned to develop. Therefore you should leave New Ideas unmapped in the integration status mappings.
In this example, the Planned status is mapped to the Jira backlog, so whenever an idea is moved to the Planned status, it will be created in the Jira backlog immediately. The new Jira issue will have the Viima idea's name as the summary and a matching description. All Jira issues created in the Jira backlog by this integration are always put into the first status in Jira, in this case, To Do. The Viima idea will automatically get the Jira issue's key as the value for the Jira issue key custom field. If the Viima idea already had a value for the Jira issue key custom field, the integration will try to find a Jira issue with a matching key on the Jira board. If an existing issue is found, it will be used in the syncing, and if not, the integration will ignore the Viima idea and not sync it.
When the Jira issue is moved forward in the development process by moving it from the backlog to the active sprint, the integration will automatically move the Viima idea to the In Progress status according to the status mappings. Also, if the issue's name or description is edited in Jira, those changes will be updated to Viima as well. Note that it might take 5 minutes for the sync to occur from Jira to Viima.
If you move the issue in Jira to a status that doesn't have a status mapping, in this case, Code Review for example, the integration will look for a previous Jira status that has a mapping and sync by it. In this case, a previous mapping is found in the In Progress status, and according to its mapping, the Viima idea should be in In progress status. The same logic applies in Viima: if you move an idea in Viima to a status that doesn't have a mapping, the integration will look for a previous mapping and sync the Jira issue according to it.
How to integrate Viima with Jira?
Below are step-by-step instructions on how to integrate your Viima board with Jira. You must have an existing Jira board as well as a Jira user and you need to be an admin of the Viima board to create the integration.
1. Creating a Jira integration
Go to the Settings section in the Admin portal and choose the Integration tab.
Click the Jira integration subsection to open it, and then click the Add new button to integrate your Viima board with a Jira board. This opens a four-step creation process which might take a few minutes to complete.
2. Setting Jira board and user details
In the first step, you need to tell the integration some details about your Jira board and Jira user. Note, that you need to have an existing Jira board and user to advance, as the integration will not create a Jira board or a user for you.
The Jira board name is the exact name of the board in Jira that will be used in the integration.
Jira service URL is an address to your Jira organization, such as
https://organization.atlassian.net/. You should see the URL in the browser's address bar when you're on your organization's Jira page.
The Jira project key is the key for your Jira project. The key is written in uppercase in Jira, such as PROJ.
Jira user email is the email address of the user in Jira which will be used to create and edit the issues in Jira. Note, that this user must have access to the Jira board and be able to create and edit issues.
The Jira user API token is an API token for the user mentioned above. The API token is required for authentication in communicating with Jira's API. Note, that the API token is not the user's password. If you don't have an API token for the user, please see Atlassian's documentation on how to create an API token. For security reasons, we don't show a previously given API token for admins when editing this integration.
If you get an error when clicking Next step, please check the form fields for typos. Make sure the values are exactly in the same form as in the examples.
3. Mapping statuses
In the status mappings step you must create links between your Viima statuses and Jira statuses. You can do so by dragging a line from a Viima status to a Jira status (or the other way around). The line indicates a mapping. Ideas moved to Viima statuses that have mappings will be created as Jira issues (if the issue doesn't exist already). If a Viima status doesn't have a mapping, no issue will be created.
You can delete a mapping by clicking the mapping line.
The Backlog box means that issues will go to the Jira backlog to the first Jira status. All other boxes indicate statuses in the active sprint in Jira.
Note, that you need to have at least one mapping before advancing. If you don't want to sync Jira's active sprint issues to Viima, simply connect only the Backlog to a Viima status of your choice.
4. Setting integration details
In this step, you can define the integration's categories and default issue type.
Select the categories in Integration categories in which you would like to have the ability to sync ideas with Jira. By default, syncing is allowed in all categories. For example, you might want to exclude some categories so that ideas in them will not be pushed to Jira. In this case, simply select all the other categories in the dropdown except the ones you want to exclude.
In the Default issue type field, you can choose the issue type in Jira which all new Jira issues created by the integration will have. Currently, the integration doesn't support choosing issue type for each created issue separately, but you can manually change the issue type later in Jira, because the issue type will not be synced after the issue has been created.
All set!
Once you've reached the fourth phase of the integration setup and completed it, you are all set to go. Enjoy your new seamless flow of raw ideas to implemented tasks.