Shotgun Panel

Shotgun Panel

Panel UI with Shotgun information about your scene, yourself and the things around you.
By: Shotgun Software
Latest Version: v1.3.3 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-multi-shotgunpanel

Table of Contents:

Overview Summary

Documentation

            The Activity Stream

            Creating and Replying to Notes

            Notes, Versions, Publishes and Tasks

            The Info Tab

            Searching

            Actions

            The Current Work Area and the Me Area

            Configuring the Shotgun Panel

                  Configuring what is being displayed

                  Configuring Actions

Installation, Updates and Development

Configuration Options

Release Notes History

Overview

The Shotgun Panel lets you quickly access Shotgun information from an embedded panel. It provides easy access to information about the task that the user is currently working on and you have instant access to the activity stream, notes, tasks, versions and publishes. Play back versions sent to review by other members of your team. Reply to notes directly from inside your application. If you pipeline tracks dependency information, you can browse this directly from the Shotgun Panel as well.

Overview Video

The following video gives a quick overview of features and functionality.

Documentation

The Shotgun Panel is a small and lightweight version of Shotgun which runs directly inside artist applications such as Maya and Nuke. In application where the Toolkit integration supports docking, the Shotgun Panel will appear seamlessly docked inside the UI. In other applications, it will be displayed as a normal window.

The Shotgun panel implements a subset of the concepts found inside the Shotgun web app, and includes an activity stream, access to Notes and Publishes, and a global search function that let's you quickly navigate around your project. You can work with Notes and launch Versions for playback in Screening Room. An extensive actions framework makes it possible to quickly and easily write add actions menu items to various points in the UI that run your custom code.

The Shotgun panel consists of a couple of main UI elements. On top you'll find a toolbar with buttons for navigation and searching. Right below the toolbar you have the details area which displays information about the item you are currently viewing. This details area is configurable, so if you want to display custom fields or have data that is extra important in your pipeline, it is easy to make it appear here. Lastly, you find a number of Content tabs. These all display listings of Shotgun data and makes it easy to navigate around in the Shotgun Panel to quickly browse things like publishes, review Versions, or see who is assigned to the Tasks linked to your current focus.

Below is a brief overview of the different tabs and features available in the Toolkit Shotgun Panel.

The Activity Stream

The activity stream works just like the activity stream in Shotgun - it shows you all the things happening in and around the object you are looking at: users creating Notes, Versions being submitted for review, and publishes being created by the pipeline. You can add new Notes directly from the activity stream and also reply to existing Notes. Attachments will show up automatically and clicking them will show a large preview.

Creating and Replying to Notes

Creating or replying to a Note is easy with the Shotgun Panel. Simply navigate to an activity stream or Note details page and click either create note or reply to note. A dialog will appear where you can type in the Note text. You can use @name notation if you want to send the Note to a specific person - this will add that person to the TO field of the Note automatically.

Notes, Versions, Publishes and Tasks

The Notes, Versions, publishes, and Tasks tabs all work the same way - by displaying data associated with the current item you are seeing. You can double click an item to focus on that item. Once you have navigated to a Publish, you can view the dependencies for that publish. This is useful if your pipeline is tracking dependency information and gives you instant access to how your assets are interconnected.

The Info Tab

If you cannot find what you are looking for in the other tabs, try navigating to the info tab. This holds most of the Shotgun fields for your focused entity and you can click on the blue hyperlinks in order to navigate around to other Shotgun locations.

Searching

If you want to quickly navigate to another location or object in Shotgun, you can use the built-in search. This is similar to the global search in the Shotgun web application. Just start typing the name or description of what you are looking for, and results will be displayed once you have typed in three or more characters.

Actions

You can also use the Shotgun Panel to use Shotgun data to run operations in your scene. Similar to the Toolkit Loader, the Shotgun Panel has an actions system that makes it easy to register snippets of code to be triggered by a menu on an item in the browser. You can access actions from the detail area as well as from the listings. The actions button in the details area also contains some handy built-in functions to quickly jump to Shotgun and to refresh your current view.

The Current Work Area and the Me Area

