Create workflows with the Smartsheet Jira Connector

This article contains the steps to create and edit synchronization workflows in the Smartsheet Jira Connector.

Who can use this?

Plans:

  • Business
  • Enterprise
  • Smartsheet Advance Package

The Smartsheet Jira Connector is a premium offering. For information about pricing, contact our sales team. If you purchased the Smartsheet Jira Connector on your plan, log in to create workflows between Smartsheet and Jira. 

Log in to the Smartsheet Jira Connector

Get started

Before you create your first workflow between a sheet in Smartsheet and Jira, both applications must establish a connection. Ensure that an administrator on your plan has performed the initial connection setup. 

Prerequisites

To create workflows in the Smartsheet Jira Connector, you must have the following permissions: 

  • You must be a Smartsheet user with Editor permissions or higher on any mapped sheet.
  • You need a Jira account. You must be able to sign in to Jira and have access to the projects you’d like to build a workflow for.
  • If your System Admin activates the Restrict Users setting in the Jira Connector, they must assign you the Smartsheet Jira Connector User role. They can assign this role in the Smartsheet Admin Center or the Jira Connector interface.
  • If you're unable to access the Salesforce Connector and the error message instructs you to reach out to your Smartsheet System Admin, you may need to have your permissions granted. Learn how to contact your Sys Admin. 

Create a workflow

Once you have permissions and have established the initial connection to your Jira environment, users can create workflows to sync information between Jira and Smartsheet. 

With the Smartsheet Jira Connector, you can push information in a single direction (from Jira to Smartsheet or from Smartsheet to Jira) or bi-directionally, 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.

While you're only required to have Editor permissions or higher on the target sheet, we recommend having at least Admin permission levels, as you may need to add new columns to the sheet during the workflow-building process.

Step 1: Start the workflow wizard

  1. Log in to the Smartsheet Jira Connector. 
  2. Select Add Workflow to start the workflow wizard.

You can also access the Jira Connector in Table view by selecting Data Integrations > Manage Connectors > Jira, or Data Integrations > Create workflow. Then, select the Jira tile in the Data Integrations panel.

Step 2: Configure the settings

  1. Choose the desired direction for the workflow — you can't change this once you've saved the workflow. This determines whether the workflow is manual or automatic.

To make any fields bidirectional or syncing between Smartsheet and Jira automatic, choose Keep issues automatically updated in both Smartsheet and JIRA. As with this setting, you can decide later whether to make a specific field bidirectional or just a one-way sync.

  1. Select the sheet to which you want to sync Jira data or Create a new sheet…  — you can’t change this once you've saved the workflow.

You can only create one Connector workflow per sheet.

  1. Select the Jira projects you want to sync to the sheet. You can’t change this once you've saved the workflow.

  2. Select Continue.

    Configure settings for the new workflow

Step 3: Map the fields 

Smartsheet maps fields from Jira to columns. The Jira fields you can select from depend on what fields are available in the projects you select for the workflow. When you set up field mapping, you can specify the direction in which you want data to flow.

Complete the mappings on this page, delete or add Jira fields and Smartsheet columns as desired, and select Continue when done. 

Things to consider
  • You must specify a Smartsheet column to map Jira fields. The Smartsheet column can't be blank.
  • You must include the Issue Key and Error Column, which automatically map to your field and only flow from Jira to Smartsheet. If you use an existing sheet, the system adds a new Issue Key and Error Column, but you can map these fields to existing columns. The Issue Key serves as Jira's primary issue identifier and maps to the sheet's primary column for correct parent rows and hierarchy creation. Deleting either of these columns from your Smartsheet disrupts the workflow and triggers an error code during the next data sync.
  • Specific fields from Jira appear with only a unidirectional mapping option (Issue Key, Jira Link, Issue Link, Created Date). These fields are read-only from Jira and can't be written to from Smartsheet. You can only see specific Jira fields depending on your Jira account permissions. 
  • If you select New column in Smartsheet when creating a mapping, the column type depends on the field you're mapping (for example, a Date from Jira maps to a Smartsheet Date column), and the type appears in parentheses. 
  • The Reporter field in Jira shows the Reporter Email Address and Reporter Display Name options in the workflow wizard.
  • The Assignee field in Jira shows the Assignee and Assignee Display Name options in the workflow wizard.
  • To use the Assignee field in Jira with a Contact List column in Smartsheet, ensure your email is the same in Smartsheet as in your Jira login.

You can map Jira’s Time to Resolution and Time to First Response fields, though this requires the following considerations:

  1. 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 map to its column in the sheet.
  2. Data from these fields displays in minutes as an integer.
  3. Time to Resolution’s Earliest Duration and Longest Duration only have values when the Jira issue is resolved at least once.
  4. Time to Resolution’s Ongoing Duration is only valuable when the issue is unresolved.

Step 4: Optional filters

