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
- 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 from Jira are mapped to columns in a Smartsheet. The Jira fields you will be able to select from will depend on what fields are available in the project(s) you select for the workflow. When you set up field mapping, you can specify the direction that you want data to flow in.
Here are some things to keep in mind as you set up mapping:
- Issue Key and Error Column are required and will be added to your workflows field mappings by default. These cannot be removed in the workflow, and can only flow from Jira to Smartsheet, though you can select the columns these map to. If you delete one of these columns from your Smartsheet sheet, Jira will return an error code the next time the data is synced. (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.
- Certain fields from Jira will appear with only a unidirectional mapping option (Issue Key, Jira Link, Issue Link, Created Date, etc.). These fields are read-only from Jira and cannot be written to from Smartsheet.
- 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.
- You must always specify a Smartsheet column to map fields to. These cannot be left blank.
- When creating new columns in a workflow, the column type created in the sheet will vary depending on the field type being mapped (for example, a date value from Jira will be mapped to Date column).
NOTE: The mapped column in the workflow wizard will show the column type in the sheet within parentheses.
- The Reporter field in Jira will show as Reporter Email Address and Reporter Display Name options in the workflow wizard.
- The Assignee field in Jira will show as “Assignee” and “Assignee Display Name” options in the workflow wizard.
- To use the Assignee field in Jira with a Contact List 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.)
- The following Jira fields will be added automatically when creating a new workflow. If building a workflow off an existing Smartsheet, columns already present with matching field names will be mapped automatically in the workflow wizard. Those fields are: (Issue Type, Summary, Reporter Email Address, Description, Priority, Assignee)
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.
For example, a Filter could be used to view Jira issues assigned to certain people, of a certain type, or to sync 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.
NOTE: If your JQL filter is invalid, the workflow will become disabled. If you’re having issues with a JQL query in workflow, try verifying it is valid in Jira.
- 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).
For Jira Cloud, certain fields will not be usable when Filtering Jira issues in the Jira Connector. For more information see our Smartsheet for Jira: Important Jira Cloud Privacy Changes article.
Here are some things to expect when creating sheet filters:
- If you create multiple filters using the workflow wizard, keep in mind that, filter criteria will always use an AND operator for successive filters.
- Filter criteria will be available to choose from will depend on the columns present in your sheet. If you would like to filter on other options that are not listed, you’ll first need to add the new column you want to filter on to the sheet.
- Filtering operators will vary depending on the field type (for example, text fields will have operators appropriate for text such as “is blank” or “contains”).
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.
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
To get to the Run History page:
Click Dashboard from the menu (upper-left) to view the list of workflows.
Click the timestamp under Run Date to see a workflow’s Run History page.
You can then click the timestamp under Last Run of a specific run instance to see any error messages.
Manual Sorting of Rows
Due to the filtered row finder process that runs for automatic workflow types, manual resorting of issues synced from Jira will not be honored. Issues will automatically return to their original state (ascending by Issue Key) when the filtered row finder process runs. If you would like to sort issues synced with an automatic workflow, consider using the Row Grouping option in your workflow.
The Filtered Row Finder process does not run for manual workflows, so you can manually sort rows in your sheet if using that workflow type.
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.
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.