ShotGrid

License: PRO+ (Professional Edition or higher)
Plugin Type: Post-Index Plugin
Author: Diskover Data, Inc.

Overview

The Diskover ShotGrid plugin synchronizes metadata from Autodesk ShotGrid (formerly Shotgun) with your Diskover indices, enabling VFX and animation pipelines to search and analyze production assets alongside file system metadata. By enriching indexed directories with ShotGrid data, this plugin creates a unified search experience where artists and supervisors can find files using both storage criteria (size, age, extension) and production criteria (shot status, project, assigned assets) in a single query.

Use Cases

VFX Pipeline Metadata Enrichment: Automatically sync shot status, assigned artists, and asset relationships from ShotGrid to file directories. Artists and supervisors can quickly locate all files associated with "in progress" shots directly through Diskover search without switching applications.

Production Tracking Integration: Link file system storage usage with production tracking data. Identify how much storage is consumed by specific projects, sequences, or shot statuses—all from within Diskover's familiar interface.

Cross-Domain Search Capabilities: Combine file system queries with production metadata in powerful ways. For example, find all EXR files over 1GB that belong to shots marked as "final" in ShotGrid.

Asset Management and Discovery: Locate all render outputs, plates, and working files associated with specific ShotGrid shots or assets by searching the enriched shotgrid.* fields, making it easier to track down production deliverables.

Sample data from a Shotgrid execution:

Here we can see the entire list of metadata returned from the Shotgrid plugin!

Installation

Prerequisites

Before installing the ShotGrid plugin, ensure you have:

• Diskover Core installation with plugin support

• Python 3.9 or higher

• Elasticsearch 7.x or 8.x (as supported by your Diskover installation)

• ShotGrid API credentials (Script Name and API Key)

Setting Up ShotGrid API Access

You'll need to create an API script in your ShotGrid instance to allow Diskover to query production data. This involves:

1. Logging into ShotGrid as an administrator

2. Navigating to Admin Menu → Scripts

3. Creating a new script with appropriate read permissions

4. Recording the Script Name and API Key for use in configuration

For detailed instructions on creating and managing API scripts, refer to the Autodesk ShotGrid API Documentation.

Installing Python Dependencies

The plugin requires the shotgun_api3 library to communicate with ShotGrid.

Linux:

python3 -m pip install -r /opt/diskover/plugins_postindex/diskover_shotgrid/requirements.txt

Windows:

python -m pip install -r "C:\Program Files\Diskover\plugins_postindex\diskover_shotgrid\requirements.txt"

Verifying Installation

To verify the plugin is installed correctly, check the version:

Linux:

python3 /opt/diskover/plugins_postindex/diskover_shotgrid/diskover_shotgrid.py --version

Windows:

python "C:\Program Files\Diskover\plugins_postindex\diskover_shotgrid\diskover_shotgrid.py" --version

Configuration

Configuration is managed through the Diskover-Web Admin interface under Settings → Plugins → Post Index → ShotGrid.

Sample Configuraiton in Diskover Admin:

Here is the beginning of our sample configuration There are many other configuraitons for the Shotgrid plugin - covered in detail below!

Connection Settings

Project Mapping Configuration

Finding Your ShotGrid Project ID:

When viewing a project in ShotGrid, the URL contains the project ID:

https://mystudio.shotgrid.autodesk.com/page/project_overview?project_id=122
                                                                        ^^^
                                                              This is your project ID

Field Mapping Configuration

The plugin uses two field mapping lists to control which ShotGrid metadata is synchronized:

Each field mapping requires three properties:

Key Parameter Behavior:

Example Configuration

Below is an example configuration for a VFX studio with multiple active projects:

# Connection Settings
shotgrid_user: "diskover-sync"
shotgrid_api_key: "your-secret-api-key-here"
shotgrid_host: "mystudio.shotgrid.autodesk.com"

# Path Configuration
projects_path: "/mnt/projects"

# Project Mapping
project_name_to_id:
  'project_alpha': 122
  'project_beta': 145
  'commercial_2024': 203

# Shot Field Mappings
fields_to_pull:
  - es_field: "project"
    shotgrid_field: "project"
    key: "id"
  - es_field: "sequence"
    shotgrid_field: "sg_sequence"
    key: "id"
  - es_field: "shot_code"
    shotgrid_field: "code"
    key: "id"
  - es_field: "status"
    shotgrid_field: "sg_status_list"
    key: "id"
  - es_field: "Created_By"
    shotgrid_field: "created_by"
    key: "name"
  - es_field: "tags"
    shotgrid_field: "tags"
    key: "name"
  - es_field: "date_updated"
    shotgrid_field: "updated_at"
    key: "id"
  - es_field: "type"
    shotgrid_field: "sg_shot_type"
    key: "id"
  - es_field: "description"
    shotgrid_field: "description"
    key: "id"
  - es_field: "assets"
    shotgrid_field: "assets"
    key: "id"

