Global Unique Identifiers (GUIDs) in Spotfire used to identify Document nodes

Global Unique Identifiers (GUIDs) in Spotfire used to identify Document nodes

book

Article ID: KB0082718

calendar_today

Updated On:

Products Versions
Spotfire Developer All Versions

Description

About Spotfire Global Unique Identifiers (GUIDs).
 
Note: This article only covers GUIDs used to identify Document nodes, and not the Library GUIDs. The GUID is a runtime generated hashstring that identifies objects in the Spotfire node tree.

Issue/Introduction

Global Unique Identifiers (GUID:s) in Spotfire used to identify Document nodes when using the API

Resolution

What does the GUID look like?

Document.ActivePageReference.Id == 4fb8eaf3-b5b4-4525-8028-b7a699c6e7d0. The GUID is the five sectioned hashstring.

Spotfire uses a runtime generated hashstring that uniquely identifies most complex objects in the node tree. These GUIDs are generated when the object is first constructed. GUIDs are never static, and will be rebuilt when certain conditions apply. The implication of this is that we cannot recommend storing and using GUIDs between sessions or clients. 
 
When are the GUIDs rebuilt?

When a linked analysis is opened, the document is cloned since it cannot be shared. When a Visual is cloned, a new GUID is generated (see GetObjectData method in Visual). If the document has linked data, the entire document must be cloned to create a local version of the data table. This will also rebuild the GUID identifiers, since we now have a new node tree. This is a common occurrence when an analysis is opened on the Web Player. In general, we can never assume that the GUIDs will be the same when an analysis is opened on different clients (Desktop vs Web Player). 

 
When should we use GUIDs?

GUIDs should be used very sparsely. If we temporarily have multiple objects and need to identify them by something other than TypeId and Title, we can use the GUID. If there are multiple objects with the same name, it may be useful to compare them using the GUID.

 
Compare by GUID:
if (myObject.Id == guid) {do something}
 
 
Are there better alternatives to using the GUID?

Usually it is better to use the object reference instead. GUIDs can only be used to identify objects, whereas object references are also called upon the object itself. Using the Title is the preferred way to find and compare objects of the same type. Object TypeIdentifiers are used to identify the sub-type of each object (ListBoxFilter, BarChart, etc.). If you are writing extension code, see 'UndoableCrossReferenceProperty' below.

Store object reference and use that:

Document doc = AnalysisApplication.Document;
doc.ActivePageReference = doc.Pages[2];
 
Compare by title:
if (myObject.Title == otherObject.Title) {do something}

Find which visual is a BarChart and change it to a LineChart.
if (visual.TypeId == VisualTypeIdentifiers.BarChart) { visual.TypeId = VisualTypeIdentifiers.LineChart; }
 
 
What is an UndoableCrossReferenceProperty?

The UndoableCrossReferenceProperty is used in the Spotfire C# extension code and fulfills the same purpose as the GUID. It is a static property that is permanently linked to a specific object in the node tree. From there on it can be used as a permanent reference to that object. The UndoableCrossReferenceProperty, unlike the GUID, is guaranteed to always work even if the surrounding Document changes. Always use the UndoableCrossReferenceProperty when working with extension code when you need a permanent reference to a specific object.

Additional Information

UndoableCrossReferenceProperty:
https://docs.tibco.com/pub/doc_remote/sfire_dev/area/doc/api/TIB_sfire-analyst_api/html/T_Spotfire_Dxp_Framework_DocumentModel_UndoableCrossReferenceProperty_1.htm
 
Typical GUID: