Use case: Read the upload url for a file attachment of an annotation

Before you start

Before you retrieve an upload URL for a file attachment, ensure you have completed the following prerequisites:

  1. Verify Permissions: Confirm that you have the necessary rights to create or update attachments for annotations. This typically requires being the annotation creator or having appropriate project permissions.
  2. Create Attachment Record First: Understand that getting an upload URL is part of a two-step process:
    • First, create or identify an attachment record in the system
    • Then, get an upload URL to actually transfer the file content
  3. Prepare File Information: Have details about the file you plan to upload, including:
    • File name
    • MIME type
    • Size (to ensure it doesn't exceed limits)
    • Content to be uploaded
  4. Understand URL Expiration: Be aware that upload URLs provided by the Collaboration system are temporary and expire after a certain period (usually 24 hours or less). They should be used promptly rather than stored long-term.
  5. Set Up SDK Environment: Ensure your Unity environment is properly configured with the Collaboration SDK to interact with the annotation system.

How do I...?

Get an upload URL for a newly created attachment

To retrieve an upload URL for a new file attachment:

  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 and complete asset identifier (GUID) for the asset.
  3. Obtain the Attachment ID: Ensure you have the unique identifier for the specific attachment you want to get the upload url for. Use the SDK to create a new attachment record. This step is necessary to establish the context for the upload.
  4. Request the Upload URL: Use the SDK to request a temporary upload URL for the attachment.
  5. Use the URL Promptly: Remember that the upload URL has a limited validity period.

Example:

var response = await annotationManagement.ReadAnnotationFileAttachmentDownloadUrlAsync(
  projectId: projectId,
  annotationId: annotationId,
  attachmentId: attachmentId,
  cancellationToken: cancellationToken);

var downloadUrl = response.Url;

Get an upload URL for updating an existing attachment

If you need to update the file content of an existing attachment:

  1. Identify the Existing Attachment: Determine which attachment needs to be updated.
  2. Request a New Upload URL: Get a fresh upload URL for the existing attachment.
  3. Consider Metadata Updates: If the file type or name is changing, update the attachment metadata as well.

Upload a file using the obtained URL

Once you have the upload URL, you'll need to actually upload the file:

  1. Prepare the File Content: Get the file data ready for uploading.
  2. Execute the Upload: Use the URL to upload the file content.
  3. Handle Upload Progress: For larger files, consider implementing progress tracking and user feedback.
  4. Implement Retry Logic: For transient issues, consider adding retry functionality with appropriate backoff.
Note

Upload URLs are temporary and should be used promptly after retrieval. The upload step is a critical part of the attachment process. Without it, the attachment exists in the system but contains no actual file data. Always ensure the upload completes successfully.

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