The icon on the top left navigates you to your current work area. This is typically the Task that you are currently working on and is a quick way to get access to Notes, review Versions and other information relevant to what you are currently working on. This is also the location that the Shotgun Panel always starts focused on.

On the top right you find a button displaying the current user's thumbnail. This button will take you to a page which displays information associated with the current user. This includes

  • All the publishes and Versions you have submitted
  • Tasks that are assigned to you
  • All note conversations where you are either participating or where the Note is relevant to you - e.g. Notes that are associated with Tasks that you are assigned to.

Configuring the Shotgun Panel

There are two main areas that you can configure extensively in the Shotgun Panel: The appearance of text in the UI and the actions you want to associate with data. The sections below outline how to control the configuration for the two systems.

Configuring what is being displayed

The values in the detail area and the listings are both configurable through the shotgun_fields hook. You can subclass this hook and change the implementation in order to display the exact values you want:

Templating System

The hook supports a simple templating language, allowing for great flexibility. It also supports the HTML subset supported by Qt, so you can control color, font size, weight, etc. of your displayed values. The template language works in the following way:

  • Shotgun values are enclosed in {brackets}, for example <b>Description:</b> {description}. When this template is rendered, the {description} part will be replaced with the description field value.

  • If you want an optional pre- or post-fix for a value which is only shown if the value is not empty, you can use the syntax {[Prefix]sg_field[suffix]}. The template {[Start: ]start_date} {[End: ]end_date} will render Start: 12 July 2009 End: 14 July 2012 if both values are populated but Start: 12 July 2009 if end date isn't set.

  • You can define fallbacks in the case some values are not set. For Shotgun Versions, the artist fields takes precedence over the created_by field in order to support a workflow where a producer submits versions on behalf of an artist. In this case, the Version will be created by the producer but the artist field will be set to the artist. This, however, is not always the case - in some cases, artist is left blank in pipelines where artists submit their own work. When displaying versions, it is therefore useful to be able to check the artist field first, and in case this isn't set, fall back on the created_by field. This is done using the {field1|field2} syntax, for example: Created By: {artist|created_by}. You can combine this with optional fields too, e.g. {[Created By: ]artist|created_by}

This hook contains the following methods:

Controlling items appearing in lists

The get_list_item_definition() method returns a dictionary that controls the appearance of items in the various listings, given a Shotgun entity type. It returns a dictionary with the keys top_left, top_right and body, for example:

{
 "top_left": "<big>{code}</big>",
 "top_right": "{updated_at}",
 "body": "By: {created_by}<br>Description: {description}"
}

Controlling the top detail area

The get_main_view_definition() method returns a dictionary with the keys title and body given a Shotgun entity type. These values controls the appearance of an object in the detail area, for example:

{
 "title": "{type} {code}",
 "body": "By: {created_by}<br>Description: {description}"
}

Controlling the fields shown in the Info tab

The get_all_fields() methods returns a list of fields to display for a given entity when this is rendered in the Info tab.

Configuring Actions

Actions are little snippets of code that operate on a piece of Shotgun data. Examples include:

  • An action that launches RV for a given Shotgun Version
  • An action that allows a user to assign herself to a given Task
  • An action that loads a Shotgun publish into Maya as a Maya reference.

The actual payload of an action is defined in an action hook. Once you have defined the action logic, you can then map that action to Shotgun objects in the app configuration. These action mappings may for example look like this:

action_mappings:
  PublishedFile:
  - actions: [reference, import]
    filters: {published_file_type: Maya Scene}
  - actions: [texture_node]
    filters: {published_file_type: Rendered Image}
  Task:
  - actions: [assign_task]
    filters: {}
  Version:
  - actions: [play_in_rv]
    filters: {}

In the above example, we use the actions reference, import, texture_node, assign_task and play_in_rv. We then map the actions to various Shotgun objects and conditions. For example, we are requesting the import action to appear for all publishes of type Maya Scene.

