CreateUser - Create a new user EditUserName - Change the full name of an existing user EditAdminUser - Change the administrator who is associated with an existing user EditUserEmail - Change the email for an existing user EditSysAdminStatus - Assign/remove system administrator status for an existing user UnlockUser - Unlock a user who has been locked out of MACRO due to entering an incorrect password EnableUser - Enable or disable a user |
These routines cover a range of user management tasks. There are separate routines to import and export user role associations.
A system administrator user can never be created or edited by a non-system administrator user. If the currently logged-in user is non-system administrator, a “PermissionDenied” error will be returned if an attempt is made to create or edit a system administrator user.
CreateUser |
Create a new MACRO user account.
The new user will be automatically created as enabled.
The password assigned to a new user is a temporary password and can only be used for logging in to a MACRO module, at which point the password must be changed. It is not possible for a new user to log in to the API until their initial password has been reset in this way.
Input
Ensure all text parameters conform to these formatting rules.
Parameter |
Description |
curuser |
Currently logged-in user as returned from Login |
userid |
User name for new user |
fullname |
Full name for new user |
password |
Temporary password for new user (must comply with password policy) |
adminuser |
The system administrator who is to be responsible for dealing with forgotten passwords for the new user (may be left blank) |
emailaddr |
Email address for new user (may be left blank) |
sysadmin |
True to assign system administrator status, False to create as standard user |
public static Enums.eUserResult CreateUser(UserProperties curuser, string userid, string fullname, string password, string adminuser, string emailaddr, bool sysadmin) |
Output
· Return code indicating success or failure
EditUserName |
Change the full name of an existing user.
Input
Ensure all text parameters conform to these formatting rules.
Parameter |
Description |
curuser |
Currently logged-in user as returned from Login |
userid |
User name of user being edited |
fullname |
New full name for user being edited |
public static Enums.eUserResult EditUserName(UserProperties curuser, string userid, string fullname) |
Output
· Return code indicating success or failure
EditAdminUser |
Change the system administrator who is associated with an existing user.
Input
Parameter |
Description |
curuser |
Currently logged-in user as returned from Login |
userid |
User name of user being edited |
adminuser |
Admin user for user being edited (may be left blank). This specified adminuser must be a system administrator user, otherwise a UserNotFound error will be returned. |
public static Enums.eUserResult EditAdminUser(UserProperties curuser, string userid, string adminuser) |
Output
· Return code indicating success or failure
EditUserEmail |
Change the email for an existing user.
Input
Ensure all text parameters conform to these formatting rules.
Parameter |
Description |
curuser |
Currently logged-in user as returned from Login |
userid |
User name of user being edited |
emailaddr |
New email address for user (may be left blank) |
public static Enums.eUserResult EditUserEmail(UserProperties curuser, string userid, string emailaddr) |
Output
· Return code indicating success or failure
EditSysAdminStatus |
Assign/remove system administrator status for an existing user.
This call is only available to system administrator users. A non-system administrator user is not permitted to edit the system administrator status of any other user.
Input
Parameter |
Description |
curuser |
Currently logged-in user as returned from Login |
userid |
User name of user being edited |
isSysAdmin |
True to assign system administrator status, False to remove |
public static Enums.eUserResult EditSysAdminStatus(UserProperties curuser, string userid, bool isSysAdmin) |
Output
· Return code indicating success or failure
UnlockUser |
Clear the lock which is applied automatically when a user has entered an incorrect password too many times, as specified by the password policy.
Input
Parameter |
Description |
curuser |
Currently logged-in user as returned from Login |
userid |
User name of user being unlocked |
public static Enums.eUserResult UnlockUser(UserProperties curuser, string userid) |
Output
· Return code indicating success or failure
EnableUser |
Enable or disable a user.
Input
Parameter |
Description |
curuser |
Currently logged-in user as returned from Login |
userid |
User name of user being enabled/disabled |
enable |
True to enable the user, False to disable the user |
public static Enums.eUserResult EnableUser(UserProperties curuser, string userid, bool enable) |
Output
· Return code indicating success or failure
The user management routines return an integer code as type Enums.eUserResult indicating the overall result, as listed in the table below:
Code |
Value |
Description |
0 |
Success |
The operation was successful. When editing a user, Success may be returned even if nothing has changed. |
1 |
PermissionDenied | The current user does not have the relevant MACRO permissions to perform the action or a non-system administrator is trying to edit a system administrator |
2 |
InvalidUserName
|
The given user name is not valid, e.g. it contains invalid characters, too many characters or is empty |
3 |
InvalidFullName |
The given user full name is not valid, e.g. it contains invalid characters, too many characters or is empty |
4 |
InvalidPassword | The specified password is not valid, e.g. it is empty or does not comply with the current Password Policy |
5 |
InvalidEmail | The specified email address is not valid, e.g. it contains invalid characters, too many characters or does not contain the "@" character or a dot after the @ |
6 |
UserExists | In Create User, user already exists |
7 |
UserNotFound | User does not exist, e.g. when specifying Admin User or when editing an existing user |
99 |
Unknown |
An unknown error occurred |