Accessing Users and Roles

All of the login records are stored in the "Users" nested list at the top-level. All, that is, except the system administrator login - which is built-in. The system administrator login defaults to "admin" and it set on the Application record. You can disable the system admin login entirely by setting the login name to an empty string. To force a user to login, you set the "Requires Login" flag on the Configuration tab in your application.

In DbfScript, you can get hold of the currently-logged in user by using the GetUser() function. This returns the record under /Users that refers to the currently logged-in user. If the user is logged in as the system admin, this will return null (in DbfScript, you can check it with Exists(GetUser()) or by comparing it to Nothing()).

The record returned by GetUser() is the User record. You can retrieve information from this like any other record:

var #user = GetUser()
message "Your login name is " + #user/UserID

You can also change things on the user record, like this:

var #user = GetUser()
set #user/SomeField = "SomeValue"
save #user

If you're using the built-in authentication (and not Active Directory) you can reset the password, too, like this:

var #user = GetUser()
set #user/Password = str:RandomPassword()
save #user

You can also programmatically add new users, simply add a record under /Users with the appropriate fields filled-in:

var #user = new record for &root/Users
set #user/FullName = "John Smith"
set #user/UserID = "someuser"
set #user/Password = str:RandomPassword()
set #user/EMail = "[email protected]"
insert #user at &root/Users

It's also important to pay attention to the roles that a user has. The roles determine what permissions that user has. The set of roles associated with a user are set at runtime in the actual application. You can see if under the User record, in the "Roles" tab.

To see if a user has a specific role, you can use the HasRole() function, for example:

if HasRole("Manager") then
    message "You are a manager!"
end if

The Roles nested field is added by WorkflowFirst during publish, so you don't see it in WorkflowFirst when looking at the User record structure. However, you can assume it will be there when you're using DbfScript.

For example, to add a role to a user, you can do this:

elevate on
var &userPath = GetPath(GetUser())
var #role = new record for &root/Users/Roles
set #role/RoleID = "Manager"
insert #role at &userPath/Roles

Keep in mind that all role names are internal IDs - so that means you need to remove spaces from the role titles when you use them in script. So if the role title is "Human Resources Manager", the role ID will be "HumanResourcesManager".

You may notice that we have "elevate on" at the start. In some cases, modifying the roles from the currently-logged-in user will hit a security issue - in which case simply put "elevate on" at the beginning of the script to ensure it runs with administrator rights.

Also, note that any changes to the user's roles won't take effect until they log-out and in again, or if their session timeout expires (after which they will be re-authenticated, usually every 20 minutes).

You can just as easily remove roles, for example:

delete at &userPath/Roles[RoleID="Manager"]

This example will delete the role with the name "Manager" from the path to the user, &userPath.

You can also just detect if the current user is a system admin (ie. if their "Is Admin" flag is set to Yes in their user record). This gives them permission to edit other users, for example. You can check this by using the IsUserAdmin() function. If the user is logged in as the system administrator, this function will also return true.

if IsUserAdmin() then
message "You're an admin!"
end if

Next Topic: Advanced Examples

Please post all questions on the support forum. Thank you.