Use case: Create an annotation

Before you start

Before you create an annotation, ensure you have completed the following prerequisites:

  1. Verify Permissions: Check that you have the required Annotation Creator role or equivalent permissions within the system to create annotations.
  2. Set Up Unity Environment: Ensure that your Unity Editor environment is linked to the correct organization and project to manage annotations effectively.
  3. Review the API Documentation: Familiarize yourself with the appropriate endpoint for creating annotations as outlined in the Swagger documentation.

How do I create an annotation?

You have two options for creating an annotation:

Create an annotation with no attachments:

  1. Obtain the Project Identifier: Ensure you have the correct project identifier (GUID) for the project.
  2. Obtain the Asset Identifier: Ensure you have the correct asset identifier (GUID) for the asset you want to add the annotation to.
  3. Define the Annotation text: Prepare the text content for the annotation. Keep in mind that there are restrictions for the text content:
    • Can be null
    • If not null, it must be less than 10,000 characters
    • Cannot be empty or contain only whitespace characters
    • Cannot start or end with whitespace characters
  4. Use the SDK: Call the CreateAnnotationAsync method in the Unity Collaboration SDK with the required properties.
  5. Handle Responses: Ensure your implementation verifies whether the annotation was successfully created and handles any errors appropriately.
  6. Refresh Annotations View: If your project has a UI displaying annotations, refresh the view to include the newly created annotation.

Example:

var text = "Updated annotation content with new information.";

var annotationId = await annotationManagement.CreateAnnotationAsync(
    projectId: projectId,
    assetId: assetId,
    text: text,
    cancellationToken: cancellationToken);
    
// The status will be set to `Active` by default, but you can specify it if needed.

Using this method, you can create an annotation without attachments. Attachments can be added later using the Create an attachment in an annotation guide.

Create an annotation with attachments:

  1. Obtain the Project Identifier: Ensure you have the correct project identifier (GUID) for the project.
  2. Obtain the Asset Identifier: Ensure you have the correct asset identifier (GUID) for the asset you want to add the annotation to.
  3. Define the Annotation text: Prepare the text content for the annotation.
  4. Prepare Attachments: If you want to include attachments, prepare a list of ICreateAttachmentRequest objects with the necessary properties for desired type of attachment (file or spatial-3d).
  5. Use the SDK: Call the CreateAnnotationAsync method in the Unity Collaboration SDK with the required properties.
  6. Handle Responses: Ensure your implementation verifies whether the annotation was successfully created and handles any errors appropriately.
  7. Refresh Annotations View: If your project has a UI displaying annotations, refresh the view to include the newly created annotation.

Example:

var text = "Updated annotation content with new information.";

var attachments = new List<ICreateAttachmentRequest>
{
    new CreateFileAttachmentRequest(
        filePath: "/path/to/attachment.jpg", // Replace with actual file path
        fileSize: 120500, // Replace with actual file size
        fileType: "image", // Replace with actual file type
        contentType: "image/jpeg" // Replace with actual content type
    ),
    new CreateSpatial3DAttachmentRequest(
        label: "text-for-the-label", // Replace with actual text
        position: new SpatialPosition(), // Replace with actual spatial attachment position
        camera: new CameraDetails(), // Replace with actual camera data structure
        time: new TimeDetails(), // Replace with actual time data structure, optional parameter
        local: new LocalSpaceDetails(), // Replace with actual local space details, optional parameter. Contains data for the attachment with spatial parameters that are relative to parent
    ),
    new CreateSketchAttachmentRequest(
        sketchData: "{ "dataProperty" : "data" }", // JSON with sketch data
        camera: new CameraDetails(), // Replace with actual camera data structure
    )
};

var annotationId = await annotationManagement.CreateAnnotationAsync(
    projectId: projectId,
    assetId: assetId,
    text: text,
    attachments: attachments,
    cancellationToken: token);

How do I add a mention to an annotation?

To mention a user in an annotation, in the text field, use the format :user[username]{#user_id}.

For example :user[Jane Doe]{#9876543211011}, where Jane Doe is the user's display name and 9876543211011 is the user's Unity ID. The username is used when rendering the Annotation for display; in this case, @Jane Doe will be displayed.

Note

Please note that the CreateAnnotationAsync method, when used with attachments, does not return the attachment IDs. In this case, in order to obtain the attachment IDs, you can use the ReadAnnotationAsync method and check the Attachments property of the returned IAnnotation object.

See the Read an annotation guide for more details on how to handle attachments.

See the Create an attachment in an annotation guide for more details on how to handle attachments.

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