Creating filters is an optional but helpful way to control the data synced between Smartsheet and Jira. If you'd like to not filter down your data, select Continue through the JIRA Filters and Sheet Filters pages and skip to Step 5. 

Based on your data needs, you can choose between Jira and sheet filters. Use Jira filters to import specific Jira information into Smartsheet, like issues tied to a particular assignee. Opt for sheet filters to sync with Jira if you want only specific Smartsheet rows, such as those with a checked checkbox.

Jira filters

If you're only syncing one Jira project, define your filters by selecting Add filter, the Jira field to filter by, and the filter criteria. All filters set in this way have an AND relationship. 

You can set Jira filters with a Custom JQL query if you're syncing multiple Jira projects. This allows you to use both AND and OR operators.

 An invalid JQL filter turns off the workflow. If you’re having issues with a JQL query in the workflow, verify whether it's valid in Jira.

Sheet filters

Define sheet filters by selecting Add filter, the Smartsheet columns to filter by, and the filter criteria. All added filters have an AND relationship.

The filter criteria available to you depend on the columns present in your sheet. If you want to filter options that aren't listed, add the new column to the sheet first.

Step 5: Define row groups (Optional)

By default, Jira Connector Workflows maintain the hierarchy of your Story, Task, and Subtask relationships from Jira. For example, issues that are children of a Story appear in the sheet beneath that Story as child rows. To deactivate this, uncheck Maintain Jira hierarchy grouping: Story, Task, Subtask, etc.

You can add rows and sub-groupings by Jira fields or primary column values to your sheet as an optional step. To add a row grouping, select Add group and either select the Jira field you'd like to group by, or in Add Custom Group, list the primary column value you’d like to group by.

If your workflow maintains the Jira hierarchy, child issues appear under their parent issue.

Issues sorted by priority

When you define custom row groups by the primary column of your sheet, you can use an existing value in your primary column or create a new value to create a new parent row grouping. If your custom row group isn't placed within the existing hierarchy, the new parent row appears at the bottom of your sheet.

Row grouping example

Keep the following in mind when defining row groups:

  • If your Issue Key field maps to a column that isn't the primary column in the sheet, you can’t create new issues in Jira from Smartsheet while Row Grouping is enabled. You can still create new Issues in Jira and sync them to Smartsheet.
  • Issues with no grouping value set in Jira appear in a hierarchy named Field [Group] not set.  

Step 6: Save your workflow

The Update Summary field on the Save page shows the number of fields to be updated in Jira and Smartsheet. If the Update Summary count appears unexpectedly high or low, go back to add or remove filters as needed.

  1. Once you're satisfied with the Update Summary count, label your workflow under Workflow Name. This helps you quickly locate it later on the Jira Connector dashboard.
  2. To convert new rows in Smartsheet to items in Jira, check the box next to Sync new rows created in Smartsheet to Jira.
  3. Finally, after all your adjustments, select Save Workflow.

Once you've saved the workflow, you can’t change any of the values on the Settings page, such as the direction of the workflow, the sheet you're syncing, or the Jira projects included in this workflow.

After saving your workflow, you land on the dashboard, and your workflow automatically runs and updates records based on your workflow configuration settings. 

A bidirectional sync continues to run automatically unless deactivated or deleted. For a one-way sync setup to update, you must manually run the workflow.

Edit workflows

You can always edit your created workflow. Smartsheet Jira Admins can deactivate or delete any organizational workflows, but can't edit them.

To edit the workflow, select the gear icon to the left of the workflow name and select any of the following: 

  • Edit Workflow: Go back to the workflow wizard to edit the workflow (can't change the direction of the workflow, sheet synced, or Jira projects included)
  • Rename Workflow: Change the workflow name
  • Disable/Enable Workflow: Stop or start the workflow automation
  • Delete Workflow: Delete the workflow entirely (you can't recover deleted workflows)

Filtered out by Connector—not synced

Suppose a sheet row doesn't sync with Jira, either due to filter conditions in the workflow or because the issue no longer exists in Jira. In that case, the row automatically moves to the Filtered out by Connector—not synced section of your sheet. 

Even though a row is no longer synced, it might contain essential column data, attachments, or comments. Because of this, Smartsheet doesn't delete rows from your sheet. Instead, it creates this Filtered out by Connector—not synced section to retain the information filtered out by the Connector. 

You can't turn the Filtered out by Connector—not synced functionality off; it protects against data loss due to accidental workflow or other changes. 

If you're sure you don't need the items listed under the Filtered out by Connector—not synced row, you can delete the rows from your sheet. The rows in question don't return to the sheet until they meet the filter criteria set in the Connector workflow.

For example, in the image below, four child rows are currently filtered out (not synced) by the Connector.

Connector failed to sync

If a row moves to Filtered out by Connector—not synced but begins to match the filter criteria again, it automatically starts syncing again and moves from the Filtered out by Connector—not synced section of your sheet to the correct sheet section (based on row groupings).