Event Driven Triggers
Shotgun creates an EventLogEntry for every action that happens in Shotgun. You can see these events in a 'History' tab on a detail page and other places in the UI (learn more here), but these events are also fully available through the API. Besides being able to go back and see a detailed history of events in Shotgun, you can write your own event listener scripts to poll the EventLog and act on certain events you care about. Your script can execute other internal scripts in your pipeline, or it can use the Shotgun API and update other information in Shotgun, or both.
Example Use Cases
So when might you want to utilize something like this? Let's say whenever the status for a Shot's 'Layout' Task is marked as 'final', you would like to automatically set the 'Animation' Task status to 'ready to start' so the animator will know it's ready to start working on. Hey, we can do that! Instructions and sample code here. Some other examples:
- Fire off a script to create the appropriate Shot directories on the filesystem whenever a new Shot is created in Shotgun.
- Notify the artists assigned to a Shot if it goes 'on hold'
- Make a directory read-only when an Asset is finalled
- Copy relevant Version (or Take) information to a dailies system when the Version is added to a Review in Shotgun
- Twitter a random quote that begins with the same letter as the third word in a Scene's description field when the Scene grows to 25 shots... if you wanted to, you could do that too. You get the idea.
How It Works
Below is a simple diagram of EventLogEntries generated by Shotgun. Your script will use the API to get a list of events that have occurred since the last time it asked. It will then look at each event type (eg. Shotgun_Task_Change) and see if any of them are ones that we care about. Once it finds an event that is interesting, it will examine the details of the event even further (eg. what field was changed, what the value was changed to, etc. At this point you can even use the API to request more information for an entity if you need to). If the event proves worthy, the script will then act on the event and execute whatever code you decide needs to be executed whether its using the Shotgun API or something in your pipeline or both. When there are no more events to look at, we repeat the process and use the API to get a list of events that have occurred since the last time we asked.
Polling the EventLog Versus Triggers Inside Shotgun
Shotgun provides a constant stream of event information and you can listen to it all and act only on the Events you care about. We believe this has some very strong advantages over having Shotgun control triggers itself.
Flexible. Your trigger scripts can run independent of Shotgun. This allows your script to interact both with Shotgun and your pipeline in any way you want. You define the rules and actions as you wish without being bound by any constraints. Shotgun doesn't need to know anything about the event triggers you have. All it needs to do it keep generating the EventLogEntries. You control every other aspect of what happens next.
Remote. Your scripts can run from anywhere that has network access to the Shotgun server. Your script simply needs API access to run.
Multiplicity. (a terrible movie) But you can have multiple scripts running concurrently. Different departments may have different needs and thus be listening for different events. There's no restriction saying that all triggers be run from the same script. You may wish to break up your triggers into separate logical scripts. The polling query is very light and doesn't have any noticeable impact on performance.
Accountability. If your scripts make changes to Shotgun, they too create their own events allowing you to see exactly what scripts made changes.
Flexible. Yeah, we said this one already, but it's worth repeating.
All internal event types follow the format "Shotgun_[entity_type]_[New|Change|Retirement]". Some examples are "Shotgun_Shot_New" and "Shotgun_Asset_Change". Here are some of the main Event types:
- Shotgun_Reading_Change (for when a Note or Ticket is read)
A Note About Transactions and Potentially Missing Events
Shotgun executes destructive database queries in transactions and only writes to the EventLog when the transaction is complete. Because of this, it's possible that you may miss events using the "highest id" method here. However, the Event Trigger Framework on our GitHub site has code that should handle these situations.
- GitHub: shotgunEvents (Python-based event trigger framework)
- GitHub: Example: Task Status Triggers
Once you've downloaded the Event Monitor, in the “src” directory there is an “examplePlugins” directory.
- 2011-09-30: updated links to GitHub shotgunEvents framework
- 2009-10-07: updated the note about possibly missing events to reflect we don't recommend the suggested workaround for hosted clients due to performance concerns.