Setting Up Smartling Issue Management for Jira

To monitor Smartling issues in Jira, you can configure a direct integration between the two platforms.

This integration is a paid product. For pricing information, contact your Smartling Customer Success Manager.

Overview

Smartling Issue Management for Jira is compatible with both Jira Server (on-premise) and Jira Cloud. Setup involves five steps completed across both platforms, with your Smartling representative finalizing the configuration on the Smartling side.

1. Copy your Smartling Account UID (Smartling)
2. Create a dedicated Jira user for the integration (Jira)
3. Generate a Personal Access Token for that user (Jira)
4. Create a Jira webhook (Jira)
5. Send configuration details to Smartling to complete setup (Smartling)

Step 1: Copy your Smartling account UID

Your Smartling Account UID is required when configuring the Jira webhook in Step 4.

1. Log in to your Smartling dashboard as an Account Owner or Project Manager.
2. Click the Smartling logo in the top-left corner to go to your Account Dashboard.
   
3. In the browser address bar, copy the 8-character alphanumeric Account UID. It appears between /accounts/ and /account-overview/:
   
4. Save this value. You will need it in Step 4.

Step 2: Create a dedicated Jira user for the integration

The integration authenticates via a Personal Access Token (PAT), which inherits the permissions of the Jira user who created it. For security and auditability, create a dedicated Jira user solely for the Smartling integration rather than using a personal account.

Create the Jira user

1. Log in to Jira as an administrator.
2. Go to Jira Administration > User management.
3. Click Create user and fill in the required details.
   

For more information, see Atlassian's documentation on creating users.

Required user permissions

The integration user needs the following project permissions:

• Browse Projects (to get issue types, statuses, fields, issues, comments)
• Create Issues
• Edit Issues
• Transition Issues (to open/close issues)
• Add Comments
• Edit Own Comments
• Edit All Comments
• Delete Own Comments
• Delete All Comments

Grant these permissions using one of the two options below.

Option 1: Edit the permission scheme

Editing the Permission Scheme gives you the most control and limits access to only the projects you intend to integrate.

1. Log in to Jira as an administrator.
2. Go to Jira Administration > Projects and select the project you want to integrate.
3. Click Project settings > Permissions.
4. Verify that the required permissions are present for the integration user.
5. To modify permissions, click Actions > Edit permissions.
   
6. For each required permission, click Edit and add the integration user under Granted to > Single user.

Make sure the permission scheme you configure is applied only to projects you want integrated with Smartling. You can create a dedicated scheme and apply it to all relevant projects via Jira Administration > Issues > Permission schemes.

To verify permissions, use the Permission helper button on the Permission schemes page: select the user, an issue from the target project, and the permission to check, then click Submit.

See also: Atlassian's documentation on managing project permissions.

Option 2: Add the user to the Developers role

A quicker alternative is to add the integration user to the Developers role, which includes all required permissions by default.

1. Log in as a project administrator and open the project.
2. Go to Project settings > Users and roles.
   
3. Click Add users to a role.
4. In the Users or groups field, select the integration user.
5. From the Role dropdown, select Developers.
   
6. Click Add.
   

See also: Atlassian's documentation on managing project role memberships.

Optional global permission: Browse users and groups

If you want Smartling to display the original Jira author when syncing comments and status changes, the integration user also needs the Browse users and groups global permission.

This is a Jira global permission, not a project permission. It must be granted by a Jira administrator in Jira Administration > System > Global permissions.

If this permission is not granted, the integration continues to work normally. Comments and status changes will still sync to Smartling, but without author attribution.

Step 3: Generate a Personal Access Token

Log in to Jira as the dedicated integration user you created in Step 2, then follow these steps:

1. Go to your Profile page.
2. Select the Personal Access Tokens tab.
3. Click Create token.
4. Give the token a descriptive name, for example: Smartling Issues Jira Integration.
5. Optionally, set an expiry date for the token.
6. Click Create and copy the token value. You will need it in Step 5.

See also: Atlassian's documentation on Personal Access Tokens.

Step 4: Create a Jira webhook

