Use case: Link a Jira Issue to an Annotation

Before you start

  1. Verify Permissions: Ensure you have appropriate permissions in both Unity and Jira to link issues and access annotations.
  2. Annotation Must Exist: You need the Unity projectId and annotationId of the annotation you want to link.
  3. Issue Must Exist: The Jira issue must already exist and be accessible through a valid Jira ServerConfig and ProjectConfig.
  4. Linked Jira Project: Your Unity project must be linked to a Jira ProjectConfig for the operation to work.
  5. Review Link Behavior: Understand how linking is reflected in both systems. In Unity, the annotation may show the Jira issue key and summary; in Jira, there may be a backlink or label depending on implementation.

How do I...?

To associate an existing Jira issue with a Unity annotation:

  1. Ensure All Prerequisites Are Met: Verify that the Unity project and Jira project are correctly configured and linked.
  2. Get Required IDs: Collect the projectId, annotationId, and the Jira issueId (e.g., BUG-45).
  3. Use the SDK: Call the LinkIssueToAnnotationAsync method in the Unity Collaboration SDK with the required properties.
  4. Confirm the Link: Ensure the issue key appears on the annotation or in your application UI.

Example:

await jiraIssueService.LinkIssueToAnnotationAsync(
    projectId: projectId,
    annotationId: annotationId,
    jiraIssueId: jiraIssueId,
    jiraProjectConfigId: jiraProjectConfigId,
    cancellationToken: cancellationToken);

Error Handling

  • 400 Bad Request: Invalid input.
  • 401 Unauthorized: Authentication required.
  • 403 Forbidden: Insufficient permissions.