Skip to content

Working with Files (Attachments)

Jump to bottom
beccadownes edited this page Feb 28, 2012 · 3 revisions

Working With Attachments

Introduction

As of Shotgun v2.2.0 the Attachment entity is available via the API. An Attachment entity in the API shows up in the Shotgun UI as a File (on a Files page, or a Files tab in a detail page, for example). You can access Attachments directly to create and modify uploaded files, url links, and local files, and link them to other entities (Shots, Versions, etc). This entity works a lot like other entity types within Shotgun with a few exceptions which are detailed below.

Requirements

  • Python API v3.0.3+
  • Shotgun v2.2.0+

Default structure

The following lists the default fields that Shotgun creates for Attachments. Your instance may look different. Many of these fields are optional, some are automatically filled in. These exceptions are listed below in the descriptions of each field.

  • description "string" (Description)
  • this_file {dictionary} (File)
  • filename "string" (File Name)
  • file_size integer (File Size)
  • id integer (Id)
  • attachment_links [list] (Links)
  • open_notes [list] (Open Notes) * Read-only
  • open_notes_count integer (Open Notes Count) * Read-only
  • project {dictionary} (Project) entity field linking the Attachment to a single Project
  • attachment_reference_links {dictionary} (Reference For) multi-entity field for linking Attachment to multiple entities when used as reference
  • sg_status_list "string" (Status) status field returned as the short code
  • tag_list [list] (Tags) list of Tags linked to the Attachment as strings
  • image "string" (Thumbnail) url of the associated thumbnail
  • sg_type "string" (Type) used to classify Attachments

description

Optional field to provide descriptive text about the file.

this_file (on_create only)

this_file is the actual file reference and is represented by a dictionary. Within the dictionary is a new link_type key which designates the Attachment as an uploaded file, a url link, or a local file. There are also additional keys returned for local files only. You cannot modify this field after you have created an Attachment.

  • Uploads Designated by link_type: 'upload', this is represents a file that was uploaded to Shotgun. Uploading files to Shotgun is currently done using the upload() method of the API. You cannot create an Attachment with an uploaded file directly.
  {'content_type': 'image/jpeg',
   'link_type': 'upload',
   'name': 'western1FULL.jpg',
   'url': 'https://superdeathcarracer.shotgunstudio.com/file_serve/attachment/538'}
  • Web links Designated by link_type: 'web', this is represents a url link. Examples include an 'http://' link to another server or a custom protocol used to launch a local application like 'rvlink://' or 'cinesync://'
  {'content_type': None,
   'link_type': 'web',
   'name': 'Join GUN12158',
   'url': 'cinesync://session/GUN12158'}
  • Local Files Designated by link_type: 'local', this is represents a local file link. Additional keys are provided in order to give access to the relative path information on other platforms. For more information on each of these key values see Working With Local Files.
  { 'content_type': 'video/quicktime',
    'link_type': 'local', 
    'name': 'my_test_movie.mov', 
    'local_path': '/Users/kp/Movies/testing/test_movie_002.mov' 
    'local_path_linux': '/home/users/macusers/kp/Movies/testing/test_movie_002.mov'
    'local_path_mac': '/Users/kp/Movies/testing/test_movie_002.mov'
    'local_path_windows': 'M:\\macusers\kp\Movies\testing\test_movie_002.mov'
    'local_storage': {'id': 1,
                      'name': 'Dailies Directories',
                      'type': 'LocalStorage'},
    'url': 'file:///Users/kp/Movies/testing/test_movie_002.mov'}

filename

For uploaded files only. This is automatically assigned when the file is uploaded and stores the filename of the file.

file_size

For uploaded files only. This is automatically assigned when the file is uploaded and stores the size of the file in bytes.

id (read-only)

The internal unique Shotgun id for this Attachment

attachment_links

A list of entity dictionaries used for linking Attachments to multiple entities.

open_notes (read-only)

