Copy Files

Copies files stored in Shotgrid path fields to destination folders on either local or cloud storage. Can be triggered from Versions, Playlists, Deliveries, or other entities.

API Url:

https://app.slingshotsystems.io/ami/<show id>/copy_files/<option>

Configuration¶

Each key under copy_files defines a separate AMI option. The key name becomes the <option> segment of the API URL above.

sg_ami:
  copy_files:
    EXRs_to_staging: # (1)!
      description: Copy EXRs to staging area # (2)!
      trigger_entity: Playlist # (3)!
      copy_versions_where: # (4)!
        - - playlists
          - is
          - ${trigger_entity}
      paths: # (5)!
        - from: $sg_path_to_frames
          to: /Volumes/VFX/_stage/${trigger_entity_name}/${entity.type_mapped}
          is_from_path_frames: true # (6)!
          rename: null # (7)!
          method: hardlink # (8)!
          service: local # (9)!
          create_shared_link: false # (10)!
          path_substitutions: {} # (11)!
      sg_extra_version_fields: [] # (12)!
      sg_extra_entity_fields: [] # (13)!
      sg_field_value_map: # (14)!
        entity::type: # (15)!
          customentity05: Slate
          level: Env
      on_finish: [] # (16)!

Each key under copy_files defines a separate AMI option. This name becomes part of the API URL: .../copy_files/EXRs_to_staging. You can configure multiple named options (e.g. Movies_to_staging, EXRs_to_staging) and each will get its own Shotgrid Action Menu Item.
Optional description for your own reference.
The Shotgrid entity type to install this Action Menu Item on. Common options: Version, Playlist, Delivery, Launch.

When set to Version, the selected Versions are copied directly and copy_versions_where must not be set.

For any other entity type, copy_versions_where is used to find the associated Versions.
Required when trigger_entity is not Version. Shotgrid filters¹ used to find the Versions to copy from the triggering entity.

$trigger_entity is substituted with the triggering entity's type and id at runtime.

If this field is omitted when trigger_entity is not Version, Slingshot will default to [["entity", "is", "$trigger_entity"]], which will match all versions directly linked to the trigger entity.

For trigger entity types that are related to Versions through other fields (for example Playlist via playlists, or Delivery via sg_deliveries), you must set copy_versions_where explicitly.
A list of source/destination path pairs to copy. Multiple paths can be listed to copy several files per version in one operation. See template variables below.
If true, treats the from path as a frame sequence directory and copies the entire folder rather than a single file.
Optional: if set, the copied file will be renamed to this value at the destination.
File operation to perform: copy, hardlink, or move.

Note

Hardlinks are not supported on s3, box, or aspera_files services.
File storage service for this path: local, s3, box, maxlo, or aspera_files.
If true, generates a shared link for the copied file and displays it in the job results. Not supported for the local service.
An optional mapping of path substitutions to apply before performing the copy — useful for cross-platform drive letter remapping.
```
path_substitutions:
  "z:\\": /Volumes/z_drive
```
Additional Shotgrid Version fields to fetch. Useful when you need deep-linked field values in path templates that aren't returned by default (e.g. sg_task.Task.content).
Additional fields to fetch from the triggering entity (e.g. Playlist, Delivery). Useful for dot-notation templates like ${trigger_entity.sg_custom_field}.

Note

Accepts the deprecated alias sg_extra_playlist_fields.
A hard-coded map of field value substitutions. For each named field, the matching value can be used in a template by adding _mapped, e.g. ${sg_vendor_mapped}.

Use the special key DEFAULT to catch any pre-template value not explicitly listed.
```
sg_field_value_map:
  sg_vendor:
    "Studio VFX": studio_vfx
    "Partner HQ": partner_hq
    DEFAULT: unknown_vendor
```
You can use "::" syntax to target nested fields, e.g. sg_task::content becomes ${sg_task.content_mapped}.
Optional: a list of finish actions to run after all copy operations are complete.

Template Variables¶

You can use template variables in paths which will be substituted at runtime.

All Shotgrid Version field codes are available as template variables (e.g. $sg_path_to_movie, $code, $sg_status_list).

Deep linked Version fields (e.g. ${sg_task.Task.content}) are also available but must be explicitly included in sg_extra_version_fields.

The following additional variables are available:

