Project Reference Management

Feature Introduction

Reference management enhances the experience of importing and working with assets within Projects. With reference management, users can now rename and import assets, and have the links to those assets dynamically remapped within their respective project workflows. This feature helps Itential Platform users efficiently create and manage their projects.

The guide will explain how Reference Management works within Projects for the Platform 6 release, including related API endpoints, and how to troubleshoot any issues that may occur while using the feature.

API Endpoints

A user should be familiar with Projects in general, as well as each component type (i.e., workflows, forms, templates, transformations, etc). Users should know how to open a project in the editor view and import/transfer components into the project. Additionally, there are various APIs that are related:

Reference Management in Projects

Reference Management in Projects is designed to ensure integrity so that when one asset changes, any other assets relying on it are updated, thereby preventing errors and properly managing asset references.

When importing an asset with references (such as a workflow or JST) into a project, the references can be selected for import into the project along with the parent asset. When this is done, the referenced assets are re-mapped to be local to the project. For example, a workflow is selected for import into a project, a referenced JST is discovered and offered to the user for import along with the workflow. If this option is selected, the workflow and JST are both copied into the project, and the workflow is modified so that it references the JST that was just copied into the project.

When renaming referenced assets within a project, assets also will have their references updated to the new name. For example, if a project has a workflow that references a JST by “JST A”, and that name is updated to “JST B”, then the reference within the workflow will be updated to point to “JST B”.

Use Cases

The following use cases are good examples of how Reference Management supports the user experience and efficiently manages projects.

Use Case 1: A user has a project with a workflow and a form. The workflow references the form. The form is renamed, and the reference to the form within the workflow is automatically updated to the new name.

Use Case 2: A user has an empty project. A workflow from the global space is selected for import into the project. Upon import, the user is offered to copy the references from that workflow into the project. If the user selects to copy these references into the project, the parent workflow is now updated to point to the references that are now local to the project.

How to Use Reference Management

To use this feature, you must have a running instance of Platform 6. The Reference Management logic is built directly into the Itential Platform, specifically the Project space in Studio (formerly Automation Studio).

Access Projects

To use the Reference Management feature, you need to first access the Projects page.
There are a couple of ways to do this. You can click View All Projects on the upper-right of the screen of the Itential Platform homepage (Figure 1). Alternately, you can select Automation Studio from the left side navbar menu to open the Studio application (Figure 2) and then click the Projects icon in the top toolbar, or click the Try Projects button in the Projects card (Figure 3).

Figure 1

 

Figure 2

 

Figure 3

Build a New Project

Once on the Projects screen, you can then build a new project by clicking New Project, giving it a name, and then selecting Build from the template type dropdown. This will allow you to copy over components from the global space into the project.

Figure 4

 

Figure 5

Select Components

If you select a component, such as a workflow, that references other components, you have the option to copy those other components into the project as well. When this occurs, the Project Reference Management tool will automatically update your parent workflows to point to the new components.

From the examples below, selecting the parent workflow will automatically select any referenced components as well. When the boxes are checked, the components will be copied into the new project. When unchecked, the component will not be copied, but the parent workflow will still reference that component from the global space, instead of the local project space.

Figure 6

 

Figure 7

 

Alternatively, if you choose not to copy over the components into the project and instead choose to reference the components from the global space, the parent workflow is then updated to reference (point) outside of the project. In other words, whatever the user decides to do, any references to components are automatically updated to point to the specified location. In the example image (Figure 7), "Child Workflow 3" will not be copied to the project.

Internal Project Reference Management

To utilize Reference Management inside of a project, you will need to build a project by clicking New Project, giving it a name, and the selecting Example Project from the template type dropdown. Once inside the project, you will notice the left navigation bar now contains a Project References pop-out button. When you click the button, the Project References Management view will pop-up onto the canvas. From this view, you can get information about the references, if any, used in the project. You can also see the total number of externally referenced projects, whether from the global space or other projects, as well as the option to refresh the status of the references and collapse the view. Clicking any component within this view will open that component up in a new tab.

Figure 8

 

Figure 9

 

Known Limitations, Troubleshooting & Support

Currently, there are no known limitations, constraints or issues associated with this feature.

Should you encounter any issues or need support, please reach out to the Itential Service Desk using the Customer Portal link.

Logs & Monitoring

Any API call used while utilizing the Projects app is logged with other API calls, based on user configuration. More information on logging and monitoring in the Itential Platform is available in the Event Logs & Logging guide.

Testing & Validation (Developer)

All testing and validation is fulfilled automatically by Itential.

Tests for the UI components are defined in the following files for the two (2) UI elements:

• 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 the services/app-automation_studio/test/api/tests/ folder, specifically the ./projects/POST.projects.id.components.add.js file for adding components.

Related Reading

• addComponentsToProject API