Your Work Files

ShotGrid Workfiles

Using this app you can browse, open and save your Work Files and Publishes.
Latest Version: v0.13.0 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-multi-workfiles2

Please Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for more details.
Overview Summary
            File Open dialog
                  Navigating your work areas
                  Finding files
                  Accessing previous versions
                  User sandboxes
                  Narrowing results
            File Save dialog
                  Saving in a different context
                  Adding the file extension dropdown
            Context Change dialog
            Step filtering
            Deferred queries
            Known Issues
Installation, Updates and Development
Configuration Options
Release Notes History

This application forms the basis for file management in the Shotgun Pipeline Toolkit. It lets you jump around quickly between your various Shotgun entities and gets you started working quickly. No path needs to be specified as the application manages that behind the scenes. The application helps you manage your working files inside a Work Area and makes it easy to share your work with others.


File Open dialog

Navigating your work areas

The main dialog is split in two halves. On the left hand side, there is a series of tabs. The first tab is called "My Tasks" and will display all the tasks that are assigned to the current user. It is very reminiscent of the "My Tasks" page on the Shotgun website.

Alternatively, the user can also browse for a Shotgun entity using the entities tabs. By default, the workfiles application allows to browse for any tasks associated on shots or assets by looking at the respective tab.

The set of tabs is entirely configurable through the entities settings in the environment files.

You can disable/enable this dialog by setting the show_file_open: true/false in the app settings.

Finding files

On the right hand-side you will see the working files and publishes associated with the selection from the left hand-side. Working files and publishes can be viewed together or separately using the tabs "All", "Working" and "Publishes".

Accessing previous versions

There are two ways to access previous versions. First, the user can click on the "All versions" box at the top of the browser, which will uncollapse the versions and list them all individually in the browser. Another option is to right-click on a file, which will allow you to access the last 10 versions.

User sandboxes

If your pipeline configuration uses user sandboxes, only the files for the current user will be seen by default. If the user wants to see the files from other user's sandboxes, a button at the top will allow to pick which sandboxes to show files from.

Narrowing results

You can narrow results in the any of the views by typing text. The search will match any item's name.

File Save dialog

By default, the "File Save" dialog allows the user to save a file in the current context. The user will be prompted for a scene name, version number and an optional file extension, if available and the "Save" button will be greyed out. Only once the application has confirmed the next available version number for a scene name will the Save button at the bottom right be enabled.

You can disable/enable this dialog by setting the show_file_save: true/false in the app settings.

Saving in a different context

In order to save a file in a different context, a user can click on the expand button at the top-left of the dialog which will expand the "File Save" dialog and allow to pick another context to save into.

Adding the file extension dropdown

With the new file save dialog, it is possible to pick the extension of the file being saved. In order to enable this, you need to tweak your pipeline configuration's templates.yml file. First, a token needs to be defined in the token list inside templates.yml.

    type: str
        ma: Maya Ascii (.ma)
        mb: Maya Binary (.mb)
    default: ma
    alias: extension

maya_extension is the token's name. choices is a dictionary of file types that will be displayed in the dropdown. The keys (ma and mb) are the possible values that this template token can have. The values (Maya Ascii (.ma) and Maya Binary (.mb)) are UI friendly descriptions that can be used by a Toolkit application. The alias is an hint that is required by the workfiles application. It tells the application that this token is an extension and should be displayed in the dropdown widget.

Then, this token can be added to any Maya specific template.

    definition: '@shot_root/work/maya/{name}.v{version}.{maya_extension}'
    root_name: 'primary'

Context Change dialog

The context change dialog is similar to the open dialog except that it doesn't have a the right hand side for file browsing. You can select a task or entity and change your current engine context by pressing press the change context button.

You can disable/enable this dialog by setting the show_change_context: true/false in the app settings.

Step filtering

When retrieving Tasks, and if step is included in the hierarchy, the amount of data retrieved from Shotgun can be reduced with Pipeline Step filtering: only Tasks linked to the selected list of Steps will be retrieved.

