9 - Migrate Roles

Last updated 8/05/2025

In the previous chapters, we created the Member role for members of the Book Club application and imported the users for the application. There are a number of users that have been imported and none of them have a role assigned to them, you have two ways you can assign their role. You can add them individually by logging in as admin, selecting a user record and selecting the Member role in the Role field.

Figure 1 - User record

Alternatively, We can migrate our Member role into the Book Club application and assign it to all members by using Five's

getRoleKey()

function.

Once the Member role is assigned to the members, you can log in with each member by using their user ID on the user record and the password: Demo123!

Navigate to Functions

1. Click Logic in the menu.

2. Click Functions in the sub-menu.

Figure 2 - Functions menu item

Add the MigrateRoles Function

1. Click the Add Item button.

2. Type MigrateRoles in the Function ID field.

3. Click in the Code field to open the Code Editor.

Figure 3 - Add MigrateRoles function

4. Copy the code block below and paste it over the template in the Code Editor.

Migrating roles

function MigrateRoles(five, context, result)  {
    const iRoleKey = five.getRoleKey('Member');
    const updateResults = five.executeQuery(`UPDATE iUser SET iRoleKey = ? WHERE UserID <> 'admin' AND UserID <> 'public'`, 0, iRoleKey);
    if (updateResults.isOk() === false) {
        return five.createError(updateResults);
    }

    return five.success(result, 'Migration completed');
}

5. Click the Save button in the editor app bar.

Figure 4 - Save button

6. Click the Save button in the form app bar.

Figure 5 - Save button

Navigate to Processes

1. Click Tasks in the menu.

2. Click Processes in the sub-menu.

Figure 6 - Processes menu item

Add the Migrate Roles Process

The Migrate Roles process needs to be created so the

MigrateRoles()

function can be attached to the Do Run event. In the Book Club application, when we click the Run button, the code will be executed on the server and migrate the Member role with the users imported into the Book Club application.

1. Click the Add Item button.

2. Type Migrate Roles in the Title field.

Figure 7 - Add Migrate Roles process

3. Click the Events tab.

Figure 8 - Events tab

4. Click the lookup icon in the Do Run field and select MigrateRoles.

Figure 9 - Do Run field

5. Click the Save button in the form app bar.

Figure 10 - Save button

Navigate to Menus

1. Click Visual in the menu.

2. Click Menus in the sub-menu.

Figure 11 - Menus menu item

Add the Migrate Roles Menu

We will run the Migrate Roles process manually as it only needs to be ran once, so the Migrate Roles process will need a menu. The function, process, and menu can be deleted after the roles have been migrated.

1. Click the Add Item button.

2. Type Migrate Roles in the Caption field.

3. Type 100300 before MigrateRoles in the Menu ID field.

4. Type 100300 in the Menu Order field.

5. Click the lookup icon in the Action field and select MigrateRoles (Process).

6. Click the lookup icon in the Parent Menu field and select 100000AdministrationMenu (AdministrationMenu).

Figure 12 - Add Migrate Roles menu

7. Click the Save button in the form app bar.

Figure 13 - Save button

Run the Book Club Application

Deploy or run the Book Club application so you can run the Migrate Roles process and assign the Member role to the book club members.

1. Either click the Run or the Deploy to Development button in the toolbar.

info

The admin login needs to be used to migrate the roles to the users.

2. Type admin in the Username field.

3. Type your password in the Password field.

4. Click the Sign In button.

Figure 14 - Sign In button

5. Click Administration Menu in the menu.

6. Click Migrate Roles in the menu.

Figure 15 - Migrate Roles menu

7. Click the Run button.

Figure 16 - Run button

8. Click the OK button.

Figure 17 - OK button

9. Click Users in the menu.

10. Select a member user in the list.

info

You can see in the Role field, the user has the Member role with the exception of the admin and public users as we specified in the function for them not to be assigned the Member role.

Figure 18 - Users form