This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

Home > Class Reference > %SYS namespace > Security.Users

Security.Users

persistent class Security.Users extends %Library.Persistent, %XML.Adaptor, %SYSTEM.Help

SQL Table Name: Security.Users

Define the security User database, and methods which manipulate them.
The system includes a set of pre-defined System users.

User names have the following properties:
1) User names are not case sensitive.
2) Maximum length of a user name is 128 characters.
3) User name cannot contain "*" A user cannot have duplicate roles defined
At least one user must hold the %All role
All the roles granted to a user must exist in the roles database.

Note: The speed at which a single process can create several users at a time is limited by the PBKDF2 encryption method which hashes the password.

The table for this class should be manipulated only through object access, the published API's or through the System Management Portal. It should not be updated through direct SQL access.

Property Inventory (Including Private)

Method Inventory (Including Private)

Properties (Including Private)

property AccountNeverExpires as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Account Expiration behavior.
0 - Account expires normally.
1 - Account will never expire.
Property methods: AccountNeverExpiresDisplayToLogical(), AccountNeverExpiresGet(), AccountNeverExpiresGetStored(), AccountNeverExpiresIsValid(), AccountNeverExpiresLogicalToDisplay(), AccountNeverExpiresLogicalToODBC(), AccountNeverExpiresLogicalToXSD(), AccountNeverExpiresNormalize(), AccountNeverExpiresSet(), AccountNeverExpiresXSDToLogical()
property Attributes as list of %Binary);
Attributes to apply to user when they log in.
Property methods: AttributesBuildValueArray(), AttributesCollectionToDisplay(), AttributesCollectionToOdbc(), AttributesDisplayToCollection(), AttributesGet(), AttributesGetObject(), AttributesGetObjectId(), AttributesGetStored(), AttributesGetSwizzled(), AttributesIsValid(), AttributesLogicalToXSD(), AttributesOdbcToCollection(), AttributesSet(), AttributesSetObject(), AttributesSetObjectId(), AttributesXSDToLogical()
property AutheEnabled as %Integer [ InitialExpression = 0 ];
Two factor Authentication options which are enabled for this user.
Options are:
$$$AutheTwoFactorSMS - SMS Text authentication
$$$AutheTwoFactorPW - Time-based One-time Password
Property methods: AutheEnabledDisplayToLogical(), AutheEnabledGet(), AutheEnabledGetStored(), AutheEnabledIsValid(), AutheEnabledLogicalToDisplay(), AutheEnabledNormalize(), AutheEnabledSet(), AutheEnabledXSDToLogical()
property ChangePassword as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Change password on next login.
0 - Password change not required.
1 - Password change required before next login.
Property methods: ChangePasswordDisplayToLogical(), ChangePasswordGet(), ChangePasswordGetStored(), ChangePasswordIsValid(), ChangePasswordLogicalToDisplay(), ChangePasswordLogicalToODBC(), ChangePasswordLogicalToXSD(), ChangePasswordNormalize(), ChangePasswordSet(), ChangePasswordXSDToLogical()
property Comment as %String (MAXLEN = 2048);
Comment.
Property methods: CommentDisplayToLogical(), CommentGet(), CommentGetStored(), CommentIsValid(), CommentLogicalToDisplay(), CommentLogicalToOdbc(), CommentNormalize(), CommentSet()
property CreateDateTime as %String [ InitialExpression = $zts ];
Account creation date and time.
$H format in utc.
Property methods: CreateDateTimeDisplayToLogical(), CreateDateTimeGet(), CreateDateTimeGetStored(), CreateDateTimeIsValid(), CreateDateTimeLogicalToDisplay(), CreateDateTimeLogicalToOdbc(), CreateDateTimeNormalize(), CreateDateTimeSet()
property CreateUsername as %String (MAXLEN = 160) [ InitialExpression = $username ];
$username of user who created the account.
Property methods: CreateUsernameDisplayToLogical(), CreateUsernameGet(), CreateUsernameGetStored(), CreateUsernameIsValid(), CreateUsernameLogicalToDisplay(), CreateUsernameLogicalToOdbc(), CreateUsernameNormalize(), CreateUsernameSet()
property EmailAddress as %String (MAXLEN = 512);
Email address of the user.
Property methods: EmailAddressDisplayToLogical(), EmailAddressGet(), EmailAddressGetStored(), EmailAddressIsValid(), EmailAddressLogicalToDisplay(), EmailAddressLogicalToOdbc(), EmailAddressNormalize(), EmailAddressSet()
property Enabled as Security.Datatype.BooleanYN [ InitialExpression = 1 ];
Allow user to log in.
0 - Disable login.
1 - Enable login.
Property methods: EnabledDisplayToLogical(), EnabledGet(), EnabledGetStored(), EnabledIsValid(), EnabledLogicalToDisplay(), EnabledLogicalToODBC(), EnabledLogicalToXSD(), EnabledNormalize(), EnabledSet(), EnabledXSDToLogical()
property ExpirationDate as %Date;
Last date an account can be used.
$H date value of when an account becomes disabled.
Property methods: ExpirationDateDisplayToLogical(), ExpirationDateGet(), ExpirationDateGetStored(), ExpirationDateIsValid(), ExpirationDateLogicalToDisplay(), ExpirationDateLogicalToOdbc(), ExpirationDateLogicalToXSD(), ExpirationDateNormalize(), ExpirationDateOdbcToLogical(), ExpirationDateSet(), ExpirationDateXSDToLogical()
property Flags as %Integer [ InitialExpression = 1 ];
Flags associated with user.
Bit 0 - User created via normal security mechanisms (Cache Password User).
Bit 1 - User created via LDAP.
Bit 2 - User created via Delegated Authentication.
Property methods: FlagsDisplayToLogical(), FlagsGet(), FlagsGetStored(), FlagsIsValid(), FlagsLogicalToDisplay(), FlagsNormalize(), FlagsSet(), FlagsXSDToLogical()
property FullName as %String (MAXLEN = 2048);
Full name of the user.
Property methods: FullNameDisplayToLogical(), FullNameGet(), FullNameGetStored(), FullNameIsValid(), FullNameLogicalToDisplay(), FullNameLogicalToOdbc(), FullNameNormalize(), FullNameSet()
property HOTPKey as %Binary (MAXLEN = 20, MINLEN = 20) [ InitialExpression = $System.Encryption.GenCryptRand(20) ];
Time-based One-time Password key.
This property is automatically generated when the user is created using the $System.Encryption.GenCryptRand() method.
Property methods: HOTPKeyDisplayDisplayToLogical(), HOTPKeyDisplayGet(), HOTPKeyDisplayGetStored(), HOTPKeyDisplayIsValid(), HOTPKeyDisplayLogicalToDisplay(), HOTPKeyDisplayLogicalToXSD(), HOTPKeyDisplayNormalize(), HOTPKeyDisplaySet(), HOTPKeyDisplayXSDToLogical(), HOTPKeyGenerateDisplayToLogical(), HOTPKeyGenerateGet(), HOTPKeyGenerateIsValid(), HOTPKeyGenerateLogicalToDisplay(), HOTPKeyGenerateLogicalToXSD(), HOTPKeyGenerateNormalize(), HOTPKeyGenerateSet(), HOTPKeyGenerateXSDToLogical(), HOTPKeyGet(), HOTPKeyGetStored(), HOTPKeyIsValid(), HOTPKeyLogicalToXSD(), HOTPKeySet(), HOTPKeyXSDToLogical()
property HOTPKeyDisplay as %Boolean [ InitialExpression = 0 ];
Display the Time-based One-time Password QR code or key on next login for the user to scan with their authentication device.
Property methods: HOTPKeyDisplayDisplayToLogical(), HOTPKeyDisplayGet(), HOTPKeyDisplayGetStored(), HOTPKeyDisplayIsValid(), HOTPKeyDisplayLogicalToDisplay(), HOTPKeyDisplayLogicalToXSD(), HOTPKeyDisplayNormalize(), HOTPKeyDisplaySet(), HOTPKeyDisplayXSDToLogical()
property HOTPKeyGenerate as %Boolean [ InitialExpression = 0 , Transient ];
0 - Do not generate a new Time-based One-time Password key when user is saved.
1 - Generate a new Time-based One-time Password key when user is saved.
Property methods: HOTPKeyGenerateDisplayToLogical(), HOTPKeyGenerateGet(), HOTPKeyGenerateIsValid(), HOTPKeyGenerateLogicalToDisplay(), HOTPKeyGenerateLogicalToXSD(), HOTPKeyGenerateNormalize(), HOTPKeyGenerateSet(), HOTPKeyGenerateXSDToLogical()
property InvalidLoginAttempts as %Integer (MINVAL = 0, XMLPROJECTION = "NONE") [ InitialExpression = 0 ];
Number of invalid login attempts since last successful one.
Property methods: InvalidLoginAttemptsDisplayToLogical(), InvalidLoginAttemptsGet(), InvalidLoginAttemptsGetStored(), InvalidLoginAttemptsIsValid(), InvalidLoginAttemptsLogicalToDisplay(), InvalidLoginAttemptsNormalize(), InvalidLoginAttemptsSet(), InvalidLoginAttemptsXSDToLogical()
property InvalidLoginDateTime as %String (XMLPROJECTION = "NONE") [ InitialExpression = 0 ];
Last invalid login date and time
Property methods: InvalidLoginDateTimeDisplayToLogical(), InvalidLoginDateTimeGet(), InvalidLoginDateTimeGetStored(), InvalidLoginDateTimeIsValid(), InvalidLoginDateTimeLogicalToDisplay(), InvalidLoginDateTimeLogicalToOdbc(), InvalidLoginDateTimeNormalize(), InvalidLoginDateTimeSet()
property InvalidLoginDevice as %String (MAXLEN = 256, XMLPROJECTION = "NONE");
Last invalid login device
Property methods: InvalidLoginDeviceDisplayToLogical(), InvalidLoginDeviceGet(), InvalidLoginDeviceGetStored(), InvalidLoginDeviceIsValid(), InvalidLoginDeviceLogicalToDisplay(), InvalidLoginDeviceLogicalToOdbc(), InvalidLoginDeviceNormalize(), InvalidLoginDeviceSet()
property InvalidLoginService as %String (MAXLEN = 64, XMLPROJECTION = "NONE");
Last invalid login Service
Property methods: InvalidLoginServiceDisplayToLogical(), InvalidLoginServiceGet(), InvalidLoginServiceGetStored(), InvalidLoginServiceIsValid(), InvalidLoginServiceLogicalToDisplay(), InvalidLoginServiceLogicalToOdbc(), InvalidLoginServiceNormalize(), InvalidLoginServiceSet()
property InvalidLoginStatus as %Status (XMLPROJECTION = "NONE") [ InitialExpression = $$$OK ];
Last login error
Property methods: InvalidLoginStatusGet(), InvalidLoginStatusGetStored(), InvalidLoginStatusIsValid(), InvalidLoginStatusLogicalToOdbc(), InvalidLoginStatusLogicalToXSD(), InvalidLoginStatusSet(), InvalidLoginStatusXSDToLogical()
property LastModifiedDateTime as %String [ InitialExpression = $zts ];
Account modified date and time.
$H format in utc.
Property methods: LastModifiedDateTimeDisplayToLogical(), LastModifiedDateTimeGet(), LastModifiedDateTimeGetStored(), LastModifiedDateTimeIsValid(), LastModifiedDateTimeLogicalToDisplay(), LastModifiedDateTimeLogicalToOdbc(), LastModifiedDateTimeNormalize(), LastModifiedDateTimeSet()
property LastModifiedInfo as %String (MAXLEN = 1024);
Information describing last modification of the user.
Property methods: LastModifiedInfoDisplayToLogical(), LastModifiedInfoGet(), LastModifiedInfoGetStored(), LastModifiedInfoIsValid(), LastModifiedInfoLogicalToDisplay(), LastModifiedInfoLogicalToOdbc(), LastModifiedInfoNormalize(), LastModifiedInfoSet()
property LastModifiedUsername as %String (MAXLEN = 128) [ InitialExpression = $username ];
$username of the person who last modified it.
Property methods: LastModifiedUsernameDisplayToLogical(), LastModifiedUsernameGet(), LastModifiedUsernameGetStored(), LastModifiedUsernameIsValid(), LastModifiedUsernameLogicalToDisplay(), LastModifiedUsernameLogicalToOdbc(), LastModifiedUsernameNormalize(), LastModifiedUsernameSet()
property LoginDateTime as %String (XMLPROJECTION = "NONE") [ InitialExpression = 0 ];
Last Successful login date and time.
$H format in utc.
Property methods: LoginDateTimeDisplayToLogical(), LoginDateTimeGet(), LoginDateTimeGetStored(), LoginDateTimeIsValid(), LoginDateTimeLogicalToDisplay(), LoginDateTimeLogicalToOdbc(), LoginDateTimeNormalize(), LoginDateTimeSet()
property LoginDevice as %String (MAXLEN = 256, XMLPROJECTION = "NONE");
Last Successful login device
Property methods: LoginDeviceDisplayToLogical(), LoginDeviceGet(), LoginDeviceGetStored(), LoginDeviceIsValid(), LoginDeviceLogicalToDisplay(), LoginDeviceLogicalToOdbc(), LoginDeviceNormalize(), LoginDeviceSet()
property LoginService as %String (MAXLEN = 64, XMLPROJECTION = "NONE");
Last Successful login Service.
Property methods: LoginServiceDisplayToLogical(), LoginServiceGet(), LoginServiceGetStored(), LoginServiceIsValid(), LoginServiceLogicalToDisplay(), LoginServiceLogicalToOdbc(), LoginServiceNormalize(), LoginServiceSet()
property Name as %String (MAXLEN = 160) [ Required ];
User Name.
Includes domain if multiple domains are enabled in the format username@domain.
Property methods: NameDisplayToLogical(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameLowerCaseDisplayToLogical(), NameLowerCaseGet(), NameLowerCaseGetStored(), NameLowerCaseIndexCheck(), NameLowerCaseIndexDelete(), NameLowerCaseIndexExists(), NameLowerCaseIndexOpen(), NameLowerCaseIndexSQLCheckUnique(), NameLowerCaseIndexSQLExists(), NameLowerCaseIndexSQLFindPKeyByConstraint(), NameLowerCaseIndexSQLFindRowIDByConstraint(), NameLowerCaseIsValid(), NameLowerCaseLogicalToDisplay(), NameLowerCaseLogicalToOdbc(), NameLowerCaseNormalize(), NameNormalize(), NameSet(), NameSpaceDisplayToLogical(), NameSpaceGet(), NameSpaceGetStored(), NameSpaceIsValid(), NameSpaceLogicalToDisplay(), NameSpaceLogicalToOdbc(), NameSpaceNormalize(), NameSpaceSet(), NameToDescription()
property NameSpace as %String (MAXLEN = 64);
NameSpace to run in only if a terminal session.
Property methods: NameSpaceDisplayToLogical(), NameSpaceGet(), NameSpaceGetStored(), NameSpaceIsValid(), NameSpaceLogicalToDisplay(), NameSpaceLogicalToOdbc(), NameSpaceNormalize(), NameSpaceSet()
property Password as Security.Datatype.Password (MAXLEN = 20);
PBKDF2 hashed password for Cache Authentication.
This is used with a salt function obtained from $System.Encryption.GenCryptRand. This property is set by the class when the PasswordExternal property is modified. Do not set this property directly.
To modify the password for a user using objects, get an instance of the object and modify the PasswordExternal property:
i '..Exists(Username,.User,.Status) q Status
s User.PasswordExternal=Password
s Status=User.%Save()
When using the Modify() class method to change a user's method, you can either set Properties("Password")=NewPassword, or Properties("ExternalPassword")=NewPassword.
Property methods: PasswordChangedDateTimeDisplayToLogical(), PasswordChangedDateTimeGet(), PasswordChangedDateTimeGetStored(), PasswordChangedDateTimeIsValid(), PasswordChangedDateTimeLogicalToDisplay(), PasswordChangedDateTimeLogicalToOdbc(), PasswordChangedDateTimeNormalize(), PasswordChangedDateTimeSet(), PasswordExternalDisplayToLogical(), PasswordExternalGet(), PasswordExternalIsValid(), PasswordExternalLogicalToDisplay(), PasswordExternalLogicalToOdbc(), PasswordExternalNormalize(), PasswordExternalSet(), PasswordGet(), PasswordGetStored(), PasswordIsValid(), PasswordLogicalToDisplay(), PasswordLogicalToOdbc(), PasswordLogicalToXSD(), PasswordNeverExpiresDisplayToLogical(), PasswordNeverExpiresGet(), PasswordNeverExpiresGetStored(), PasswordNeverExpiresIsValid(), PasswordNeverExpiresLogicalToDisplay(), PasswordNeverExpiresLogicalToODBC(), PasswordNeverExpiresLogicalToXSD(), PasswordNeverExpiresNormalize(), PasswordNeverExpiresSet(), PasswordNeverExpiresXSDToLogical(), PasswordSet(), PasswordUpdatedDisplayToLogical(), PasswordUpdatedGet(), PasswordUpdatedIsValid(), PasswordUpdatedLogicalToDisplay(), PasswordUpdatedLogicalToXSD(), PasswordUpdatedNormalize(), PasswordUpdatedSet(), PasswordUpdatedXSDToLogical(), PasswordXSDToLogical()
property PasswordChangedDateTime as %String [ InitialExpression = $zts ];
Last password change date and time.
$H format in utc.
Property methods: PasswordChangedDateTimeDisplayToLogical(), PasswordChangedDateTimeGet(), PasswordChangedDateTimeGetStored(), PasswordChangedDateTimeIsValid(), PasswordChangedDateTimeLogicalToDisplay(), PasswordChangedDateTimeLogicalToOdbc(), PasswordChangedDateTimeNormalize(), PasswordChangedDateTimeSet()
property PasswordExternal as %String (MAXLEN = 128, XMLPROJECTION = "NONE") [ InitialExpression = $c(0) , Transient ];
Clear text password.
This property is not stored in permanent storage. It is initially set to the value of $c(0). When it is modified, the Password property is updated to the PBKDF2 salted hashed value.
Property methods: PasswordExternalDisplayToLogical(), PasswordExternalGet(), PasswordExternalIsValid(), PasswordExternalLogicalToDisplay(), PasswordExternalLogicalToOdbc(), PasswordExternalNormalize(), PasswordExternalSet()
property PasswordNeverExpires as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Password expires behavior.
0 - Password expires normally.
1 - Password never expires.
Property methods: PasswordNeverExpiresDisplayToLogical(), PasswordNeverExpiresGet(), PasswordNeverExpiresGetStored(), PasswordNeverExpiresIsValid(), PasswordNeverExpiresLogicalToDisplay(), PasswordNeverExpiresLogicalToODBC(), PasswordNeverExpiresLogicalToXSD(), PasswordNeverExpiresNormalize(), PasswordNeverExpiresSet(), PasswordNeverExpiresXSDToLogical()
property PhoneNumber as %String (MAXLEN = 256);
Phone number for two-factor authentication
Property methods: PhoneNumberDisplayToLogical(), PhoneNumberGet(), PhoneNumberGetStored(), PhoneNumberIsValid(), PhoneNumberLogicalToDisplay(), PhoneNumberLogicalToOdbc(), PhoneNumberNormalize(), PhoneNumberSet()
property PhoneProvider as %String (MAXLEN = 256);
Mobile phone service provider for two-factor authentication
Property methods: PhoneProviderDisplayToLogical(), PhoneProviderGet(), PhoneProviderGetStored(), PhoneProviderIsValid(), PhoneProviderLogicalToDisplay(), PhoneProviderLogicalToOdbc(), PhoneProviderNormalize(), PhoneProviderSet()
property Roles as list of %String (MAXLEN = 64);
Roles assigned to the user.
Property methods: RolesBuildValueArray(), RolesCollectionToDisplay(), RolesCollectionToOdbc(), RolesDisplayToCollection(), RolesDisplayToLogical(), RolesGet(), RolesGetObject(), RolesGetObjectId(), RolesGetStored(), RolesGetSwizzled(), RolesIsValid(), RolesLogicalToDisplay(), RolesLogicalToOdbc(), RolesNormalize(), RolesOdbcToCollection(), RolesSet(), RolesSetObject(), RolesSetObjectId()
property Routine as %String (MAXLEN = 64);
Routine to run only if terminal session, ""=Programmer mode.
Property methods: RoutineDisplayToLogical(), RoutineGet(), RoutineGetStored(), RoutineIsValid(), RoutineLogicalToDisplay(), RoutineLogicalToOdbc(), RoutineNormalize(), RoutineSet()
property Salt as %Binary (MAXLEN = 8);
Salt value for Hashed password from $System.Encryption.GenCryptRand.
Property methods: SaltGet(), SaltGetStored(), SaltIsValid(), SaltLogicalToXSD(), SaltSet(), SaltXSDToLogical()
property SuperUser as Security.Datatype.BooleanYN (XMLPROJECTION = "NONE") [ InitialExpression = 0 , ReadOnly ];
User holds the %All role.
Property methods: SuperUserDisplayToLogical(), SuperUserGet(), SuperUserGetStored(), SuperUserIsValid(), SuperUserLogicalToDisplay(), SuperUserLogicalToODBC(), SuperUserLogicalToXSD(), SuperUserNormalize(), SuperUserXSDToLogical()

Methods (Including Private)

classmethod AddRoles(Username As %String, ByRef Roles As %String, Admin As %Boolean = 0) as %Status
Add role(s) to the User's definition.
Parameters:
Username - Name of the user to add roles to
Roles - Comma delimited list of roles
Admin - SQL ADMIN OPTION, TRUE if this user can GRANT the Role to another user/role. Only applicable in SQL.
classmethod Copy(Name As %String, NewName As %String, NewFullName As %String = "", SQLSysPrivs As %Boolean = 1, SQLObjPrivs As %Boolean = 1) as %Status
Copy a User.
Copy an existing User in the Security database to a new one.
Parameters:
Name - Name of the User to be copied.
NewName - Name of the user to be created.
NewFullName - Full name of the new user.
SQLSysPrivs - Copy SQL system privileges.
SQLObjPrivs - Copy SQL object provileges.
classmethod Create(Username As %String, UserRoles As %String, Password As %String, FullName As %String, NameSpace As %String, Routine As %String, ExpirationDate As %String, ChangePassword As %Boolean, Enabled As %Boolean, Comment As %String, Flags As %String = 1, PhoneNumber As %String, PhoneProvider As %String, ByRef Attributes As %String, AccountNeverExpires As %Boolean, PasswordNeverExpires As %Boolean) as %Status
Create a User.
Create a User in the Security database.
There are 2 ways to call this method and pass the parameters:

s x=##Class(Security.Users).Create(User,Roles,Password,FullName,...)
or
s x=##Class(Security.Users).Create(User,.Properties)

Where Properties are contained in an array subscripted by property name, passed by reference. See the Get() method for a description of the Properies array. Valid properties for the Create() method are described below, other values are ignored.
Parameters:
Name - Name of the user to create
UserRoles - List format of roles to assign to the user
Roles are in the format:
"Role1,Role2" For example:
s Roles="%Developer,%Operator"
s Roles="" would create a user with no roles
Password - Cache authentication password for the user in clear text.
FullName - Full name of the user
NameSpace - Namespace of the user for terminal access
Routine - Routine the user runs for terminal access. Routine="" means programmer mode.
ExpirationDate - ODBC date format of when the user account expires, or ""=no expiration
ChangePassword - 0/1, User cannot log in until the password is changed
Enabled - 0/1, account is disabled/enabled
Comment - Comment
Flags - Internal use only, pass 1 for this
Bit 0 - User created normally for Cache authentication
Bit 1 - User created by LDAP authentication
Bit 2 - User created by User Defined authentication
PhoneNumber - Phone number for two-factor authentication PhoneProvider - Mobile phone service provider for two-factor authentication EmailAddress - Email address of the user.
HOTPKey - HOTP key used for Display Time-Based One-time Password
HOTPKeyDisplay - 0/1 - Display QR Code and key on next login
Attributes (byref) - Array of attributes to be associated with the user
Attribute(Name)=Value
AccountNeverExpires - 0/1, Account will never expire
PasswordNeverExpires - 0/1, Password will never expire
classmethod Delete(Username As %String) as %Status
Delete a User.
This method will delete a User from the security database.
Parameters:
Username - Username to delete
classmethod Exists(Username As %String, ByRef User As %ObjectHandle, ByRef Status As %Status, Flag As %Integer = 0) as %Boolean
User exists.
This method checks for the existence of a user in the security database.
Parameters:
Username - Name of the user to check existence of
Flag - Internal use only, must be 0 or not passed
Requires the %Admin_Secure:USE privilege to change the $USERNAME value.
Return values:
If Value of the method = 0 (User does not exist, or some error occured)
User = Null
Status = User "x" does not exist, or other error message

If Value of the method = 1 (User exists)
User = Object handle to user
ActualUserName = exact-case of user's name (used by SQL) Status = User "x" already exists
classmethod ExpireUserPasswords(Names As %String, ByRef Count As %Integer) as %Status
Set selected users accounts as having to change their password on next login.
This does not affect LDAP or Delegated authentication accounts. It also does not affect users who have the PasswordNeverExpires flag set.
Parameters:
Names - Comma separated list of user names, "*" = All
Count - Return value of number of users expired.
This method requires %Admin_Secure:USE permission to run.
classmethod Export(FileName As %String = "UsersExport.xml", ByRef NumExported As %Integer = 0, Usernames As %String = "*", Roles As %String = "*", SQLPrivileges As %Boolean = 0, ByRef NumSQLPrivilegesExported As %Integer) as %Status
This method exports User records to a file in xml format.
Parameters:
Filename - Output file name
NumExported (byref) - Returns number of records exported.
Usernames - Comma separated list of Usernames to export, "*" = All
Roles - Comma separated list of Roles, "*" = All. Export Users containing only these roles
SQLPrivileges - 1/0 flag. If 1, export all SQL Privileges from all namespace on this system that have been directly granted to this Role
NumSQLPrivilegesExported *byref) - Returns number of SQL Privileges and SQL Admin Privilege Set records exported
classmethod Get(Username As %String, ByRef Properties As %String) as %Status
Get a User's properties.
Gets a User's properties from the security database.
Parameters:
Username - Name of the user to get
Return values:
Properties - Array of properties
Properties("AccountNeverExpires") - 0=Expires normally, 1=Never expires
Properties("Attributes",Name) = $lb(Value1,Value2) - Attributes and values to associate with process
Properties("ChangePassword") - 0=Don't change, 1=Change before next login Properties("Comment") - Comment
Properties("EmailAddress") - Email Address
Properties("Enabled") - 0=Disabled, 1=Enabled
Properties("ExpirationDate") - Expiration date of account, ODBC date format
Properties("Flags") - Flags of the user
Properties("FullName") - Full name of the user
Properties("InvalidLoginAttempts") - Number of invalid login attempts since last success
Properties("InvalidLoginDateTime") - $h value of last invalid login attempt
Properties("InvalidLoginDevice") - Last device for invalid login attempt
Properties("InvalidLoginStatus") - Last error status for an invalid login attempt
Properties("InvalidLoginService") - Last service used for an invalid login attempt
Properties("LegacyPassword") - Legacy password for Cache Direct
Properties("LoginDateTime") - $h value for last valid login attempt
Properties("LoginDevice") - Last valid login device
Properties("LoginService") - Last valid login service
Properties("NameSpace") - Default Namespace for terminal login
properties("PasswordNeverExpires") - 0=Expires normally, 1=Never expires
Properties("PhoneNumber") - Phone number for two-factor authentication
Properties("PhoneProvider") - Mobile phone service provider for two-factor authentication
Properties("Roles")- Comma-separated List format of roles
Roles are in the format:
"Role1,Role2"
For example:
s Properties("Roles")="%Developer,%Operator"
Properties("Routine") - Routine the user runs for terminal access. Routine="" means programmer mode.
Properties("Salt") - Salt used to generate password.
Properties("SuperUser") - 0=No, 1=Yes.
classmethod GetResourceSet(Username As %String = "", Roles As %String = "", ByRef Resources As %String) as %Status
Get a User's or Roles set of resources.
Gets a User's set of resource/permission pairs he would be granted if logged in.
Parameters:
Username - Name of the user to get
Roles - Comma delimited list of roles to return resources for
Resources - Comma delimited list of resource:permission pairs
classmethod GetRoleSet(Username As %String, ByRef Roles As %String) as %Status
Get a User's set of roles.
Gets a User's set of roles he would be granted if logged in.
Parameters:
Username - Name of the user to get
Return value:
Roles - Comma delimited list of roles a user would be granted if logged in
classmethod Import(FileName As %String = "UsersExport.xml", ByRef NumImported As %Integer, Flags As %Integer = 0, ByRef NumSQLPrivsImported As %Integer) as %Status
Import User records from an xml file.
Parameters:
FileName - Filename to import User records from
NumImported (byref) - Returns number of records imported
Flags - Control import
Bit 0 - Do not import records, just return count
Note: On failure, no records will be imported
classmethod Modify(Username As %String, ByRef Properties As %String) as %Status
Modify a User's properties.
Modifies a User's properties from the security database.
Parameters:
Username - Name of the user to modify
Properties - Array of properties to modify.
See the Get() method for a description of the Properties parameter.
To change a user's method, you can either set Properties("Password")=NewPassword, or Properties("ExternalPassword")=NewPassword.
If a specific property is not passed in the properties array, the value is not modified.
If a value is unchanged it is not set to prevent the property modified state from being set.
classmethod UnExpireUserPasswords(Names As %String, ByRef Count As %Integer) as %Status
Set selected users accounts to not have their password change on next login.
This does not affect LDAP or Delegated authentication accounts. Parameters:
Names - Comma separated list of user names, "*" = All
Count - Return value of number of users updated.
This method requires %Admin_Secure:USE permission to run.

