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

There are two main approaches to creating relationships in Teamwork Graph:

Approach 1: Creating relationships via setObjects

When you ingest objects using setObjects, you can create relationships indirectly by including relationship attributes in the object payload:

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.

This approach is ideal when you're creating objects and their relationships in a single operation.

Approach 2: Creating relationships via setRelationships

You can also create relationships directly using the setRelationships method, which allows you to create or update relationships independently of object ingestion. This is useful when:

• You need to create relationships between objects that already exist in the graph
• You want to manage relationships separately from object creation
• You need to create relationships in bulk without modifying the objects themselves

See the Relationship operations API reference for details on using setRelationships and deleteRelationship.

When to use each approach

The following sections detail how to use setObjects to create relationships. For information about using setRelationships, see the Relationship operations documentation.

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
• Relationship operations API reference - Direct relationship management using setRelationships and deleteRelationship
• Connector reference - Detailed connector API documentation
• Connector object types - Learn about object types available for building connectors