By default, Backbone Work Sync makes every change on Jira Cloud as its app user. You can choose a service account instead, per synchronization. Backbone Work Sync then uses that service account to write changes.
This article explains when to use a service account, how to prepare one, and how to add it to a synchronization.
When to Use a Service Account
A service account is useful in these situations:
-
Spaces in a chain: you synchronize between three spaces and want changes to travel from space A to space B to space C. This only works on Cloud with a service account. See Synchronize multiple spaces.
-
Traceability: you want to see which synchronization made a change. Give each synchronization its own service account with a clear name.
-
Control over access*: you want to decide exactly what the synchronization can do. You set the service account's space permissions and scopes yourself.
-
A custom name: you want synced changes to show a name your team recognizes, not the app user.
Service accounts don't take a Jira license seat. See Atlassian's documentation for how many service accounts your organization can create.
Why still use the default user? If none of the above apply, the default app user is still beneficial. The default app user works right away with no setup or credentials to manage, and it already has all the permissions it needs. It also works in setups that service accounts don't yet support, such as for Data Center when syncing Cloud to Data Center, with no credentials that can expire and interrupt your sync.
How Backbone Work Sync Recognizes Its Own Changes
To avoid syncing a change back and forth endlessly, Backbone Work Sync ignores changes made by the account it writes with. With the app user, every synchronization on your instance writes as the same account. So when one synchronization updates a work item, every other synchronization ignores that update too.
With a service account, each synchronization ignores only its own service account. Changes written by other synchronizations count as normal changes and get synchronized.
Don't use the service account for anything else, such as scripts or manual edits. Backbone Work Sync ignores every change that account makes.
How to Create a Service Account
Step 1: Create the Service Account and Give It Access
In Atlassian Administration, select Directory > Service accounts, and create a service account. Give it a name that says what the account does, then select the app roles and groups it needs to access the spaces it synchronizes. See Create a service account in the Atlassian documentation.
Step 2: Create an OAuth 2.0 Credential
Backbone Work Sync signs in as the service account with an OAuth 2.0 credential. To create one:
-
In Atlassian Administration, select Directory > Service accounts.
-
Select the service account you created.
-
Select Create credentials, then OAuth 2.0.
-
Give the credentials created a name
-
Select the scopes listed in Required scopes.
-
Select Create.
-
Copy the client ID and client secret - copy both values right away. Atlassian can't show the client secret again after you close the dialog.
Required scopes
Select all of the following scopes for the credential:
|
Scope |
What Backbone Work Sync uses it for |
|---|---|
|
|
Identify the service account behind the credential |
|
|
Read, create, and update synced work items, including comments, attachments, and worklogs |
|
|
Look up users to map them between Jira instances |
|
|
Change space settings, such as adding versions and components |
|
|
Clone spaces and their schemes |
|
|
Read, create, and update Jira Service Management requests, including request types, comments, and participants |
|
|
Manage customers and organizations of synced requests |
|
|
Read boards and move work items to the backlog |
|
|
Read and create sprints, and move work items into sprints |
|
|
Read data from the Jira Software REST API, such as a work item's sprint |
|
|
Read Assets objects to sync Assets fields |
Copy and paste the following text into the scope search bar in order to quickly filter out all required scopes:
read:me, read:account, read:jira-work, write:jira-work, read:jira-user, manage:jira-project, manage:jira-configuration, read:servicedesk-request, write:servicedesk-request, manage:servicedesk-customer, read:board-scope:jira-software, write:board-scope:jira-software, read:sprint:jira-software, write:sprint:jira-software, read:issue-details:jira, read:project:jira, read:issue:jira-software, read:cmdb-object:jira
For details, see Create OAuth 2.0 credential for service accounts in the Atlassian documentation.
How to Use a Service Account
When you create a synchronization, each space can use either the default app user or a service account. The detailed setup steps are covered in create a new synchronization.
Change the Service Account
You can't change the account of an existing synchronization. That means you can't:
-
Switch an existing synchronization from the app user to a service account.
-
Replace one service account with another.
-
Enter a new credential for the same service account.
To move a synchronization to a different account, create a new synchronization with that account. Then move your work item pairs to it, as described in migrate a Backbone synchronization to a new Backbone synchronization.
Don't revoke the credential of a service account a synchronization still uses. Backbone Work Sync won’t be able to synchronize work items anymore and wil throw errors