Querying data from Forge connectors

If you have added data to Teamwork Graph by building a custom Forge connector, you can query that data through the Teamwork Graph API if there are equivalent object types and relationships exposed.

This page explains how connector object types map to API object types, and which of that data you can query today.

How connectors and the API work together

1. Connectors push objects and relationships into Teamwork Graph using connector object types. Data is mapped to a common schema and stored in the graph.

2. The Teamwork Graph API lets you query the graph using API object types and relationships. Objects that you added via connectors appear in the graph and can be queried when they map to an API object type.

Not every connector object type has a corresponding API object type. The table below shows which connector object types you can query via the API and which are not yet available to query.

Connector object type to API object type mapping

The following table maps connector object types to API object types. Use it to see which objects you've added via connectors you can query with the Teamwork Graph API. The Available relationships column lists relationship types you can use in Cypher to traverse to or from that API object type; see the relationship types overview for the full list.

Querying Forge connector data with Cypher

If the object types you've ingested with your Forge connector have a corresponding API object type and relationships, you can query that data using the Teamwork Graph API and Cypher.

For that data to show up in relationship API queries, you need to create the right relationships when you push objects from your connector. Many of these relationships are created automatically when you use certain fields in your connector payload.

How relationships are created when you push objects

When you push objects from a connector, Teamwork Graph creates traversable relationships from the fields you send. Key fields that create relationships between object include:

• parentKey and containerKey, which create parent–child or container relationships (e.g. External document has child external document)
• createdBy and owners, which link objects to users (e.g. Atlassian user created documents)
• associations, which link objects to other objects (e.g. document to Jira work item via issueIdOrKeys; see Create relationships for supported types)

For more details, see Create relationships.

If you don't set these when you push objects, those relationships won't be created and you won't be able to query them with Cypher.

Example

If you add an external document (for example, a document from Google Drive) via a custom Forge connector and you want to:

1. Link it to the user who created or owns it.
2. Link it to a specific Jira ticket.

When you push the document from your connector, include:

• createdBy with the user's accountId or equivalent so the document is linked to that user.
• associations with associationType: "issueIdOrKeys" and values: ["PROJ-123"] so the document is linked to that Jira work item.

After you've pushed the document, you can query the graph with Cypher. Below are examples for the relationships that are available in the API today.

Find external documents created by a user

Use the Atlassian user created documents relationship. This was created when you set createdBy on the document:

1
2
MATCH (user:AtlassianUser {ari: $userAri})-[:atlassian_user_created_documents]->(doc:ExternalDocument)
RETURN doc

Pass the user's ARI as userAri in your query parameters. This returns all external documents (including ones you added via connectors) that are linked to that user as creator.

Find child documents of a parent document

If you pushed documents with a parentKey pointing to another document, use the External document has child external document relationship:

1
2
MATCH (parent:ExternalDocument {ari: $parentAri})-[:external_document_has_child_external_document]->(child:ExternalDocument)
RETURN child

Pass the parent document's ARI as parentAri to get its child documents.

Documents linked to a Jira work item

When you push a document with associations using issueIdOrKeys, the link between the Jira work item and the document is created in the graph. Whether you can query that link via Cypher depends on the relationship types exposed in the API.

The API reference includes relationship types such as Jira work item links external design and Jira work item links external commit.

Additional relationship types for other associations (for example, document–work item) may be exposed over time. If there is a specific relationship you require, please reach out to your Atlassian representative so we can better understand your use case.

Check the relationship types overview for the current list of queryable relationships.

Regardless of API exposure, setting the right associations when you push the object is required for the link to exist so it can be used by the API and other experiences (e.g. Rovo, search) when supported.

Running the Cypher queries

Execute these Cypher queries via the Teamwork Graph API by wrapping them in a GraphQL cypherQuery request, as described in Call the Teamwork Graph API.

Use parameterized queries (e.g. $userAri, $parentAri) rather than embedding values in the query string.

Next steps

• To query the graph: Call the Teamwork Graph API
• To add data to the graph: Build a Teamwork Graph connector
• To create relationships when you push objects so that data is queryable: Create relationships
• To understand object types in the API: API object types overview