Setting Up Smartling Issue Management for Jira

 

If you would like to monitor Smartling Issues in Jira, a direct integration between the two platforms can be configured.

Please note that this integration is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.

Prerequisites and configuration steps

Smartling Issue Management for Jira can be configured for Jira Server (on premise) and Jira Cloud.

To get started, please reach out to your Smartling representative, who can set up the integration between Smartling and Jira. During the configuration process, you will be asked to complete these steps:

• Step 1: Log into your Smartling account. From there, you will need to copy your Smartling Account UID.
• Step 2: Create a dedicated Jira user account for the Smartling integration.
• Step 3: Generate a personal access token for the Jira user.
• Step 4: Configure a Jira WebHook to enable communication between the two platforms.
• Step 5: Your Smartling representative will then be able to complete the configuration.

By completing these configuration steps, you can seamlessly integrate Smartling and Jira for streamlined workflow and improved collaboration.

 

Step 1: Copy your Smartling Account UID

1. Login to your Smartling dashboard as an Account Owner or Project Manager.
   
   
2. Click on the Smartling logo in the top left corner to navigate to your Account Dashboard.
   
   
   
3. From the browser address bar, copy the Account UID, which consists of 8 alphanumeric characters. The Account UID is located between “/accounts/” and “/account-overview/”:
   
   
4. Keep this Smartling Account UID on file for now, as it will be needed in step 4.

 

Step 2: Create a dedicated user account in Jira 

To connect Smartling with a Jira server, you have to generate a Personal Access Token (PAT) for a Jira user. Because PAT works on behalf of the user who created it and has the same permissions level, we recommend creating a dedicated Jira user account for the Smartling integration.

Create a Jira user

To create a Jira user for the Smartling integration, follow these steps:

1. Login to Jira as an administrator user.
2. Choose User management from the Jira Administration menu.
3. Click Create user.
4. Provide the necessary information and click Create user.
   

Tip: For more information, see the documentation provided by Jira.

 

User permissions

To function properly, Smartling's integration requires certain permissions to be granted to the used personal access token. The permission level of personal access tokens is set to the level of access that the Jira user currently has. Therefore, the dedicated Jira user for the Smartling integration needs to be granted all of 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

To grant these permissions to the Jira user for the Smartling integration, you have two options:

Option 1: Edit Permission Scheme

You can grant Smartling's integration access by editing the Permission Scheme used by your localization project(s). This process consists of several steps, but ensures maximum security. Alternatively, you can check option 2 for an alternative approach.

To view and configure the necessary project permissions, follow these steps:

1. Login to Jira as an administrator user.
2. Choose Projects from the Jira Administration menu.
3. Select the Jira project you want to connect with Smartling.
4. Click Project settings.
5. Select Permissions tab.
6. Ensure that the required permissions listed above are granted to the Smartling integration Jira user.
7. To modify permissions of the project permission scheme, click Actions and then Edit permissions.
   
8. Grant the permissions listed above for the Smartling integration Jira user by clicking on the Edit links and choosing the user for the Single user option under Granted to.

Make sure that the permission scheme you have configured is used only by the projects you want to integrate with Smartling. You can create a separate scheme and use it for all required projects. The list of all permission schemes can be found by choosing Issues from the Jira Administration menu and selecting Permission schemes tab.

Tip: For more information, visit the documentation provided by Jira.

You can check permissions also by clicking on the Permission helper button on a permissions scheme page:

1. Select the user in the User field
2. Select an Jira issue for the Jira project you want to integrate with Smartling in the Issue field
3. Select the required permission in the Permission field
4. Click Submit

Option 2: Edit project Users and Roles

An alternative way to grant the required permissions to the Smartling integration Jira user is to to add the user to the Developers role:

1. Log in as a project administrator and open your project.
2. Select Project settings > Users and roles.
   
   
3. You'll see all users and groups associated with each project role.
4. Click the Add users to a role button.
5. Select the user that you created for the Smartling integration in the Users or groups field.
6. From the Role dropdown, select the Developers role.
   
7. Click the Add button.
   

Tip: You can find more information in the documentation provided by Jira.

 

Step 3: Create a personal access token for the Jira user

After having created a Jira user with the required permissions for the Smartling integration, you can create a personal access token:

1. Login to Jira using the dedicated user account you created in step 2.
2. Go to the Profile page in Jira.
3. Select the Personal Access Tokens tab.
4. Click Create token.
5. Give your new token a name, e.g. Smartling Issues Jira Integration.
6. Optionally, for security reasons, you can set your token to automatically expire after a set number of days.
7. Click Create.

Tip: For more information, see the documentation provided by Jira.

 

Step 4: Create WebHooks in Jira

Smartling needs to use Jira WebHooks in order to stay up-to-date with any changes that are made to Jira issues. By creating a webhook, you enable this synchronization between Jira and Smartling.

Tip: More information about Jira Webhooks can be found here.

1. Log in as a user with the Administer Jira global permission.
2. Choose Administration > System:
   
