Documentation

We're working on full documentation and it will be coming soon. We'll make sure it's worth the wait!

Using {name} in Templates

The {name} token is an artist-driven string that can be used in templates. It allows artists to differentiate the files within their work area (and subsequent publishes) with descriptors of their choice. Different studio pipelines have different policies for artist input on naming, and workflows can be configured to utilize the {name} token with three levels of control:

• Mandatory, artists must enter a {name} in order to save a file through Toolkit.
• Optional, artists can enter a {name} if desired/necessary to save a file through Toolkit.
• Not at all, artists do not have to and are not allowed to enter a {name} when saving a file through Toolkit.

Mandatory {name}

Toolkit's default configuration makes the {name} token mandatory, meaning artists must enter in a value when saving a file. The app configuration has a 'saveas_default_name' key that drives the initial value that appears in the Shotgun Save As dialog:

tk-multi-workfiles:
    ...
    saveas_default_name: scene
    ...
    template_publish: maya_shot_publish
    template_publish_area: shot_publish_area_maya
    template_work: maya_shot_work
    template_work_area: shot_work_area_maya

The specified templates must also include the {name} token as part of their definition:

shot_work_area_maya: '@shot_root/work/maya'
shot_publish_area_maya: '@shot_root/publish/maya'
maya_shot_work: '@shot_root/work/maya/{Shot}.{Step}.{name}.v{version}.ma'
maya_shot_snapshot: '@shot_root/work/maya/snapshots/{Shot}.{Step}.{name}.v{version}.{timestamp}.ma'
maya_shot_publish: '@shot_root/publish/maya/{Shot}.{Step}.{name}.v{version}.ma'

With this configuration, artists will not be able to do a Shotgun Save As without populating the {name}, and it will start with a value of 'scene' that can be changed in the UI:


Optional {name}

The {name} token can also be made optional, meaning artists can enter in a value when saving a file but don't necessarily have to if they don't feel it's needed and/or a studio has a convention where artists "opt in" to the {name} when the work they are doing dictates it. The 'saveas_default_name' key can still be used in this scenario to set an initial value, but it can also be set to an empty string ('') for the "opt in" case:

tk-multi-workfiles:
    ...
    saveas_default_name: ''
    ...
    template_publish: maya_shot_publish
    template_publish_area: shot_publish_area_maya
    template_work: maya_shot_work
    template_work_area: shot_work_area_maya

The specified templates must also use the optional key syntax to denote the fact that the {name} token may or may not be present:

shot_work_area_maya: '@shot_root/work/maya'
shot_publish_area_maya: '@shot_root/publish/maya'
maya_shot_work: '@shot_root/work/maya/{Shot}.{Step}[.{name}].v{version}.ma'
maya_shot_snapshot: '@shot_root/work/maya/snapshots/{Shot}.{Step}[.{name}].v{version}.{timestamp}.ma'
maya_shot_publish: '@shot_root/publish/maya/{Shot}.{Step}[{name}].v{version}.ma'

With this configuration, Shotgun Save As will start up with an empty {name}, and artists can choose to fill it in through the UI:


No {name}

Finally, the {name} token can be removed altogether, meaning templates will be fully defined for artists and they will not have to specify anything when saving files through Toolkit. In this case, the 'saveas_default_name' key in the app configuration is ignored, and the template definitions do not include {name} at all:

shot_work_area_maya: '@shot_root/work/maya'
shot_publish_area_maya: '@shot_root/publish/maya'
maya_shot_work: '@shot_root/work/maya/{Shot}.{Step}.v{version}.ma'
maya_shot_snapshot: '@shot_root/work/maya/snapshots/{Shot}.{Step}.v{version}.{timestamp}.ma'
maya_shot_publish: '@shot_root/publish/maya/{Shot}.{Step}.v{version}.ma'

With this configuration, Shotgun Save As will remove the text box that was used to receive text input for the {name} token, and artists will just be presented with the full output filename and path for confirmation before saving: