Part of my pipeline is not using toolkit yet, but I would like to write a script or some code to create publishes in Shotgun, so that files published in this part of the pipeline is showing up in toolkit loaders, in the Shotgun notification stream and so that I can do dependency data mining.
I have a bunch of published files on disk that I would like to register as proper publishes in Shotgun. How do I write a script to do this?
Toolkit Apps are typically responsible for creating new Publishes inside of Shotgun. These publishes are then used whenever data is processed or loaded into a scene downstream in the pipeline.
The prime example of an app that creates published files is our multi publish app, which is used across all engines and can be configured to export various file formats and outputs. Our loader, breakdown and file manager apps are examples of apps that use publishes to populate their UIs. Publishes can also be connected to other publishes via dependency links - this is a very powerful way of tracking how different files in the pipeline are related to each other.
With Shotgun 7.2, we revamped the Publish app, so it can now run standalone. In addition to workflows within software packages like 3dsMax, Houdini, Maya, Nuke, Nuke Studio, and Photoshop, you can drag and drop any arbitrary file to publish it.
If part of your pipeline is using Toolkit and other parts are not, it can be beneficial to set up the non-toolkit pipeline to create publishes in Shotgun. This means those files can easily be handled by the Loader and breakdown apps. You also get access to all the event stream and notification services that Shotgun provides to keep everyone on the team up to speed with what is going on in the project.
Creating publishes using the register_publish() API method
While it is possible to create publish records in Shotgun using a raw shotgun API call, we would strongly recommend using Toolkit's convenience methods. All toolkit apps that create publishes are using a API utility method method called
Basically, this method will create a new
PublishedFile entity in Shotgun and is trying to make that easy by using toolkit concepts. Your code would need to do something along these lines:
# Get access to the toolkit API
# this is the file we want to publish.
file_to_publish = "/mnt/projects/proj/seq_abc/shot_123/comp/foreground.v034.nk"
# alternatively, for file sequences, we can just use
# a standard sequence token
# file_to_publish = "/mnt/projects/proj/seq_abc/shot_123/comp/renders/v034/foreground.%04d.exr"
# The name for the publish should be the filename
# without any version number or extension
name = "foreground"
# initialize an API object. If you have used the toolkit folder creation
# to create the folders where the publish file resides, you can use this path
# to construct the API object. Alternatively you can create it from any Shotgun
# entity using the sgtk_from_entity() method.
tk = sgtk.sgtk_from_path(file_to_publish)
# use the file to extract the context. The context denotes the current work area in toolkit
# and will control which entity and task the publish will be linked up to. If you have used the toolkit
# folder creation to create the folders where the publish file resides, you can use this path
# to construct the context.
ctx = tk.context_from_path(file_to_publish)
# alternatively, if the file you are trying to publish is not in a location that is
# recognized by toolkit, you could create a context directly from a Shotgun entity instead:
ctx = tk.context_from_entity("Shot", 123)
ctx = tk.context_from_entity("Task", 123)
# Finally, run the publish command.
# the third parameter (file.nk) is typically the file name, without a version number.
# this makes grouping inside of Shotgun easy. The last parameter is the version number.
Note that there are also several additional options you can populate in addition to the basic ones shown above:
- The publish name should be without any version number and extension. When Toolkit and Shotgun groups publishes together into version "streams", it typically groups items by publish name and entity link.
- The publish file type parameter in the example above will set a Published File Type property on the publish. This allows you to categorize different types of content. In Toolkit Apps and other places this can then be used to distinguish between different types of data. We recommend a brief description of the content of the file rather than a repetition of the file extension (which can be accessed separately). Examples: Nuke script, Rendered Sequence, Background Plates, Diffuse Texture Map, Maya Rig, Alembic Geometry.
- To register dependencies, pass a dependency_ids=[123, 456] parameter with a list of all the publish ids that the file you are publishing depends on. For example, if you are publishing a nuke script, scan your nuke scene and find all the read nodes - in this particular case, these are your dependencies.
- Alternatively, if you don't have the publish ids, you can instead pass a list of paths using the dependency_paths parameter.
- To associate a thumbnail with the publish, pass a thumbnail_path parameter.
- If the publish is associated with a particular version that is to be reviewed, pass in its id via the version_entity parameter.
- Add a short description of what the publish contains using the commentparameter.
For a full list of parameters, see the Core API documentation.
Writing a Custom Publishing App
If you are writing a custom app for publishing, things get a lot easier! In this case, you can grab the toolkit API handle via self.sgtk and a context from self.context. So no need to create them like in the example above - the system takes care of all that.
Creating Publish Records by hand using the Shotgun API
Alternatively, you can just manually insert publish records directly into Shotgun. In that case, make sure to include all the basic fields shown in the example above.