You can identify an MDriven object in URLs, integrations, and OCL by using an ExternalId; this page is for developers who need identifiers that continue to work when a model changes.
What an ExternalId identifies
An ExternalId identifies one object. Its original form combines the model's internal class index and the object's database primary-key value:
<classindex>!<objectid>
For example, 9!10 identifies the object with primary key 10 in the class represented by class index 9.
The class part is required because an object ID alone does not tell the framework which class contains the object. The internal class index can change when you update the model, so do not use the numeric form in links that users may save, share, or retain over time.
Choose an identifier form
Use the form that matches how long the identifier must remain valid.
| Form | Example | Use it when | Limitation |
|---|---|---|---|
| Numeric class index and object ID | 9!10
|
You use an identifier within a model version or in an internal scenario. | The class index can change when the model changes. |
| Class name and object ID | Thing!10
|
You need a more resilient URL or external reference within the same database instance. | The object ID is still a database-local integer and is not the best choice for references retained outside that instance. |
| Class name and GUID property value | Thing!GP!ad833fd8383c4389a88f3349166e7a74
|
You expose a reference in a link, email, integration, or other location where it can be saved and used later. | This requires a GUID property that can be resolved for the class. |
Use a class name instead of a class index
You can replace the internal class index with the class name:
<ClassName>!<objectid>
For example, use Thing!10 instead of 9!10. The class name avoids tying the reference to a class index that may be reassigned by a model update.
A class ID of 0 represents the topologically highest class in the model, often an abstract root class. The framework can attempt resolution from that root, but it may need to search tables to determine the object's relevant class. Specify the class name when you know it rather than relying on this broad lookup.
Use GUID values for exposed, durable links
For links and references that can leave the current database instance, use a GUID (Globally Unique Identifier) property rather than the database object ID. GUIDs are intended for object identification across systems; integer primary and foreign keys should remain internal to a database instance.
The GUID-based ExternalId format is:
<ClassName>!GP!<guid>
GP means Guid Property. Write the GUID in compact N format: 32 hexadecimal characters with no hyphens.
For example:
Thing!GP!ad833fd8383c4389a88f3349166e7a74
Use this form when a recipient can store the URL, such as an emailed invitation or a bookmarked file link. The reference is not based on a class index or a database-local row ID.
Prepare a class for GUID-based references
- Add and maintain a GUID property for the class you intend to expose.
- Ensure the property's value uniquely identifies the object. The documented OCL resolution behavior supports a property named
Guidwith type GUID or string when its value matches the supplied value. - Build the reference with the class name,
!GP!, and the compact GUID value. - Use that reference in the URL, integration payload, or stored external reference.
For example, if a Thing object has GUID ad833fd8-383c-4389-a88f-3349166e7a74, use:
Thing!GP!ad833fd8383c4389a88f3349166e7a74
Example: address an image attribute
An MVC GetImage request can take an object identity followed by a hyphen and the name of the Blob attribute. If SomeImage is the Blob attribute, the numeric form is:
http://localhost:5052/Turnkey/GetImage?img=9!10-SomeImage
Prefer the class-name form when the URL must survive class-index changes:
http://localhost:5052/Turnkey/GetImage?img=Thing!10-SomeImage
Prefer the GUID-property form for a link that may be saved or shared:
http://localhost:5052/Turnkey/GetImage?img=Thing!GP!ad833fd8383c4389a88f3349166e7a74-SomeImage
The final -SomeImage part is the attribute name, not part of the ExternalId.
For ViewModel-driven file downloads, use Using BlobDownloadLink. That feature uses GetVMFile; consult this page when you need to control how an ExternalId is formed in a URL.
Create and resolve ExternalIds in OCL
In OCL, use externalId to obtain an object's external identifier. For example:
Customer.allInstances->first.externalIdUse objectfromExternalId when you have an ExternalId and need the corresponding object. The resolver recognizes alternative representations, including GUID-based values when an appropriate GUID property matches. See OCLOperators externalId and OCLOperators objectfromExternalId for the operator syntax and behavior.
ExternalId is not VMClassId
Do not confuse an ExternalId with a ViewModel class identifier (VMClassId). A VMClassId identifies an object in the context of a ViewModel or ViewModel nesting and has a different format, such as 2!9;PersonSeeker.