# Project Field Mappings
project_fields_to_pull:
  - es_field: "project_id"
    shotgrid_field: "id"
    key: "id"
  - es_field: "project_name"
    shotgrid_field: "name"
    key: "id"
  - es_field: "project_status"
    shotgrid_field: "sg_status"
    key: "id"
  - es_field: "project_created_by"
    shotgrid_field: "created_by"
    key: "name"
  - es_field: "project_tags"
    shotgrid_field: "tags"
    key: "name"
  - es_field: "project_updated_at"
    shotgrid_field: "updated_at"
    key: "id"

Execution / Usage Guide

The ShotGrid plugin can be executed manually from the command line or scheduled to run automatically after indexing completes.

Command-Line Reference

python3 diskover_shotgrid.py [-h] [--version] [-c NAME] [-d] [-l TOPPATH] [index]

Manual Execution

Linux:

# Process a specific index
python3 /opt/diskover/plugins_postindex/diskover_shotgrid/diskover_shotgrid.py diskover-projects-2024.01.15

# Auto-detect the latest index for a path
python3 /opt/diskover/plugins_postindex/diskover_shotgrid/diskover_shotgrid.py -l /mnt/projects

# Use a named configuration with debug output
python3 /opt/diskover/plugins_postindex/diskover_shotgrid/diskover_shotgrid.py -c production -d -l /mnt/projects

Windows:

# Process a specific index
python "C:\Program Files\Diskover\plugins_postindex\diskover_shotgrid\diskover_shotgrid.py" diskover-projects-2024.01.15

# Auto-detect the latest index for a path
python "C:\Program Files\Diskover\plugins_postindex\diskover_shotgrid\diskover_shotgrid.py" -l "D:\projects"

# Use a named configuration with debug output
python "C:\Program Files\Diskover\plugins_postindex\diskover_shotgrid\diskover_shotgrid.py" -c production -d -l "D:\projects"

Automated Execution

For production environments, you can automate ShotGrid metadata synchronization using Diskover's built-in scheduling capabilities.

Using Post-Crawl Commands (Index Tasks)

Configure the ShotGrid plugin to run automatically after each index crawl completes by adding it as a Post-Crawl Command in your Index Task configuration.

Sample Post-Crawl Command configuraiton for Shotgrid executing with an Index Task:

In your system ensure to replace the ConfigurationName above with a named configuraiton that you’ve created at Diskover Admin → Plugins → Post-Index → Shotgrid – If you are not using a custom configuration and you’re just using Default than the -c flag and the ConfigurationName is not required!

Linux Example:

Windows Example:

Available Index Task Tokens:

• {indexname} — The name of the index that was just created

Important: The Post-Crawl Command field should contain ONLY the executable (e.g., python3, python). All script paths, flags, and arguments go in the Post-Crawl Command Args field.

Using Custom Tasks

For more flexible scheduling or to run the plugin independently of indexing, create a Custom Task in Diskover-Web.

Sample Custom Task Configuration:

Here we can see the Run Command & args needed for the Custom Task - Note that in this case you cannot use the {indexname} variable as this is not a task that creates an index, so we must use the -l (toppath) CLI option and pass in our top path!

Expected Behavior During Execution

When the plugin runs, it performs two sequential phases:

