Relationships

Relationships are the connective tissue of the Teamwork Graph. They are the connections between two objects in the Graph that describe how those objects are related. Relationships are fundamental to how the Teamwork Graph connects, organizes, and enables insights across Atlassian experiences.

For example, if a Jira work item is linked to a Confluence page, Teamwork Graph stores a relationship between those two objects. This allows features like Rovo, analytics dashboards, or automation workflows to “connect the dots” across work. Key characteristics of relationships include:

• Every relationship has a type: For example, user-created-issue, issue-is-parent-of-issue, document-mentioned-issue.

• Relationships are directional: One object is the “subject” (starting point) and the other is the “object” (endpoint). For example, in “issue A is-parent-of issue B,” the relationship goes from issue A to issue B.

• They form a semantic network: Relationships form a web of connections that can be queried to answer questions, power analytics, and drive automation.

Types of relationships

In Teamwork Graph, there are two types of relationships: canonical and inferred.

Canonical relationships

Canonical relationships are direct, authoritative connections between objects in the Graph. These are created from clear, unambiguous data sources—typically as a result of user actions or explicit events. For example:

• Creating a Confluence page or Jira work item
• Linking a Jira work item to a Confluence page
• Adding a project to a goal

When you, as a developer, create relationships while ingesting data into Teamwork Graph (using attributes like parentKey, containerKey, createdBy, or associations), you are creating canonical relationships. These are the foundational, “source of truth” connections in the Graph.

Inferred relationships

Inferred relationships are connections that are not directly recorded by explicit actions or events, but are derived by Teamwork Graph itself. These are calculated by analyzing patterns, metadata, or using machine learning models on existing data. For example:

• Inferring “top collaborators” for a user based on their interaction history
• Suggesting relevant work items based on behavioral patterns

Currently, developers can only create canonical relationships when ingesting data into the Graph. Teamwork Graph creates inferred relationships, building on those canonical relationships you provide.

Why create relationships?

As a developer, setting up relationships between objects when ingesting data into Teamwork Graph is essential for unlocking the full value of that data. Relationships are what enable Teamwork Graph to “connect the dots” across different tools and data sources, making your data discoverable, actionable, and valuable in Atlassian experiences.

By defining relationships, you empower downstream features and integrations to deliver richer insights, automation, and user experiences, such as:

• Rovo: Rovo can query existing relationships to answer customer questions more intelligently. For example, this community post highlights how Rovo Chat leverages relationships to provide relevant answers.

• Analytics: Relationships make it possible to build dashboards that connect and visualize data across systems. For example, we’re collaborating with EAP partners to build charts that track how test case statuses change over time for specific work items or epics. This is possible by linking work items and epics to their related test cases and statuses in Teamwork Graph. If you’re interested in building such dashboards, please contact the Home Dashboard team.

• Custom applications, agents, and automation workflows: By establishing relationships between entities when you ingest data into Teamwork Graph, you lay the foundation for powerful custom solutions. The upcoming Teamwork Graph consumption API (EAP) will allow you to build applications, agents, and automation workflows that can query and act on these relationships. The richer and more meaningful your relationships are, the more your custom solutions can leverage them to deliver advanced insights, automation, and integrations. If you’re interested in developing these solutions, reach out to us—we can help you identify which relationships will best support your use case.

How to create relationships

Relationships can be created in a few ways via the setObjects operation:

1. Through the parentKey and containerKey attributes, indicating a relationship between the ingested object and its parent or container.

2. Through attributes that relate to a user, such as createdBy or owners.

3. Through the associations attribute, which provides a way to generically link objects.

Parent and container

An object can have a parent or container defined through the parentKey or containerKey attribute. The type of this is equivalent - the Entity key. For example, ingesting a Document object with a parent Document:

1
2
    {
      id: document-1,
      parentKey: {
        type: 'atlassian:document',
        value: {
          entityId: document-2
        }
      }
    }

While the API supports any object type being used as a parent or container, some combinations create defined relationships in the Teamwork Graph:

Associations

Relationships can be ingested through the associations property of an object to create a link between your object and another object. For example, this list of associations creates a relationship between the ingested object and a Jira work item:

1
2
    associations: {
      set: {
        associationType: "issueIdOrKeys",
        values: ["ABC-123"]
      }
    }

Association types

Teamwork Graph supports the following association types:

Jira work items

An association type referencing work items in Jira.

Teamwork Graph objects

An association type referencing another object you have sent. You do not need to ingest the object before you associate with it - a stub will be created in place, until the full object is ingested.

1
2
{
  "entityId": "document-1"
}

Relationship types

Not all object types can be associated with another Teamwork Graph object type. At the moment, we only support the following use cases: