Use case: Read annotations across organization with entity mention filtering

Before you start

Before you search for annotations across an organization by entity mention, 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 multiple projects with entity mention filtering

To retrieve annotations across an organization filtered by entity mentions, follow these steps:

  1. Prepare the Organization Identifier: Ensure you have the correct organization identifier (GUID) for your organization.
  2. Prepare Project Identifiers: Ensure you have a list of project identifiers (GUIDs) for the projects you want to search within. The endpoint will aggregate annotations from all these projects.
  3. Prepare entity mention filters: Prepare entity mention IDs to filter annotations that mention specific entities (users, assets, hashtags, etc.).
  4. Prepare entity type filter (optional): Optionally specify the entity type to filter by (e.g., "user", "hashtag", "asset").
  5. Prepare fields to include: Prepare a list of fields to include in the response (e.g., Attachments, ReplyUsers, ReplyCount, LatestReply).
  6. Execute Search: Use the SDK to search for annotations across the organization.
  7. Verify Result: Check that the returned annotation list contains the annotations you expected to find from across the specified projects.
  8. Access Annotation Details: Once found, you can access properties of the annotations.

Example:

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

var mentionEntityIds = new List<string>() { "entity-123", "entity-456" };
var includeFields = new List<IncludeField>() { IncludeField.Attachments, IncludeField.ReplyUsers };

var constraints = new RequestConstraintsByMention(includeFields, mentionEntityIds);

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

Filter by specific entity types

You can filter annotations by entity type to narrow down your search:

Get annotations mentioning specific users:

var mentionEntityIds = new List<string>() { "user-123", "user-456" };

var constraints = new RequestConstraintsByMention(mentions: mentionEntityIds, mentionEntityType: MentionEntityType.User);

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

Get annotations mentioning specific hashtags:

var mentionEntityIds = new List<string>() { "important", "bug" };

var constraints = new RequestConstraintsByMention(mentions: mentionEntityIds, mentionEntityType: MentionEntityType.Hashtag);

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

Get annotations mentioning specific assets:

var mentionEntityIds = new List<string>() { "asset-guid-123" };

var constraints = new RequestConstraintsByMention(mentions: mentionEntityIds, mentionEntityType: MentionEntityType.Asset);

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

Use pagination for large result sets

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

var filteringOptions = new FilteringOptionsWithSortingField(limit: 20);

var result = await annotationManagement.ReadAnnotationsByEntityMentionAcrossOrganizationAsync(
    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.ReadAnnotationsByEntityMentionAcrossOrganizationAsync(
        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: 20, sortingOrder: SortOrder.Ascending, sortingField: SortingField.AnnotationId);

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

Sort by latest reply (most recent activity first):

var includeFields = new List<IncludeField>() { IncludeField.LatestReply }
var constraints = new RequestConstraintsByMention(includeFields: includeFields);

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

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

Available entity types

The following entity types can be used for filtering:

  • user: Filter annotations mentioning specific users
  • hashtag: Filter annotations mentioning specific hashtags
  • asset: Filter annotations mentioning specific assets

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 reply
  • 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 entity mention, searching annotations across organization, and updating an annotation.

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