Learn how to use Softsync and integrate Jira and Teamwork
How to syncronize Jira and Teamwork:
Welcome to the SoftSync user guide.
Welcome to the SoftSync user guide. In this guide, you can review 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 is an application to easily view, track and update your projects across platforms, no coding needed! Communication across departments can be limited by the tools each department uses. It’s time to remove the barriers in your workflows. SoftSync is a powerful application that helps you synchronize projects, tasks and user activities between Jira Cloud and Teamwork. Connect your project data and boost your team’s efficiency with seamless automation.
1.1 Browser compatibility
To be able to use SoftSync properly, you must have a compatible browser installed on your desktop computer. SoftSync supports all the desktop browsers compatible with Jira Cloud. This includes the latest released versions of Microsoft Edge, Mozilla Firefox, Google Chrome, and Safari.
Currently, SoftSync is not compatible with mobile browsers.
For detailed information, see Atlassian Jira Cloud Supported Browsers.
1.2 Cookies Permission
SoftSync uses browser cookies to provide users with a better experience. In order to navigate and use our application, your browser must allow websites to store cookies.
1.3 Jira Platform Support
SoftSync is currently only available for Jira Cloud.
Please contact us if you are currently on Jira Server and interested in integrating it with Teamwork through SoftSync.
2.1 Account
To synchronize Jira and Teamwork using SoftSync, you must create a new admin account in Teamwork. This account should not be used for other purposes. For ease of use, you can name it “Jira-Teamwork SoftSync Integration” or something similar. When creating this new account, make sure to configure it as an “Administrator”. This account will be used by SoftSync for synchronization in Teamwork.
You should not delete or downgrade the permissions for this account to ensure that the sync continues to work as expected.
2.2 Webhooks
To ensure the synchronization between Teamwork and Jira works, you must enable webhooks in your Teamwork account. Log in to your Teamwork account and find the tab Webhooks under the Settings menu.
Ensure webhooks are enabled. This will allow for Softsync to enable syncing with Teamwork.
To install SoftSync and integrate Jira and Teamwork, you must have global administrator permission on the Jira System. There are two different ways you can install SoftSync: the Atlassian Marketplace or Jira Plugin Manager.
3.1 Installation via Atlassian Marketplace
- In the Atlassian Marketplace page, type SoftSync into the search. You can also click on this link: SoftSync – Jira Teamwork Integration. This link will take you directly to the application page.
- Once you are on the SoftSync application page, you can install the application. You can try our 30-day free trial or purchase it right away.
- Log in to your Jira account and proceed with installing the application.
3.2 Installation via Jira Plugin Manager
Log in to your Jira account, then click on the gear icon on the top corner of your screen, and you’ll see the Jira Administration menu.
Click on Applications.
3. Once you’re on the Application marketplace, type SoftSync into the search bar.
4. You can either purchase the application or start a 30-day free trial.
Congratulations! You have successfully installed SoftSync. Now it’s time to configure it.
You must be logged in to Jira as an admin. Now click on the ‘Configure’ button.
We strongly recommend you to backup all your data in Teamwork and Jira before configuring SoftSync. Learn more about Teamwork backups. Learn how to back up your data in Jira. SoftSync does not create or store any backups. You are responsible for the safety and integrity of your data.
4.1 Teamwork Integration Setup
Once you click on the ‘Configure’ button, you’ll be redirected to a connection page. Here we will make a connection with Teamwork. You will need your Teamwork authentication details.
Here are the authentication details that you will 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
2.
Teamwork API Key: To get your Teamwork API key, you must be logged in to the Teamwork admin account you created for SoftSync. Please refer to section 2.1 Account for more details. Click on the profile icon at the top right corner of your screen, where you’ll see your account’s details. Then, click on ‘Edit My 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.
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.
5.
Please read the license agreement and privacy policy carefully. Once you have read it, click ‘I agree’ to continue the installation.
6.
Once you click ‘Proceed’, the application will validate the data you entered. You may receive an error 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, SoftSync will not work.
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
4.2.1 General Settings Configuration
SoftSync’s general settings help you configure how to synchronize data between Jira and Teamwork. These settings include:
1.
Synchronization Type – This setting allows you to configure the direction for synchronizing your projects.
- Two Way Sync: the application 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
The default value is Two Way Sync.
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.
The default value is Jira.
3.
Direction for One Way Synchronization – If you choose One Way Sync, you should decide which will be the synchronization source. The default is “Sync Jira to Teamwork”.
- Sync Jira to Teamwork
- Sync Teamwork to Jira
4.
Users Synchronization – In this setting, you choose to synchronize users.
If the users are not synchronized, or a user is not found in the target application, SoftSync will not update the following properties related to users:
- Watchers/followers
- Reporter – SoftSync will use the SoftSync API key in Jira, the account used for integration in Teamwork.
- Assignee – ‘Unassigned’ value is used.
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. Currently, SoftSync does not automatically create users in Jira or Teamwork if not found.
Ref: Known Issues 6.1.2.14.
5.
Automatic Project Link Creation Settings – In this setting, SoftSync will search for the source project by name in the target platform. If SoftSync finds a project with the same name in the target platform, it will automatically link them and start the sync. If SoftSync doesn’t find a project with the same name, a new project will be created if the “Automatic Project Creation Settings” is enabled, as described below.
6.
Automatic Project Creation Settings – In this setting, a project will be automatically created in the target platform. When selected, set up the required fields for the project created on the target platform.
Jira requires a project name, project type (Classic or Next-Gen if supported), and a project template.
Teamwork requires a project name and project company.
If you chose two-way synchronization, then you will need to set this for both Jira and Teamwork.
7.
Task Statuses synchronization – In this setting, you can decide which statuses to synchronize in Teamwork and Jira. While Jira has custom statuses, Teamwork has a fixed list of statuses. To correctly synchronize statuses between Jira and Teamwork, you will need to indicate the Task Statuses you wish to synchronize.
SoftSync provides you with the full list of custom statuses from Jira. You can now select which statuses in Jira you wish to synchronize.
If you disable the ‘Done’ or ‘Completed’ statuses, then SoftSync will not trigger the sync for that task when it’s status changes ‘Done’ or ‘Completed’. We recommend leaving these statuses checked.
NOTE: Since Jira supports dynamic status, SoftSync will create a custom field: JIRA_STATUS, which will import all the statuses from the corresponding Jira project. This field will then sync the current status from Jira in Teamwork for the task/subtask. This field is also editable in Teamwork.
8.
Priority Mapping – In this setting, you will define the mapping between Teamwork and Jira priorities.
While Jira has custom priorities, Teamwork has a fixed list of priorities. To correctly synchronize priorities between Jira and Teamwork, you will need to define the mapping between Teamwork and Jira.
Adding a new custom priority to Jira:
If a new custom priority is added later in Jira, it will be mapped with the value ‘None’ in Teamwork until you define the mapping. If a Teamwork priority is not mapped to a Jira priority, then SoftSync will map to the first priority in Jira. Ref: Known Issues 6.1.1.18
Multiple Jira priorities mapped to Teamwork
You can have multiple priorities in Jira mapped to the same priority in Teamwork. As shown in Image 15, Jira priorities ‘Highest’ and ‘High’ are both mapped to Teamwork priority ‘High’.
When a task is created in Teamwork with ‘High’ priority, SoftSync will use the default map and create the task in Jira with the priority ‘High’ based on the default mapping. You can update the default map that is set by SoftSync.
Removing Jira priorities
If a custom priority is removed later in Jira, SoftSync should update Teamwork with the new priority.
If Teamwork’s priority is set as None and is not mapped with any Jira priorities, SoftSync will map to the first Jira priority by id.
9.
Status Mapping – In this setting, you will define the status mapping between Teamwork and Jira.
Jira supports multiple custom statuses, such as In Progress, Backlog, To Do, and others. Teamwork, on the other hand, only supports the statuses Open or Completed. To sync the statuses correctly between platforms, you must define the status mapping. If the default status is missing in the project you sync (because projects can have different statuses as well), then SoftSync will use the first status of the workflow. Ref: Known Issues 6.1.2.15.
You can skip the synchronization settings once you define the status mapping settings. Without this mapping, SoftSync will show you an error message.
Adding a new custom status to Jira
If you add a new custom status later in Jira, it will not be selected for sync automatically. You must go to the Status Mapping Settings, select this status for syncing, and then define the mapping.
4.2.2 Initial synchronization
The initial synchronization allows you to select the projects you want to synchronize across Jira and Teamwork.
The initial synchronization can take hours 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.
You can skip this step and run it at a later stage.
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 a Teamwork project name if the names match. In the drop-down menu for each project in Jira, you can select the corresponding project in Teamwork.
You can also exclude projects you don’t wish to synchronize. Simply click the “Exclude” button. You can remove projects in bulk by selecting multiple projects using the checkbox and clicking ‘Exclude Selected’.
Defining project mapping is not a required step for initial sync; you can skip it and do it later. 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 section 5.1 Projects List or details.
4.2.2.2 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 – In this setting, SoftSync will synchronize the project description.
2.
Issue Type – In this setting, you can sync all issue types or only selected issue types. In Teamwork, you cannot customize the Issue type. Teamwork only supports task lists, tasks, and sub-tasks. In Jira, you can customize the Issue type. You can set up which types you want to sync.
Teamwork requires you to have tasks under a task list, but Jira allows you to have issues without an Epic. To make it easier for syncing tasks and issues between task lists and Epics, SoftSync understands Epics from Jira as task lists from Teamwork. If the Epic exists, SoftSync will sync task lists from Teamwork into Epics in Jira, as well as its tasks and subtasks.
However, if the Epic for an issue type does not exist in your Jira project, Teamwork will have a custom task list created with all the tasks from Jira without Epics. Each issue type with at least one task in Jira will trigger a custom task list on Teamwork, named under the Jira ticket type, with the bugs or tasks under it.
The naming convention used is “Missing Epic – %IssueType%”. For instance, all bugs that don’t belong to an Epic will be moved to a task list “Missing Epic” in Teamwork.
Please note that if the Epic name is missing in the create screen for the Jira Classic Project, SoftSync will not create an Epic. Also, if the Epic link is missing, SoftSync will not define a link between the child and Epic. Ref: Known Issues: 6.1.2.13.
Learn more about Epic Name vs. Epic Link on Jira Knowledge Base.
3.
Issue Type Properties – In this setting, you define which properties 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.
- Time Log → optional. It requires permission on both Jira and Teamwork. If it’s disabled, time logs will not be synchronized.
- Start Date and Due Date → optional. It requires permission from Jira. If it’s disabled, start and due dates will not be synchronized
- Comments → optional.
- Attachments → optional. Note: If you select attachments to be synchronized, please ensure that you have enough storage space available in your Teamwork and Jira accounts.
- Status → optional. Please refer to section 4.2.1.7 Task Status Synchronization. Teamwork supports only Open and Completed statuses, while Jira supports custom statuses.
To sync time logs between Teamwork and Jira, you must enable permissions for time logs in both platforms.
In Teamwork, go to the Project → Settings → Project Features → Enable ‘Time’. See screenshot below.
In Jira, this configuration depends on the type of project that you’re integrating. If it’s a Classic Project, follow these instructions from Atlassian. If it’s a Next-Gen Project, select your project under Project Settings → Issue Types → For each Issue Type → select Time Tracking. See screenshot below.
Once you have installed the SoftSync plugin and completed the setup, you can review the settings and make any changes by visiting General Settings, as shown in Image 21.
5.1 Projects List
Once you complete the Synchronization Setup, you’ll see the Projects List synchronization management page. Image 22 shows –
Linked Projects
Unlinked Projects
On the Project Links page, you can:
•
Manually link a new project at any time. Please refer to 5.3 Link Project.
Configure project links that you already defined. Please refer to 5.5 Configure Link.
Remove project links by clicking on the Unlink button. Please refer to 5.6 Unlink.
Track activity within projects using the Export Log feature. Please refer to 5.7 Export Logs.
5.2 Project General Settings
When you need to update or manage general project settings, you can do this by clicking on the General Settings menu. In the General Settings, you can define the default settings used for each project.
These settings are similar to the ones you set up during Initial Synchronization. See section 4.2.1 General Settings Configuration for reference.
NOTE: If the automatic option for project synchronization is set, SoftSync will automatically know which data to sync. If you choose to manually create the link, SoftSync will use the default setup, allowing you to update settings.
Please note that changing any of the general setting’s details will trigger initial synchronization for all the linked projects. This synchronization may take hours, depending on the number of tasks, task lists, and sub-tasks.
You can choose to apply changes to new requests. In this case, SoftSync will save the project synchronization configuration changes but will not re-synchronize the already linked projects.
5.3 Link Project
You can manually link an additional project at any time. Simply click on the Link action from the Unlinked projects list. You’ll see the same settings as you would during initial synchronization. Here’s what you’ll need to do:
Define which Teamwork project should be linked to Jira
Select the issue types you want to sync
Select the issue types properties you want to sync for this specific project
Each project can have different synchronization settings.
5.4 Bulk Link
Bulk Link is located above the Unlinked projects. It allows you to select a list of projects you want to synchronize and define the synchronization settings. It works similarly to the 4.2.2 Initial Synchronization. It automatically filters out the projects that are already linked.
5.5 Configure Link
By clicking on ‘Configure Link’, you can change the chosen link’s synchronization settings in the same way as explained in 4.2.2.2 Project Synchronization Settings.
Please note that changing any of the general setting’s details will trigger initial synchronization for all the linked projects. This synchronization may take hours, depending on the number of tasks, task lists, and sub-tasks.
You can choose to apply changes to new requests. In this case, SoftSync will save the project synchronization configuration changes but will not re-synchronize the already linked projects.
5.6 Unlink
You can remove the link between Teamwork and Jira projects at any time. Click on ‘Unlink’, and SoftSync will ask you for confirmation. If you remove the link, no other data is synchronized between platforms.
5.7 Export Logs
You can track the activity for each project at any given time by using the feature Export Logs under the Linked Projects. You can also click on the top right corner settings menu and export logs for all projects. SoftSync will allow you to download and save log files in the CSV format.
6.1 SoftSync V1
Version 1.0 of SoftSync has some limitations. Please contact us via our support page if any of these limitations impact your usage of SoftSync. We are eager to get your feedback.
6.1.1 SoftSync Limitations
SoftSync does not yet support:
6.1.1.1 User invitation is not yet supported. If you invite someone to a project and the application finds a user, you can define them as a reporter, watcher, or assignee. However, if you invite someone and the user is not found, the application will use the internal user instead of inviting them.
6.1.1.2 Changes in projects while unlinked are not fully synced once you link them back. SoftSync considers one application as the primary in the case of data conflicts. If you create new tasks, task lists, subtasks, or delete, SoftSync will synchronize the information. If you unlink projects and add new comments, attachments, or time logs in the secondary application, those will not be synced to the primary application when you restore the link.
6.1.1.3 SoftSync does not sync cloned/duplicated tickets in Jira or Teamwork.
6.1.1.4 If you move a time log or an epic from one project to another, SoftSync cannot synchronize it.
6.1.1.5 New file version feature in Teamwork.
6.1.1.6 If you unlink a project during the sync process, the synchronization will not stop.
6.1.1.7 Bulk editing tasks in Teamwork or Jira.
6.1.1.8 Hidden assignee fields in Jira view/create issue screens.
6.1.1.9 In Jira, the epic status will not change to completed when the last task underneath it is marked as done. We will add this functionality in future versions.
6.1.1.10 SoftSync will sync completed tasks from Teamwork, even if you didn’t select the completed status to be synced.
6.1.1.11 If a custom priority is removed later in Jira, SoftSync will not update Teamwork with the new priority.
6.1.1.12 SoftSync does not sync tags in comments or descriptions.
6.1.1.13 SoftSync does not yet support synchronizing custom fields.
6.1.1.14 SoftSync can’t synchronize the project lead/owner.
6.1.1.15 If the reporter for an issue in Jira is not found, SoftSync will use the Site Admin instead of an internal user.
6.1.1.16 SoftSync does not yet support synchronizing permissions or access restrictions that are defined on your Jira or Teamwork, for example, private comments, tasks, or issues.
6.1.1.17 SoftSync will not synchronize text styles.
6.1.1.18 If Teamwork’s priority is set as None and is not mapped with any Jira priorities, SoftSync will map to the first Jira priority by id.
6.1.1.19 SoftSync does not sync Jira and Teamwork boards.
6.1.1.20 SoftSync does not update JIRA_STATUS for subtasks on initial sync. These are updated correctly on webhook updates.
6.1.1.21 If Jira or Teamwork comments have attachments, the order of the comments will not be kept.
6.1.1.22 When you update a Jira task and it has attachments embedded in the task description, these attachments will be duplicated on Teamwork.
6.1.1.23 If you add an attachment in the comment description in Jira and it is updated in Teamwork, these attachments will have a broken preview in Jira.
6.1.2 Jira and Teamwork Limitations
SoftSync does not yet support these actions as those are limitations from Jira or Teamwork:
6.1.2.1 Synchronization of watchers on ‘Add/Delete Watcher’ is not yet supported. You can only set or update watchers when other fields are updated, but SoftSync can not trigger the update webhook on ‘Add/Delete Watcher’. However, SoftSync will sync watchers and followers when an update for a ticket is received.
6.1.2.2 For the status sync to happen, SoftSync generates a custom field in Teamwork with the name: JIRA_STATUS to represent the Jira status as Teamwork supports only open and closed statuses. Please note that custom fields are supported only on Enterprise plans in Teamwork.
6.1.2.3 Multiple levels of sub-tasks. In Teamwork, you can have sub-levels for sub-tasks; Jira doesn’t support this. SoftSync syncs only task lists, tasks, and sub-tasks without support for structures with more than three levels.
6.1.2.4 Jira API does not allow users to define the comment reporter as an existing user. SoftSync uses the SoftSync admin user as the reporter.
6.1.2.5 SoftSync does not support the Jira Import CSV Feature. This issue is a known limitation from Jira.
6.1.2.6 If a user adds a Teamwork comment, but it is deleted in Jira, Jira will return with the wrong Author for the comment. You should remove comments directly in Teamwork.
6.1.2.7 Hiding attachments from a ticket in Jira and Teamwork does not trigger the update task webhook. SoftSync will not trigger an update in this case.
6.1.2.8 Reusing or deleting an existing Teamwork attachment and adding it to a task does not trigger the update task webhook in Teamwork. SoftSync will not trigger an update in this case.
6.1.2.9 Changing the task reporter in Teamwork does not trigger the update task webhook in Teamwork. SoftSync will not trigger an update in this case.
6.1.2.10 Importing tasks using .mpp or .mppx files in Teamwork does not trigger the update task webhook in Teamwork. SoftSync will not trigger an update in this case.
6.1.2.11 Adding new fields in Jira view/create screen like start date, due date, time estimates do not trigger a webhook in Jira. SoftSync will not trigger an update in this case.
6.1.2.12 Changing an epic link or parent in Jira does not trigger the update webhook. SoftSync will not trigger an update in this case.
6.1.2.13 When creating a Classic Project in Jira, you should add the Epic Name in the create screen for Jira Classic Projects, as it is a required field. The Epic Link should be defined on the screen as well; otherwise, the parent’s setting will not be possible in Jira. Learn more about Epic Name vs. Epic Link on Jira Knowledge Base.
6.1.2.14 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. Currently, SoftSync does not automatically create users in Jira or Teamwork if not found.
6.1.2.15 If the default status is missing in the project you sync (because projects can have different statuses as well), then SoftSync will use the first status of the workflow.
You can remove the integration at any moment by clicking on the ‘Remove Integration’ button. This action will trigger a confirmation. On confirming, all the links defined between Jira and Teamwork will be destroyed. You will be redirected back to the connection/login page.
