SoftSync Configuration

SoftSync Configuration

You installed the application successfully, and now it’s time to configure it. You must be logged in to Jira as an admin, then click on the ‘Configure’ button.

 
Image 4: Configuring the application

4.1 Teamwork Integration Setup

Once you clicked on the ‘Configure’ button, you’ll be redirected to a connection page, where you will enter your Teamwork authentication details.
 

Image 5: Teamwork Connection

Here are the authentication details that you should provide:

1. Teamwork subdomain URL:  you should enter the subdomain for your Teamwork account. Usually, this subdomain URL is username.teamwork.com or companyname.teamwork.com.

 
Image 6: Entering Teamwork subdomain URL

2. Teamwork API Key: To get your Teamwork API key, you must be logged in to your Teamwork account with the user you created initially, which you named “Jira-Teamwork Integration Tool”. Click on the profile icon on the top right corner of your screen, where you’ll see your account’s details. Then, click on ‘Edit My Details’:

 
Image 7: Teamwork panel details

3. Go to the tab API & Mobile, then click on the button ‘Show Your Token’. Once you see your token, you can copy it to your clipboard.
 

Image 8: Teamwork API token screen

4. Copy your API token, go back to the integration authentication page and paste it into the required field.

If you need help finding your Teamwork API key, please read: Locating Your API Key.

NOTE: Your company team members should not use this account since it only serves to integrate Jira and Teamwork. You should not turn off the API key for this account; otherwise, synchronization will stop working.

5. Please read the license agreement and privacy policy carefully. Once you finished reading it, click ‘I agree’ to continue the installation.
 
Image 9: License Agreement and Privacy Policy

6. Once you click ‘Proceed’, the application will validate the data you entered. However, you may see an error message if the API token you used is from an account that does not have admin rights. If this is the case, you must ensure that this account has admin rights and access to all projects.

7. If there are no validation errors, the application will ask you to confirm access to your account. The access needed includes reading projects and reading/modifying your tasks and their details. If you agree with these, please click ‘Grant access’. If you disagree, the application will not work correctly. 

 
Image 10: Granting access to projects and tasks

4.2 Synchronization Setup
Once the connection with Teamwork is all set, here are the next steps to follow:

1. Defining synchronization settings.
2. Setting up the initial synchronization.

You can only skip the synchronization settings after you define the status mapping settings. If you try to skip without defining the mapping, SoftSync will show you an error message.

4.2.1 General Settings Configuration

The SoftSync’s general settings configure how you want it to synchronize data between Jira and Teamwork. These settings include:

1. Synchronization Type  the default value is ‘Two Way’ Sync. This setting means that the data is synchronized in both directions. 

• Two Way Sync: the app synchronizes data in both directions: from Teamwork to Jira and from Jira to Teamwork.
• One Way Sync: you can choose if you want the application to only synchronize data from Teamwork to Jira or from Jira to Teamwork.

2. Source Platform  if you choose Two Way Sync, you should decide which application will be the main source for synchronization if there are inconsistencies in data in Teamwork or Jira.

 
Image 11: Choosing synchronization settings and source platform

3. Direction for One Way Synchronization  if you choose One Way Sync, you should decide which will be the synchronization source.

• Sync Jira to Teamwork
• Sync Teamwork to Jira
 
4. User Synchronization  in this setting, you can decide if the users should also be synchronized between the sources or not.

• If the users are not synchronized, the application will not update the following properties related to users:

i. Watchers/followers
ii. Reporter – in this case, the plugin user is used.
iii. Assignee – in this case, ‘Unassigned’ value is used.

• If the users are synchronized, but a user is not found in the target application, SoftSync will use the same rules as in the section above.

NOTES:
• Teamwork supports multiple assignees for a task. However, Jira supports just one assignee per task. 
• The first assignee from Teamwork will be synchronized as a Jira assignee. The other assignees on Teamwork will be defined as watchers for Jira. 
• The watchers should be synchronized with the Teamwork task, as well as followers.

 
Image 12: Setting up user synchronization

NOTE: For the first version, if a user is not found in the target platform, SoftSync will not invite them to the application. We will implement this automatic invitation in a future version. The possibility to create a separate Jira Ticket for each Teamwork assignee is also a feature coming soon.


