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...?

Follow these steps to create an annotation:

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:
   • 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.

Follow these steps to 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);

Note

Remember to handle the attachment upload process separately after creating the annotation, as the attachment creation may return an upload URL that you need to use to upload the file content and finally finalize the attachment. See the Create an attachment in an annotation guide for more details on how to handle attachments.