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 (EntityKey) [Optional]
      ├─ type (string) [Required]
      └─ value (jsonNode) [Required]
  └─ containerKey (EntityKey) [Optional]
      ├─ type (string) [Required]
      └─ value (jsonNode) [Required]
  └─ permissions [] [Required]
      └─ accessControls []
         └─ principals []
            └─ type (string)
            └─ id (string)
  └─ associations [] [Optional]
      ├─ associationType (string)
      └─ values []

UserReference

A reference to an Atlassian or third-party user.

When ingesting objects, the details of the user referenced on certain attributes are not required. Instead, details of a user should be sent through the setUsers operation. See setUsers for more information.

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.

Depending on the context, the entityKey should include specific object types as follows:

ParentKey

• Comment: Must be either atlassian:pull-request, atlassian:project, atlassian:work-item, or atlassian:document
• Document: Can have atlassian:document
• Message: Can have atlassian:message

ContainerKey

• Branch: Must have atlassian:repository
• Commit: Must have atlassian:repository
• Deployment: Can have atlassian:repository
• Build: Can have atlassian:repository
• Message: Must have atlassian:conversation
• Pull request: Must have atlassian:repository
• Work item: Can have atlassian:space

Examples

Generic key

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

Non-generic key

1
2
{
  "type": "atlassian:branch", 
  "value": {
    "repositoryId": "repo-123"
  }
}

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.

Atlassian workspace

Grants access to anyone in the Atlassian Graph workspace.

Container

Grants access to all users within the container.

Example

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

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

• set replaces all associations with the supplied ones.

Associations have the following format:

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

Association types

There are currently three types of associations available:

• IssueIdOrKeysAssociation
• EntityOrContainerAssociation
• ServiceIdOrKeysAssociation

IssueIdOrKeysAssociation

An association type referencing issues in Jira.

Example

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

EntityOrContainerAssociation

An association type referencing entities or containers using a generic association key.

1
2
{
  "type": "atlassian:<objectType>",
  "value": {
    "entityId": "entity-id"
  }
}

GenericAssociationKey

The generic association key structure used in EntityOrContainerAssociation.

Example

1
2
{
  "updateSequenceNumber": "999",
  "lastUpdatedAt": "2024-04-16T09:31:32+00:00",
  "set": [
    {
      "associationType": "genericAssociationKey",
      "values": [
        {
          "type": "atlassian:document",
          "value": {
            "entityId": "document-1"
          }
        }
      ]
    }
  ]
}

ServiceIdOrKeysAssociation

An association type referencing services by their identifiers or keys.

Example

1
2
{
  "updateSequenceNumber": "999",
  "lastUpdatedAt": "2024-04-16T09:31:32+00:00",
  "set": [
    {
      "associationType": "serviceIdOrKeys",
      "values": [ "SVC-123" ]
    }
  ]
}

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