Create relationships

When you build a connector and add data to Teamwork Graph, creating relationships between your objects and other data in the graph is essential for unlocking the full value of that data. Relationships enable Teamwork Graph to "connect the dots" across different tools and data sources, making your data discoverable, actionable, and valuable in Atlassian experiences.

This guide explains why relationships matter and how to create them using the Teamwork Graph connector SDK.

Why create relationships

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.

• 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 Teamwork Graph API allows you to build applications, agents, and automation workflows that can query and act on these relationships.

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"
}

Supported 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:

Related resources

• Relationships - Overview of relationships in Teamwork Graph
• Connector reference - Detailed connector API documentation
• Connector object types - Learn about object types available for building connectors