The list of Steps displayed in a tab is controlled with the step_filter_on setting. If not set, all existing Pipeline Steps are displayed.

The example below defines two tabs, respectively displaying Tasks for Assets and Shots:

  - caption: Assets Tasks
    entity_type: Task
    step_filter_on: Asset
    - [entity, type_is, Asset]
    hierarchy: [entity.Asset.sg_asset_type, entity, step, content]
  - caption: Shots Tasks
    entity_type: Task
    step_filter_on: Shot
    - [entity, type_is, Shot]
    hierarchy: [entity.Shot.sg_sequence, entity, step, content]

Deferred queries

For better performances, building the Entities tree can be broken into two step queries: - A first query is used to retrieve records from Shotgun and populate the top of the tree. - A second query is used to retrieve children as the user expand the tree.

With the following settings, Assets and Shots would be retrieved from Shotgun when the app is started. And then Tasks linked to a particular Asset or Shot would only be retrieved when this Asset or Shot is selected or expanded in the tree view.

  - caption: Assets
    entity_type: Asset
    hierarchy: [sg_asset_type, code]
      entity_type: Task
      link_field: entity
      hierarchy: [step]
  - caption: Shots
    entity_type: Shot
    hierarchy: [sg_sequence, code]
      entity_type: Task
      link_field: entity
      hierarchy: [step]

Known Issues

  • 3ds Max and Motionbuilder Support - File performance is slower in these DCCs under Windows compared to Maya and Nuke.
  • Perforce/Versionless files - The application still needs to go through testing with the Perforce workflow so it is very likely that it won't work well.

Related Apps and Documents


The Shotgun Loader lets you quickly overview and browse the files that you have published to Shotgun. A searchable tree view navigation system makes it easy to quickly get to the task, shot or asset that you are looking for and once there the loader shows a thumbnail based overview of all the publishes for that item. Through configurable hooks you can then easily reference or import a publish into your current scene.


The Publish app allows artists to publish their work so that it can be used by artists downstream. It supports traditional publishing workflows within the artist’s content creation software as well as stand-alone publishing of any file on disk. When working in content creation software and using the basic Shotgun integration, the app will automatically discover and display items for the artist to publish. For more sophisticated production needs, studios can write custom publish plugins to drive artist workflows.

Scene Snapshot

A Shotgun Snapshot is a quick incremental backup that lets you version and manage increments of your work without sharing it with anyone else. Take a Snapshot, add a description and a thumbnail, and you create a point in time to which you can always go back to at a later point and restore. This is useful if you are making big changes and want to make sure you have a backup of previous versions of your scene.

Shotgun Pipeline Tutorial

This document provides a step-by-step tutorial for Technical Directors (TDs) wishing to set up a simple, end-to-end pipeline using Shotgun integrations and the Toolkit platform. The goal of the tutorial is to provide users with an understanding of the fundamental aspects of the integrations and platform as well as the know how to build and customize a Shotgun-base pipeline to fit their studio's specific needs.

Installation and Updates

Adding this App to the Shotgun Pipeline Toolkit

If you want to add this app to Project XYZ, in an environment named asset, execute the following command:

> tank Project XYZ install_app asset tk-maya tk-multi-workfiles2

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.19.18 or higher to use this.


Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.


Type: bool

Description: A flag to enable the context change dialog. A context change window is provided where the user can pick an entity to change context to without opening a file.


Type: bool

Default Value: True

Description: A flag to enable the open file dialog. A open file window is provided where the user can pick an entity and select the files associated with that context to open run other actions on.


Type: bool

Default Value: True

Description: A flag to enable the save file dialog. A save file window is provided where the user can save the current workfile to the Toolkit templated folder structure.


Type: bool

Description: A flag whether to launch the UI at application startup. This option is not supported on all engines because of differences in the way some platforms start up. Currently, only maya nuke and 3ds Max support this option.


Type: template

Description: A reference to a template which locates a work file on disk.


Type: template

Description: A reference to a template which locates the work directory on disk


Type: template