A List of Note entities linked to the current Attachment that have a status that does not equal 'clsd'. This is a read-only field.

open_notes_count (read-only)

An integer count of the list of Note entities linked to the current Attachment that have a status that does not equal 'clsd'. This is a read-only field.

project (required)

Required field. The Project entity that this Attachment belongs to. This must be assigned when creating an Attachment.

attachment_reference_links

Similar to attachment_links but used specifically for linking files to entities as reference.

sg_status_list

Standard status field for tracking statuses.

tag_list

List of tags that are currently assigned to the Attachment.

image

The url location of the thumbnail image assigned to this Attachments. For uploads, Shotgun automatically tries to create a thumbnail from the file using ImageMagick. Essentially, the formats that ImageMagick supports are the formats that Shotgun supports. Alternatively, you can assign your own thumbnail to an Attachment using the upload_thumbnail() method.

sg_type

An optional field for designating different types of Attachments

Creating Attachments

  • Web Links

myurl = { 
  'url': 'http://apple.com/itunes',
  'name': 'Apple: iTunes' 
  }
data = {
    'this_file': myurl,
    'project': {'type':'Project','id':64}}         
result = sg.create('Attachment', data)

  • Uploads

Currently uploads cannot be created directly on Attachments. Instead, you need to use the upload() method. We have plans to change this in the near future.

  • Local Files

When setting a file/link field value to a local file, only the local_path is mandatory. Shotgun will automatically select the appropriate matching local storage for your file based on the path. You can optionally specify the name and content_type fields if you wish to override their defaults. Any other keys that are provided will be ignored.

  • content_type: string (optional) the mime-type of the associated local file. This is assigned automatically using a best-guess based on the file extension.
  • name: string (optional) the display name of the local file. This is set to the filename by default.
  • local_path: string the full path to the file. Shotgun will find the LocalStorage that has the most specific match to this path and automatically assign that LocalStorage to the file.
my_local_file = {
    'this_file': {
        'local_path': '/Users/kp/Movies/testing/test_movie_002.mov',
        'name': 'Better Movie'
        },
    'attachment_links': [{'type':'Version','id':88}],
    'project': {'type':'Project','id':64}
    }
result = sg.create('Attachment', my_local_file)

result is:

{ 'attachment_links': [{'id': 88,
                        'name': 'testv1',
                        'type': 'Version',
                        'uuid': '625482fa-ea09-11df-ad0b-003048d17544'}],
  'id': 369,
  'project': {'id': 64, 'name': 'QA', 'type': 'Project'},
  'this_file': {'content_type': 'video/quicktime',
                'link_type': 'local', 
                'local_path': '/Users/kp/Movies/testing/test_movie_002.mov' 
                'local_path_linux': '/home/users/macusers/kp/Movies/testing/test_movie_002.mov'
                'local_path_mac': '/Users/kp/Movies/testing/test_movie_002.mov'
                'local_path_windows': 'M:\\macusers\kp\Movies\testing\test_movie_002.mov'
                'local_storage': {'id': 1,
                                  'name': 'Dailies Directories',
                                  'type': 'LocalStorage'},
                'name': 'Better Movie', 
                'url': 'file:///Users/kp/Movies/testing/test_movie_002.mov'}, 
 'type': 'Attachment'}]

The content_type was assigned a best-guess value based on the file extension. Shotgun selected the most appropriate specific LocalStorage match and assigned it to local_storage automatically. For more information see Working With Local Files

Updating Attachments

Since you cannot modify the this_file field after you create an Attachment, the process for updating Attachments exactly like updating other entity types in Shotgun and is the same for all Attachments.

result = sg.update('Attachment', 369, {'description': 'This file is awesome'})

result is

[{'description': 'This file is awesome', 'id': 369, 'type': 'Attachment'}]

Deleting Attachments

The process of deleting an Attachment is just like other entities in Shotgun

result = sg.delete('Attachment', 369)

result is

True
Clone this wiki locally