Shotgun Event Plug-in Guide

Overview

Shotgun is a customizable web-based Production Tracking system for digital studios, and is developed by Shotgun Software. Using Deadline’s Shotgun event plug-in, artists can automatically create new Versions for Shots or Tasks in Shotgun when they submit a render job to the farm. When the job finishes, Deadline can automatically update the Version by uploading a thumbnail and marking it as complete or pending for review.

image0

Creating Versions

Versions can be created automatically at submission time or manually after a job has finished.

Automatic Version Creation

When you submit a new job to Deadline, you can have Deadline automatically create a new Version in Shotgun. This is done by connecting to Shotgun prior to submitting the job and choosing the Task that the job is for. The majority of the submission scripts that ship with Deadline include the Shotgun connection option. For this example, we will use Nuke, but the process is basically the same for each submission script.

First, find the tab or panel with the Shotgun settings. For Nuke, this is under the Shotgun/Draft tab.

image1

Press the Connect To Shotgun button to bring up Deadline’s Shotgun browser. Enter your Shotgun Login Name and press Connect. If the connection is successful, Deadline will collect the list of Tasks you are assigned to. If there are problems connecting, Deadline will try to display the appropriate error message to help you diagnose the problem.

image2 image3

After you have selected a Task, you must specify a Version name and a description. If you have configured Version name templates in the Shotgun event plugin configuration, you can select one from the drop down. You can also manually type in the version name instead.

image4

After you have configured the Version information, press OK to return to the Nuke submitter. The Shotgun settings will now contain the Version information you just specified. To include this information with the job, leave the Submit Shotgun Info With Job option enabled. If you want to change the Version name or description before submitting, you can do so without reconnecting to Shotgun.

image5

You can now press OK to submit the job. If the Shotgun event plugin is configured to create the new version during Submission, the submission results will show the Version’s ID. Otherwise, the Version won’t be created in Shotgun until the job completes.

image6

Manual Version Creation

To manually create a Version from a completed job, right-click on the job in the Deadline Monitor and select Scripts -> Create Shotgun Version. This will bring up the Shotgun browser so that you can connect, pick the appropriate Task, and specify a Version name and description. After specifying the appropriate information, press OK to create the new version.

image7

Selecting An Existing Version

Some of our submission scripts can edit an existing Shotgun version. For example, our Quicktime submitter allows you to select an existing Shotgun Version to upload the movie to when the job completes.

image8

Press the Connect To Shotgun button to bring up Deadline’s Shotgun browser. Enter your Shotgun Login Name and press Connect. If the connection is successful, Deadline will collect the list of Tasks you are assigned to. If there are problems connecting, Deadline will try to display the appropriate error message to help you diagnose the problem.

image9 image10

After you have selected a Task, you can select a Version for that Task. Then press OK to return to the Quicktime submitter. The Shotgun settings will now contain the Version information you just specified. To upload the movie file to the selected Version, leave the Upload Movie File To Shotgun On Completion option enabled.

image11

You can now press OK to submit the job. When the job finishes, the rendered movie will automatically be uploaded to the selected Version.

Advanced Workflow Mode

When setting up the Shotgun event plugin, you can enable an Advanced Workflow Mode. This mode allows you to create Versions by selecting a Task, or by selecting a Project and Entity. Studios that don’t use the Task-centric approach will probably find the Advanced Workflow Mode more suitable to their needs.

image12 image13

Setup

Follow these steps to setup Deadline’s connection to Shotgun.

Create the API Script in Shotgun

In Shotgun, you must first create a new API script so that Deadline can communicate with Shotgun. This can by done from the Admin menu.

image14

After the Scripts page is displayed, press the [+] button to create a new script, and enter the following information in the window that appears. If you can’t see one or more of the following fields, use the More Fields drop down to show them.

  • Script Name: deadline_integration
  • Description: Script for Deadline integration
  • Version: 1.0
  • Permission Group: API Admin

image15

After you have created the new script, click on the deadline_integration link in the Scripts list and note the value in Application Key field (it’s a long key consisting of alphanumeric characters). You’ll need this key when configuring Deadline’s Shotgun connection in the next step.

image16

Configure the Shotgun Connection