When an object is loaded into the Panel, the action configuration above is read in and analyzed. A list of suitable actions for the current object is determined and the generate_actions() hook method will be executed. Shotgun data for the given entity will be passed to the hook at this point so that the hook code can determine if the action can be run for this particular Shotgun object. This is a way to allow each hook to run a check prior to being displayed. For example, the play_in_rv hook may only be relevant in the case there is media available locally - the action mappings set up in the configuration tells the panel which actions to enable for a given shotgun entity but they may not all be displayed because the generate_actions() method may determine that they are not suitable for the given object.

The actions returned from the generate_actions() method will be displayed on the actions menu and when a user clicks on it, the execute_acton() hook method is called to run the action.

For each application that the panel supports, there is an actions hook which implements suitable actions. For example, with something like Maya, the default hook will implement reference, import and texture_node actions, each carrying out specific Maya commands to bring publishes into the current Maya scene. As with all hooks, it is perfectly possible to override and change these, and it is also possible to create a hook that derives from the built in hook, making it easy to add additional actions to a built-in hook without having to duplicate lots of code.

The panel uses Toolkit's second generation hooks interface, allowing for greater flexibility. This hook format uses an improved syntax. You can see this in the default configuration settings, looking something like this:

actions_hook: '{self}/tk-maya_actions.py'

The {self} keyword tells Toolkit to look in the app's hooks folder for the hook. If you are overriding this hook with your implementation, change the value to {config}/panel/maya_actions.py. This will tell Toolkit to use a hook called hooks/panel/maya_actions.py in your configuration folder.

For more information, please see the hook files that come with the app. The hooks also take advantage of inheritance, meaning that you don't need to override everything in the hook, but can more easily extend or augment the default hook in various ways, making hooks easier to manage.

By using inheritance in your hook, it would be possible to add additional actions to the default hooks like this:

import sgtk
import os

# toolkit will automatically resolve the base class for you
# this means that you will derive from the default hook that comes with the app
HookBaseClass = sgtk.get_hook_baseclass()

class MyActions(HookBaseClass):

    def generate_actions(self, sg_data, actions, ui_area):
        """
        Returns a list of action instances for a particular object.
        The data returned from this hook will be used to populate the 
        actions menu.

        The mapping between Shotgun objects and actions are kept in a different place
        (in the configuration) so at the point when this hook is called, the app
        has already established *which* actions are appropriate for this object.

        This method needs to return detailed data for those actions, in the form of a list
        of dictionaries, each with name, params, caption and description keys.

        Because you are operating on a particular object, you may tailor the output 
        (caption, tooltip etc) to contain custom information suitable for this publish.

        The ui_area parameter is a string and indicates where the publish is to be shown. 

        - If it will be shown in the main browsing area, "main" is passed. 
        - If it will be shown in the details area, "details" is passed.

        :param sg_data: Shotgun data dictionary with all the standard publish fields.
        :param actions: List of action strings which have been defined in the app configuration.
        :param ui_area: String denoting the UI Area (see above).
        :returns List of dictionaries, each with keys name, params, caption and description
        """

        # get the actions from the base class first
        action_instances = super(MyActions, self).generate_actions(sg_data, actions, ui_area)

        if "my_new_action" in actions:
            action_instances.append( {"name": "my_new_action",
                                      "params": None,
                                      "caption": "My New Action",
                                      "description": "My New Action."} )

        return action_instances

    def execute_action(self, name, params, sg_data):
        """
        Execute a given action. The data sent to this be method will
        represent one of the actions enumerated by the generate_actions method.

        :param name: Action name string representing one of the items returned by generate_actions.
        :param params: Params data, as specified by generate_actions.
        :param sg_data: Shotgun data dictionary with all the standard publish fields.
        :returns: No return value expected.
        """

        if name == "my_new_action":
            # do some stuff here!

        else:
            # call base class implementation
            super(MyActions, self).execute_action(name, params, sg_data)

We could then bind this new action to a set of publish types in the configuration:

action_mappings:
  PublishedFile:
  - actions: [reference, import, my_new_action]
    filters: {published_file_type: Maya Scene}
  Version:
  - actions: [play_in_rv]
    filters: {}

By deriving from the hook as shown above, the custom hook code only need to contain the actual added business logic which makes it easier to maintain and update.

Related Apps and Documents

Loader

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.

Publish

Multi Publish 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.

Shotgun Workfiles

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.

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-shotgunpanel

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-shotgunpanel.

Special Requirements

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

Configuration

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.

action_mappings

Type: dict

Default Value: {u'PublishedFile': [{u'filters': {}, u'actions': [u'publish_clipboard']}], u'Task': [{u'filters': {}, u'actions': [u'assign_task', u'task_to_ip']}], u'Version': [{u'filters': {}, u'actions': [u'quicktime_clipboard', u'sequence_clipboard']}]}

Description: Associates shotgun objects with actions. The actions are all defined inside the actions hook, so a number of actions are available by default and in addition to this you can add your own actions if you like.

actions_hook

Type: hook

Default Value: {self}/general_actions.py

Description: Hook which contains all methods for action management.

shotgun_fields_hook

Type: hook

Default Value: {self}/shotgun_fields.py

Description: Hook which controls how values are presented

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!

v1.3.3

2017-Mar-14

Removes problematic profiles from png files used as icons.

Details:

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.

v1.3.1

2017-Feb-06

Added missing app class member doc url

v1.3.0

2017-Jan-30

Adds a new menu icon for the Shotgun Panel app.

v1.2.14

2017-Jan-16

Updated to use open sans font.

v1.2.13

2016-Dec-05

Sets the minimum-required version of tk-framework-qtwidgets to v2.5.10.

v1.2.12

2016-Nov-21

Make Shotgun Panel lists items when the user is in site context.

Details:

When the user is in site context, the Shotgun Panel now lists all user's items in the Notes, Versions, Publishes and Tasks tabs.

v1.2.11

2016-Nov-08

Clears an internal reference to the current panel when it is closed by Qt.

v1.2.10

2016-Nov-04

Properly handles garbage-collected panel widgets during context change.

v1.2.9

2016-Nov-01

Adds basic support for on-the-fly context changes.

v1.2.8

2016-Oct-25

Tweaks to hyperlink styling. This incorporates styling cues provided by the qtwidgets framework.

v1.2.7

2016-Aug-10

Added startup splash screen

v1.2.6

2016-Jul-08

Adds support for the site context.

v1.2.5

2016-Feb-25

add Tasks tab to layout when working on a Task

Details:

This allows you to see who else is working on the same Shot or Asset you are.

v1.2.4

2016-Feb-19

Added user activity metrics for particular actions

v1.2.3

2015-Nov-24

Fixed bug preventing the version history tab from displaying correctly.

v1.2.2

2015-Nov-24

Fixed minor issue with references to refactored overlay system.

v1.2.1

2015-Nov-23

Added API methods for navigation

v1.2.0

2015-Nov-23

Now uses v4.x.x of the shotgunutils framework.

v1.1.0

2015-Nov-10

Migrated reusable components into frameworks. Misc fixes and polish

Details:

  • Moved several widgets out from the app and into the qtwidgets framework for easier reuse.
  • Upgraded to use v3 of the shotgun utils framework. Refactored to use background task manager.
  • Fixed an issue in Houdini where action menu items were positioned incorrectly.
  • Fixed an issue a task query using the incorrect logic

v1.0.6

2015-Nov-09

Right aligns action menus with action buttons to prevent them from displaying offscreen.

v1.0.5

2015-Oct-09

Added actions hook for Flame.

v1.0.4

2015-Sep-15

Updated hooks and configuration to not include rv launch action.

v1.0.3

2015-Sep-14

First public release of the Shotgun Panel.

Follow

4 Comments

  • 0
    Avatar
    Benoit Leveau

    Small typo:

    Configuring what is being displayed | Templating System

    {[Start: ]{start_date} {[End: ]end_date}

    should be

    {[Start: ]start_date} {[End: ]end_date}

  • 0
    Avatar
    Manne Öhrström

    Thanks for that Benoit! Fixed in the docs - will go out with the next release.

  • 0
    Avatar
    Daniel Harjanto

    How do I filter out task from a certain steps in the item list?

    Also how do we order item lists ?

  • 0
    Avatar
    Steven Quinones

    Why can't we create a version in the Shotgun panel? That would be fantastic, then I won't have to go to the browser to publish a version.

Please sign in to leave a comment.