Smartsheet for Jira: Creating and editing synchronization workflows

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.

Creating Workflows: Getting Started

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:

• Jira Cloud
• Jira Self-Hosted Server

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:
https://connectors.smartsheet.com/c/Jira 

Working with Synchronization Workflows

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

1. Log in to Smartsheet for Jira (https://connectors.smartsheet.com/c/Jira).
    
2. From the Smartsheet for Jira Dashboard (upper-left menu > Dashboard), click Add Workflow to start the workflow wizard.
   
   
3. Choose the desired direction for the workflow.
   
   You won't be able to change this later. If you change your mind, you'll need to create a new workflow.
    
4. Select a sheet that you want to associate with the Jira Projects (or click Create a new sheet) and select a Jira project to associate with it. 
   
   NOTES:
   • 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.
   • 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.)
   • The sheet and projects you select in your workflow cannot be changed once the workflow is saved. To add or remove Jira projects or change the sheet, create a new workflow.
   • If the workflow is a manual single direction workflow, you must run it from the workflows dashboard.
5. Click Continue to follow the rest of the steps in the wizard.
    
6. For help with setting up fields and filters, see the section of this article on Field Mapping & Filters.

Modify or Delete a Workflow

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:

1. Start from the Smartsheet for Jira Dashboard (upper-left menu > Dashboard).
2. In the Name column, locate the name of workflow, and click Settingsnext to the workflow name. 
3. Select the action that you want to perform.

Using Field Mapping & Filters

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.

Field Mapping

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.)

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).
  
  The mapped column in the workflow wizard will show the column type in the sheet within parantheses.
   

• 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 from these fields will 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.

Jira Filters

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:

1. 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.
   
   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.
    
2. 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.

Sheet Filters

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”).