After you have created the Deadline API Script in Shotgun, you can now configure the Shotgun event plug-in from the Deadline Monitor. Enter Super User Mode from the Tools menu, and then select Tools -> Configure Event Plugins.

image17

The event plugin settings are split up into a few sections. The most important sections are the Options and Connection Settings, as these control how Deadline connects to Shotgun. In most cases, the Field and Value Mapping sections can be left alone because they map to fields that exist in the default Shotgun installation. Only studios that have deeply customized their Shotgun installations might have to worry about changing the Field and Value Mapping settings.

Options

  • Enabled: The Shotgun event plugin must be enabled before Deadline can connect to Shotgun.
  • Create Version On Submission: If enabled, Deadline will create the Shotgun Version at time of submission and update its status as the job progresses. Otherwise, the Version will only be created once the job completes.
  • Enable Advanced Workflow: If enabled, the user can select a Project and Entity instead of just a Task.
  • Thumbnail Frame: The frame to upload to Shotgun as a thumbnail.
  • Convert Thumbnails with Draft: Whether or not to attempt to use Draft to convert the Thumbnail frame prior to upload.
  • Thumbnail Conversion Format: The format to convert the Thumbnail to prior to upload (see above).
  • Version Templates: Presets for Version names that uses can select from (one per line). Available tokens include ${project}, ${shot}, ${task}, ${user}, and ${jobid}. For example:
    • ${project} - ${shot} - ${task}
    • ${project}_${shot}_${task} (${jobid})
  • Enable Verbose Errors: Whether or not detailed (technical) error information should be displayed when errors occur while connecting to Shotgun.

Connection Settings

  • Shotgun URL: Your Shotgun URL.
  • Shotgun Proxy: Your proxy (if you use one).
  • API Script Name: The name of the API script you created in Shotgun earlier (deadline_integration).
  • API Application Key: The key from the script you created in Shotgun earlier (it’s a long key consisting of alphanumeric characters).

Shotgun Field Mappings

  • These are the Version fields that Deadline is expecting to exist in Shotgun. The default values match those from a default Shotgun installation, so you will only have to edit these settings if you have customized the Version Field names in your Shotgun installation.
  • Note that some of the Fields you can specify aren’t created by default in Shotgun. You will have to manually create those fields in Shotgun and specify their names here, if you wish to use them. An example of such fields would be Deadline Job ID, and Average/Total Render Time.

Status Value Mappings

  • These are the Version status values that Deadline is expecting to exist in Shotgun. The default values match those from a default Shotgun installation, so you will only have to edit these settings if you have customized the Version Status values in your Shotgun installation.

Draft Field Mappings

  • Draft Template Field: The field code for a Task field that contains a Draft Template relevant to the Task. If this is specified, Deadline can automatically pull in the specified template at submission time.

Test the Shotgun Connection

After you have configured the Shotgun connection, you can test it from the Deadline Monitor by selecting Scripts -> Test Shotgun Connection. This will bring up Deadline’s Shotgun browser. Enter your Shotgun Login Name and press Connect. If the connection is successful, Deadline will collect the list of Tasks you are assigned to. If there are problems connecting, Deadline will try to display the appropriate error message to help you diagnose the problem.

image18 image19

Set up Shotgun Columns in the Deadline Monitor

Deadline uses the job Extra Info properties 0 to 5 for Shotgun specific settings, and you can configure the columns in the Job List in the Monitor to properly represent these settings. In the Monitor, enter Super User mode from the Tools menu, and then select Tools -> Configure Repository Options. Find the Job Settings section and click on the Extra Properties tab. It will show the following:

image20

Rename the Extra Info properties as shown in the following image. After committing these changes, you will now be able to see these Shotgun specific columns in the Job List in the Monitor.

image21

FAQ

Which editions of Shotgun does Deadline support?

Deadline supports the Studio and Partner editions of Shotgun, because those editions include the necessary API access.

Which versions of Shotgun does Deadline support?

Deadline supports Shotgun 2.3 and later (including version 3.x).

Which version of the Shotgun API does Deadline use?

Deadline 5.1 ships with version 3.0.6 of the Python Shotgun API, whereas Deadline 5.2 ships with version 3.0.9.