Writing event driven triggers

Note: For more information about event driven triggers, please see our documentation at https://github.com/shotgunsoftware/shotgunEvents.

Shotgun creates an event log entry for every action that happens in Shotgun. You can see these events in your Shotgun site, as well as through the Shotgun API.

In addition to seeing 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

Here are some examples of using event driven triggers:

  • Automatically set the ‘Animation’ Task status to ’ready to start’ whenever the status for a Shot’s ‘Layout’ Task is marked as ‘final’, so the animator knows to start working on the Shot.
  • 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 finaled.
  • 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.

How event driven triggers work

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 (e.g., Shotgun_Task_Change) and see if any of them are ones that you care about.

Once it finds an event that is interesting, it will examine the details of the event even further (e.g., 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, it repeats the process and use the API to get a list of events that have occurred since the last time you asked.

Event log polling

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. This provides the following 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 is 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: 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.

Event types

All internal event types follow the format “Shotgun_[entity_type]_[New|Change|Retirement].” Some examples are “Shotgun_Shot_New” and “Shotgun_Asset_Change.” For more information, see “Event types” documentation at https://github.com/shotgunsoftware/shotgunEvents/wiki/Technical_Overview#event-types.

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.