AYON

Clustta integrates with AYON so teams can keep production planning in AYON while using Clustta to create, version, synchronize, and launch workfiles.

An administrator links an AYON project to a Clustta project, maps its folder types, task types, templates, and statuses, then imports the required production structure. Artists work from Clustta: they open an assigned asset, Clustta restores any missing file data, prepares the configured application, and launches the workfile.

What the integration does

The integration maps AYON production data to Clustta entities:

AYON	Clustta
Project	Linked project
Folder	Collection
Task	Asset and workfile
Folder type	Collection type
Task type	Asset type and file template
Task status	Project status

Clustta can also:

• Open the mapped AYON task in the AYON project browser.
• Push mapped status changes to AYON.
• Upload a checkpoint preview as an AYON reviewable activity.
• Set an uploaded image as the AYON task thumbnail.

Clustta remains responsible for the workfile, checkpoints, synchronization, dependencies, and recovery. AYON remains the production tracking system.

Before you begin

You need:

• An AYON Server reachable from the computers configuring and using the integration.
• An AYON service-user API key that can read the projects, folders, tasks, task types, and statuses you want to import.
• A Clustta plan that includes integrations when using the hosted service.
• Permission to manage integrations in the Clustta project.
• Clustta collection types, asset types, and file templates for the AYON work you want to import.
• The required DCC applications installed on artist workstations.

Use the AYON Server origin as the server URL, for example:

https://ayon.example.com

Do not append an individual REST endpoint such as /api/profile. Clustta adds the required AYON API paths.

Connect Clustta to AYON

1. In Clustta Desktop, open Settings > Connections > Integrations.
2. Select Connect Integration, then select AYON.
3. Enter the AYON Server URL and service-user API key.
4. Select Connect.

Clustta validates the key against AYON and stores it for the current Clustta client. This connection is used to browse AYON projects, import production structure, and send supported updates back to AYON.

Link an AYON project

1. Open the Clustta project that will contain the workfiles.
2. Open Project Settings > Connections > Integrations.
3. Select Link and choose AYON.
4. Select the matching AYON project.
5. Select Link Project.

The link stores the AYON project name as its external identifier. A Clustta project can have one linked external integration at a time.

Configure the mappings

Complete the project mappings before importing AYON tasks.

Directory Mapping

Use Directory Mapping to define where AYON folders and tasks appear in the Clustta collection tree. Review the generated paths and output names before importing.

Asset Type Mapping

Use Asset Type Mapping to map each AYON task type to:

• A Clustta asset type.
• A Clustta file template.

The selected template determines the workfile created for the imported task. For example, map an AYON Modeling task to a Blender asset type and .blend template, or a Compositing task to the appropriate Nuke template.

Every task type selected for import needs a valid template mapping. Clustta reports missing type or template mappings in the import preview.

Status Mapping

Use Status Mapping to map each Clustta status to an AYON task status.

The mapping is used in both directions where supported:

• The initial import translates an AYON task status to the matching Clustta status.
• Later Clustta status changes are pushed to the mapped AYON task.
• Creating a single-asset checkpoint with Send to AYON enabled pushes the mapped status and any selected preview.

Avoid mapping multiple Clustta statuses to the same AYON status when you expect statuses to import into Clustta. An ambiguous reverse mapping cannot be applied reliably.

Import the AYON project structure

1. Open the create menu in the linked Clustta project.
2. Select the integration import action.
3. Wait for Clustta to load the AYON import preview.
4. Expand the hierarchy and review the collections and task assets.
5. Select the folders and tasks you want to create or link.
6. Resolve any missing type or template mappings shown for the selection.
7. Select Import selected.

The preview shows items that will be created, linked to existing Clustta entities, or skipped because they are already mapped. Selecting a collection includes its eligible descendants, and selecting a child includes any required parent collections.

Each imported AYON task becomes a mapped Clustta asset. Its workfile is created from the template assigned to that AYON task type. The integration mapping allows Clustta to send later status and preview updates to the correct AYON task.

Items blocked by the current user's permissions cannot be selected. The importing user needs the relevant collection and asset creation permissions.

Linking is not enough

Linking the projects does not create workfiles. Configure the mappings and complete the integration import before asking artists to launch AYON tasks from Clustta.

Configure Clustta as the launcher

By default, Clustta opens an asset with the operating system application associated with its file extension. Artists can also use Open With from the asset menu to choose an application.

