Team REST APIs for Jira Cloud

Abstract

Team REST APIs to migrate Tempo data from Jira Server / Data Center to Jira Cloud

Note

The code examples provided below are for curl and you will need to adapt them to your preferred means of dealing with REST APIs. All information provided in curly brackets “{}” need to be replaced with the variables from your instance.

Important

For any requests to Jira (which are necessary to update issues) you will need an API token from Atlassian. You can find more information about creating and managing Atlassian API tokens here.

Teams

Teams can be created with the teams endpoint:

curl --request POST 'https://api.tempo.io/core/3/teams' -H 'Content-Type: application/json' -H 'Authorization: Bearer {TempoAuthorisationToken}' --data-raw '{"name": "Senior Product Experts","leadAccountId": "{AtlassianID}"}'

Once the Tempo team has been created you will get a response with the information of the Tempo Team ID ("id":24). You will need that information later on to populate the team memberships and to update the Tempo team Jira custom field.

Team roles

Team roles can be created with the roles endpoint:

curl --request POST 'https://api.tempo.io/core/3/roles'
 -H 'Content-Type: application/json'
 -H 'Authorization: Bearer {TempoAuthorisationToken}' -data-raw '{"name": "Product Expert"}

The role name must be unique to be accepted by Tempo.

Team members

You can add team members to your Tempo teams from the endpoint:

curl --request POST 'https://api.tempo.io/core/3/team-memberships' 
-H 'Authorization: Bearer {TempoAuthorisationToken}' 
-H 'Content-Type: text/plain' 
--data-raw '{"teamId": 24,"accountId": "557058:ce712bf4-aa3b-4af3-a925-3633d2f4bacd","roleId": 6,"commitmentPercent": 100,"from": "2020-01-01"}'

The team and the team role ID need to be retrieved from the responses while creating the teams/team roles.

Team Permissions

Since Tempo has implemented new Permissions Roles, which allow sharing of permission settings across teams, it is recommended that you set permissions on a multi-team level rather than apply the permissions on team level. With the new Permission Roles, permissions for users that need access to data across multiple teams can be configured and maintained in a single place. This reduces the effort to set the permissions and increases the transparency to see granted permissions across your organization.

Team Permission Roles can be created and maintained from a public REST API (/permission-roles).

curl --request POST 'https://api.tempo.io/core/3/permission-roles' 
-H 'Authorization: Bearer {TempoAuthorisationToken}' 
-H 'Content-Type: text/plain' 
--data-raw '{
  "name": "Tempo worklog managers",
  "permissionKeys": [
    "permissions.worklog.view"
  ],
  "permittedAccountIds": [
    "557058:ce712bf4-aa3b-4af3-a925-3633d2f4bacd",
    "jira-account-id"
  ],
  "accessType": "TEAM",
  "accessEntityIds" : [
    1,3,5
  ]
}'

When the "accessType" is "GLOBAL" the section for "accessEntityIds" can be skipped. Otherwise provide the Tempo teams IDs where the permission role should apply to.

You can use the following permission keys to access the team permissions. Multiple permission keys can be applied at one time using an array (separated by commas).

"permissions.plan.approve"
"permissions.plan.manage"
"permissions.plan.view"
"permissions.team.manage"
"permissions.worklog.approve"
"permissions.worklog.manage"
"permissions.worklog.view"

When the permission is specified it is set to "true" else "false"(default value).

Update the Team Custom Fields

After a restore of the database on the Cloud instance the Tempo Account and Team field exist but any related data needs to be updated with the newly created Tempo Account and Tempo Team information. 

First we need to get the custom field ID of the Tempo Account and Tempo Team fields:

curl --request GET 'https://{JiraCloudUrl}/rest/api/3/field' -H 'Authorization: Basic {base64encodedAtlassianEmail:AtlassianAPIToken}' 

Within the response of that call you will find the information of the Tempo Account and the Tempo Team field:

{
        "id": "customfield_10201",
        "key": "io.tempo.jira__account",
        "name": "Account",
And
 {
        "id": "customfield_10200",
        "key": "io.tempo.jira__team",
        "name": "Team",

To update the Jira issue with the new Tempo Account/Team values use the Jira issue endpoint with a PUT request:

curl --request PUT 'https:///{JiraCloudUrl}/rest/api/3/issue/{IssueKey}' 
--H 'Content-Type: application/json' 
--H 'Authorization: Basic {base64encodedAtlassianEmail:AtlassianAPIToken}'  
--data-raw '{"fields": {"customfield_10201": {TempoAccountID}}'

As the update of the Jira custom field only accepts the Tempo Account ID (key or name can not be passed) you will need to find the Tempo Account from the imported Tempo Accounts. The Tempo Accounts are returned from the API call:

curl --request GET 'https://api.tempo.io/core/3/accounts' -H 'Authorization: Bearer {TempoAPIToken}'