5. Automatic Project Creation Settings  in this setting, you can decide if projects should be automatically created in the target platform and linked to their source when created.

• Based on the synchronization type: Two Way/One Way, you must set up the required fields for the project creation for the target platform; if it is Two Way, for both of them, if it is One Way, only for one of them.

i. Jira requires a project name, project type (Classic or Next-Gen if supported), and a project template.
ii. Teamwork requires a project name and project company.

• Automatically link Jira with Teamwork project by name  if this is enabled, once you create a new project, the application will search by name in the target platform. If the application finds a project with the same name, it will link them and start the sync. If the application doesn’t find a project with the same name, it will create a new project if this setting “automatic project creation” is enabled.

 
Image 13: Setting up project synchronization


NOTE: While Jira has custom statuses and priorities, Teamwork has a fixed list of statuses and priorities:

• Statuses:
o Open
o Completed

• Priorities:
o None
o Low
o Medium
o High

To correctly synchronize statuses and priorities between Jira and Teamwork, there are some configurations that you should adjust – Status Synchronization and Priority and Status Mapping – and we’ll explain those in detail below.


6. Task Statuses synchronization  in this setting, you can decide which statuses to synchronize between Teamwork and Jira. SoftSync allows you to get the full list of custom statuses from Jira.  In the Status mapping, the selected statuses for sync from Jira are displayed, and you can map it with the Teamwork statuses.

 
Image 14: Choosing task status to sync.


7. Priority and Status Mapping  you should define the mapping between Teamwork and Jira priorities and statuses to properly support the sync. 

If a new priority is added after that in Jira, it will be mapped with the value ‘None’ in Teamwork until you define the mapping. In Jira, it will use the first Jira priority. If a new status is added in Jira, it will not be selected for sync automatically. You’ll have to go to general settings, select this status, and then define the mapping between Jira and Teamwork status. The application will still sync the ticket with the new status, using Open status for Teamwork. You can have multiple Jira values mapped to a single Teamwork value. In future versions, you’ll be able to update the map view with the default setup as well.

For example, if you have priorities in Jira set as ‘Highest’ or ‘High’, these will be mapped as ‘High’ in Teamwork. You will have a default mapping setup, and you can choose which one. By default, it is the first map defined, but you can update it.

When a task is created in Teamwork with ‘High’ priority, it will use the default map defined for ‘High’; it can be ‘Highest’ or ‘High’ in Jira, depending on which one you chose as default.

1. If you remove the priority from the Jira level, and Jira automatically updates the matching issues with another status, SoftSync will not trigger Jira's priority synchronization to Teamwork.
2. If Teamwork's priority is set as None and is not mapped with any Jira priorities, SoftSync won’t use the default Jira priority for the task. The application takes the first by id for now, and we will improve this feature in future updates.

SoftSync will have an updated user interface in the future to reflect the default defined mapping.

1. SoftSync uses the first status of the workflow if the default status defined in the mapping between Teamwork and Jira is missing.
2. If you don’t select the done/complete tasks for synchronization, SoftSync will not trigger the status change to done/complete or from done/complete in the target application.


 

 
Image 15/16: Defining priority and status mapping.

4.2.2 Initial synchronization

The initial synchronization is the stage where you decide which Jira projects you want to synchronize with Teamwork projects and the properties for project maps. You can also skip this step and run it at a later stage.

The initial synchronization can take some time depending on the number of task lists, tasks, and sub-tasks you have to synchronize. We highly recommend performing the initial sync during non-working hours and notifying the teams not to use Jira and Teamwork projects during synchronization. 
4.2.2.1 Project mapping

SoftSync will get all the existing projects from Jira and Teamwork, allowing you to define the mapping between both. It will automatically suggest values for Teamwork projects if the names match. On the drop-down menu for each project, you can select the corresponding project on the other application.

You can also exclude projects you don’t want to synchronize. Simple click the remove button of the project you wish to exclude. You can remove projects in bulk by using the checkbox, selecting the projects, and clicking ‘Exclude Selected’.

 
Image 17: Setting up initial project synchronization


