User permissions

Remember that, when we deliver an application to a customer, we're trying to provide them with the best experience that we can. Nothing's worse than building the best application you can build and everything tests out great, but then you deploy it to the customer and nobody can run it because they don't have any permissions set up. This adds a layer of complexity for the customer that doesn't really need to be there, so the administrator needs to figure out what new entities were added so that they can update their permission sets.

In this recipe, you will see that, with your AL application, you can create a set of user permissions that will be installed when your application is deployed. Then, all an administrator has to do is assign those permissions to the appropriate users!

Getting ready

You're going to need an AL project to work in that's connected to a development sandbox. We will continue to build on the project that we started in this chapter. You can download it from the GitHub link at the start of this chapter.

How to do it...

1. Open up your AL project in Visual Studio Code. Press Ctrl + Shift + P to open the Command Palette and type or select AL: Generate permission set containing current extension objects.

Wait... what? That's it? Yeah, it is that easy! When this command runs, it will create a file named extensionPermissionSet.xml.

This file will contain default permissions for every AL object file that you have created in your project:

• • Tables: Allow the user to run each table and have full read/write/modify access to the data in the table
  • Everything else: Allows the user to execute all other AL object types (such as pages, codeunits, and reports)

Your file should look similar to this:

<?xml version="1.0" encoding="utf-8"?>
<PermissionSets>
  <PermissionSet RoleID="ALPROJECT1" RoleName="ALProject1">
    <Permission>
      <ObjectType>0</ObjectType>
      <ObjectID>50100</ObjectID>
      <ReadPermission>1</ReadPermission>
      <InsertPermission>1</InsertPermission>
      <ModifyPermission>1</ModifyPermission>
      <DeletePermission>1</DeletePermission>
      <ExecutePermission>0</ExecutePermission>
      <SecurityFilter />
    </Permission>
    <Permission>
      <ObjectType>1</ObjectType>
      <ObjectID>50100</ObjectID>
      <ReadPermission>0</ReadPermission>
      <InsertPermission>0</InsertPermission>
      <ModifyPermission>0</ModifyPermission>
      <DeletePermission>0</DeletePermission>
      <ExecutePermission>1</ExecutePermission>
      <SecurityFilter />
    </Permission>
    <Permission>
      <ObjectType>8</ObjectType>
      <ObjectID>50101</ObjectID>
      <ReadPermission>0</ReadPermission>
      <InsertPermission>0</InsertPermission>
      <ModifyPermission>0</ModifyPermission>
      <DeletePermission>0</DeletePermission>
      <ExecutePermission>1</ExecutePermission>
      <SecurityFilter />
    </Permission>
    <Permission>
      <ObjectType>8</ObjectType>
      <ObjectID>50100</ObjectID>
      <ReadPermission>0</ReadPermission>
      <InsertPermission>0</InsertPermission>
      <ModifyPermission>0</ModifyPermission>
      <DeletePermission>0</DeletePermission>
      <ExecutePermission>1</ExecutePermission>
      <SecurityFilter />
    </Permission>
  </PermissionSet>
</PermissionSets>

If you make manual updates to the file that was generated by Visual Studio Code, and you run the command again to generate the XML file, your changes will be lost. You can avoid this by renaming the file that was generated so it doesn't get overwritten. Any manual changes need to be merged with the generated file.

2. At this point, it's a really good idea to change the RoleID and RoleName values in the file. This makes it easier for the administrator who is assigning the permissions and trying to figure out what each permission set is for.

Set these properties to the following values:

RoleID="TVSHOW"
RoleName="Television Show"

If you prefer, you can also manually create a permission set file by creating an empty XML file, and then using the tpermsets and tpermset snippets to quickly build the structure of the file.

3. Now, we can publish our application to make sure that our permission set gets installed properly.

In Visual Studio Code, press F5 to build and publish the application.

4. When your browser opens up, log in to your sandbox and click the icon at the top-right of the window in order to open the Tell Me What You Want to Do search page. In the search box, type in permission sets and click the link to open the PERMISSION SETS page. In the list of available permission sets, you should see the TVSHOW set that you just created:

5. Click on the TVSHOW permission set row, and on the ribbon at the top, click on More options | Navigate | Permissions | Permission Set to open up the permission set details. Here, you can see which permissions are included in the permission set. It should look like this:

As you can see, our permission set includes full access to the Television Show data, and access to run everything that is included in our application.

How it works...

When you create the XML file using the specific structure outlined previously, the AL compiler is able to automatically determine that the file contains permission sets and permissions, and it will automatically load the permission sets into Business Central when your application is installed. This way, the customer does not need to try and figure out what objects have been added, nor do they need to update any existing permission sets that they have already defined.

You can create multiple permission sets within your application, and you can define the permissions in as much detail as you like. For example, you could define two permission sets, where one has only read-only access to the data, and the other set has full access, thereby giving the customer the option of assigning different levels of user access.

There's more...

Once your permission sets have been installed, the last step is for the administrator to assign the permission sets to the applicable users. This can be done by either assigning the permission set directly to the user or by assigning the permission set to a user group. By doing this, all users within that group will inherit the new permission set.

See also

You can find more information on managing permissions in Business Central on the Microsoft Docs page at https://docs.microsoft.com/en-us/dynamics365/business-central/ui-how-users-permissions.