Shotgun Panel

Shotgun Panel

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

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.

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

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.

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

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

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.

Shotgun Workfiles

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

Admin Guide

This is the Admin Guide for Shotgun Integrations.

Development Guide

This is the Development Guide for Shotgun Integrations.

User Guide

This is the User Guide for Shotgun Integrations.

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

enable_context_switch

Type: bool

Description: Flag to control whether the context switch UI should be displayed or not.

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

2017-Sep-09

Play in sg panel now navigates to media player

Details:

This changes the behaviour of the sg panel so that if you click the play icon for a version, it will navigate you to the sg media center page rather than screening room which was previously the case. Back when we originally wrote this code, the media center was not yet released and they did not have proper urls that you can navigate to. This change aligns the behaviour in the panel with what you get in other parts of Shotgun.

v1.4.7

2017-Aug-17

Stops app init when there's no GUI. This resolves issues when PySide is not available.

v1.4.6

2017-Aug-16

Minor styling tweaks to address some issues in Houdini 16.

v1.4.5

2017-Aug-10

Styling tweaks for Houdini 16 compatibility.

v1.4.4

2017-Jul-26

Publishes associated with versions are now correctly displayed.

v1.4.3

2017-Jun-27

Removes the browser hierarchy view in favor of the previous search UX.

Details:

The UX for searching Shotgun for an entity has been reverted back to what it was prior to the v1.4.0 release.

v1.4.2

2017-Jun-12

Adds panel load actions for 3dsmax

v1.4.1

2017-May-25

Fixes issue with panel startup display

v1.4.0

2017-May-04

Support for context switching, new actions and polish

Details:

  • Adds context switching support as a new feature that can be opted into by enabling a setting.
  • Retina friendly icons
  • Lots of general polish
  • Added default houdini actions
  • Added image plane support to maya
  • Added nuke studio actions
  • Improved formatting and hints
  • improved tab management
  • fixed bug where time stamps were reported incorrectly
  • fixed bug where sometimes the ordering of items would be incorrect

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.