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 All Persistent Objects
save
If the object instance is a persistent object it saves the object to the persistence layer. If the developer added objects to the instance’s relationship member collections, they will be persisted as well. The save() BIF is called on a variable holding an object instance.
Person p = Person:new(); p.cars.append(Car:new()); p.cars.append(Car:new()); p.save();
read
Reads an existing object instance from the persistence layer. Called on the object's namespace.
Person p = Person:read(getUserUUID());
delete
Deletes the instance. Called on the object's namespace.
Person:delete(plist.pop());
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;
}