Variable	Value
`$trigger_entity_name`	Display name of the triggering entity (e.g. Playlist name)
`${trigger_entity.field_code}`	Any field on the triggering entity, e.g. `${trigger_entity.sg_type}`
`${trigger_entity.EntityType.field_code}`	Any deep linked field on the triggering entity, e.g. `${trigger_entity.Shot.code}` for the linked Shot's name. Note you must include deep linked fields explicitly in `sg_extra_entity_fields`.
`${trigger_entity_to.EntityType.field}`	Fields on entities linked via the trigger entity's "to" field (e.g. `${trigger_entity_to.Group.code}` for the name of the vendor that the playlist `to` field is set to.)
`$date`	Current date in `YYYY-MM-DD` format

trigger_entity_to

Some triggering entities have a configured "to" field containing related recipient entities:

Trigger Entity	"To" Field
Playlist	`sg_slingshot_copy_to`
Delivery	`addressings_to`
Launch	`sg_vendor_groups`

When ${trigger_entity_to.EntityType.field} is used in a to path, Slingshot will generate one copy operation per recipient entity on that field. For example, if a Playlist has three Groups in sg_slingshot_copy_to, and ${trigger_entity_to.Group.code} is used in the to path, the file will be copied three times — once to each group's folder.

on_finish¶

After all copy operations complete, one or more finish actions can be run.

Currently the only supported action is update_sg_entity.

update_sg_entity¶

Updates Shotgrid entities based on the copy results.

This can be used to automatically update Shotgrid fields (e.g. sg_path_to_frames, sg_status_list) on the Versions that were copied, or to set summary fields (e.g. sg_slingshot_copied_count) on the triggering entity (e.g. Playlist) itself.

on_finish:
  - name: update_sg_entity # (1)!
    entity: version # (2)!
    data: # (3)!
      sg_path_to_frames: $to_path1
      sg_status_list: rev
  - name: update_sg_entity
    entity: trigger_entity # (4)!
    data:
      sg_slingshot_copied_count: $copied_file_count
      sg_slingshot_copy_date: $date

The finish action module.
version updates each Version's Shotgrid fields after they're copied.

trigger_entity updates each trigger entity's Shotgrid fields once after all of its Versions have been processed.

Note

entity: trigger_entity cannot be used when trigger_entity: Version as there is no triggering entity in that case.
A mapping of Shotgrid field codes to values. Values are templated before submitting. See on_finish template variables below.

If a required template variable is missing for a specific Version (e.g. the source path was empty), that Version's update will be skipped with a warning rather than failing the entire job.
When targeting trigger_entity, only aggregate variables are available — per-copy path tokens ($to_path1, etc.) cannot be used.

on_finish Template Variables¶

entity: version¶

All Version Shotgrid field codes are available, plus:

Variable	Value
`$to_path1`, `$to_path2`, …	Full destination path for copy path index N (includes rename if set)
`$to_dir1`, `$to_dir2`, …	Destination directory for copy path index N
`$from_path1`, `$from_path2`, …	Resolved source path for copy path index N
`$from_dir1`, `$from_dir2`, …	Source directory for copy path index N
`$trigger_entity_name`	Display name of the triggering entity
`${trigger_entity.field_code}`	Any field on the triggering entity
`$date`	Copy job start date in `YYYY-MM-DD` format

Path indices are 1-based and match the order of entries in the paths list. Unindexed tokens (e.g. $to_path with no number) are not supported.

If a path was not successfully copied for a particular Version, any template variables for that path index will be missing and the update for that Version will be skipped with a warning.

entity: trigger_entity¶

Trigger entity Shotgrid fields are available as ${trigger_entity.field_code}, plus:

Variable	Value
`$trigger_entity_name`	Display name of the triggering entity
`${trigger_entity.id}`	Shotgrid ID of the triggering entity
`${trigger_entity.type}`	Entity type of the triggering entity
`${trigger_entity.field_code}`	Any field on the triggering entity
`$copied_version_count`	Number of Versions that had at least one file copied
`$copied_file_count`	Total number of files copied across all Versions
`$copied_size`	Human-readable total bytes copied (e.g. `1.2 GiB`)
`$date`	Copy job start date in `YYYY-MM-DD` format

Per-copy path tokens ($to_path1, $from_path1, etc.) are not available for entity: trigger_entity.

For information on the filter syntax, see: Shotgrid REST API - Searching ↩