Security Manager Module
| Description | Creates a new account (either a user account or a role). |
| Returns | Object value |
| Usage | Script Only. |
| Related to: | ModifyAccount | DeleteAccount |
| Format | \SecurityManager.AddAccount (NewAccountData [, PtrReturnCode, HaveLock]); |
| Parameters |
| NewAccountData |
| Required. An AccountData Structure, a single dimension array of AccountData structures or a dictionary of AccountData structures containing the data for the new account(s). |
| PtrReturnCode |
| Optional. A pointer to a value that will contain one of the defined result codes at the conclusion of the operation. (Security Manager Return Codes) |
| HaveLock |
| Optional. A Boolean value that indicates whether the working copy lock is held by the calling code. Default FALSE. |
| Comments |
To use this API, the calling code must be running in a security session that has Manager privilege. Adding an account is an asynchronous operation. If the asynchronous operation was not attempted, due to detection of an error, the return value will be Invalid. If the asynchronous operation is attempted, the return value will be an object value. The object value will become Invalid when the asynchronous operation completes. At that time (or when the method returns Invalid), the value addressed by PtrReturnCode can be examined to determine the status of the operation. The contents of the value addressed by PtrReturnCode are undefined until the method returns Invalid. A single account can be added by supplying a single AccountData structure in NewAccountData. Multiple accounts can be added in one operation by providing a single dimension array or dictionary of AccountData structures in NewAccountData. The result code returned in the value addressed by PtrReturnCode will be a scalar value if a single structure was supplied in NewAccountData. If an array of structures or a dictionary of structures was supplied, a single dimension array of the same size as NewAccountData will be returned in the value addressed by PtrReturnCode, each element containing the result code for the corresponding NewAccountData element. Adding an account requires a working copy write lock. If such a lock is held by the calling code, the HaveLock parameter must be set to TRUE. Otherwise omit this parameter or set it to FALSE. If the calling code holds a read lock on the working copy, this must be released before AddAccount can complete its operation. The AccountData structure(s) provided must have the Username member set to a unique name. If the account being added is a user account (as opposed to a role), a password meeting application password strength settings must be provided. On return the AccountID member of each AccountData structure that was successfully processed will be set to a unique user ID that will not change for the life of the account. The Password member is not erased. It is strongly recommended that calling code ensure that unencrypted passwords are destroyed as soon as possible after completion of this operation. |
Example:
( {parms for a subroutine that generates a new operator account }
NewName { Name for the new account };
NewPword { Temporary password for the new account };
)
[
PROTECTED NewAccount { structure holding the new account being made };
PROTECTED WaitObj { will be set Invalid on comletion };
PROTECTED OperationResults { will hold the result of the AddAccount operation };
PROTECTED NewID { unique ID for the new account };
]
Main [
If 1 Done;
[
NewID = \SecurityManager.CreateAccountID(NewName);
NewAccount = \SecurityManager.AccountData(NewID, NewName, NewPword, { AccountID, AccountName, Password }
Invalid, Invalid, 0, { AltID, AutoLogoff, Force password reset }
New(1), { Rules }
FALSE, FALSE, { IsRole, Disable }
Invalid); { CustomData }
NewAccount.Rules[0] = \SecurityManager.SecurityRule("Operator", Invalid, Invalid, FALSE);
WaitObj = \SecurityManager.AddAccount(NewAccounts, &OperationResults);
]
]
Done [
If !Valid(WaitObj);
[
{ The account is added, so we're finished. You may want to check the contents of OperationResults. }
Slay();
]
]
