Project Reference Validation

Feature Introduction

Itential Platform users can now build Projects within Studio (formerly Automation Studio) to include existing assets within an automation or orchestration. This new feature capability is available in Platform 6 through a reference validation mechanism to ensure project assets are suitable for their intended use.

The guide will explain how Project Reference Validation works within Platform 6, including the API endpoints for testing and validation, and how to troubleshoot any issues that may occur while using the feature.

Reference Validation in Projects

Reference Validation brings the ability to migrate projects between environments with the confidence that the project will operate as expected in the new environment. This feature analyzes the external references to a project (Golden Configurations, Triggers, LCM Resources, Compliance Reports and any other Studio component such as a JST, Template, or JSON Form) and notifies the user if any referenced assets are missing or not identical between environments.

Use Cases

When moving projects between environments, users can experience unexpected behavior by a project if that project references an external asset with different functionality within the destination environment. This new feature will validate whether a referenced asset has changed between environments and alert users of the reference mismatch and give them the opportunity to resolve the mismatch. Essentially, this feature capability allows users to discover, select and import/export existing assets into a Project across environments. The following use cases give a better example.

Use Case 1: A user imports a project which references a Studio component within the global space of IAP. The imported project checks to ensure that the referenced asset exists. If the asset does not exist, the user is alerted about the missing asset and then prompted to continue or to cancel the import.

Use Case 2: A user has a project which compares a devices config against a Golden Config. The project is exported from the staging environment and then imported into a production environment. Upon import, the project references a different version of the Golden Config. Projects now notifies the user of the mismatch, prompting the user to continue or to cancel the import.

How to Use Reference Validation

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

This feature works in a single environment; however, to test different scenarios using this feature, you should have two (2) environments, "old" and "new" respectively.

• "Old" - Development/Staging
• "New" - Staging/Production

There are three main scenarios where you will use Reference Validation in Projects:

• Importing a new project that references a global asset from your "Old" environment (i.e., the project file does not contain all referenced components).

• Importing a new project that references a global asset in your "New" environment, but the "New" global asset does not match the "Old" global asset.

• Push and Pull changes for a project using an external Git Versioning Control System will behave in the same manner as the above two scenarios, as Git just simplifies the import/export process.

The first two scenarios are described in further detail in the next few sections.

Importing a New Project with Global Asset References

This situation applies when a user attempts to import a new project into their "New" environment, except the project references global assets in the "Old" environment. To see how this works, the customer should create a project in their "Old" environment that references a component in the global space.

Step 1: Create a Project in the Old Environment

Here's the steps involved to reference a component in the global space.

1. From the Projects main page, click the New Project button.
2. Give the project a name and choose the Build option from the Project Template dropdown.
3. Select components so that at least 1 (one) component stays in the global space. In Figure 4, "Child Workflow 3" will not be copied to the project; thus, the new project will reference it from the global space.

Figure 1

 

Figure 2

 

Figure 3

 

Figure 4

Step 2: Export and Import the Project

Next, export your project from the "Old" environment and then navigate to the "New" environment and click the Import Project button. You will then be notified that your project is missing components in the "New" environment. At this point, you can choose to Continue, despite the risk of your project not working as expected, or Cancel the import. In this situation, let’s choose to Continue. If you navigate to the project, you can see the Project Reference Management UI will not show the global asset (as it doesn’t exist in the "New" environment). If you were to run this workflow, it would error out by saying {component_name} not found.

Here's the steps involved:

1. Export the project by clicking the Download button on the Project screen.
2. Import the project into the "New" environment.
3. Select the file you just exported and click the Import button. A warning screen displays.
4. Click Continue on the warning screen. Your project will be referencing an asset that doesn’t exist in this environment. This means if you tried to run the workflow, it would not work, saying {component_name} not found.

Figure 5

 

Figure 6

 

Figure 7

 

Figure 8

 

If you choose not to continue:

• From the "New" environment, delete the project that was just created. Now, when you try to import it, you will see the same error message as before.
• This time, click Cancel. Since you are missing the global asset, you will need to import it into the "New" environment. To do this, go back to the "Old" environment and export the global asset that is being referenced.
• Then, in the "New" environment, import that global asset into the global space by navigating to Studio (formerly Automation Studio) and importing there.
• Now, try to import your project again. This time, it should import as expected.

Importing a New Project with Updated Global Assets References

This situation applies when a user tries to import a project into the "New" environment that contains references to global assets, except the "New" environment’s global assets have been modified.

1. Create a project in the "Old" environment that references something in the global space (see the steps for this above).
2. From there, export that project. Also, export the globally referenced asset.
3. In the "New" environment, upload just the globally referenced asset.
4. Make some changes to that globally referenced asset. This causes the hash of the asset to be modified (and therefore, it won’t match the hash of the exported project).
5. Now, try and import the project to the "New" environment. You will see an error message saying a component does not match (Figure 9). You can still click Continue to import anyway, however, be aware the project will reference the updated component and not the old one, which can cause unexpected behavior.

Figure 9