You can use Smartsheet for Jira to track and manage Jira issues in Smartsheet. Once an Administrator has established a connection between Smartsheet and Jira (Cloud Server or Self-Hosted Server), you’ll be able to track work items, monitor progress, and make updates between the two services.
Synchronization workflows give you the power to share information between the two systems. You’ll be able to specify the sync directions when you set up field mapping for the workflows.
In this article:
- Required Permissions to Use the Integration
- Working with Synchronization Workflows
- Using Field Mapping and Filters
- Keep Related Issues Together with Smartsheet Hierarchy
- Best Practices for Working with Jira Data in Smartsheet
- Finding and Fixing Workflow Errors
- Troubleshooting Workflow Issues
Installing Smartsheet for Jira
Once the integration has been purchased, a Smartsheet for Jira Admin (an account type unique to the integration) or someone that is both a Smartsheet SysAdmin and a Jira Admin must install it using their respective Jira instance:
Required Permissions to Use the Integration
To create workflows in Smartsheet for Jira, you must have all of the following account types:
- Licensed Smartsheet User—Your Smartsheet SysAdmins can give you a license. See Managing Users for more information.
- Jira User—Your Smartsheet SysAdmins can make you a Jira User. See Managing Users for more information.
- Account in Jira—You must be able to sign in to the Jira application. Contact your organization's Jira Admin for details.
Logging in to Smartsheet for Jira
Once Smartsheet for Jira has been installed and configured, you’ll use the following URL to create and sync workflows with the integration:
Create workflows in Smartsheet for Jira to synchronize issues between Jira and Smartsheet. With Smartsheet for Jira, you have the option to push information in a single direction (from Jira to Smartsheet or from Smartsheet to Jira) or bidirectionally, instantly updating issues in both applications.
You can sync with an existing sheet, or create a new sheet to launch a Smartsheet project using issues in Jira.
Create a New Workflow
- Log in to Smartsheet for Jira (https://connectors.smartsheet.com/c/Jira).
- From the Smartsheet for Jira Dashboard (upper-left menu > Dashboard), click Add Workflow to start the workflow wizard.
- Choose the desired direction for the workflow.
IMPORTANT: You won’t be able to change this later. If you change your mind, you’ll need to create a new workflow.
- Select a sheet that you want to associate with the Jira Projects (or click Create a new sheet) and select a Jira projects to associate with it.
- If you select an existing sheet, an Issue Key and Error column will be added to the sheet, as they’re required columns for the connector to work.
- Note that you can select multiple Jira projects to include in your workflow. If you do select multiple projects, you'll only be able to apply Jira filters with Jira Query Language (JQL). (See Jira's JQL help article for more information.)
- Click Continue to follow the rest of the steps in the wizard.
- For help with setting up fields and filters, see the section of this article on Field Mapping & Filters.
Once you’ve created a workflow, you can change the included fields, change the mapping direction for fields, update or modify a filter, or delete a workflow altogether:
- Start from the Smartsheet for Jira Dashboard (upper-left menu > Dashboard).
- In the Name column, locate the name of workflow, and click Settingsnext to the workflow name.
- Select the action that you want to perform.
When you use Smartsheet for Jira, field mapping and filters give you control over what data is exchanged and how it moves between the two systems.
Fields in Jira issues are mapped to columns in a Smartsheet sheet. When you set up mapping, you can specify the direction that you want the data to flow. Here are some things to keep in mind as you set up mapping:
- Issue Key and Error Column are required. If you delete one of these columns from your Smartsheet sheet, Jira will return an error code the next time the data is synched. (See Finding and Fixing Workflow Errors for more information.)
NOTE: The Issue Key is the primary identifier for issues in JIRA. Without this required value, the Smartsheet for Jira Connector cannot write changes back to that Issue in Jira.
- You must always specify a map (you can’t leave Smartsheet fields blank).
NOTE: Fields must be on the Create Issue screen in the Jira application to appear as options in the workflow wizard. More information on screens in Jira can be found in the Atlassian Documentation article on Defining a Screen.
- Smartsheet data types will vary depending on the nature of the data you’re syncing (for example, a date value from Jira will be mapped to a column with a date value).
- The Reporter field from Jira will be mapped to Smartsheet as Reporter Email Address, Reporter Display Name, and Reporter Username.
- The Assignee field from Jira will be mapped to Smartsheet as Assignee Display Name and Assignee Username.
NOTE: To use the Assignee field in Jira with a Contact type column in Smartsheet, make sure the user’s email is the same in Smartsheet as the user's Jira login. (For more information about column types, see the Column Types article in the Help Center.)
Mapping Time to Resolution and First Response Fields
You can also map Jira’s Time to Resolution and Time to First Response fields in order to leverage Service-Level Agreement (SLA) information in Smartsheet. Use this data to get a better picture on your SLA metrics.
Keep the following in mind when mapping these fields:
- Both “Time to First Response” and “Time to Resolution” are broken up into subcategories (such as Earliest Duration Goal, Earliest Duration, and Ongoing Duration Goal), so each subcategory must be mapped to its own column in the sheet.
- Data will from these fields be mapped to the sheet as an integer in minutes.
- Mapping Goals (earliest, ongoing, and longest) allow you to sync the SLA’s you’ve set in Jira to take advantage of Smartsheet formulas and visualization features.
- Time to Resolution’s Earliest Duration and Longest Duration will only have values when the Jira issue is resolved at least once.
- Time to Resolution’s Ongoing Duration will have a value only while the issue is unresolved.
Use filters to better control the volume and type of issues that you work with, Use a filter, for example, to view Jira issues assigned to certain people or of a certain type or to push only certain rows from Smartsheet to Jira.
You can use one of two methods for defining criteria in Jira filters in your workflow:
- Jira Query Language (JQL)—Although JQL requires understanding of computer programming, you can apply more advanced filtering logic—for example, using both AND and OR operators with multiple criteria.
- Workflow wizard—If you create multiple filters using the workflow wizard, keep in mind that filter criteria always uses an AND operator for successive filters. Also note that criteria and operators will be specific to the Jira projects used in the workflow:
- Filter criteria that show up by default are dependent on the Jira project types that you have mapped. It’s possible to add more criteria by clicking add field at the bottom of the filter page.
- Filter operators will vary depending on the field type (for example, text fields will have operators appropriate for text).
Define row groups in your workflow to automatically keep your Jira tasks and subtasks together as parent and child tasks in Smartsheet. Create row groups to have your workflow organize your Issues and Stories underneath their corresponding Sprints without having to manually move them around in your sheet after they sync.
You can also define row groups when you want Jira issues organized in the context of a larger project with other tasks that aren’t in Jira. For example, you can create a Development group in your workflow for Jira issues to automatically appear in your sheet in Smartsheet as child rows underneath a Development parent row.
Keep the following in mind when defining row groups:
- If your Issue Key field is mapped to a column that is not the Primary Column in the sheet, you will not be able to create new issues from Smartsheet while Row Grouping is enabled.
- In the Group by field, you can select the Primary column value of an existing row in your sheet to group Jira issues, or type a new Primary column value to create a new parent row to group Jira issues. The new row will be created at the bottom of your sheet.
- Smartsheet for Jira will maintain that your Epic, Story, Task, and Subtask relationships from Jira, even if they are in different sections. For example, if your Task and Subtasks are in different sprints in Jira, the subtasks will sync to Smartsheet as children underneath the same sprint as the parent Task.
- You can define a sub group for an additional layer of organization. Have Jira issues sync, for example, underneath a Website parent row that is also a child to a Development row in Smartsheet.
- Jira Issue Keys must have the correct hyperlinks in the Issue Key column on your sheet. (If an Issue Key column doesn’t exist yet, it will be added to your sheet automatically when the workflow runs for the first time.) Manually copying and pasting Issue Keys from Jira into your sheet may cause the workflow to not sync as expected.
Save and Refresh Often
Because you'll be working across two systems, the opportunities for synchronization errors are increased as more people collaborate. To help minimize the risk of sync issues, save changes and refresh your sheets as you make updates. Saving and refreshing frequently will ensure that others see your changes and that those changes are synchronized to Jira and Smartsheet according to the workflows you've set up.
Lock Columns to Avoid Errors
Data in the Issue Key field (which is a required field) should not be modified in Smartsheet. To secure the integrity of the data in this column, the sheet Owner or someone shared to the sheet with Admin privileges should lock the Issue Key column. For more information, see Locking & Unlocking Columns and Rows in the Smartsheet Help Center.
You can use the View History command to see a record of changes that were made to a cell. For sheets that include data shared between Smartsheet and Jira, the name of the user associated with the change will always be the name of the person who created the workflow.
For more information about tracking changes in Smartsheet, see Viewing Cell History in the Smartsheet Help Center.
Push Data from Smartsheet to Jira for Specific Rows Only
To give you greater control over which rows explicitly push data back to Jira, create an Update Issue in Jira column in the sheet in Smartsheet and a filter in the Smartsheet for Jira workflow:
- In Smartsheet, in the sheet that you plan to connect to the Jira projects, create a new column, select the Checkbox type, and name the column "Update Issue in Jira."
- Log in to the Smartsheet for Jira page, and follow the steps to create a workflow, specifying a bi-directional workflow in the workflow wizard. (Or click Settings > Edit Workflow on a bi-directional workflow you’ve already created to bring up the wizard for that workflow.)
- Add a filter that syncs only rows from the sheet that have the Update Issue in Jira column checked.
The next time the sheet and the Jira projects are synced, data will be pushed back to Jira only for the rows for which the Update Issue in Jira checkbox is checked.
Avoid Creating Multiple Workflows That Sync to a Single Sheet
Data can be overwritten if multiple workflows are set up to sync to one sheet. It's best to create only one workflow rule which includes multiple Jira Projects.
Several resources are available to help you detect and resolve errors as you build and run workflows. These resources include:
- The Workflow History page in Smartsheet for Jira. (For more information about how to use this, see “Reviewing Workflow History” below.)
- Error reports: As issues occur, error reports are sent via email to the workflow owner and to the person who edited the issue/row in the workflow that caused the problem.
- The Sync Error column in Smartsheet (a column of this type should exist in every sheet that’s associated with a Jira projects).
When editing or viewing the sheet, you can track any workflow synchronization errors with the Sync Error column.
Reviewing Workflow History
After you run a workflow, you’ll be able see its synchronization history — including any errors that occurred — via the workflow’s History page:
- To get to the History page, click Dashboard from the menu.
- Click the link under Last Run to get to the Run History page.
- Click the date in the Last Run column to see additional information about any errors that occurred during synchronization.
Error: Field '<field name>' cannot be set. It is not on the appropriate screen, or unknown.
You’ll receive this error if the field value that you are attempting to set is not present on the Edit screen in Jira (in Jira you can specify which fields appear on the Edit screen). For a field to be editable from Smartsheet for Jira, that field must be configured to be present on the Edit screen in Jira.
To resolve this issue, do either of the following:
- Option 1: Configure the Edit screen in Jira and add the specified field to the screen. For more information about Jira screens, including the steps to change the configuration, please see Defining a Screen in the Jira documentation.
- Option 2: Map the specified field in one direction only, such that the the arrow on the Map Jira fields to sheet columns step is pointing from Jira to Smartsheet. Note that because this will create a one-way map, any revisions you make to the fields in Smartsheet will not be written back to Jira.
Issue could not be saved to Jira
You must have write permissions to the connected Jira projects to save data to it.
Data is not removed from a sheet after filter updates
Smartsheet will not delete data that you’ve already pulled from Jira because each row might contain important column data, attachments, or comments.
When the Jira Issues in your sheet no longer meet the workflow filter criteria, Smartsheet creates a "Filtered out by Connector—not synced" section at the top of your sheet to retain the information that is filtered out by the Connector. Any rows which are “filtered out” will not sync until they meet the filter criteria again, and these rows can be deleted if your team no longer needs them included in the sheet.
See the How to Use "Filtered Out by Connector—Not Synced" article to learn more.
Error updating error column in Smartsheet
You’ll receive an error if the Sync Error column is removed from the connected sheet in Smartsheet. To resolve the problem, ensure that the sheet includes a Sync Error column. If needed, you can edit your workflow to map the Sync Error column back to your sheet. For details on this, check out the above section on modifying workflows.
NOTE: When you map the Sync Error column back into your workflow, it will be re-created to the right of all other columns in your sheet.