ShotGrid Data Modeling: Built-in Asset Entity vs. Custom Entities

The Dilemma: Generic Assets or Specialized Entities

When introducing a new category of trackable items—such as Props, Sets, or Digital Assets—into a ShotGrid production, you face a architectural choice: do you use the built-in Asset entity or create a Custom Entity? Choosing incorrectly often leads to "schema bloat," where a single entity contains dozens of fields that only apply to 10% of the records, making the UI cluttered and reporting inefficient.

Comparing the Approaches

The primary decision hinges on whether your new item shares the lifecycle of a standard character or environment asset, or if it requires a fundamentally different data structure and permission set.

Feature	Built-in Asset Entity	Custom Entity (e.g., 'Prop')
Setup Speed	Instant; out-of-the-box.	Requires Admin configuration.
UI Integration	Automatic inclusion in Asset pages.	Manual page/filter creation required.
Data Isolation	Low; shared fields across all assets.	High; dedicated schema per entity.
Versioning	Native integration with Versions.	Requires manual linking to Versions.
Maintenance	Low; managed by ShotGrid updates.	Moderate; requires schema management.

Trade-off Analysis

Use the Built-in Asset Entity when: Your items follow the standard pipeline (Modeling → Rigging → Texturing). If a "Prop" is essentially just a character that doesn't move, keeping it in the Asset entity allows you to use existing Asset-based reports and pipeline hooks without writing new code.

Use a Custom Entity when: The item has a distinct lifecycle or requires metadata that would clutter the Asset entity. For example, a "Prop" that requires tracking for physical procurement (Supplier, Shipping Date, Material Cost) is a poor fit for the Asset entity, which is designed for digital production milestones.

Implementing a Custom Prop Entity

To implement a custom entity, you must have Administrator permissions. While this can be done via the UI, using the shotgun_api3 Python library ensures the schema is documented and reproducible across different sites (e.g., from Staging to Production).

Prerequisites: Install the API library via pip install shotgun_api3.

import shotgun_api3

# Connection details
SERVER = "https://yourstudio.shotgrid.autodesk.com"
SCRIPT_NAME = "your_script_name"
SCRIPT_KEY = "your_script_key"

sg = shotgun_api3.Shotgun(SERVER, SCRIPT_NAME, SCRIPT_KEY)

# Define the custom entity 'Prop'
# Note: Custom entities are created via the Admin API or UI.
# This example demonstrates creating a record within a pre-configured custom entity
# and verifying the schema.

prop_data = {
    "project": {"type": "Project", "id": 123}, # Replace with actual Project ID
    "code": "Prop_Wooden_Chair_01",
    "sg_material": "Oak",
    "sg_supplier": "Furniture Co",
    "sg_url": "https://supplier.com/item/123"
}

try:
    # Create the record in the 'Prop' entity
    prop_id = sg.create("Prop", prop_data)
    print(f"Successfully created Prop with ID: {prop_id}")

    # Verification: Query the record back to ensure persistence
    verified_prop = sg.find_one("Prop", [["id", "is", prop_id]], ["code", "sg_material"])
    print(f"Verified Prop Code: {verified_prop['code']} Material: {verified_prop['sg_material']}")

except Exception as e:
    print(f"Error: {e}")

Operational Risks and Limitations

• UI Visibility: Custom entities are invisible to users by default. You must navigate to Admin > Pages to create a new page for the entity and define which columns are visible.
• API Rate Limits: Frequent schema changes via the API can trigger rate limits. Perform schema updates during maintenance windows.
• Permissioning: Unlike the Asset entity, which inherits standard project permissions, custom entities require explicit permission sets to be defined in the Admin panel to prevent unauthorized edits.

Verifying the Result

To confirm the implementation is successful, perform these three checks:

1. API Schema Check: Run sg.schema_field_read('Prop') to ensure the custom fields (sg_material, etc.) are registered with the correct data types.
2. UI Validation: Log into the ShotGrid web interface, go to Admin > Custom Entities, and confirm the "Prop" entity is listed.
3. Data Persistence: Create a record via the UI and verify it is queryable via the API to ensure there are no synchronization lags or permission blocks.

Rollback Procedure

If the custom entity creates too much overhead, you can migrate data back to the Asset entity by exporting the Custom Entity records to CSV and importing them into the Asset entity. Once data is migrated, delete the custom entity via Admin > Custom Entities. Warning: Deleting a custom entity permanently erases all associated records and their history.