For a consistent studio setup, configure a project launch hook:

1. Open Project Settings > Advanced > Scripts.
2. Configure the tracked script directory and allowed script extensions if launch preparation requires a script.
3. Define any project environment variables required by the DCC.
4. Open Project Settings > Hooks.
5. Add a launch hook for the workfile extension.
6. Select the required installed application version, optional preparation script, environment variables, and failure policy.

A version-only hook can select the required DCC version without running a script. Scripted launch preparation currently supports Blender (.blend) and Maya (.ma, .mb). Clustta discovers supported installed DCC versions on each workstation.

Use <ProjectRoot> in an environment value when the path should resolve from each collaborator's local project directory. Hook scripts must be tracked project assets. Clustta asks the artist to review and trust a script before its first execution and again when the trusted configuration or script contents change.

Artist workflow

Open an AYON task from Clustta

1. Start Clustta Desktop and open the linked project.
2. Find the imported task asset or filter the browser to the artist's assignments.
3. Double-click the asset to launch it, or use Open With from its menu.

If the workfile is not available locally, Clustta restores the current checkpoint first. It also fetches tracked files required by the matching launch hook. Clustta then runs the configured preparation and opens the workfile in the selected DCC.

If no launch hook matches the extension, Clustta uses the operating system's default application.

Save and checkpoint work

Artists save in the DCC as usual, then create a Clustta checkpoint. The checkpoint records the workfile history and can be synchronized with the studio repository.

For a mapped AYON asset, the checkpoint dialog shows Send to AYON. When enabled for a single-asset checkpoint:

• The mapped Clustta status is pushed to the AYON task.
• A selected preview is uploaded as an AYON reviewable activity.
• An image preview can become the AYON task thumbnail when it is used as the asset cover.

The Clustta checkpoint is still created if the later AYON push fails. Clustta reports the integration error separately so the artist can retry after fixing the connection or credentials.

Change task status

Changing the status of a mapped asset in Clustta pushes the corresponding mapped status to AYON in the background. If AYON does not change, confirm the asset has an AYON mapping, the status mapping exists, and the stored API key remains valid.

Verify the workflow

Use one AYON task for an end-to-end check:

1. Confirm AYON appears as connected in Settings > Connections > Integrations.
2. Confirm the Clustta project is linked to the expected AYON project.
3. Confirm the AYON task type has an asset type and file template mapping.
4. Import the task and confirm its collection and asset appear in Clustta.
5. Double-click the asset and confirm Clustta opens it in the expected DCC.
6. Save a small change and create a checkpoint with Send to AYON enabled.
7. Confirm the checkpoint exists in Clustta.
8. Confirm the mapped status and optional reviewable appear on the AYON task.

Troubleshooting

Clustta cannot connect to AYON

Check the AYON Server URL, API key, TLS certificate, and network access from the workstation. The key must return a valid profile and allow the selected project metadata to be read.

No AYON projects appear when linking

Confirm the API key can read active AYON projects. Clustta lists active projects returned by AYON.

The import preview reports missing mappings

Open Project Settings > Connections > Integrations and configure the missing collection type, asset type, or file template. Reload the preview after saving the mappings.

The workfile opens in the wrong application

Check the operating system's default application for the file extension or use Open With. For a project-wide choice, configure a version-only launch hook for that extension.

The required DCC version is not found

Install the selected application version on the artist's workstation or update the project launch hook. Project launch settings synchronize, but DCC installations do not.

A launch script is blocked

Review the trust prompt and the listed tracked scripts. Missing scripts, modified script paths, unavailable environment paths, or a Block launch failure policy can stop the launch. Correct the reported issue and try again.

A status or preview does not reach AYON

Confirm that:

• The asset was created or linked through the AYON import and has an integration mapping.
• The Clustta status maps to an AYON task status.
• AYON is still connected in the current Clustta client.
• The API key can update the task and create reviewable activities.
• Send to AYON was enabled when creating the checkpoint.

Only a single-asset checkpoint can send a preview to AYON. Multi-asset checkpoints do not upload a shared preview.

Current behavior

The AYON integration is an import-and-launch workflow. AYON structure is brought into Clustta through the project import, while mapped status and checkpoint preview updates are sent back during normal Clustta work.

For application versions, scripts, and environment preparation, see DCC launch configuration.