3. Select WebHooks from the Advanced menu, (you may be asked for admin credentials as well):
   
   
   You will now see the WebHook management page:
   
   
   
4. Click the + Create a WebHook button.
   
   
   
5. Enter WebHook name, e.g. “Smartling Issues Jira Integration (account <Smartling accountUid>)”.
6. Set the status to Enabled.
7. Enter this WebHook URL: 
   
   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}
   
   Make sure to substitute “<accountUid>” with your Smartling account UID.
   Please don’t update any other variables in the URL. For, example the “${project.id}” should be left untouched.
   
   
8. Set an event filter to send events only to specific Jira projects. Only Jira projects that will be integrated with Smartling should be specified. To filter issues, you must use a Jira Query Language (JQL) query.
   Here are some examples of how to filter issues based on the project:
   
   
   
   To get help writing JQL, click the "Syntax help" button. For more information, consult the JQL.
9. Select issue events that Smartling will listen for:
   • Issue updated
   • Issue deleted
   • Comment created
   • Comment updated
   • Comment deleted

10. Keep the Exclude body option unchecked and click the Create button
    
    
    

Step 5: Contact Smartling to complete the configuration

The configuration of the Smartling integration can then be completed by the Smartling team. During this last step, your Smartling translation projects will be mapped to the Jira projects where you would like to track any issues.

Please send the following information to your Smartling Customer Success Manager:

• Jira server URL:
  This is the publicly available URL of your Jira instance (e.g. https://mycompany.atlassian.net).
• The personal access token you created in step 3.
• If you use Jira Cloud, then also provide the integration user email address.
• Jira project key(s) to integrate with.
• A list of Smartling projects that should be integrated with each Jira project key.
  For example, Jira “LOC” should be connected with Smartling ProjectA and ProjectB. Jira “DEV” should be connected with Smartling ProjectC.
• Jira <-> Smartling issue type mapping: Jira issue type name for Smartling SOURCE and TRANSLATION issue types. It’s common to use the same Jira issue type for both Smartling issue types.
• Jira <-> Smartling workflow status mapping: Jira workflow status names for Smartling OPENED and RESOLVED issue statuses.
• Jira fields mapping - how the Jira ticket summary and description fields should look like.
  The integration provides a variety of Smartling Issue fields that can be used in the configuration. Please see “Smartling Issue Fields” for a list of available fields. For example, the Jira “summary” could be:
  Issue from {reporterFullName} for string {stringHashcode}
  and “description”:
  Smartling issue opened by _{reporterFullName}_ in project [{projectName}|{projectLink}] with text:
  {issueText}
  
  *Source string*: [{sourceString}|{sourceStringLink}]
  *Job*: [{jobName}|{jobLink}]
  *File Uri*: {fileUri}
• List of required Jira fields and how they should be filled. For example, your Jira issue may require a "Budget" field (which includes a list of options). Tell us which option should be used for all new Jira issues created by the integration.
• We can map further fields as required. Please feel free to discuss this with your Smartling representative. 

Smartling Issue Fields

Please see below a list of fields that are recorded in Smartling for each issue. These fields can be mapped to your Jira issues as required.

• issueCategory = "Category"
• issueText = "Issue description"
• sourceString = "Source string"
• sourceStringLink = "Source string link"
• translatedString = "Translated string"
• translatedStringLink = "Translated string link"
• reporterFullName = "Reporter"
• resolverFullName = "Resolver"
• jobUid = "Job UID"
• jobName = "Job name"
• jobDescription = "Job description"
• jobDueDate = "Job due date"
• jobLink = "Job link"
• fileUri = "File Uri"
• namespace = "Namespace"
• variant = "Variant"
• tags = "Tags"
• projectUid = "Smartling project UID"
• projectName = "Smartling project name"
• projectLink = "Smartling project link"
• stringHashcode = "String hashcode"
• stringLocale = "String locale"
• createdDate = "Created date"
• severity = "Severity"

Jira endpoints used by the Smartling integration

The table below lists all API endpoints used by the Smartling integration, along with the Jira permissions required for each endpoint. This information is for reference only and is not necessary for configuring the integration.

 

Changing the configuration

If any changes to the configuration are needed, please reach out to your Smartling representative.

Removing the Smartling integration from Jira

The steps below are only necessary if you want to remove the integration between Smartling and Jira.

1. Contact your Smartling representative 

If you want to stop using the integration, contact your Smartling Customer Success Manager first. The Smartling team will disconnect the Smartling integration from your Jira server (to stop using the Jira API).

2. Disable the integration Jira user

Disable the Jira user account used for the Smartling integration.

3. Delete the WebHook

Remember to delete the Smartling integration WebHook after disconnecting Smartling from your Jira server.

1. Log in as a user with the Administer Jira global permission.
2. Choose Administration > System.
3. Under the Advanced section, select WebHooks (you may be additionally asked to provide admin credentials).
4. Find a WebHook with a name that includes the specific Account Uid, select it from the list, and then click the Delete button.
   
5. Confirm the WebHook deletion.