[This post is part of a series of articles about working from home in Shotgun.]
Studio workflows often include setting environment variables, either when an artist starts working on a given project, or when they start work on a given task. It can be a challenge to set these up consistently on remote machines. Shotgun Toolkit offers a couple hooks – small Python scripts that are designed to allow easy customization at a specific point in the pipeline – that you can customize to set environment variables and deploy to remote users with your Toolkit pipeline configuration.
The before_app_launch hook: This hook runs just before a user launches a DCC in a Toolkit-aware way. Use it to set environment variables that are DCC-specific. You can see our default copy of before_app_launch in Github here. It includes an example of setting an environment variable.
The tank_init core hook: Tank is the original name of Shotgun Toolkit, and the tank_init hook runs every time an instance of the Toolkit API is initialized. It’s one of the first hooks that runs in any Toolkit workflow. If you want to set environment variables that will be referenced in your Toolkit configuration itself, this is a good place to set them, as it runs before the Toolkit environment configuration is read.
before_app_launch is an app hook, running as part of the tk-multi-launchapp, whereas tank_init is a core hook, part of the Toolkit core API itself. Because of this distinction, the process for taking over these hooks differs slightly. The steps to take over each are below.
Note: Because we’re dealing with remote workflows, you’ll need to use a distributed config, ie, you’ll upload a copy of your pipeline configuration to Shotgun, to be automatically cached to users’ workstations as needed. In order to edit your configuration, you’ll need to download it, make modifications, then re-upload it. This post provides the details on managing your uploaded config.
Customizing the before_app_launch hook
Make a copy of the hook
You’ll first need to make a copy of the hook, so that you can add your modifications to it. If your studio already has a custom before_app_launch hook, use that as your starting point. If not, use Shotgun’s default.
The simplest way to get Shotgun’s default version of the hook is from our Github repository.
Copy the contents of before_app_launch.py into
hooks/tk-multi-launchapp/before_app_launch.py
within your pipeline configuration. If there is no tk-multi-launchapp directory within hooks/, you can create it.
Note: The above Github link points to the master branch, which represents the latest version of the tk-multi-launchapp. If your configuration uses an older version of this app, you can get the hook from the specific version by expanding the “Branch: master” dropdown in the upper left corner of the page, going to the “Tags” tab, and choosing your desired version.
You now have a copy of the hook within your config, and you’re ready to make modifications to it.
Make your modifications
In your copy of the hook file, add the logic to set your desired environment variables. You can see an example of setting an environment variable in the default hook’s code.
Point your configuration to your modified hook
In the environment configuration section of your Pipeline Configuration (env/*), add the following line to the tk-multi-launchapp settings in every environment where you want to use your hook:
hook_before_app_launch: "{config}/tk-multi-launchapp/before_app_launch.py"
If you’re not sure where to make this change, as long as your pipeline configuration is based on the Default Configuration, then you can add it to every block in env/includes/settings/tk-multi-launchapp.yml.
And that’s it. Your pipeline configuration is now using a custom before_app_launch hook. Once you upload your config, users will get this change.
Customizing the tank_init core hook
Because tank_init is a core hook, ie, it’s a hook for the Toolkit Core API, as opposed to being a specific app’s hook, the steps to take it over are different from before_app_launch’s.
Make a copy of the hook
Just as for before_app_launch, you’ll first need to make a copy of the tank_init hook before adding your modifications. If your studio has a custom tank_init, use that as your starting point. If not, use Shotgun’s default.
You can get Shotgun’s default version of the hook from our Github repository. Copy the contents of tank_init.py into
core/hooks/tank_init.py
within your pipeline configuration.
Note: The above Github link points to the master branch, which represents the latest version of tk-core. If your configuration uses an older version of tk-core, you can get the hook from the specific version by expanding the “Branch: master” dropdown in the upper left corner of the page, going the “Tags” tab, and choosing your desired version.
For core hooks, simply having the hook in the core/hooks directory in your pipeline config will make it live once your config is uploaded. So, unlike with before_app_launch, you don’t need to make any changes within your environment configuration to point to this hook.
Make your modifications
In your copy of the hook file, add the logic to set your desired environment variables. You can see an example of setting an environment variable in the before_app_launch hook’s code.
Upload your pipeline configuration
And that’s it! When you upload your now customized config, your changes will be in place, and when users interact with your Toolkit pipeline, their cached configuration will be automatically updated and your custom code will run, setting any needed environment variables on their machines.