Use case: Read annotations across organization with profile filtering

Before you start

Before you search for annotations across an organization, ensure you have completed the following prerequisites:

1. Organization Access: Ensure you have the necessary permissions to access annotations across multiple projects within your organization.
2. Verify Permissions: Ensure you have the necessary access rights to view annotations within the projects you want to query.
3. Understand Project Scope: The endpoint aggregates annotations from all specified projects the user has access to within the organization.
4. Set Up SDK Environment: Confirm that your Unity environment is correctly configured with the Collaboration SDK to interact with the annotation system.
5. Consider Project Context: Be aware of the projects you want to query to correctly interpret the aggregated annotations.

How do I...?

Read annotations across organization with profile filtering

To retrieve annotations across an organization with profile-based filtering, follow these steps:

1. Prepare the Organization Identifier: Ensure you have the correct organization identifier (GUID) for your organization.
2. Prepare filtering profiles: Prepare a list of base profiles to filter annotations (e.g., All, Active, Resolved, Draft, Sending, HasJiraTickets).
3. Prepare fields to include: Prepare a list of fields to include in the response (e.g., Attachments, ReplyUsers, ReplyCount, LatestReply).
4. Execute Search: Use the SDK to search for annotations across the organization.
5. Verify Result: Check that the returned annotation list contains the annotations you expected to find from across the organization.
6. Access Annotation Details: Once found, you can access properties of the annotations.

Example:

var organizationId = new OrganizationId("5772925064011");
var organizationReference = new OrganizationReference(organizationId);

var baseProfile = new List<BaseProfile>() { BaseProfile.All, BaseProfile.Active };
var includeFields = new List<IncludeField>() { IncludeField.Attachments, IncludeField.ReplyUsers };

var constraints = new RequestConstraintsByBaseProfile(includeFields, baseProfile);

ReadAnnotationsResult result = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
    organizationReference,
    constraints: constraints,
    cancellationToken);

Filter annotations by specific profiles

You can apply different base profiles to filter the results:

Get all active annotations across projects:

var baseProfile = new List<BaseProfile>() { BaseProfile.All, BaseProfile.Active };
var constraints = new RequestConstraintsByBaseProfile(baseProfile: baseProfile);

var result = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
    organizationReference,
    constraints: constraints,
    cancellationToken: cancellationToken);

Get only resolved annotations:

var baseProfile = new List<BaseProfile>() { BaseProfile.All, BaseProfile.Resolved };
var constraints = new RequestConstraintsByBaseProfile(baseProfile: baseProfile);

var result = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
    organizationReference,
    constraints: constraints,
    cancellationToken: cancellationToken);

Get only threads (root annotations):

var baseProfile = new List<BaseProfile>() { BaseProfile.AnnotationThreads };
var constraints = new RequestConstraintsByBaseProfile(baseProfile: baseProfile);

var result = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
    organizationReference,
    constraints: constraints,
    cancellationToken: cancellationToken);

Get annotations with Jira tickets:

var baseProfile = new List<BaseProfile>() { BaseProfile.All, BaseProfile.HasJiraTickets };
var constraints = new RequestConstraintsByBaseProfile(baseProfile: baseProfile);

var result = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
    organizationReference,
    constraints: constraints,
    cancellationToken: cancellationToken);

Use pagination for large result sets

When dealing with many annotations across multiple projects, use pagination:

var baseProfile = new List<BaseProfile>() { BaseProfile.All };
var constraints = new RequestConstraintsByBaseProfile(baseProfile: baseProfile);

var filteringOptions = new FilteringOptionsWithSortingField(limit: 20);

var result = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
    organizationReference,
    constraints,
    filteringOptions,
    cancellationToken: cancellationToken);

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

    var nextResult = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
        organizationReference,
        constraints,
        filteringOptions,
        cancellationToken: cancellationToken);
}

Sort results by different fields

You can sort annotations by annotation ID or latest reply:

Sort by annotation ID (creation order):

var filteringOptions = new FilteringOptionsWithSortingField(limit: 10, sortingOrder: SortOrder.Ascending, sortingField: SortingField.AnnotationId);

var result = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
    organizationReference,
    constraints,
    filteringOptions,
    cancellationToken);

Sort by latest reply (most recent activity first):

var baseProfile = new List<BaseProfile>() { BaseProfile.All };
var includeFields = new List<IncludeField>() { IncludeField.LatestReply };
var constraints = new RequestConstraintsByBaseProfile(includeFields, baseProfile);

var filteringOptions = new FilteringOptionsWithSortingField(limit: 10, sortingOrder: SortOrder.Descending, sortingField: SortingField.LatestReply);

var result = await annotationManagement.ReadAnnotationsByProfileAcrossOrganizationAsync(
    organizationId,
    constraints,
    filteringOptions,
    cancellationToken);

Available base profiles

The following base profiles can be combined to filter annotations:

• All: Include all annotations (baseline for other filters)
• AnnotationThreads: Include only root annotations (not replies)
• Active: Include only active annotations
• Resolved: Include only resolved annotations
• Unresolved: Include only unresolved annotations
• Draft: Include only draft annotations
• Sending: Include only annotations in sending status
• HasJiraTickets: Include only annotations with linked Jira tickets

Available include fields

The following fields can be included in the response:

• Attachments: Include attachment information
• ReplyUsers: Include list of users who replied
• ReplyCount: Include count of replies
• LatestReply: Include timestamp of latest repl~~~~y
• AnnotationThreadAttachmentsCount: Include count of attachments per thread
• ReplyLastReadTimestamp: Include timestamp of when current user last read replies
• ReplyUnreadCount: Include count of unread replies for current user

Available sorting fields

• annotationId: Sort by annotation creation order
• latestReply: Sort by most recent reply~~~~ activity

For related annotation operations, see documentation on searching annotations by profile and updating an annotation.

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