Description: A reference to a template which locates a publish file on disk.


Type: template

Description: A reference to a template which locates the publish directory on disk


Type: hook

Default Value: {self}/scene_operation_{engine_name}.py

Description: All the application specific scene operations (open, save etc) that the app needs to carry out are collected together in this hook.


Type: hook

Default Value: {self}/

Description: Specify a hook that will be used to copy the file 'source_path' to 'target_path'.


Type: hook

Default Value: {self}/

Description: Specify a hook that, if needed, can filter the raw list of work files found for the current work area


Type: hook

Default Value: {self}/

Description: Specify a hook that, if needed, can filter the raw list of publishes returned from ShotGrid for the current Work area.


Type: hook

Default Value: {self}/

Description: Specify a hook that, if desired, provides a badge icon to include in the UI when displaying a publish or work file.


Type: hook

Default Value: {self}/

Description: Hook which contains all custom action methods.


Type: hook

Default Value: {self}/

Description: Specify a hook that will create the task and do any input validation that is required.


Type: list

Default Value: [{'caption': 'Assets', 'entity_type': 'Task', 'step_filter_on': 'Asset', 'filters': [['entity', 'type_is', 'Asset']], 'hierarchy': ['entity.Asset.sg_asset_type', 'entity', 'step', 'content']}, {'caption': 'Shots', 'entity_type': 'Task', 'step_filter_on': 'Shot', 'filters': [['entity', 'type_is', 'Shot']], 'hierarchy': ['entity.Shot.sg_sequence', 'entity', 'step', 'content']}]

Description: This setting defines the different tabs that will show up on the left hand side. Each tab represents a ShotGrid query, grouped by some ShotGrid fields to form a tree. This setting is a list of dictionaries. Each dictionary in the list defines one tab, and should have the following keys: caption specifies the name of the tab, entity_type specifies the ShotGrid Entity type to display. filters is a list of standard API ShotGrid filters either in the standard or complex format. hierarchy is a list of ShotGrid fields relative to the entity type, defining the grouping of the tree. An optional sub_query key can be used to define a deferred query which will be run to collect children when an Entity is expanded in the tree view, typically Tasks for a Shot or an Asset. It is a dictionary with the following keys: entity_type key to specify the child Entity type to collect, link_field the ShotGrid field name used to link the Entity to its parent, filters a list of standard ShotGrid API filters, hierarchy a list of fields defining the grouping in the sub-tree. The optional step_filter_on setting is an Entity type and can be used to restrict the list of Steps used for filtering to only the Steps for the specified Entity type.


Type: bool

Default Value: True

Description: Define if the My Tasks view should be visible or not.


Type: bool

Description: Automatically expands the root level of the treeviews.


Type: list

Description: List of additional fields to display with the task in the My Tasks list.


Type: list

Default Value: [['task_assignees', 'is', '{context.user}']]

Description: List of filters to apply to the tasks in the My Tasks tab.


Type: list

Description: List of file extensions to be shown in the work files view. If empty then all files that match the template will be shown.


Type: list

Description: A list of fields that should be ignored when comparing files to determine if they are different versions of the same file. If this is left empty then only the version field will be ignored. Care should be taken when specifying fields to ignore as Toolkit will expect the version to be unique across files that have different values for those fields and will error if this isn't the case.


Type: bool

Default Value: True

Description: Controls whether new tasks can be created from the app.


Type: list

Default Value: ['All', 'Working', 'Publishes']

Description: A list of tab names that are visible in the main browser. Values can be any combination of the following tab names: 'All', 'Working', and 'Publishes'. The order of the specified values determines the order of the tabs in the app.


Type: str

Default Value: scene

Description: The default name that gets used by when saving a work file using the save-as command


Type: bool

Description: Control how the save-as command determines the inital name to be used. If set to True then the name from the current scene will be used and the version incremented. If False then a new unique name will be used and the version reset

Release Notes

Welcome to the release notes for this App. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!



Rebranded to ShotGrid



Switches from using the support email alias to pointing to the support site. Does some cleanup

