A GUID (Globally Unique Identifier) is a 128-bit identifier that you use to identify an object reliably across database instances, APIs, imports, exports, and exposed links. This page is for MDriven developers who need stable object identities beyond one database.

What a GUID is

A GUID is usually written as 32 hexadecimal digits in five groups of 8-4-4-4-12, for example:

30dd879c-ee2f-11db-8314-0800200c9a66

A GUID has approximately 2^128 possible values (about 10^38). The available range makes two independently generated GUIDs being the same practically unlikely.

A GUID has no meaning by itself. It can identify any kind of object, such as a user, vehicle, file, or business record. The class and the application context determine what the identifier represents.

Use GUIDs as stable cross-system identities

Use a GUID when an object must be recognized outside the database instance in which it was created. This is especially useful when you:

• Send object data through an API.
• Import or export reference data between systems.
• Copy data between database instances.
• Create links that users or other systems may save.
• Need to distinguish objects created independently in different systems.

For example, System A and System B can each create a User with the same name and other business data. Their GUID values identify them as different objects even if their database row numbers happen to be the same.

GUIDs also support long-lived integration. When one system produces reference data, it must communicate deletions as well as new and changed objects; otherwise, a consuming system cannot know that an object should no longer exist. Object Identity describes the MDriven pattern for tracking creation, changes, and deletions for this purpose.

GUIDs and database keys

Keep the two identity roles separate:

Identifier	Use it for	Do not use it for
GUID	Identifying an object outside a database instance: APIs, transfer between systems, and stable exposed links.	Database-local table relationships and database-instance-specific row identity.
Integer primary and foreign key	Connecting tables efficiently inside one database instance.	Identifying an object after it has moved to another database instance or across an external interface.

MDriven databases use integer primary and foreign keys to connect tables. Treat these integer values as internal to that database instance. When you transfer or identify an object between systems, use its GUID rather than its integer row ID.

Do not include a GUID in a database index intended for ordinary database relationships. GUID values are unique and are not the database-local relationship keys used by MDriven for primary and foreign key connections.

Add and assign a GUID

A GUID is not required on every class, but it is strongly recommended for classes whose objects may be integrated, exported, or exposed outside the current database.

Use the following approach:

1. Add an attribute of type Guid to the class that needs a stable external identity.
2. Assign a new value when the object is created.
3. Preserve that value for the lifetime of the object; do not replace it during ordinary updates.
4. Use the value when an external system, API, or link needs to refer to the object.

In OCL or EAL, the newGuid operation creates and stores a new GUID in a Guid attribute. For an attribute named Guid, an object creation expression can be:

self.Guid.newGuid()

The Guid attribute must not be null when you use newGuid. See newGuid for the operation and its examples.

= Use a shared superclass for consistent identity

For a model with many business classes, place common identity and lifecycle attributes in a superclass and set it as the package's default superclass. A typical lifecycle pattern includes:

• CreateTime to record when the object was created.
• ChangeTime to record later changes.
• Guid to provide a stable cross-system identity.
• A deletion record that retains the deleted object's GUID.

For example, an OnCreate method can assign the creation time and GUID:

CreateTime:=DateTime.Now;self.Guid.newGuid()

An OnUpdate method can record the change time:

self.ChangeTime:=DateTime.Now

Object Identity documents this superclass pattern, including deletion logging with OnDelete and the event methods that MDriven triggers.

GUIDs in exposed identifiers and links

ExternalId values normally identify an object with a class identifier and a database-local object ID, such as Thing!10. This form is tied to a particular database instance and can be affected by model changes.

When a class has a Guid property, an ExternalId can instead use the Guid property form:

<classid>!GP!<guid>

Here, GP means Guid Property. GUIDs in this form can be sent without hyphens. For example:

Thing!GP!ad833fd8383c4389a88f3349166e7a74

Use this form for exposed links that need to remain tied to the same object over time, rather than to a database-local row number. See The ExternalId explained for the complete ExternalId syntax and link examples.

Persistence mapping

A Guid is one of the native attribute types available in MDriven. AutoGuid is a persistence-mapping option for a database-generated Guid value. If you are new to MDriven, focus first on modeling and normal persistence; change persistence mapping only when you have a specific requirement.

Checklist

Before exposing or synchronizing a class, verify that:

• The class has a Guid attribute when it needs an identity outside the current database.
• A new GUID is assigned when the object is created.
• The GUID is preserved when the object is updated.
• APIs, imports, exports, and cross-database transfers use the GUID rather than the integer row ID.
• Deleted objects can be identified by their GUID when consumers need to synchronize removals.

See also

• Documentation:Object Identity
• Documentation:OCLOperators newGuid
• Documentation:Autoguid
• Documentation:The ExternalId explained
• Documentation:Api documentation