Use case: Export annotations for a project

Before you start

Before you export annotations from a project, ensure you have completed the following prerequisites:

1. Project Access: Ensure you have the necessary permissions to access and read annotations from the target project.
2. Understand Export Format: The export format includes additional metadata beyond standard annotation data, such as asset names, annotation URLs, and associated issue IDs.
3. Plan for Pagination: Export operations return paginated results. Plan to handle multiple pages if your project contains many annotations.
4. Set Up SDK Environment: Confirm that your Unity environment is correctly configured with the Collaboration SDK.
5. Consider Performance: Exporting large numbers of annotations may take time. Consider implementing progress indicators for better user experience.

How do I...?

Export annotations from a project

To export annotations from a project with full metadata, follow these steps:

1. Prepare the Project Identifier: Ensure you have the correct project identifier (GUID) for the project you want to export from.
2. Define Target Filter (Optional): Optionally specify a target path with wildcard (**) to filter annotations by location.
3. Configure Pagination: Set the page size limit (default is 10) and prepare to handle pagination tokens.
4. Configure Sorting (Optional): Choose sorting order (Ascending/Descending) and field ("annotationId" or "latestReply").
5. Execute Export: Use the SDK to export annotations with the specified criteria.
6. Handle Pagination: Use the next token from the result to fetch subsequent pages if needed.
7. Access Export Data: Process the exported annotations with their additional metadata.

Example:

var projectId = new ProjectId("87cf845f-8ca7-4b2f-9cc1-c3d731335810");
var limit = 50; // Export 50 annotations per page
var sortingOrder = SortOrder.Descending;
var sortingField = SortingField.LatestReply; // Sort by most recent activity

var projectReference = new ProjectReference(projectId);
var filteringOptions = new FilteringOptionsWithSortingField(limit: limit, sortingOrder: sortingOrder, sortingField: sortingField);

ExportAnnotationsResult result = await annotationManagement.ExportAnnotationsAsync(
    projectReference,
    filteringOptions: filteringOptions,
    cancellationToken: cancellationToken);

// Process the exported annotations
foreach (var exportedAnnotation in result.Annotations)
{
    Debug.Log($"Annotation ID: {exportedAnnotation.AnnotationId}");
    Debug.Log($"Asset Name: {exportedAnnotation.AssetName}");
    Debug.Log($"Annotation URL: {exportedAnnotation.AnnotationUrl}");
    Debug.Log($"Issue IDs: {string.Join(", ", exportedAnnotation.IssueIds)}");
}

// Handle pagination
if (!string.IsNullOrEmpty(result.Next))
{
    var filteringOptions = new FilteringOptionsWithSortingField(next: result.Next, limit: limit);

    var nextResult = await annotationManagement.ExportAnnotationsAsync(
        projectReference,
        filteringOptions: filteringOptions,
        cancellationToken: cancellationToken);
}

Export annotations with target filtering

To export only annotations matching a specific target path, use wildcard matching:

var projectId = new ProjectId("87cf845f-8ca7-4b2f-9cc1-c3d731335810");
var projectReference = new ProjectReference(projectId);

var target = "assets/projects/{projectId}/assets/{assetId}/**"; // Export all annotations for a specific asset

ExportAnnotationsResult result = await annotationManagement.ExportAnnotationsAsync(
    projectReference,
    requestTarget: target,
    cancellationToken: cancellationToken);

Export all annotations with pagination

To export all annotations from a project across multiple pages:

var projectId = new ProjectId("87cf845f-8ca7-4b2f-9cc1-c3d731335810");
var projectReference = new ProjectReference(projectId);

var allAnnotations = new List<IAnnotationExport>();
string nextToken = null;

do
{
    var filteringOptions = new FilteringOptionsWithSortingField(next: nextToken, limit: 100);

    ExportAnnotationsResult result = await annotationManagement.ExportAnnotationsAsync(
        projectReference,
        filteringOptions: filteringOptions,
        cancellationToken: cancellationToken);

    allAnnotations.AddRange(result.Annotations);
    nextToken = result.Next;

} while (!string.IsNullOrEmpty(nextToken));

Debug.Log($"Total annotations exported: {allAnnotations.Count}");

Understanding the export format

The export format includes additional metadata not available in standard annotation queries:

• AssetName: The human-readable name of the asset where the annotation is located
• AnnotationUrl: A direct URL to view the annotation in the Unity Dashboard or web interface
• IssueIds: List of Jira or other issue tracking system IDs linked to this annotation
• Standard Annotation Data: All regular annotation properties (body, status, created date, etc.)

This enriched format is ideal for:

• Generating reports on annotation activity
• Integrating with external systems
• Creating backups with full context
• Analyzing annotation patterns across projects

For related annotation operations, see documentation on searching annotations and reading annotations.

See the API documentation for more details on the ExportAnnotationsAsync method.