User

The User object type represents an Atlassian account user.

Using this object type with the Teamwork Graph API allows you to access users and traverse their relationships, including relationships with other objects across Atlassian.

Constructing the ARI for a user

An Atlassian Resource Identifier (ARI) is a globally unique identifier for objects across Atlassian, and is used in the Teamwork Graph API to identify a specific object.

For users, the ARI follows this pattern:

1
2
ari:cloud:identity::user/{userId}

Your user ID uniquely identifies your user account. To find it:

1. Log into your Atlassian account.
2. Go to this URL, replacing yourinstancename with your site's name:

   1
   2
   https://yourinstancename.atlassian.net/rest/api/3/myself
   

3. Save the accountId value from the response. This is your user ID.

Querying user relationships

The Teamwork Graph API enables you to explore how users are connected to each other and to other objects across Atlassian. Relationships represent these links between users and other objects. Each relationship has a specific name, for example, the UserAssignedIssue relationship connects a user to assigned Jira work items.

See available relationships for users below.

To query a relationship, use the appropriate relationship name in your GraphQL or Cypher query. See the example below.

Example: List assigned issues of a user

This example shows how to use the Teamwork Graph API to list all Jira work items where a user is the assignee, using the UserAssignedIssue relationship.

See the User assigned issue relationship documentation for more details.

1. Open the GraphiQL playground

   Go to https://yourinstancename.atlassian.net/gateway/api/graphql/twg to access the GraphiQL Playground for testing queries, replacing yourinstancename with your Atlassian site. Sign in on the top right corner.

2. Enter the sample query

   Paste the following GraphQL query into the query editor:

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

3. Set the query variables

   In the Variables tab, enter:

   1
   2
   {
     "cypherQuery": "MATCH (user:IdentityUser {ari: $id})-[:user_assigned_issue]->(issue:JiraIssue) RETURN issue",
     "params": {
       "id": "ari:cloud:identity::user/5fb4febcfacfd60076a1c699"
     }
   }
   

   Replace the id value with your user ARI string. See above for how to find the ARI.

4. Add required headers

   In the HTTP Headers tab, add:

   1
   2
    {
    "X-Force-Flock": "false",
    "X-Force-Dynamo": "true"
    }
   

5. Run the query

   Click the play button to execute the query. The response will appear on the right, listing all issues assigned to the specified user, including their IDs, summaries, descriptions, and statuses.

cURL example

You can also run this query using cURL or your preferred HTTP client by sending a POST request to the same endpoint with your API token credentials. Replace the id value with your user ARI.

1
2
curl -X POST \
  --data-binary '{
  "query": "query UserHasAssignedIssues($cypherQuery: String!, $params: CypherRequestParams) { cypherQuery(query: $cypherQuery, params: $params) { edges { node { columns { value { ... on CypherQueryResultNode { id data { __typename ... on JiraWorkItem { id description } } } } } } } } }",
  "variables": {
    "cypherQuery": "MATCH (user:IdentityUser {ari: $id})-[:user_assigned_issue]->(issue:JiraIssue) RETURN issue",
    "params": {
      "id": "$id"
    }
  }
}' \
  -H "Authorization: Basic YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Force-Flock: false" \
  -H "X-Force-Dynamo: true" \
  https://yourinstancename.atlassian.net/gateway/api/graphql/twg

Available fields

The following table lists all available fields you can request when querying for a user object. These fields represent specific data associated with each user that you can retrieve through the Teamwork Graph API. You can include any combination of these fields in your GraphQL queries to get exactly the data you need.

For example, if you only need the user name:

1
2
... on User {
  name
}

Or if you need comprehensive user information for an Atlassian account user:

1
2
... on AtlassianAccountUser {
  id
  name
  email
}

Available relationships

The above sample query is only one of the many relationships available for this entity. For each relationship, there will be a small modification to the Cypher query to search for data, which is explained on each relationship's detailed page.

The following relationships are currently supported for users:

From relationships

Relationships where user is the source object.

To relationships

Relationships where user is the target object.