Use case: Create an attachment in an annotation

Before you start

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

1. Verify Permissions: Confirm that you have the necessary rights to add attachments to annotations. This typically requires being the annotation creator or having appropriate project permissions.
2. Existing Annotation: You must have an existing annotation to which you want to add the attachment. Make sure you have its unique identifier.
3. Prepare Attachment Content: Have the content you wish to attach ready. This could be:
   • An image file (PNG, JPG, etc.)
   • A document (PDF, DOC, etc.)
   • A reference to a Unity asset
   • A URL to external content
   • Any other supported attachment type

How do I...?

You have two options to create an attachment:

Create an attachment to an existing annotation

Attach a file to an annotation

To add a file attachment to an existing annotation:

1. Identify the Project Identifier: Ensure you have the correct project identifier (GUID) for the project.
2. Identify the Annotation: Determine which annotation should receive the attachment.
3. Prepare the File: Get the file ready for uploading.
4. Create the Attachment: Use the SDK to create and associate an attachment with the annotation.
5. Upload the File: After creating the attachment, upload the file content to the provided upload URL.
6. Finalize the Attachment: Ensure the attachment is finalized and available for use in the annotation.

Example:

var attachmentRequest = 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
);

// - or - 

var attachmentRequest = 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
 );

 // - or -

 var attachmentRequest = new CreateSketchAttachmentRequest(
    sketchData: "{ "dataProperty" : "data" }", // JSON with sketch data
    camera: new CameraDetails(), // Replace with actual camera data structure
 );

var result = await annotationManagement.CreateAnnotationAttachmentAsync(
    projectId: projectId,
    annotationId: annotationId,
    requestModel: attachmentRequest,
    cancellationToken: token);
   
var attachmentId = result.AttachmentId;
var uploadUrl = result.UploadUrl;

Use the upload URL to upload the file content and finally finalize the attachment:

await annotationManagement.FinalizeAnnotationAttachmentAsync(
    ProjectController.SelectedProjectId.Value,
    annotationId,
    attachmentId,
    cancellationToken: token);

Create an annotation with attachments

To create an annotation with attachments in one step, look here: Create an annotation with attachments.

Note

The finalization process of an attachment is to notify the server that the attachment's file content has been successfully uploaded.

This means that only FileAttachment(s) and SketchAttachment(s) need to be finalized after uploading their content, whereas Spatial3DAttachment(s) don't, as they don't have a file content.

For more information on working with attachments, see the documentation on updating attachments and deleting attachments.

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