Understanding AF GUID Dependencies in OSIsoft PI System Client Applications

When managing OSIsoft PI AF (Asset Framework) databases, especially during migrations or major updates (such as deleting and recreating data via XML import), it's essential to understand how client tools handle the identity of AF elements—specifically, whether they reference objects by their unique GUIDs or by their paths. This distinction becomes crucial, as importing can result in new GUIDs being assigned to seemingly identical elements, potentially impacting your client applications and displays.

What Happens During an AF Import?

When you export and delete elements from one PI AF system and then import them (for example, via XML), each element gets assigned a new GUID. This is by design and ensures the uniqueness of each element within the database. However, while the element names and paths might remain unchanged, the internal unique identifier (GUID) will not.

Path vs. GUID: How Do Client Tools Reference Elements?

OSIsoft PI client tools—such as PI ProcessBook, PI Coresight (now PI Vision), PI DataLink, and Web Parts—primarily use the path of an element to locate it within the AF hierarchy. This design choice means that, in most standard configurations, your displays and reports will continue to function after a migration that changes GUIDs, provided the paths/names remain the same.

However, there are exceptions. If a client tool or custom integration stores the GUID of an element—especially across sessions or for functionalities like notifications and custom data references—problems can occur when those GUIDs change after migration. There have been known issues, particularly in PI Notifications, where reliance on the GUID resulted in broken configurations after import/export operations.

Pro Tip: While changing element or parent names will break path-based references, path-based references are generally safer than relying solely on GUIDs, given the volatility of GUIDs during migrations.

Known Issues and Best Practices

• Notifications: Historically, notifications were particularly sensitive to GUID changes. Bugs relating to import/export operations and broken notifications were observed when objects were referenced exclusively by GUID.

• Client Application Bugs: While most OSIsoft client applications are intended to use object paths, there have been bugs where GUIDs were inadvertently stored or referenced. It's best to consult OSIsoft's documentation or support channels for up-to-date bug reports if you're concerned about a specific product version.

• Custom Integrations: If you build your own applications or data references, always be cautious about referencing by GUID alone. Instead, consider storing both the GUID and path:

  • Use the GUID for fast/easy lookups.
  • Fall back to the path if the GUID cannot be found (e.g., after a migration).

This dual-reference approach provides robustness against both migration (GUID change) and hierarchy reorganization (path change).

Migrating Between Environments: Essential Tips

• Copying PIFD Database: The only way to guarantee that GUIDs remain the same across environments is to copy the entire PIFD SQL database. XML or AF export/import operations, even with the "Include Unique IDs" option, will generate new GUIDs for newly created objects.

• Testing is Essential: Always test client applications (especially custom ones or those requiring persistent references) after migration to confirm that all references still work as intended.

Conclusion

For most users, relying on element paths is the intended and safe method, as designed by OSIsoft for their standard client tools. However, if your workflow involves AF migrations, custom integrations, or scenarios where unique identifiers are critical, it's vital to understand the nuances between path and GUID references. When in doubt, store both—and always test your applications after significant AF structural changes to ensure continuity and reliability.

Further Reading:

• OSIsoft PI Asset Framework Documentation
• Handling PI AF GUIDs in Client Applications

Keywords: PI System, Asset Framework, GUID, path, migration, client tools, ProcessBook, Coresight, DataLink, Notifications