Administration and Setup of the Smartsheet Jira Connector

If your system admin activates the Restrict Users setting in the Jira Connector, you must also hold the Jira User role in Smartsheet. 

The Smartsheet Jira Connector is available as a premium offering.

If you have the Smartsheet Jira Connector purchased on your plan, use the following URL to log in and create workflows between Smartsheet and Jira: https://connectors.smartsheet.com/c/jira

Terminology and Permission levels

Before beginning, these are some helpful terms: 

• Connection: The link between Smartsheet and a specific Jira instance.
• Workflow: The link within Jira Connector connecting Jira elements to a Smartsheet sheet. 

Three types of users can interact with the Smartsheet Jira Connector:

• Smartsheet System Admin — Manages and restricts Jira Connector Admins and Jira Connector Users. 
• Jira Connector Admin — Establishes the connection between a Jira instance and the Smartsheet Jira Connector.
• Jira Connector User — Creates workflows that sync information between Smartsheet and Jira.

Features by Permission type

Use this chart as a reference for features based on the types of users that can access the Connector.

*Smartsheet System Admins and Connector Admins can create and edit their own workflows if the Restrict Access feature is disabled. They must have the Connector User role if the Restrict Access is enabled. See Restricting Access to Smartsheet Jira Connector for more information on the Restrict Access setting.

Connection setup

To begin using the Smartsheet Jira Connector, you must first set up the connection between Smartsheet and your Jira instance so users can build workflows to connect specific elements in Smartsheet and Jira. 

You may need to set up your Firewall Settings and configuration before setting this connection up. 

Smartsheet advises using a generic licensed email account (e.g., smartsheet-jira@yourdomain.com) for both Smartsheet and Jira to establish the connection. This prevents the need to redo connections or workflows if the person managing the Jira link leaves your organization, as connection ownership can't be changed.

While only the Smartsheet System Admin role OR the Smartsheet Jira Connector Admin role is required, Smartsheet recommends that you have both roles to set up the Connector.

The account used for setup must remain active with Admin rights in both Jira and Smartsheet. Removing this user's Admin status triggers an error: Missing user credentials for this endpoint. Restoring Admin permissions fixes the connection, resuming normal workflow sync. If Jira Admin credentials are removed, you must rebuild the application link due to token changes.

As the Smartsheet Jira Connector enables the implementation of automatic workflows, the application must have Jira System Administrator credentials to create or configure a Webhook with the Jira REST API. The Jira System Administrator’s credentials are only used to create and configure the webhooks.

Step 1: Register a new Jira Server in the Smartsheet Jira Connector

If you want to set up the Connector with a Self-hosted Jira Server and a firewall, follow the instructions in Jira Connector Firewall settings.

1. Log in to the Smartsheet Jira Connector. If prompted to allow access to your Smartsheet account, select Allow.
2. Select the menu in the upper-left corner of the page and then select Account Admin.
3. Select Register New Jira Server.
4. In the Settings page:
   • Enter the JIRA Host URL of the Jira environment you want to connect to your Smartsheet environment (e.g., https://mbfcorp.atlassian.net/). 
   • The JIRA API URL likely is the same as your JIRA Host. 
   • For Name, either accept the default name or change it to a more helpful descriptor. 
   • Select your JIRA Version.
5. When you have completed these items on the Settings page, select Continue.
6. On the Configuration page, see the Consumer Key, Consumer Name, and Public Key. Copy these values as you will need them later.

Step 2: Create an Application Link (AppLink) to Smartsheet in Jira

1. Sign in to Jira (you must have Jira Administrator permissions).
2. Go to Jira Settings (the gear icon in the top right corner) and select Products.
   
3. On the Products page, under Integrations, select Application links.

In previous Self-hosted versions of Jira, choose Settings (the gear icon)  > Applications, and select Application Links.
 

      4. Select Create link; a Create link box pops up. Fill out the fields as follows: 

• For Jira Cloud, select Direct application link and enter https://app.smartsheet.com for the Application URL, then select Continue (or Create new link).

• For Jira Self-hosted versions 9 and above, select Atlassian product and go to https://app.smartsheet.com for the Application URL, then select Continue (or Create new link).

    5. Once prompted with one of the following messages, select Continue and keep the new URL unchanged.

• No response was received from the URL you entered - it may not be valid. Please fix the URL below, if needed, and select Continue.
  -OR-
• The supplied Application URL has been redirected once. Please check the redirected URL field to ensure this is a URL you trust. 

    6. You’ll now have a Review link or Link applications box pop up. Fill out the fields as follows:

• In the Application Name box, type Smartsheet. 
• For Application Type, accept the default value of Generic Application.
• For Jira Self-Hosted v9 and above, check the Create incoming link box.
• Select Continue.

Step 3: Edit the Application link

1. For the Application link you just created in Step 2, select the three-dot menu that appears when you hover over the Application Link or select the Edit icon (version dependent). 
2. A Configure box pops up. Select Incoming Authentication.
   
3. Fill in the fields as follows: 
   • Service Provider Name (if needed): Smartsheet
   • Consumer Name: Paste in the Consumer Name you copied from the Jira Connector in Step 1
   • Consumer Key: Paste in the Consumer Key you copied from the Jira connector in Step 1
   • Public Key/Shared Secret: Paste in the Public Key you copied from the Jira Connector in Step 1
   • Description: Add in a description as desired
   • If the Request Token URL, Access Token URL, or Authorize URL are required in your Jira environment, use this URL to populate those fields: https://api.smartsheet.com/2.0/token
4. At the bottom of the Incoming Authentication, select Save, then Close in the bottom right corner. 

Step 4: Complete the Smartsheet Jira Connection

1. Return to the Smartsheet Jira Connector configuration (should still be on the Configuration page where you copied the keys) and select Continue.
2. On the Connect screen, select Connect to complete the connection from the Smartsheet side.
3. A dialogue screen asks if you allow Smartsheet to read and write to your Jira environment. Select Allow. 

Your connection between Smartsheet and Jira is now set up! Licensed users on your account can now create workflows between items in Jira and sheets in Smartsheet. 

You can connect multiple Jira environments to your Smartsheet account with the Smartsheet Jira Connector. Repeat the above instructions for each additional Jira instance you want to register. 

Connector limitations

1. The Smartsheet Jira Connector has a maximum capacity of 20,000 rows, which aligns with Smartsheet’s row limit.
2. Limit data pulls to 10 projects at once for best performance.
3. Avoid mapping to the End Date column if Dependencies are enabled.
4. The connector will re-sort the sheet each time it runs; use reports for custom sorting.
5. Manual reordering of Jira tasks could cause errors; use Custom Grouping instead.
6. Assign tasks to Jira sprints, not Smartsheet, due to one-way connection restrictions.
7. The Jira Portfolio add-on, which introduces the Initiative issue type, is not supported.
8. You might encounter Level of Effort concerns when connecting to large project plans.
9. System-generated, unique ID and specific Project Settings columns may cause complications (one-way or no mapping) when mapping the connector.
10. Ensure you have admin or editor access on both platforms to avoid permission-related errors in workflow updates.