> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-cloud/studio/projects/manage-asset-references/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Manage asset references within a project

> How reference management works in Itential Platform Projects, including renaming, importing, and remapping referenced assets.

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](/itential-platform/monitor/log/overview).

## 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.

## Related reading

For more information, see the [addComponentsToProject API](https://apidocs.itential.com/api/app-automation_studio/addComponentsToProject/).

> How reference management works in Itential Platform Projects, including renaming, importing, and remapping referenced assets.