Smartling uses a Jira webhook to receive real-time updates whenever an integrated issue changes. Without the webhook, changes made in Jira will not sync to Smartling.

See also: Atlassian's documentation on managing webhooks.

1. Log in as a user with the Administer Jira global permission.
2. Go to Administration > System:
   
3. Under Advanced, select WebHooks (you may be prompted for admin credentials):
   
   The WebHook management page appears:
   
4. Click + Create a WebHook:
   
5. Enter a name for the webhook, for example: Smartling Issues Jira Integration (account <accountUid>).
6. Set the status to Enabled.
7. Enter the following URL, replacing <accountUid> with your Smartling Account UID from Step 1. Do not modify any other variables:
   
   https://api.smartling.com/issues-jira-integration-api/v2/accounts/<accountUid>/jira-webhook?jiraProjectId=${project.id}&jiraProjectKey=${project.key}&jiraIssueId=${issue.id}&jiraIssueKey=${issue.key}&jiraCommentId=${comment.id}
8. Set an event filter using JQL to limit events to only the Jira projects you are integrating with Smartling. For example:
   
   
   Click the Syntax help button in Jira or consult the JQL documentation for help writing queries.
9. Under issue events, select all of the following:
   
   • Issue updated
   • Issue deleted
   • Comment created
   • Comment updated
   • Comment deleted
10. Leave Exclude body unchecked, then click Create:
    
    

Step 5: Send configuration details to Smartling

Once you have completed Steps 1–4, send the following information to your Smartling Customer Success Manager. The Smartling team will use this to map your translation projects to the appropriate Jira projects and finalize the integration.

• Jira server URL: the publicly accessible URL of your Jira instance (for example, https://mycompany.atlassian.net).
• Personal Access Token: the token you created in Step 3.
• Integration user email address: required for Jira Cloud only.
• Jira project key(s): the keys of the Jira projects to integrate.
• Smartling project mapping: which Smartling projects should connect to each Jira project key. For example: Jira project LOC connected to Smartling ProjectA and ProjectB; Jira project DEV connected to Smartling ProjectC.
• Issue type mapping: the Jira issue type name to use for Smartling SOURCE and TRANSLATION issue types. The same Jira issue type is often used for both.
• Workflow status mapping: the Jira workflow status names that correspond to Smartling's OPENED and RESOLVED statuses.

• Jira field mapping: how the Jira ticket summary and description fields should be populated. You can use any of the Smartling issue fields listed below. For example:
  
  Summary: Issue from {reporterFullName} for string {stringHashcode}
  Description:

  Smartling issue opened by _{reporterFullName}_ in project [{projectName}|{projectLink}] with text:
  {issueText}
  
  *Source string*: [{sourceString}|{sourceStringLink}]
  *Job*: [{jobName}|{jobLink}]
  *File Uri*: {fileUri}

• Required Jira fields: any additional mandatory Jira fields and the values that should be used when the integration creates new issues (for example, a Budget field with a fixed option).

Smartling can map additional fields as needed. Ask your Smartling representative to share any additional field requirements with the Smartling team.

Smartling issue fields reference

The following fields are available for use in your Jira field mapping configuration (Step 5). Use the field token (left column) in your mapping templates.

Jira API endpoints used by the integration

The table below lists all Jira API endpoints called by the Smartling integration and the permission each one requires. This is for reference only and is not required for setup.

Changing the configuration

To update the integration configuration — such as adding a new Jira project, adjusting field mappings, or changing the webhook — contact your Smartling representative.

Removing the integration

Follow these steps in order to safely remove the Smartling–Jira integration.

1. Contact your Smartling Customer Success Manager

Notify Smartling first so the team can disconnect the integration on the Smartling side and stop API calls to your Jira instance.

2. Disable the integration Jira user

Disable the dedicated Jira user account used for the Smartling integration. 

3. Delete the webhook

Delete the Smartling webhook to stop Jira from sending events to Smartling.

1. Log in as a user with the Administer Jira global permission.
2. Go to Administration > System.
3. Under Advanced, select WebHooks.
4. Find the webhook whose name contains your Smartling Account UID, then click Delete:
   
5. Confirm the deletion.