Understanding ARIs in Teamwork Graph

An Atlassian Resource Identifier (ARI) is a globally unique identifier for objects across Atlassian. ARIs are used throughout the Teamwork Graph API to identify specific objects when querying relationships and traversing the graph.

What is an ARI?

An ARI is similar to a URL—it's a standardized way to uniquely identify any resource in the Atlassian ecosystem. Just as a URL can point to any web resource, an ARI can point to any Atlassian resource: a Jira work item, a Confluence page, a user account, or any other object.

ARIs ensure that when you reference an object in your queries, you're referring to exactly the right object, even when similar objects exist across different sites or products.

ARI structure

ARIs follow a consistent pattern across all Atlassian resources:

1
2
ari:cloud:{app}:{siteId}:{objectType}/{objectId}

Components

Common ARI patterns

While each object type has its own specific pattern, here are some common patterns you'll see:

Jira resources

Jira resources typically follow this pattern:

1
2
ari:cloud:jira:{siteId}:{objectType}/{objectId}

Examples:

• Issues: ari:cloud:jira:a436116f-02ce-4520-8fbb-7301462a1674:issue/8843576
• Projects/Spaces: ari:cloud:jira:a436116f-02ce-4520-8fbb-7301462a167:project/12345

Atlassian resources

Atlassian-wide resources (like Atlassian projects) typically use the townsquare namespace:

1
2
ari:cloud:townsquare:{siteId}:{objectType}/{objectId}

Examples:

• Atlassian Project: ari:cloud:townsquare:a436116f-02ce-4520-8fbb-7301462a1674:project/ATLAS-103368

Identity resources

User accounts and identity-related resources use the identity namespace and omit the site ID:

1
2
ari:cloud:identity::{objectType}/{objectId}

Examples:

• Users: ari:cloud:identity::user/5fb4febcfacfd60076a1c699
• Teams: ari:cloud:identity::team/19441f6d-f53e-4e35-a89f-265a30db4e68

User and team ARIs use identity as the app and have a double colon (::) instead of a site ID, since user accounts and teams exist across all Atlassian sites.

Finding your site ID

Your site ID, also called the cloud ID, uniquely identifies your Atlassian instance. Most ARIs require a site ID to identify which instance the resource belongs to.

To find your site ID:

1. Make a GET request to the following endpoint, replacing yourinstancename with your Atlassian site's name:

   1
   2
   https://yourinstancename.atlassian.net/_edge/tenant_info
   

2. In the JSON response, find the cloudId field. This is your site ID.

Example response:

1
2
{
  "cloudId": "a436116f-02ce-4520-8fbb-7301462a1674",
  "tenantId": "a436116f-02ce-4520-8fbb-7301462a1674",
  "realm": "prod"
}

In this example, the site ID is a436116f-02ce-4520-8fbb-7301462a1674.

Using ARIs in the Teamwork Graph API

When querying the Teamwork Graph API, you'll use ARIs in several ways:

Traversing the graph

When traversing relationships, ARIs identify the starting point and connected objects:

1
2
MATCH (user:AtlassianUser {ari: 'ari:cloud:identity::user/5fb4febcfacfd60076a1c699'})
      -[:atlassian_user_reported_jira_work_item]->(issue:JiraWorkItem)
RETURN user, issue

Use the Cypher query in a GraphQL request like so:

1
2
query test_getJiraWorkItem($cypherQuery: String!, $params: CypherRequestParams) {
  cypherQuery(query: $cypherQuery, params: $params) {
    edges {
      node {
        columns {
          key
          value {
            __typename
            ... on CypherQueryResultNode {
              id
              data {
                ... on JiraWorkItem {
                  summary
                }
              }
            }
          }
        }
      }
    }
  }
}

Read more about making a request with Cypher queries here

Querying specific objects

Using a Cypher query

Use an ARI to retrieve a specific object using a Cypher query:

1
2
MATCH (issue:JiraWorkItem {ari: 'ari:cloud:jira:cloud123:issue/12345643'}) RETURN issue

or

1
2
MATCH (page: ConfluencePage {ari: 'ari:cloud:confluence:cloud123:page/12345623}) RETURN page

This will allow you to return a specific object if you have the object's ARI

Using a direct object look up

The TWG API also has a few special fields that allows you to lookup an object type directly without a Cypher query

1
2
query test_directlook {
   jiraWorkItem(id: "ari:cloud:jira:cloud123:issue/1234567") {
      id
      ...
   }
}

See the full documentation on direct object lookups

Discovering an object's ARI

You may find yourself wanting to traverse the graph starting at a specific object (for example, a Jira WorkItem). However, you aren't sure what the ARI of the object is. Here are the ways in which you can discover the ARI:

Using Teamwork Graph API's URL to ARI resolution feature

The Teamwork Graph API allows consumers to pass in a URL in replacement of an ARI for a Cypher query.

In the background, the API is able to resolve the URL into an ARI for use with the Cypher query

See more details here

Discovering your Atlassian user's ARI

Every Atlassian user will have an ARI. This can be easily found:

• Navigate to home.atlassian.com
• Select your user avatar in the top right
• Click "Profile"
• The URL should have the following format: https://home.atlassian.com/o/xxx/people/**accountId**?cloudId=yyy
• Take the accountId from the URL
• Your user's ARI is ari:cloud:identity::user/**accountId**

Traversing the graph from another node

Often times, the easiest way is to traverse the graph from another object you do know the ARI of.

The easiest example is to use your AtlassianUser ARI:

• Follow the instructions above on w to discover your Atlassian user's ARI
• Run a Cypher query with a relationship that has a node that starts with AtlassianUser
  • See the list of all relationships that start from AtlassianUser here: Full list of AtlassianUser relationships

For example: If I wanted to find the ARI of a specific Jira WorkItem, I could query all the WorkItems I am assigned to by using this Cypher query:

1
2
MATCH (user:AtlassianUser {ari: 'ari:cloud:identity::user/5fb4febcfacfd60076a1c699'})
      -[:atlassian_user_assigned_jira_worhok_item]->(issue:JiraWorkItem)
RETURN issue

The response returned from a GraphQL request with this Cypher query will contain the ARI of the resource you are interested in.

Read more about making a request with a Cypher queries here

Related resources

• Object types in Teamwork Graph - Overview of all available object types
• Call the Teamwork Graph API - Learn how to query the API
• Relationships in Teamwork Graph - Learn about relationships between objects