Queries

query Detail(Names As %String, Roles As %String, LastLoginOlderThan As %Integer, Flag As %Integer = 0)
Selects Name As %String, FullName As %String, Comment As %String, Enabled As %String, ExpirationDate As %String, Roles As %String, GrantedRoles As %String, Namespace As %String, Routine As %String, LastPasswordChangeTime As %String, LastLoginTime As %String, LastLoginService As %String, LastLoginDevice As %String, LastInvalidLoginTime As %String, LastLoginError As %String, InvalidLoginAttempts As %String, LastInvalidLoginService As %String, LastInvalidLoginDevice As %String, Type As %String, EmailAddress As %String, PhoneNumber As %String, PhoneProvider As %String, AccountNeverExpires As %String, PasswordNeverExpires As %String, AutheEnabled As %String, CreateDateTime As %String, CreateUsername As %String, LastModifiedDateTime As %String, LastModifiedUsername As %String, LastModifiedInfo As %String, Flags As %Integer
List all user records, brief display.
Names - Comma separated list of user names, "*" = All
Roles - Comma separated list of Role names, "*"=ALL
LastLoginOlderThan - Select users who haven't logged in in more than x days, "*"=ALL Flag - 0 - Use "Startswith" as the selection on the name.
Flag - 1 - Use "Contains" as the selection on the name.
Note: This query may change in future versions
query List(Names As %String, Roles As %String, LastLoginOlderThan As %Integer, Flag As %Integer = 0)
Selects Name As %String, Enabled As %String, Roles As %String, LastLoginTime As %String, Flags As %Integer
List all user records, brief display.
Names - Comma separated list of user names, "*" = All
Roles - Comma separated list of Role names, "*"=ALL
LastLoginOlderThan - Select users who haven't logged in in more than x days, "*"=ALL Flag - 0 - Use "Startswith" as the selection on the name.
Flag - 1 - Use "Contains" as the selection on the name.
Note: This query may change in future versions

