P4 Dam Workflows

query_p4dam_file_reviews — each result item

query_p4dam_workflow_states — each result item

Common Workflows

1. Search and filter assets

# By keyword (filename, tags, or custom attributes):
query_p4dam_assets(search_term="monocycle")

# Narrow by project or file type:
query_p4dam_assets(project_ids=["proj-uuid"], file_extension=["png", "svg"])

# By date range or size:
query_p4dam_assets(search_term="hero", from_date="2024-01-01", to_date="2024-12-31")
query_p4dam_assets(from_size=1048576, to_size=52428800)  # 1 MB – 50 MB

# By depot path pattern:
query_p4dam_assets(path=["//depot/art/characters/..."])
query_p4dam_assets(path=["//depot/renders/*.png"])

2. Fetch full metadata for a known asset

query_p4dam_asset(depot_path="//stream/images/logo.png")

To include file_review, comments, or all_comments, pass project_id and repository_id. Find them in stream_view_matches or helix_classic_branch_matches from the initial result:

query_p4dam_asset(depot_path="//stream/images/logo.png", project_id="proj-uuid", repository_id="repo-uuid", include=["file_review", "all_comments"])

3. View a thumbnail or preview

# From query_p4dam_assets result:
fetch_p4dam_media(url=<result.thumbnail_url>)

# From query_p4dam_asset result (higher resolution):
fetch_p4dam_media(url=<result.preview_url>)

4. Create an asset bundle (helix_stream repo)

query_p4dam_projects(search_term="characters")
query_p4dam_repositories(project_id="proj-uuid")
create_p4dam_asset_bundle(
    depot_path="//stream/bundles/q3-chars.p4bundle",
    project="proj-uuid",
    repository="repo-uuid",
    view_paths=["//stream/renders/...", "//stream/textures/..."],
    stream_path="//stream/mainline",
    description="Q3 character renders"
)

5. Sync a bundle to local workspace

# Get view_paths from asset_bundle section:
query_p4dam_asset(depot_path="//stream/bundles/q3-chars.p4bundle", include=["asset_bundle"])
sync_p4dam_asset_bundle(view_paths=<asset_bundle.view_paths>)

6. Create a file review

# Discover the state short_name first:
query_p4dam_workflows(include=["states"])
create_p4dam_file_review(
    project_id="my-project",
    name="Q3 hero renders — art director pass",
    depot_path="//stream/bundles/q3-chars.p4bundle",
    view_paths=["//stream/renders/..."],
    state="open"
)

7. Transition a review to a new state

query_p4dam_workflow_states(workflow_id="default_workflow")
update_p4dam_file_review(project_id="my-project", review_id="review-uuid", state="in-review")

8. Tag assets

# Tag a single file:
update_p4dam_asset_tags(paths=[{"path": "//stream/renders/hero.png"}], create=["hero", "q3-final"])

# Tag an entire folder recursively:
update_p4dam_asset_tags(paths=[{"path": "//stream/renders/..."}], create=["q3"])

# Remove a tag:
update_p4dam_asset_tags(paths=[{"path": "//stream/renders/hero.png"}], delete=["wip"])

# Propagate to future revisions:
update_p4dam_asset_tags(paths=[{"path": "//stream/renders/hero.png"}], create=["hero"], propagatable=true)

Best Practices

• Use query_p4dam_assets first to discover assets; switch to query_p4dam_asset for full metadata on a known depot path.
• After showing query_p4dam_asset results, indicate which extra data can be fetched by re-calling with additional include values: comments (comments on the queried revision only), all_comments (comments across all revisions), file_count (number of files in a bundle), scene_refs (referenced files).
• Leave all_revisions=false (default) in asset searches unless you need history — latest-only is faster.
• When query_p4dam_asset results include thumbnail_url, preview_url, or sprite_url, the asset is an image — render it via fetch_p4dam_media. These fields are only present for image files.
• When query_p4dam_asset returns commit, always show "Submitted on {date} by {author} (#{changeset})" followed by the commit description truncated to 512 characters. If latest_commit is present and differs from commit, also show "You're viewing changeset #{commit.number}, latest is #{latest_commit.number} from {date}".
• When query_p4dam_asset returns a non-empty scene_refs, indicate that this file has referenced files, and list each by depot_path. Mark entries where exists is false as missing. Render thumbnail_url via fetch_p4dam_media if present. Applies to both query_p4dam_assets and query_p4dam_asset.
• When query_p4dam_asset returns custom_attributes, list them as "{name}: {value}", skipping entries where template.hidden is true.
• When query_p4dam_asset returns weblinks, list them as markdown links: [{text}]({url}), falling back to the URL as text if text is blank.
• When query_p4dam_asset returns file_reviews, show each as: "{name}" — state {state.short_name}, created by {creator}.
• When query_p4dam_asset returns an asset_bundle object, indicate that this asset is an asset bundle.
• When query_p4dam_asset returns an asset_bundle_origin object (but no asset_bundle), indicate that this is a .p4bundle file derived from a bundle at a different depot path (e.g. branched or integrated).
• When query_p4dam_asset returns a parent_asset_bundles object, indicate that this asset is part of an asset bundle.
• project_id and repository_id accept either UUID or short name in all tools.
• For helix_stream repos, stream_path is required when creating bundles or reviews. Find it in linked_streams from query_p4dam_repositories.
• For helix_classic repos, helix_classic_branch is required. Use query_p4dam_helix_classic_branches to discover it.
• When creating a file review, the state field value is ignored by the backend — new reviews always start in the project's first open state.
• sync_p4dam_asset_bundle requires P4CLIENT to be set in the environment.
• When results include a non-empty helix_classic_branch_matches, list each entry as "{short_name} ({project.short_name} / {repository.short_name})", marking the default branch. Applies to both query_p4dam_assets and query_p4dam_asset.
• When results include a non-empty stream_view_matches, list each entry as "{stream_path} ({project.short_name} / {repository.short_name})".