sgactions¶
This Python package is a wrapper around ActionMenuItems
in Shotgun providing a simple interface to Python callables via a YAML configuration. It also has an optional Greasemonkey-style user script to allow to injection of icons and headings.

Installation¶
Shotgun API Keys¶
There are two ways to provide Shotgun API keys to the dispatcher: environment
variables or a shotgun_api3_registry.connect()
function.
For the first, set SHOTGUN_SERVER
, SHOTGUN_SCRIPT_NAME
, and
SHOTGUN_SCRIPT_KEY
in your execution environment.
For the second, create a shotgun_api3_registry
module with a connect
function that returns a shotgun_api3.Shotgun
instance.
Python¶
The agaction
package must be importable from the environment that your browser runs in. Check ~/.xsession-errors
on Linux or the Console.app on OS X if your commands seems to be vanishing into a black hole.
Protocol Handlers and Chrome Extensions¶
Shotgun action menu items allow for execution of your code in two ways: via a POST
to another webserver under your control, or navigating to an arbitrary URI. We hook into the second method via protocol handers on OS X and Linux by responding to the sgaction
protocol. We have unified both cases into a single script:
python -m sgactions.register
This script must be run once per user per machine. It is recommended to run this command on user login, and we have provided a launchctl
agent which will perform this for you on OS X. Simply copy it to each user’s home folder:
mkdir -p ~/Library/LaunchAgents
cp LaunchAgents/com.westernx.sgactions.plist ~/Library/LaunchAgents/
or into the system wide folder:
cp LaunchAgents/com.westernx.sgactions.plist /Library/LaunchAgents/
This script will also automatically install our Google Chrome extension for adding icons, and headings. The changes will only take hold if the register command is run after Chrome has run for the first time and while Chrome is not running. This extension is known to work for Shotgun v4.0 through v4.1
Whenever a new version of sgactions is installed, re-registering may be required, and it will clean up any old hooks it may have left in your system.
Configuration¶
Actions are specified in a YAML file as a list of dictionaries, one for each action. A simple configuration looks like:
- entrypoint: my.python.package:run_sgaction
title: Run my action!
This will register “Run my action!” on every Shotgun entity to call run_sgaction
within the my.python.package
module.
We can specify the rest of the standard ActionMenuItem
fields in a similar way:
- entrypoint: my.python.package:run_sgaction
folder: My Actions
title: Run my action on Shots or Tasks!
entity_types: [Shot, Task]
list_order: 1
selection_required: true
A special syntax will also be interpreted by the browser plugin in order to create headings and icons in titles and folders. This syntax is:
Header / Title [icon]
For example, one of the actions from the screenshot above are specified via:
- entrypoint: sgfs.commands.launch_maya:sgaction
title: "3D Department / Launch Maya [application-osx-terminal]"
folder: "Toolbox [cog]"
list_order: 11
entity_types: [Task]
selection_required: true
For even more graceful degradation, you can give a “rich” title, heading, and icon that should be used, while falling back onto the original title if the browser extension fails:
- entrypoint: sgfs.commands.launch_maya:sgaction
title: "Launch Maya"
folder: "Toolbox [cog]"
rich:
title: Launch Maya
header: 3D Department
icon: application-osx-terminal
list_order: 11
entity_types: [Task]
selection_required: true
This does not work for URL-based ActionMenuItems.
We currently support the Silk icon set; simply replace underscores with dashes in the icon names.
Deployment¶
Deploying actions is a matter of calling the deployment script and giving it a configuration file:
python -m sgactions.deploy my_actions.yml
This will install new actions, and update old ones (comparing them by their entrypoint). You must manually delete them via:
python -m sgactions.deploy --list
python -m sgactions.deploy --delete <entrypoint or id from previous list>
Writing Handlers¶
Action handlers are any Python callable that accept keyword arguments. The following is a simple example:
def sgaction(**kwargs):
for item in sorted(kwargs.iteritems()):
print '%s = %r' % item
and on a Task on our testing server outputs:
cols = ['content', 'step', 'sg_sort_order', 'task_assignees', 'sg_status_list', 'start_date', 'due_date', 'duration', 'milestone']
column_display_names = ['Task Name', 'Pipeline Step', 'Sort Order', 'Assigned To', 'Status', 'Start', 'End', 'Duration', 'Milestone']
entity_type = 'Task'
ids = [43588, 43587, 43590]
page_id = 992
project_id = 66
project_name = 'Testing Sandbox'
referrer_path = '/detail/Shot/5773'
selected_ids = [43589]
server_hostname = '<snipped>'
session_uuid = '<snipped>'
sort_column = 'sg_sort_order'
sort_direction = 'asc'
title = 'Shot'
user_id = 108
user_login = '<snipped>'
Of particular interest is project_id
, which will appear in most cases and so may appear to be a constant argument, but it will not be passed along from cross-project pages, such as user pages.
Debugging¶
Standard output and error are dumped to a file in /var/tmp
that starts with sgactions
.