The map definition is a required step. The list of projects that should not be synchronized should be just excluded from the synchronization. If you accidentally removed a project, you can add it again. Please refer to the section Projects List or details. 

4.2.2.1 Project Synchronization Settings

You can have set up synchronization settings for the list of selected projects. You can enable or disable the following list of properties:

1. Project Description  if this option is enabled, SoftSync will synchronize the project description.

2. Issue Type  You can choose to sync all issue types or only selected issue types. However, in Teamwork is not possible to customize types; it only supports task lists, tasks, and sub-tasks. In Jira, you can customize the types, and here you can set up which types you need to sync. For example: it syncs only epics, tasks, or improvements. 

NOTE: In Teamwork, a Task list equals an EPIC in Jira. If the EPIC is missing in the project, Teamwork will have new task lists with names:

JIRA BASIC - %issueType%  example ‘JIRA BASIC’ – TASK or ‘JIRA BASIC – BUG’. It means that all bugs will be grouped under the Task List ‘JIRA BASIC - BUG’, and tasks under the Task List ‘JIRA BASIC - TASK’.

When creating classic projects in Jira, please note:

You must select the Epic Name and the Epic Link in the create/edit screens. If the Epic Name is missing, the Epic will not be created. If the Epic Link is missing, the Epic parent will be set for the task.

Learn more about Epic Name vs Epic Link on Jira Knowledge Base.

3. Issue Type Properties  in this setting, you can define which properties you want to sync between the two platforms.

• Key  by default selected and disabled.
• Type  by default selected and disabled.
• Priority  by default selected and disabled.
• Summary  by default selected and disabled.
• Reporter  by default selected and disabled.
• Assignee  optional. If it’s not selected, the value will be Unassigned.
• Estimated Time  optional. You can decide if you need to sync the estimated time or not.
• Time Log  optional. It requires permission from both Jira and Teamwork. If it’s disabled, time logs will not be synchronized.
• Due Date  optional. It requires permission from Jira. If it’s disabled, due dates will not be synchronized. 
• Comments  optional 
• Attachments  optional.
• Status  optional.
i. Teamwork supports only Open and Completed statuses, while Jira supports custom statuses.
ii. For the status synchronization on Teamwork, SoftSync will create a custom field: JIRA_STATUS, which will get all the statuses from the corresponding Jira project and update the custom field value in Teamwork based on the Jira Status change.
 
Image 18: Setting up project synchronization

NOTE: To sync time logs between Teamwork and Jira, you must enable permissions for time logs in both platforms. In Teamwork, you should go to the Project  Settings  Project Features  Then make sure that ‘Time’ is enabled. 

 
Image 19: Setting up time logs synchronization

In Jira, this configuration depends on the type of project that you’re integrating. If it’s a Classic Project, you must follow these instructions from Atlassian. If it’s a Next-Gen Project, you need to select your project under Project Settings  Issue Types and then select Time Tracking for each issue type you want to synchronize time log. 

 
Image 20: Setting up time tracking synchronization

    • Related Articles

    • SoftSync Synchronization Management

      5.1 Projects List Once you finished setting up the integration, the first thing you’ll see is the Projects List page. This page lists: 1. Linked projects 2. Unlinked projects    Image 21: Project Links page On the Project List page, you can: 1. ...

    • Introduction to SoftSync

      Welcome to the SoftSync user guide. In this guide, you will understand the requirements for installation, how to configure your application correctly, how to synchronize your projects, as well as other frequently asked questions. What is SoftSync? ...

    • SoftSync Application Requirements

      2.1 Account To synchronize Jira and Teamwork using SoftSync, you must create a new admin account in Teamwork, and this account should not be used for other purposes. For ease of use, you can name it “Jira-Teamwork Integration Tool” or something ...

    • SoftSync Installation

      To be able to install SoftSync, you must have global administrator permission on the Jira System. There are two different ways you can install SoftSync: via the Atlassian Marketplace or Jira Plugin Manager. 3.1 Installation via Atlassian Marketplace ...

    • SoftSync Limitations

      6.1 SoftSync V1 Limitations Because SoftSync is still in its first version, the application has some limitations on its functionalities. Although these limitations should not impact your usage, we are aware of them, and we plan to address them in ...