Use case: Search annotations by target or AssetID with UserID filtering

Before you start

Before you search for annotations by target, ensure you have completed the following prerequisites:

  1. Understand Target Uniqueness: Each annotation is uniquely associated with a specific target in your project. The target represents the exact object, asset, location, or element to which the annotation is attached.
  2. Verify Permissions: Ensure you have the necessary access rights to view the annotation and its related target within your project.
  3. Obtain Target Identifier: You'll need the unique identifier of the target object to which the annotation is attached. This could be:
    • An asset GUID
    • A specific location reference
    • Any other form of target identifier used in your project
  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 your project organization to correctly interpret the annotation once found.

How do I...?

Find annotations of an asset

To retrieve the annotations of an asset, follow these steps:

  1. Prepare the Project Identifier: Ensure you have the correct project identifier (GUID) for the project you want to search for.
  2. Prepare Asset Identifier: Ensure you have the correct and complete asset identifier (GUID) for the asset you want to search for.
  3. Prepare values for filtering: Prepare a lists of user ids for filtering and list of fields to include in response
  4. Execute Search: Use the SDK to search for the annotation associated with the specific target.
  5. Verify Result: Check that the returned annotation list contains the annotation you expected to find. If multiple annotations exist for the target (which may occur in some system configurations), you might need to filter further.
  6. Access Annotation Details: Once found, you can access properties of the annotation.

Example:

var userIDs = new List<UserID>() { developerID, designerID };
var includeFields = new List<IncludeField>() { IncludeField.Attachments, IncludeField.ReplyUsers };

ReadAnnotationsResult result = await annotationManagement.ReadAnnotationsByMentionAsync(projectId, assetId, userIDs, includeFields, cancellationToken);

Find annotations by target

To locate annotations using their target identifier, follow these steps:

  1. Prepare the Project Identifier: Ensure you have the correct project identifier (GUID) for the project you want to search for.
  2. Prepare Target Identifier: Ensure you have the correct and complete target identifier for the annotation you want to find.
  3. Prepare values for filtering: Prepare a lists of user ids for filtering and list of fields to include in response
  4. Execute Target Search: Use the SDK to search for the annotation associated with the specific target.
  5. Verify Result: Check that the returned annotation list contains the annotation you expected to find. If multiple annotations exist for the target (which may occur in some system configurations), you might need to filter further.
  6. Access Annotation Details: Once found, you can access properties of the annotation.

Example:

var target = "assets/projects/{projectID}/assets/{assetID}";
var userIDs = new List<UserID>() { developerID, designerID };
var includeFields = new List<IncludeField>() { IncludeField.Attachments, IncludeField.ReplyUsers };

ReadAnnotationsResult result = await annotationManagement.ReadAnnotationsByMentionAsync(projectId, target, userIDs, includeFields, cancellationToken);

For related annotation operations, see documentation on updating an annotation and finding replies to an annotation.