SysSingleton is the modeled application root for Turnkey applications; use it to expose application-wide state such as the currently logged-in user to your ViewModels and OCL expressions.

What SysSingleton is

SysSingleton is a class that implements the Singleton pattern: your application has one instance of the class. It acts as a global model object rather than requiring separate global variables.

In a Turnkey application, SysSingleton commonly holds the association that identifies the current SysUser. This makes login state available in the model context. For example, an expression can test whether the current user is an administrator:

SysSingleton.oclSingleton.CurrentUser.IsAdmin

SysSingleton can also have associations and code-derived attributes. Use these to make relevant runtime or application state available where model expressions run. Do not use it as a substitute for normal domain ownership: an Order should still be associated with its Customer, rather than being placed on SysSingleton only to make it easy to find.

Access the singleton in OCL

Set the Eco.IsSingleton tagged value on the SysSingleton class to true. You can then use the oclSingleton operator to obtain its only instance.

SysSingleton.oclSingleton

If no instance exists when the expression runs, oclSingleton creates one. Continue navigation from that object to read its state. For example:

SysSingleton.oclSingleton.CurrentUser

The singleton requirement is exact: there must not be two persisted SysSingleton objects. See Keep only one instance if this occurs.

Use SysSingleton for login state

SysSingleton and SysUser implement the user-login pattern. The CurrentUser association identifies the user for the active application context.

Keep CurrentUser non-persistent (transient). A persisted current-user association would store a login-specific value in the database instead of treating it as runtime state. The authentication training model demonstrates this configuration: select the CurrentUser association and verify that Persistent is false.

A typical check in an OCL expression is:

SysSingleton.oclSingleton.CurrentUser.IsAdmin

This expression starts at the application root, follows CurrentUser, and evaluates the user's IsAdmin property. Build your access checks around the authenticated SysUser and its access-group design; follow Bootcamp Chapter 11 for the authentication model, login test, and debugger exercises.

Optional runtime properties

Turnkey can populate selected optional properties on SysSingleton when they are modeled. These values are intended for per-user-session runtime information, so model them as non-persistent properties.

Need	Use
Client IP address, runtime system type, or client user-agent	SysSingleton optional properties
Notification when CurrentUser is assigned or cleared during login or logout	OnCurrentUserChanged behavior
The URL of the running Turnkey system for a fully qualified link or QR image	GetSystemUrl
TurnkeyServer setting functions exposed through an external late-bound method	MiscSetting

For example, use GetSystemUrl() when an expression must form a complete address to content in SiteAssets, rather than a relative address. That method is available at the Turnkey level, not at the MDrivenServer level; see GetSystemUrl for the required method definition and limits.

Keep only one instance

A model marked as a singleton can fail if the persistence store contains more than one SysSingleton object. You may also leave it with zero instances: oclSingleton creates an instance when one is first requested.

To remove an extra persisted instance while using MDrivenServer persistence:

1. In MDriven Designer, open Play and choose MDrivenServer persistence.
2. Start the system and open the debugger.
3. In the class picker, select SysSingleton.
4. Enter Select 50 and execute it with F5 to inspect the returned objects.
5. Choose Seeker and select one of the duplicate objects.
6. Select Delete Selected. Leave one SysSingleton instance, or remove all instances if you want oclSingleton to create one later.
7. Return to the main debugger form and click Save.
8. Refresh the application page and verify that it works again.

This procedure applies to persisted duplicates. Do not attempt to solve the issue by changing application expressions to select an arbitrary SysSingleton instance.

Working with root associations

SysSingleton is also the model root used by certain association-lookup expressions. When you use bracket qualifier syntax on an association rooted at SysSingleton, the fallback operator expects a role name and uses zero-based indexing. For example, ApiSearchResults[0] addresses the first object linked through that role. See Qualify GenericAt0 for syntax, requirements, and preferred OCL alternatives.

Learn by doing

Bootcamp Chapter 11 walks through the authentication model and has you:

1. Verify that SysSingleton has IsSingleton enabled.
2. Run SysSingleton.oclSingleton in the prototype.
3. Confirm that CurrentUser is transient.
4. Register a user in Local Turnkey Prototyper and inspect the created SysUser in the debugger.

For the MDrivenServer persistence workflow, including the duplicate-SysSingleton recovery procedure, see Bootcamp Chapter 14.

See also

• Documentation:SysUser
• Documentation:OCLOperators oclSingleton
• Documentation:SysSingleton optional properties
• Documentation:SysSingleton GetSystemUrl
• Training:Bootcamp:Chapter 11