Details: - Switched to using support_url from tk-core instead of the hard-coded email address. Also using TKMessageBox from tk-core to make sure hyperlinks are clickable and styled - Updated build_resources to use local PySide - Added core_api files to make sure testing is done with the local tk-core instead of the latest app_store version



Added a change context dialog.


  • A new context change dialog has been added, in which the user can select a task or entity and set the current engine context.
  • Support for Mari has been added, however it is intended that only the context change dialog will be used in Mari.
  • New show_context_change, show_file_open, and show_file_save app configurations options have been added so that the three different dialogs can be individually configured to show or not.



Added a parameter to open the dialogs as modal windows.



Increases the maximum save version spinner value to 9999999.



Updated the Houdini scene operation hook to work in Python 3.



Small bug fix and updated the list of supported engines.


  • Fixes rgb Qt styling warnings.
  • Adds Alias and Vred to the supported engines list.



Adds Python 3 support.



The application does not ship with the Blur Python based hooks for 3dsMax anymore.


The tk-3dsmax engine implementation has been upgraded to use pymxs. As such, the old Blur Python based hooks are not compatible anymore with the engine. They can be downloaded from here.



Workfile2 will no longer be initialized if it's being run in an environment where there isn't a UI present.



Bug fix, you can now use the and hooks to modify a file's display name in the UI. Previously if you modified an item's "name", it was ignored.



Adds hooks to allow the specification of a custom badge for Publishes and Versions. This badge is shown as an overlaid icon, similar to the "publish" and "locked" icons.



Resolves an issue with the custom_actions hook when running in some PySide2 environments.



Improved logging around failed context changes.



Minor tweak to correct a PyQt5 incompatibility.



fixes text cutoff issues in workfile display



ability to configure the tabs displayed in the app



We now hide the "my tasks" checkbox in entity tree views when deferred queries are in use.


This feature didn't function properly when deferred queries are used, so it's no longer shown when the app is configured to make use of them. This also hides that same checkbox when script-key authentication is in use and no Shotgun human user can be determined.



Fix for new file action hanging.


Fixes a bug where workfiles2 would cause the whole DCC to hang when the user ran the new file action, and had a version folder in the work file template path.



Fix for deferred mode hanging.


Fix a problem with a deferred setup where expanding items in the tree view could trigger lot of unnecessary requests to Shotgun, causing the app to hang.



Improved performances: Step filtering for Tasks and deferred queries.


It is now possible to reduce the amount of data which is fetched from Shotgun for Tasks by only retrieving Tasks for a given set of pipeline Steps. Step filtering is controlled by a small piece of UI under Entity tabs, is saved in user settings when closing the application, and restored when opening it.

A new sub_hierarchy setting is now available to run two steps queries, the second query being deferred until fetching children from Shotgun is really needed, typically as the user expand the tree view. This can allow to greatly improve performances by not systematically fetching a huge amount of data from Shotgun when the application is started. It must contain the following keys: - entity_type: the target Entity type for the deferred query. - filters: some optional filters to use for the deferred query. - link_field: the Shotgun field name to use to run the deferred query for a given Entity retrieved from the primary query. - hierarchy: A list of Shotgun field names defining the hierarchy to use when showing results from deferred queries in a tree view. Step filtering will be enabled in the UI if a step field name is included in this list.

For example, retrieving Shots grouped by Sequences and deferring Tasks retrieval could be defined with the following settings:

        - caption: Shots
          entity_type: Shot
          hierarchy: [sg_sequence, code]
            entity_type: Task
            link_field: entity
            hierarchy: [step]

An additional optional step_filter_on is now available when not using deferred queries and retrieving Tasks, allowing to only display in the UI pipeline Steps linked to a particular Entity type. For example, when retrieving Tasks for Assets with classic queries:

  - caption: Assets Tasks
    entity_type: Task
    step_filter_on: Asset
    - [entity, type_is, Asset]
    hierarchy: [entity.Asset.sg_asset_type, entity, step, content]

