Functions on Persistent Entities

Functions Applicable to All Custom Objects

new

Creates a new instance of an object. The new() BIF is called on the object's namespace.

Person p = Person:new();

Functions Applicable to Role Persistent Objects

user

Gets the current user object. Called on the object's namespace.

Nurse currentUser = Nurse:user();

invite

Creates an identity for the object if one doesn't already exist and grants the user associated with the identity permission to use the current app with the role associated with the object. The user in question is notified of the invitation by means of an SMS message. The function is called on a variable holding an object instance.

@Role("Nurse")
persistent object Nurse {
	string mobileNumber;
}
 
void sampleInvite(){
	Nurse n = Nurse:new();
    n.mobileNumber = "27820010001";
    n.invite(n.mobileNumber);
}

In addition to the standard invite built-in function, an overloaded version of the function, where an e-mail address needs to be provided in addition to the mobile number, is also available. The result of using this overloaded version of the function will be that the user in question is notified of the invitation using both an SMS message and an e-mail.

@Role("Nurse")
persistent object Nurse {
	string mobileNumber;
	string emailAddress;
}
 
void sampleInvite(){
	Nurse n = Nurse:new();
    n.mobileNumber = "27820010001";
	n.emailAddress = "nurse1@mail.com"
    n.invite(n.mobileNumber, n.emailAddress);
}

removeRole

Practically acts as an "uninvite". Called on a variable holding an object instance.

@Role("Nurse")
persistent object Nurse {
	string mobileNumber;
}
 
void exampleToRemoveRole(Nurse nurse){
    nurse.removeRole();
}

forcePasswordReset

Helium 1.49.0 provides a mechanism to force a password reset for a user using DSL code. The forcePasswordReset buit-in function will force the Helium user that is associated with the app user to reset their password upon next login.

@Role("Nurse")
persistent object Nurse {
  string mobileNumber;
}
 
void exampleToRemoveRole(Nurse nurse){
    nurse.forcePasswordReset();
}

In a typical use case, the DSL application logic might need to determine whether a user has to reset their password based on the time passed since their last password reset. Helium automatically populates built-in fields on all role objects to facilitate this. Note that these fields might be null initially if a user has not yet reset their password since this feature has been deployed.

void exampleToRemoveRole(Nurse nurse){
	if(shouldForceReset(nurse) == true) {
		nurse.forcePasswordReset();
	}
}

bool shouldForceReset(SystemAdmin nurse) {

    // Force an initial reset. All subsequent resets will be based on logic using the 
    // populated built-in _mustResetPassword and _lastPasswordReset fields
    if(nurse._mustResetPassword == null || nurse._lastPasswordReset == null) {
  		return true;
    }

    // User will already be forced to reset their password when logging in, no need 
    // to force it again at this stage
    if(nurse._mustResetPassword == true) {
  		return false;
    }

    // More than 30 days has passed since last password reset, force it now
    int daysSinceLastReset = Date:daysBetween(nurse._lastPasswordReset, Mez:now());
    if(daysSinceLastReset > 30) {
  		return true;
    }

    return false;
}

Note that the _lastPasswordReset and _mustResetPassword fields are set asynchronously by Helium. These are first set on the Helium user and then cascaded down to the app users associated with the Helium core user. This implies that in the following example, the value for _mustResetPassword will not be updated yet to reflect the recent call to forcePasswordReset.

if(nurse._mustResetPassword == false) {
	nurse.forcePasswordReset();

	// This value will still be 'false' until Helium has finished its internal async 
	// processing of the above and related updates
	bool mustReset = nurse._mustResetPassword;
}

Additional Mentions and References

• Quick Reference#PersistentEntityBIFs
• Lesson 3: User Input, Persistence, Validation, and Tables (continued)