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.
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
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:
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.
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.
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.
Read the excel, using the ExcelToRecordList action, and specify as the output structure the one we defined before, UserImport.
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.
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.
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.
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/