Indexes

index (NameLowerCaseIndex on NameLowerCase) [IdKey, Type = key];
Index methods: NameLowerCaseIndexCheck(), NameLowerCaseIndexDelete(), NameLowerCaseIndexExists(), NameLowerCaseIndexOpen(), NameLowerCaseIndexSQLCheckUnique(), NameLowerCaseIndexSQLExists(), NameLowerCaseIndexSQLFindPKeyByConstraint(), NameLowerCaseIndexSQLFindRowIDByConstraint()

Triggers

trigger BDTrigger (BEFORE event DELETE);
Before Delete trigger, call %OnDelete method and if error, don't allow the DELETE

Inherited Members

Inherited Methods (Including Private)

Storage

Storage Model: CacheStorage (Security.Users)

^|$$$SecurityMapUsers|SYS("Security","UsersD")(ID)
=
%%CLASSNAME
ChangePassword
Comment
Enabled
EventFlags
ExpirationDate
FullName
InvalidLoginAttempts
InvalidLoginDateTime
InvalidLoginDevice
InvalidLoginService
InvalidLoginStatus
LegacyPassword
LoginDateTime
LoginDevice
LoginService
Name
NameSpace
Password
PasswordChangedDateTime
Roles
Routine
SuperUser
Salt
Flags
Attributes
PhoneNumber
PhoneProvider
AccountNeverExpires
PasswordNeverExpires
EMSGroupEnabled
AutheEnabled
CreateDateTime
CreateUsername
LastModifiedDateTime
LastModifiedInfo
LastModifiedUsername
HOTPKey
HOTPKeyDisplay
EmailAddress
TOTPLastValidPasswords