1. Shot Metadata Sync: Scans the index for directories under */shots/* paths, queries ShotGrid for matching shot data, and updates Elasticsearch documents with shot-level metadata.

2. Project Metadata Sync: Scans for directories matching the project_name_to_id mapping, retrieves project-level metadata from ShotGrid, and updates the corresponding Elasticsearch documents.

Progress and status messages are logged throughout execution. Enable debug mode (-d) for detailed field mapping and API call information.

Reviewing the Output

Where to Find Results

After the plugin completes, enriched metadata appears in several locations:

Diskover-Web Search Interface: Search for files and directories using the new shotgrid.* fields. Results will display the synchronized metadata alongside standard file system attributes.

Elasticsearch Documents: Each directory document that matched a ShotGrid shot or project will contain a shotgrid object with the configured fields.

Log Files: Execution logs provide details about the sync process, including counts of successful matches and any errors encountered.

What Successful Execution Looks Like

A successful run will log messages similar to:

=== Processing Shot Metadata ===
Found 150 matching shot codes.
Retrieved 148 shots
Shot processing complete - 148 successful, 2 failed

=== Processing Project Metadata ===
Found 3 matching project codes.
Retrieved 3 projects
Project processing complete - 3 successful, 0 failed

Identifying Problems

If metadata isn't appearing as expected, check for:

• Shot not found messages: The directory name doesn't match any shot code in ShotGrid for the configured projects

• Field not found errors: A configured shotgrid_field doesn't exist in the ShotGrid schema

• Connection errors: API credentials or host configuration may be incorrect

Successful Execution in Log Output:

python3 /opt/diskover/plugins_postindex/diskover_shotgrid/diskover_shotgrid.py -l /shotgrid

INFO - Starting diskover shotgrid ...
INFO - Finding latest index name for /shotgrid ...
INFO - Found latest index diskover-shotgrid-202604092314
INFO - --- Adding mapping to Diskover Elasticsearch...
INFO - Successfully added mapping to index: diskover-shotgrid-202604092314
INFO - === Processing Shot Metadata ===
INFO - --- Getting shot path information from Diskover...
INFO - Found 7 matching shot codes.
INFO - --- Adding ShotGrid fields to documents in Diskover...
INFO - --- Generating bulk data for Elasticsearch...
INFO - Loading 4 unique shots from 2 projects
INFO - Retrieved 4 shots
INFO - Shot processing complete - 7 successful, 0 failed
INFO - Successfully updated fields for all documents.
INFO - === Processing Project Metadata ===
INFO - --- Getting project path information from Diskover...
INFO - Project discovery statistics:
INFO -   Total directories processed: 25
INFO -   Valid projects found: 1
INFO -   Directories skipped: 24
INFO -   Maximum depth found: 12
INFO -   Depth 0: 1 directories
INFO -   Depth 1: 3 directories
INFO -   Depth 2: 7 directories
INFO -   Depth 3: 2 directories
INFO -   Depth 4: 2 directories
INFO -   Depth 5: 2 directories
INFO -   Depth 6: 1 directories
INFO -   Depth 7: 1 directories
INFO -   Depth 8: 1 directories
INFO -   Depth 9: 1 directories
INFO -   Depth 10: 1 directories
INFO -   Depth 11: 1 directories
INFO -   Depth 12: 2 directories
INFO - Found 1 matching project codes.
INFO - --- Adding ShotGrid project fields to documents in Diskover...
INFO - --- Generating bulk project data for Elasticsearch...
INFO - Loading 1 projects
INFO - Retrieved 1 projects
INFO - Project processing complete - 1 successful, 0 failed
INFO - Successfully updated project fields for all documents.

Searching in Diskover

After running the ShotGrid plugin, you can search for files and directories using the enriched shotgrid.* fields in the Diskover-Web search bar.

Default Shot Fields

Default Project Fields

Example Searches

Find all directories for shots currently "in progress":

shotgrid.status:ip

Find shots that are "final" or "approved":

shotgrid.status:(fin OR apr)

Find all files in a specific ShotGrid project by ID:

shotgrid.project:122

Find files in active projects only:

shotgrid.project_status:Active

Find shots created by a specific artist:

shotgrid.Created_By:"John Smith"

Find shots with a specific tag:

shotgrid.tags:hero

Find shots updated in the last week:

shotgrid.date_updated:[now-7d TO now]

Find large files (over 1GB) in "in progress" shots:

shotgrid.status:ip AND size:>=1073741824

Find EXR files in finaled shots:

shotgrid.status:fin AND extension:exr

Find all render directories in a specific project:

shotgrid.project:122 AND name:*render*

Find all files/directories enriched with ShotGrid data:

shotgrid:*

Find shot directories without ShotGrid data (for troubleshooting):

type:directory AND parent_path:*shots* AND NOT shotgrid:*

Sample Diskover query output for Shotgrid Type = VFX:

This shows all shot directories that exist in Shotgrid and Diskover that are for VFX shots!

Troubleshooting

Connection Issues

Symptom: ConnectionError or AuthenticationError when starting the plugin.

Solutions:

• Verify the shotgrid_host does not include the https:// prefix

• Confirm the API key is correct—regenerate it in ShotGrid if needed

• Check that your network allows outbound HTTPS connections to ShotGrid

• Verify the API script has appropriate permissions in ShotGrid Admin

No Metadata Appearing

Symptom: The plugin runs successfully but no shotgrid.* fields appear in Diskover.

Solutions:

• Verify shot directories exist with the expected */shots/* path structure

• Confirm directory names match ShotGrid shot codes exactly (case-sensitive)

• Check that the projects_path points to the correct base path

• Ensure project_name_to_id contains the correct ShotGrid project IDs

• Run with debug mode (-d) to see detailed matching information

Field Mapping Errors

Symptom: ConfigurationError: 'field_name' not found in shot data

Solutions:

• Verify the field exists in the ShotGrid schema (custom fields are typically prefixed with sg_)

• Check for typos in the shotgrid_field configuration

• Confirm the field is available on the entity type you're querying (Shot vs. Project)

Debug Mode

Enable debug logging for comprehensive troubleshooting information:

Linux:

python3 /opt/diskover/plugins_postindex/diskover_shotgrid/diskover_shotgrid.py -d -l /mnt/projects 2>&1 | tee shotgrid_debug.log

Windows:

python "C:\Program Files\Diskover\plugins_postindex\diskover_shotgrid\diskover_shotgrid.py" -d -l "D:\projects" 2>&1 | Tee-Object -FilePath shotgrid_debug.log

Debug output includes field mapping operations, shot/project discovery statistics, API query parameters, and document update counts.

Support

• Diskover Documentation

• Diskover Support Portal

• Autodesk ShotGrid API Documentation

• ShotGrid API Script Setup Guide

Last Updated: April 2026