Manage asset references within a project

Reference management makes importing and working with assets easier. When you rename or import an asset, links to that asset are remapped automatically within project workflows. The feature helps you build and maintain projects more efficiently.

This guide explains how reference management works in projects, and it includes API endpoints and troubleshooting tips.

API endpoints

API endpoint	Description
`POST /automation-studio/discoverReferences`	Find referenced resources (used by validation).
`POST /automation-studio/projects/import`	Import a project from a JSON document.
`POST /automation-studio/projects/{projectId}/components/add`	Add components to a project. This call only adds the listed components; it does not copy or move any sub‑components not included.

How reference management works

Reference management keeps dependencies in sync: when you change one asset, any assets that depend on it update automatically, avoiding stale links.

When you import an asset that has references—for example, a workflow that calls a JST—you can opt to import its referenced assets as well. If you do, the system copies each referenced asset into the project and updates the parent asset to point to the local copy.

Renaming a referenced asset inside a project updates all references to that asset automatically. For example, changing JST A to JST B updates workflows called JST A.

Use cases

Use case 1: A workflow in a project references a form. Renaming the form updates the workflow reference automatically.

Use case 2: You import a workflow from global space into an empty project. The import offers to copy referenced assets; if you agree, the workflow is updated to point at the local copies.

How to use reference management

Reference management is built into the Projects area of Studio. Project 6+ is required to use it.

Access Projects

Open the Projects page by clicking View All Projects on the Platform homepage, or choose Studio in the left nav and then click the Projects icon or the Try Projects button.

Build a new project

On the Projects screen, click New Project, enter a name, and select Build as the template type. This option lets you copy components from global space into the project.

Select components

If you pick a component that references others, you can also copy those references into the project. The tool then updates the parent asset to point to the newly copied local versions.

Checked boxes copy the component into the project. Unchecked boxes leave the reference pointing to the global space.

No matter what you choose, the parent workflow’s references update automatically to the correct location (local or global).

Internal project reference management

Inside a project, open reference management by clicking New Project, naming it, and choosing Example Project as the template type. Then click the Project References pop‑out button in the left nav. The project references management view opens on the canvas.

This view shows all project references, counts of external components (global or other projects), and buttons to refresh or collapse. Click a component to open it in a new tab.

Logs and monitoring

Any API call made while using the Projects app is logged with other API calls, based on your configuration. For more information on logging and monitoring, see Logging in Itential Platform.

Testing and validation

All testing and validation is fulfilled automatically by Itential. Tests for UI components are defined in the following files:

services/app-automation_studio/src/components/ProjectsEditor/ReferencesPanel/ReferencesPanel.test.jsx
services/app-automation_studio/src/components/ProjectsHome/CreateProject/CreateProject.test.jsx

API endpoints are defined in services/app-automation_studio/test/api/tests/, specifically ./projects/POST.projects.id.components.add.js for adding components.

For more information, see the addComponentsToProject API.