Secure Custom Entities in ShotGrid: Architecture, Design, and Operational Checks

The Problem: Custom Data Needs Without Exposing Sensitive Fields

Studios often need to track artifacts that don’t fit ShotGrid’s built‑in entities—budget sheets, vendor invoices, or legal clearances. Adding such data to existing entities (e.g., Assets or Tasks) clutters the UI and can leak confidential information to users who shouldn’t see it. The goal is to create a dedicated data model that is tightly scoped to a department, with fine‑grained visibility controls.

Requirements

• Define a bespoke data structure that can reference existing entities.
• Enforce read/write permissions at both entity and field level.
• Maintain the standard project‑wide access controls so that users cannot bypass restrictions by moving between projects.
• Provide a migration path for future schema changes without data loss.

The Smallest Suitable Design

Instead of sprinkling custom fields across default entities, create a Custom Entity in the Admin UI. For example, a Vendor Invoice entity with the following fields:

Field	Type	Purpose	Visibility
Invoice Number	Text	Vendor reference	Finance (Read/Write)
Amount	Currency	Total cost	Finance Lead (Read/Write)
Linked Asset	Entity Link	Asset reference	Finance (Read)
Notes	Text	Internal comments	Finance Lead (Read/Write)

Attach the entity to the relevant project and publish it. The entity now appears in the left‑hand navigation under Custom Entities.

Permission Group Setup

Create a Finance permission group:

1. Navigate to Admin > Permissions.
2. Create a new group called Finance.
3. Grant View and Edit rights on the Vendor Invoice entity.
4. Assign the group to users who should manage invoices.

Leave all other groups with No Access to that entity.

Trust & Data Boundaries

ShotGrid evaluates permissions in the API layer before data is sent to the client. The following layers enforce the boundary:

• Entity‑level Permissions – only groups with explicit rights can query the entity.
• Field‑Level Security (FLS) – within an allowed group, specific fields can be hidden or read‑only.
• Project Inheritance – if a user is removed from the project, all custom entity access is revoked automatically.

API‑Based Permission Check

Running a simple query from the ShotGrid API confirms the boundary. As a user in the Finance group:

sg = shotgun.Shotgun('https://yourshotgrid.shotgunstudio.com', login='user', password='pass')
records = sg.find("VendorInvoice", [], ["id", "invoice_number", "amount"])
print(records)

Attempting the same call as a non‑Finance user returns an empty list and an AccessDenied error.

Operational Checks & Failure Modes

Required Field Lock

Adding a new field and marking it as Required without a default value locks all existing records to read‑only. Users cannot edit them until the field is populated. To avoid this, add the field as optional, populate it via the API, and then toggle Required.

Field Type Mutation

Changing a field’s type (e.g., from Currency to Text) after data exists triggers a destructive operation. ShotGrid warns that data will be deleted. The safe path is:

1. Create a new field with the desired type.
2. Run a migration script that copies values from the old field to the new one.
3. Delete the old field once the data is verified.

# Example migration script
old_field = "amount"
new_field = "amount_text"
records = sg.find("VendorInvoice", [], ["id", old_field])
for r in records:
    sg.update("VendorInvoice", r["id"], {new_field: str(r[old_field])})

Permission Misconfiguration

Granting Admin rights to a broad group (e.g., All Users) defeats the trust boundary and exposes confidential fields. Regular audits—using the sg.get_permission_groups() API—help catch over‑permissioning.

When to Re‑Design

• If the custom entity grows beyond 10–15 fields, consider splitting it into multiple related entities to keep the UI responsive.
• When a department’s responsibilities change (e.g., Finance takes over Budget Sheets), create a new entity and transfer data via the API.
• If field‑level security becomes insufficient (e.g., you need per‑record masking), explore ShotGrid’s field_security API to implement custom logic.

Limitations & Verification

• Custom entities are project‑scoped; they cannot be shared across projects without re‑creation.
• Field‑level security does not apply to API calls that bypass the UI; you must enforce FLS in your own API wrappers.
• Always verify changes in a test project before rolling out to production. Use the sg.check_field_type() helper to detect destructive changes.

In summary, a focused custom entity combined with dedicated permission groups and field‑level security gives studios a lightweight, secure way to track departmental artifacts without compromising the overall pipeline integrity.