Provides UI and functionality to publish files to Shotgun.
This is the legacy publish multi-app. For information about the new publisher, see the Integrations User Guide. The Publisher is a workflow app that artists can use to publish files to Shotgun. The app provides a simple UI on top of a highly customizable core that can be easily configured to publish any combination of files or data from a work scene and it's dependencies (e.g. the Maya scene, Nuke Script, OBJ's, Alembic Caches, Cameras, Textures, etc.). The multi publish app is used in all default configurations and can be easily configured to support workflows ranging from Alembic Cache generation in Maya to render publish in Nuke, art reference management in Photoshop or plate ingestion in the Shotgun and shell environments.
This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for details.
The main interface is split into three key sections:
Primary Output. Items to be published are organized by their output type with the primary output given prominence at the top of the UI. There must be exactly one item to publish for the primary output which would typically be the scene file itself.
Secondary Outputs. Secondary outputs are optional and there can be as many as required. Items from the scene (e.g. a mesh in Maya) can also be associated with multiple secondary outputs (e.g. OBJ export together with an Alembic Cache export) if needed.
Publish Details. In addition to selecting the items to publish, the interface also allows the artist to choose the Shotgun task (if they haven't already specified this in the current Work Area), capture a thumbnail and add a comment.
When using the app, the artist workflow would typically be:
- Launch the app, select the items to be published, choose the Shotgun task, set the thumbnail, enter a comment and then click 'Publish'.
- The app will perform a pre-publish validation pass on the selected items.
- If there are any problems it will ask if it should continue. If it shouldn't then it will stop and display the problems, allowing them to be fixed before continuing.
- If there were no problems or it was told to ignore any problems, it will then publish all selected items, starting with the primary.
- As long as the primary item is successfully published, the app will finish by running a post-publish step. Typically this is used to version-up the current scene and do any cleanup.
- Finally the result: Success or Failure, is displayed together with any problems reported by the publish step.
Customizing Multi Publish
Multi Publish has been designed to be extremely configurable with all the key steps being implemented as a series of hooks. As well as separating out all engine specific calls from the app, making it easy to configure for new engines, these hooks also provide complete control over the publish process.
These are the main hooks that together comprise the publish workflow:
- hook_scan_scene is responsible for scanning the current scene for items to be published. It should return a primary item together with any number of secondary items.
- hook_primary_pre_publish is typically where you would validate that the primary item can be published. This can return a list of non-fatal problems that won't stop the publish.
- hook_secondary_pre_publish is where the validation of all secondary items happens. Again this can return a list of problems that the user will have the opportunity to fix before continuing.
- hook_primary_publish will publish the primary item for the primary output. Typically this is responsible for copying the current scene file to the publish area and registering it with Shotgun. It should return the full path to the published file which is then passed as a dependency to the secondary publish hook. Raising an exception within this hook will stop the publish and notify the user.
- hook_secondary_publish publishes the secondary items for the secondary outputs. Again this typically exports or copies the published files and then registers them with Shotgun.
- hook_post_publish is the final hook in the publish workflow allowing any clean up to be done at the end of a publish. In the default hooks, this is where the scene is versioned up. This hook will only by run if the primary publish succeeded without raising an exception.
These additional hooks can be used to customize the behaviour of the app.
- hook_thumbnail can be used to provide a thumbnail for the publish in cases where performing a screen capture doesn't make any sense. If this returns a file path to a thumbnail then the screen capture functionality is disabled.
- hook_copy_file is used to do any disk based file copying of files by the app. The default hooks use a utility method on the app which in turn calls this hook. To do this, call
self.parent.copy_file(...)from within the hook.
Outputs & Items
It's important to understand the relationship between the outputs defined in the configuration and the items returned by the scan-scene hook.
Each output has a
scene_item_type property which is an arbitrary string defined by the configuration.
primary_scene_item_type must be unique.
Multiple secondary outputs can share the same
scene_item_type. For example, if the two secondary outputs: 'OBJ' and 'Alembic Cache' are given the same scene_item_type
geometry, this indicates the intention that all geometry items from the scene should have both an OBJ and Alembic Cache file published for them.
Each item returned by the scan-scene hook has a
type which must match a
scene_item_type for one of the outputs defined in the configuration.
The app will combine the list of items with the list of outputs using the mapping between the output's
scene_item_type and the item's
type and present the final list to the user to allow them to select the items for each output to be published.
Related Apps and Documents
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.
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.
This app contains a custom Write Node gizmo for Nuke, abstracting away the file system paths from the user, allowing them to focus on just naming the particular output. Shotgun takes care of the rest! This app is typically used in conjunction with the Publish app and if you install the publish app for nuke, you most likely want to install this one too!
Publishing Alembic from Maya
This tutorial shows how you can configure Multi Publish to export Alembic files when you are publishing groups of geometry from Maya.
Toolkit Pipeline Tutorial
This document provides a step-by-step tutorial for Technical Directors (TDs) setting up a simple end-to-end pipeline using Toolkit in an advanced way. New Toolkit users who finish this tutorial will understand the fundamental aspects of the platform as well as how to customize it based on their studio's specific needs. The tutorial also provides an introduction to the out-of-the-box Toolkit apps and how they fit together in the artist workflow.
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-publish
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 https://github.com/shotgunsoftware/tk-multi-publish.
- You need Shotgun Pipeline Toolkit Core API version v0.14.58 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.
Description: Specify the hook that will actually do the publish of the primary task. This hook is passed the primary task that should be published. The hook is responsible for the entire publish process and should ensure to register the publish with Shotgun.
Description: Specify the hook that will be used to do any post-publish work. Typically, this hook will be responsible for versioning up the scene to the latest version.
Description: Specify the name that should be used in menus and the main publish dialog
Current Work File
Description: This is the name the primary output will be given in the UI
Description: No description available!
Description: This is the type used to match up items returned from the scan scene hook with with the primary output
Description: Allow publishing when no Task is specified. The publish will just be linked to the entity from the current work area
Description: Specify a hook to copy the file 'source_path' to 'target_path'. This hook is used in the 'copy_file' utility function and can be accessed from other hooks by calling self.parent.copy_file(source_path, target_path, task) from within the hook.
Description: Template used to locate the primary published file within the file system. If None then this must be determined within the publish hook.
Description: This is the type that will be used when registering the primary published file with Shotgun. If not set then this must be determined within the publish hook.
Description: A reference to a template which locates a work file on disk.
Description: Specify the hook that will run before the primary publish. This hook can be used to perform any validaiton on the primary task that is passed in to ensure that it is ready to be published.
Description: Specify a hook to scan for items to publish. The hook should return a list dictionaries that represent the items to be published.
Description: This is the icon used for the primary output in the UI
Description: Define if an output should be expanable to show the items it contains when there is only a single item.
Description: Specify a hook to pre-generate a thumbnail for the publish.
Description: Specify the hook that will be used to do the publish. This hook is passed a list of secondary tasks that are to be published. The hook is responsible for the entire publish process and should ensure it registers the published files with Shotgun
Description: Specify the hook that will run before the publish. This hook can be used to perform any validaiton on the secondary tasks that are passed in to ensure that they are ready to be published.
Publish and version up the current work file
Description: This is the description of the primary output used in the UI
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!
Uses better technique for retrieving the active doc path
Updated metrics logged
Ensures secondary outputs are rebuilt post context change
Optional thumbnails and fixes for Photoshop CC jpeg exports.
- Errors when pre-generating thumbnails are now caught and do not prevent publishing anymore.
Errors can happen when pre-generating thumbnails, e.g. when trying to create a thumbnail from a huge image in Photoshop. However, users can always add a thumbnail with the screen shot button. This fix considers pre-generated thumbnails as a "nice to have" feature, and allow publishing to keep going, even if thumbnail pre-generation fails.
Photoshop CC publish hooks now leverages
generate_thumbnailmethods from tk-photoshopcc engine for thumbnail generation and Version publishing, if these methods are available in the installed tk-photoshopcc engine.
- Using these methods in Photoshop CC fixes some problems when generating jpeg thumbnails or jpeg images used when creating Versions in Shotgun, which could prevent a publish to complete.
- Furthermore, in Photoshop CC, errors when creating a Version in Shotgun do not prevent a publish to complete anymore.
Compatibility with Hiero/Nuke Studio 11.
Better handling of unicode file paths during pre-publish validation.
Switches to writing jpg for thumbnails instead of png.
This stops further libpng errors mentioned in v0.10.2 release notes from occurring.
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.
Adds support for tk-photoshopcc.
[minor] UI layout tweaks to address further visual quirks discovered during v0.9.5 testing.
[minor] UI layout tweak to address visual quirk in Maya 2017 on Windows.
[minor] Removes log_error call that was in place for debugging purposes.
Properly supports changing contexts on the fly.
Changed default icons.
QA Fix: Verifies that 3ds Max writes the .abc file to disk before publishing.
Adds support for Alembic cache publishing for 3ds Max 2016+.
QA fix to use file base name as part of publish name
QA fix to avoid multiple path matches in output file matching
QA fixes for houdini publish hooks on Windows
Prevents annoying save popup for Houdini
Adds the ability to publish alembic/mantra outputs
Bug fix for Nuke Studio support in the tk-nuke scene operation hook.
Hotfix. Bug in conditional in primary publish.
Adds Nuke Studio support.
Adds user_data argument to hooks for sharing a dict of data between them.
The user_data dict is passed to all hooks when they are executed. This dict is shared across all hook executions and, as such, can be used to store data in within a hook that can then be accessed from subsequently run hooks. Because this is a new argument being passed to each of the hooks, it's possible that custom hooks will need to be updated to accept the additional argument. That being said, tk-multi-publish hooks are all setup to accept **kwargs out of the box, so unless that has been explicitly removed from a custom hook there will not be any problems.
Fix for QLayout warnings on app launch
Merges Hiero hook operations into Nuke hooks.
Changes necessary to allow the tk-nuke engine to work within the Hiero mode of Nuke 9.0+.
Minor fix for a publish item UI error in 3ds Max 2014
throw exception if sending to Screening Room while in proxy mode and misc cleanup
Publishing proxy renders is not supported, this adds additional checks to ensure nothing slips by while in proxy mode in Nuke removed incorrectly named hook files for 3dsmaxplus engine fixed missing import
Fix to unicode strings causing Houdini operations to fail.
Added handling for edge-case crash when publishing channels from Mari
- This change implements a workaround for a rare bug where publishing flattened channels that contain only a single layer could crash Mari.
Adds .psb support in Photoshop.
This release adds Photoshop PSB support. In order to save your Photoshop scenes as PSBs, simply update your
templates.yml file entries for Photoshop (
photoshop_asset_*) to use the extension
.psb. Note that you won't be able to use
.psb at the same time for the same entity type. Also, you need the
tk-photoshop engine's version to be greater or equal to v0.3.0. Finally, you also need
tk-multi-workfiles to be updated to v0.6.7.
Updated Nuke secondary publish hook to use new colorspace friendly method when creating movies for review
- Previously, the colorspace was not being passed through from the Write node so if it was set to a non-default value, the rendered movie would be wrong.
Added support for the new 3DS Max Engine supporting MaxPlus and Max version 2015.
Improvements to the default Mari publish hooks
- Fixed logic to find the next version to use for the published channels
- Mari project is now saved when publish starts
- Folders are now created before files are published
Fixed broken publish paths and names for Mari texture publishes
Fixed issue with Mari publish permanently flattening channels!
Added support for Mari
- Added Alembic publish as a Maya secondary publish
- Added publish hooks for Mari to export texture channels and channel layers
- Items returned from the scan-scene hook that don't match a secondary publish type defined in the configuration are now ignored. Previously an exception would have been raised.
Added Motion Builder support
Updated to use the new framework versioning syntax
- This also requires core v0.14.58
fix error in dependency check in Nuke when read nodes have empty filenames
If read nodes in the current script have their file knob set to
"" by a script, this will return
None when reading the file knob value back which causes an error when trying to replace the path separator. This fix checks to make sure we have an actual (non-empty) file name before continuing on to try and match it with a template. If the
file_name is an empty string or
None, we skip the check and move on error free.
Primary pre-publish errors are now displayed in the UI.
Details: - Previously, the user was informed that there were errors but the actual errors were never displayed - this has been fixed!
Fixed issue when allow taskless publishes was set to False
Details: - Also changed the default back to True for this setting
Various fixes and new features:
Details: - Added a new setting to allow 'No Task' selection for publishes when the current context doesn't specify a task and the pipeline supports task-less publishes. - Added a second per-item progress bar for publishes when there are more than one item being published. - Fixed some issues with the progress reporting where the progress bar wasn't behaving correctly. - Updated hook to use the latest interface.
Changes to support Perforce workflow - version is now an optional parameter in all templates - added primary task parameter to secondary publish hooks - added primary and secondary tasks to post publish hook
Updated Perforce implementation (limited release)
Updated Perforce implementation (limited release)
Updated Perforce implementation (limited release)
Removed force-reset of Shotgun Write node render paths in the post-publish hook as it's no longer required for tk-nuke-writenode v1.0.0+
Updated Perforce implementation (limited release)
Fix for PyQt 4.6 compatibility.
Details: Fix for PyQt 4.6 compatibility.
Updated Perforce implementation (limited release)
Addition of setting to allow expanding of output items when there is only a single item
Initial Perforce implementation (limited release)
Order of Secondary outputs and items in the UI now respects the order from the configuration and scan-scene hook respecively
Fixes for ordering of Secondary outputs
Details: - Order of outputs in the UI now respects the order of the secondary outputs in the configuration - The order of tasks sent to the secondary output hooks now matches the configured order of the secondary outputs - Updated default secondary publish hook for Nuke to ensure that renders are published before review versions
Fixed Nuke secondary publish so that it doesn't rely on the order of tasks
Fixed Python 2.5 compatibility issues
Fixed issue when using non-ascii characters in the publish comment
Tweaked the display name when name is not specified in the template
Updated behaviour when name is either optional or absent from the templates
Relaxed template validation in app manifest
Updated to require widget framework v0.1.16
Adjustments to the Photoshop Publish Support.
Added Photoshop Support. Various Tweaks.
- Added Photoshop Support in hooks.
- Updated Autodesk icons to reflect new logos
- fixed a minor path issue with houdini on windows
- license updates
- tweaks to softimage support
Tweaked warning messages in default Nuke Hooks
Improved Nuke Review Submission Functionality in Hooks.
Minor changes to the nuke export hooks UI formatting.
Added default Review Submission to Nuke publish hooks.
Added Hiero and Houdini Support. Minor tweaks.
Updated to use latest version of the widget framework
Additional logging of call stacks for TankErrors raised within hooks
Renames and support for the new name Sgtk.
Updated to use the configured Published File Entity type.
Added missing dependency analysis for maya scene primary publish
Fixed a spelling mistake in a configuration file.
Fixed app manifest to correctly allow a null value to be used as the secondary_output.publish_template setting
Fixed various issues stopping Publish app from working with PyQt
Various bug fixes and minor improvements.
- Now uses generic tank QT paths, allowing it to work both in pyside and pyqt
- Better display of task header when the task is provided via the context
- added additional metadata to command handling
- added a check in the nuke write node hook to ensure render path is not locked
Configuration changes - the primary output is no longer stored in a dictionary.
First non-preview release to the Tank Store.
Initial Release to the Tank Store.