Please note that tk-framework-shotgunutils v5.3.5 or higher is now required for this app.



Eliminates some noise when opening the app in Photoshop.


Fixes some improper exception handling to prevent some noisy output being sent to the console/logs on launch of the app in Photoshop.



Updated metrics logged



Fixes a bug with versioning up work files in user sandboxes.


  • If the project was setup to use user sandbox work areas, and the user opens a file belonging to a different user's work area, but did not have any files in their own area, then it would fail to work out the next version for the copied file. This is now fixed



Modify the file widget layout to account for long file names.


  • The filename, version are no longer truncated in the file browser if too long. The work file name now displays an ellipsis to indicate that it is longer than it appears to be.
  • The version is now listed on the following line (instead of comma-separated name, v001).



Revert default my tasks tab filter behaviour. Now doesn't filter out tasks with fin and omt statuses by default.



Improves app usability with large amounts of tasks


  • Added an option to disable auto expansion of root level nodes in the tree views. They are now set to be collapsed by default.
  • Tree view search box behaviour changed so that it only performs the search after hitting enter, rather than after every character entered.
  • A tooltip has been added to the search box to inform users they must press enter to complete the search.
  • The My Tasks tab filters can now be configured in the same way the custom tabs can. Users can now use the following config option to customise the filters. Example:

    my_tasks_filters: - [task_assignees, is, '{context.user}'] - [sg_status_list, not_in, [fin,omt]]



Removes problematic profiles from png files used as icons.


This will silence libpng warnings from Qt when the png files are loaded as pixmaps. This is a second attempt as this profile stripping, and uses ImageMagick's "mogrify" command to achieve the desired result, which maintains color consistency.



[minor] No longer disables context changes for Photoshop CC on file load.


The tk-photoshopcc engine now handles this case without the need to explicitly disable the active-document monitoring via the previously-used context manager.



Workaround for Hiero not updating save menus



Adds support for tk-photoshopcc.



Updated to use v5 of the shotgun utils framework with improved data loading performance.



Left hand side tree view is now ordered in a case insensitive fashion.



This fixes an issue with publishes without a path set.



Left hand tree view is now sorted alphabetically.



The open operation on a file can now be cancelled and exceptions are better handled during file operations.


If the execute method in the scene_operation_<tk-engine>.py returns False during the open operation, the dialog will not be dismissed and the current context won't change.



Adds support for the alternative Shotgun filter syntax.


The alternative filter syntax can be found here.



Fixes an issue with user sandboxes.


Configuring user sandboxes to use a task's name in a template instead of step's name would cause the file list to refresh multiple times before settling on a fixed set of files.



Uses change_context rather than doing a full engine restart.


This will speed up operations that require a change of context, such as creating a new file via Workfiles2. Note that it is advised that tk-multi-publish, tk-nuke-writenode, and tk-nuke-quickdailies also be updated when moving to v0.7.39 of tk-multi-workfiles2.



Clicking on a project in Hiero or Nuke Studio will now retrieve only the publishes on that entity and not the publishes for all the project.



The application now uses the engine instance name instead of engine name when creating deferred folders. This may require an update to your project's schema.


When using deferred folder creation, the engine instance name will be used instead of the engine name. For example, the engine tk-nuke configured under the tk-nukestudio section in asset_step.yml will use tk-nukestudio as the token for comparison when evaluating a deferred folder.



Fixes an issue where the application sometimes switches context without any user intervention.



Toned down some warnings that seemed like errors when templates were not configured.


Error messages

It was brought to our attention that the new messages we introduced in v0.7.31 when templates were missing or an app missing form the environment were giving off the impression that these were grave errors that should be fixed in a user's configuration. Therefore, we've introduced messages that are much more neutral in tone, since most of these should have been considered as informational and not issues to fix.

Missing templates

There has been a slight change in behaviour for the application. It used to be that when a template was missing the file tabs would be working, but with only partial results being shown. The new behaviour is such that a missing template will always show a message to the user.



The behaviour of the user filtering button is now more consistent.


