Common properties and shapes

The following properties and shapes are common to all supported Teamwork Graph object types.

1
2
  objects {}
  ├─ schemaVersion (string) [Required]
  ├─ id (string) [Required]
  ├─ updateSequenceNumber (long) [Required]
  ├─ displayName (string) [Required]
  ├─ description (string) [Optional]
  ├─ url (string) [Required]
  ├─ createdAt (string) [Required]
  └─ createdBy [Optional]
      ├─ accountId (string) [Optional]
      ├─ email (long) [Optional]
      └─ externalId (string) [Optional]
  └─ lastUpdatedAt (string) [Required]
  └─ lastUpdatedBy [Optional]
      ├─ accountId (string) [Optional]
      ├─ email (long) [Optional]
      └─ externalId (string) [Optional]
  └─ owners [] [Optional]
  └─ thumbnail [Optional]
      └─ externalUrl (string) []
  └─ parentKey
      ├─ type (string)
      └─  value (jsonNode)
  └─ containerKey
      ├─ type (string)
      └─  value (jsonNode)
  └─ permissions [] [Required]
      └─ accessControls []
         └─ principals []
            └─ type (string)
            └─ id (string)
  └─ associations [] [Optional]
      ├─ associationType (string)
      └─ values []

User

An Atlassian or third-party user.

Example

1
2
{
  "accountId": "5b5775502abff9a219",
  "id": "WELLJST6K",
  "email": "user@email.com",
  "externalId" : "external-id-1"
}

Thumbnail

Metadata for a thumbnail. Currently only supports an external URL.

Example

1
2
{
  "externalUrl": "https://example-file.com/file/123123"
}

Entity key

The key for a given unified object type used for describing a parent or container link.

Examples

Generic key

1
2
{
  "type": "atlassian:document",
  "value": {
    "entityId": "a-document-id"
  }
}

Non-generic key

1
2
{
  "type": "atlassian:remote-link",
  "value": {
    "remoteLinkId": "a-remote-link-id"
  }
}

Composed key

1
2
{
  "type": "atlassian:commit",
  "value": {
    "repositoryId": "a-repository-id",
    "commitHash": "a-commit-hash"
  }
}

Permissions

Defines permissions for the users and/or groups who are allowed to access the object information.

Access control

Defines permissions for users and/or groups who are allowed to have access to the object.

User

Grants access to specific users.

Group

Grants access to all users within the group.

Everyone

Grants access to all logged in and anonymous users.

Atlassian workspace

Grants access to anyone in the Atlassian Graph workspace.

Container

Grants access to all users within the container.

Must have viewed

Grants access to all users who have viewed the object previously.

Example

1
2
[
  {
    "accessControls": [
      {
        "principals": [
          {
            "type": "USER",
            "id": "WELLJST6K"
          },
          {
            "type": "GROUP",
            "id": "UJHJST6K"
          }
        ]
      }
    ]
  },
  {
    "accessControls": [
      {
        "principals": [
          {
            "type": "MUST_HAVE_VIEWED"
          }
        ]
      }
    ]
  }
]

Association

The association fields for the IngestionEntity. Used for referencing another object, such as issueKey in a pull request title or users mentioned in a message.

Any use case beyond a simple reference should explore adding as separate field in the given object type instead. For example, if you want to track the owners of a document separately from the user who last updated the document.

Associations use set, add, and remove, where:

• set replaces all associations with the supplied ones. It cannot be used with add or remove.
• add extends existing associations with the new ones supplied. It cannot be used with set.
• remove removes from existing associations the ones supplied. It cannot be used with set.

Associations have the following format:

1
2
{
  "updateSequenceNumber": "1",
  "lastUpdatedAt": "2024-04-16T09:31:32+00:00",
  "set": [
    {
      "associationType": "...",
      "values": ["..."]
    }
  ],
  "add": [
    {
      "associationType": "...",
      "values": ["..."]
    }
  ],
  "remove": [
    {
      "associationType": "...",
      "values": ["..."]
    }
  ]
}

Association types

There are currently only one type of association available:

• IssueIdOrKeysAssociation

IssueIdOrKeysAssociation

An association type referencing issues in Jira.

Example

1
2
{
  "updateSequenceNumber": "999",
  "lastUpdatedAt": "2024-04-16T09:31:32+00:00",
  "add": [
    {
      "associationType": "issueIdOrKeys",
      "values": [ "TEST-1" ]
    }
  ],
  "remove": [
    {
      "associationType": "issueIdOrKeys",
      "values": [ "TEST-2" ]
    }
  ]
}

Attachment

Defines an attachment object that is present in some object types.

Example

1
2
{
  "url": "https://www.somedomain.com/files/fakefile.pdf",
  "title": "Fake File",
  "mimeType": "application/pdf"
}