How to bootstrap Users with Roles and Groups

How to bootstrap Users with Roles and Groups

  

When we deploy an application into production, sometimes we need to create a couple of users, some other times we might need to create hundreds of users. To accomplish this, it’s better to bootstrap a list of users from an excel file. In this How-to, I will try to explain how simple it is to achieve this in OutSystems Platform, using a screen to upload the excel file and processing it.


Step 1 - Reference System and User Entities/Actions


Reference the Group, Group_Role, Group_User, Role, User_Effective_Role and User_Role entities. For the actions you will need to reference the String_Split from the Text extension and the EncryptPassword from the Users module.


To get more information about End User Management, follow this link

Step 2 - Create a new Screen to upload the excel file

Create a new screen that will be responsible for listing the Users, as well as uploading an excel file and processing it.


It should look similar to this:


Step 3 - Define the format of the excel file

Define the format you need for the excel file. In this How-to, I am using an excel file with the fields Name, Username, Password, Groups, Role.


The Name, Username, Password fields are self explanatory. In the Groups and Roles fields you can specify multiple Groups and/or Roles to associate with the user, separating them with a comma.


To import the excel file, create a structure with the corresponding fields.

Step 4 - Create the action to bootstrap the Users

Just a quick note, when bootstrapping data from an excel, it is a good programming policy to export an excel file to let the user understand if there were any errors, specifically for which line of the imported excel. To accomplish this, create a new Structure with the fields to export. Usually, you can include the same fields that were imported, and add a IsOk, and a Error fields. The IsOk is used to let the user know if the line was imported correctly, and the Error field, the error detail, if any.


Now, let’s start creating the action to import the excel file.


Step 4.1 - Define a new action, with its input and output parameters and local variables

As input, receive the File and the flag to UpdateUsers. As output, define a RecordList that will contain the outcome of the bootstrapping for each record, and a HasErrors flag. Also define a local variable to capture the individual records to output.


Step 4.2 - Read the excel file to a Record List

Read the excel, using the ExcelToRecordList action, and specify as the output structure the one we defined before, UserImport.


Step 4.3 - Iterate the lines of the Excel

Now, iterate the Record list, set the record used for the output with the input fields, and check if the User already exists.


If the User already exists, and we haven’t chose the checkbox to update existing users, then return add the record to the output Record List with the error.


If the User does not exist, or we chose to update existing users, then we need to set the User attributes, Encrypt the password (using the EncryptPassword referenced Action from the Users module), and CreateUpdateUser the User record. Notice that I’ve encapsulated the CreateOrUpdateUser action inside a user action so I can deal with exceptions and capture them in the main action.


Step 4.3.1 - Split the Groups and Iterate

After creating/updating the User, iterate through the Groups, saving the information or generating an error output, if a Group is not found in the Database. Once again, I’ve encapsulated the CreateOrUpdateGroup_User action inside a user action so I can deal with exceptions and capture them in the main action.

Step 4.3.2 - Split the Roles and Iterate

Now, iterate through the Roles, saving the information or generating an error output, if a Role is not found in the database. Once again, I’ve encapsulated the CreateOrUpdateUser_Role action inside a user action so I can deal with exceptions and capture them in the main action. Take in consideration that the Roles are not unique, and in a multi tenant scenario, the roles are not related to any specific tenant.

Step 5 - Use the bootstrap action in the Screen Action

The screen action to handle the Upload should look like this:

Notice the validation UsersImport.HasErrors, and how the RecordList with the output information is returned to the user in an excel file in case of any error.


Further information on how to Export a RecordList to an Excel here.




Check the attached file with the application used in this post. A live demo is available at https://joaobatista.outsystemscloud.com/UserBootstrap/


Feel free to ask questions or give suggestions.
Dude, thank you, you made my day with this. 

Hopefully Outsystems will have similar documentation in a couple of years from now.