The user filtering button will be visible as soon as user sandboxes are detected in templates.yml file, after which the GUI will disable the button if the feature is not available for a given context and will provide informative tooltips.



Errors while scanning for files are more accurately reported.



The app will not refresh the task views as often as before.


The app cached data that was not necessary for the task views. Changing that data on the server would cause the task views to be rebuilt uselessly. The app is now only caching the fields that are required for it to function.



Fixed an issue when switching context.



Fixes issues when an engine is configured multiple times in the same environment.


The new behaviour is as follows:

  1. When looking for settings in another environment, the application will always look for application settings in the same engine instance name. This avoids cross talk between engine instances, e.g. tk-nuke vs tk-nukestudio in the default config.

  2. If there is only one set of application settings for the app, it will be used automatically, regardless of the application instance name.

  3. If there is more than one set of application settings, only the one with the same application instance name will be used. If none matches, no settings will be used and a warning will be logged to the console.



Added user activity metrics for particular actions



Adds support for on-the-fly context changes.



Adds Nuke Studio support.



Task creation is now delegated to a hook.


The hook is responsible for validating and then creating the task in Shotgun in the create_new_task method. A developper can optionally provide a QValidator for the task name field through the create_task_name_validator.



Entity tree views do not display entity type names anymore.


In order to reduce the noise and accommodate longer entity names in the entity tree, they will not prefix their name with their type anymore. The type will now be displayed in a tooltip.



The default tab when using the Shotgun Engine for Hiero is Project.



Increased app stability in multiple DCCs.



File dialogs are not modal anymore.


File dialogs are not modal anymore, except in Nuke 6 where there seems to be memory deallocation issues with PySide in a background thread. In this version of Nuke, the dialog is modal and the automatic garbage collection from Python is disabled and replaced with one that runs periodically from the main thread while the dialog is on screen.



Added previous versions sub-menus to the list of right click actions on versions.


Each sub-menu entry displays the list of actions that would be displayed if you had right-clicked on that specific version in All Versions mode.



The path cache is now updated when loading the file manager or refreshing it.



Upgraded to use Shotgun Utils Framework v4.x


Save As no longer overwrites previous versions.


Clicking on the Save button before file scanning was completed would sometimes overwrite a previous version.


Removed the grid and list view buttons since only grid view is implemented.


Fixed issue where no files are found if the current user isn't known


Bug fixes


  • Fixed issue where an exception would be raised if a Shotgun user matching a login can't be found
  • Fixed PyQt compatibility issue with My Tasks view


Various fixes, code tidy-up and updated to use the latest version of the shotgunutils framework


  • Folder icon is now used correctly for non-file child items in the list view
  • Double-clicking in the list view is now only recognised for the left mouse button
  • Fixed issue where file modified/publish times between 12-1pm were being displayed as being between 0-1am (they were still sorted correctly though)
  • Added tooltip for files that provides more information including the publish description
  • Fix to allow the project to be specified in the entity tree for Hiero/Project based workflows
  • Updated My Tasks model so that thumbnails are loaded in background threads (using the new features from the latest tk-framework-shotgunutils)
  • Lots of code tidy-up and miscellaneous fixes


Removed some debug code that was causing odd behaviour


New preview release containing fixes and tweaks.


  • Includes a number of stability improvements and performance improvements


New preview release containing fixes and tweaks.


New preview release containing tweaks to the Save UI.


New preview release containing numerous fixes and tweaks.


Initial pre-release version of the File Manager v2 for QA. Changes over v1 include:

Details - Completely new File-Open dialog: - My Tasks & Entity trees for navigating the Work Area. - File grid view written using the Qt model-view system to improve performance. - Ability to open a file from another Work Area into the current Work Area. - Ability to define Custom actions for files/publishes through a new hook - Enhanced Save-As dialog: - Added ability to navigate to and save in a different Work Area - If the file extension in the template is defined with options then those options are presented as a drop-down list to the user - Changing the version is now built into the Save-As dialog. - Removed Switch Work Area and Version Up dialogs