Using the client to create profiles and page customizations
APPLIES TO: Business Central 2019 release wave 2 and later
Besides creating profiles, profile extensions, and page customizations by writing AL code, you can use the client. The client is a useful alternative, because you work with the user interface just as the users would. This method is especially advantageous for consultants, application administrators, and less technical users.
Overview
For detailed instructions on how to use the client to create and modify profiles, see the following articles in the Business Central application help:
A consequence of using the client is that profile changes apply only to the tenant. Extension-based profiles and customizations, by contrast, are available for all tenants. However, the client lets you export user-created profiles and page customizations from a tenant, then import them on another tenant.
Profiles created in the client are marked as (User-created) profiles. The export and import functionality lets you:
- Backup profiles, profile extensions, and page customizations locally.
- Make further changes to profiles, profile extensions, and page customizations away from the production environment.
- Replicate profiles, profile extensions, and page customizations on other environments and tenants.
- Preview changes in sandbox environments before going into production.
- Move your profiles, profile extensions, and page customizations into AL extensions.
Important
You can't use the import functionality to migrate legacy profiles from Dynamics NAV or early versions of Business Central.
Exporting profiles
When you export profiles, the system exports all user-defined profiles, profile extensions, and page customizations that have been made in the tenant. It doesn't export profiles, profile extensions, and page customizations introduced by extensions.
To export profiles from the client, open the Profiles (Roles) page, and select the Export Profiles action. A zip file is downloaded to your computer. The file is referred to as a profile package.
Once you have the profile package, you can import it as-is to another tenant. Or, you extract the files and make more changes to profiles, profile extensions, and page customizations. When you're done, you compress the files into a profile package again and import it on tenants, or deploy them as part of an AL extension.
Note
To export profiles, a user requires read permission to the Profiles page and table as a minimum. This capability allows normal users to hand over profiles to others for troubleshooting.
Importing profiles
Importing profiles lets you add new profiles and page customizations on a tenant or replace existing ones. To import profiles, do the following steps:
Get the profile package that contains the new or modified profiles.
Before you import a package, we recommend that you export the current profiles so you have a copy.
Open the Profiles (Roles) page, select the Import Profiles action, and follow the instructions to import the profile package.
You don't have to import all profiles contained in the package. You can select specific profiles.
When you replace a profile, signed-in users of the profile may be interrupted briefly.
Important
To import profiles, you must be assigned the SUPER or D365 Profile Mgmt permission set.
Working with the profile package and files
A profile package is a zip file that contains profiles, profile extensions, and page customizations in separate files. These files basically contain AL source code and are grouped in a folder per profile. The following table provides an overview of the file types in a profile package.
| File type | Description |
|---|---|
| app.json | A required configuration file that includes dependencies to the base application and system application. In most cases, you shouldn't modify this file after exporting it. The app.json must be included in the profile package that you import. |
| profile.json | A required configuration file that specifies information about the profiles in the package. In most cases, you shouldn't modify this file after exporting it. The profile.json must be included in the profile package that you import. |
| profile file | An AL file for a user-created profile. There's a separate file for each profile. A profile file has the format <profile ID>.Profile.al. |
| profile extension file | An AL file for customizations made to an extension-based profile. These file types have the format <profile ID>.ProfileExt.al. |
| page customization file | An AL file that specifies all customizations made to a page for a specific profile. A page customization file has the format [page name].PageCust.al. |
The sections that follow explain a bit more about the file types and creating the profile package.
Note
This section describes the package structure and file naming for Business Central 2024 release wave 2 (version 25.0) and later.
Profile files
Each user-created profile is exported to a separate AL file in a dedicated folder. This file contains the profile object that defines the profile's ID, name, and Role Center. It also includes references to the page customizations it uses. For example, let's say you created a profile with the ID MyProfile that uses the role center page 9022 Business Manager Role Center. You then customized the Business Manager Role Center itself and the Customer list page. The exported profile package would contain a folder named MYPROFILE and a file called MYPROFILE.Profile.al. This file would include the following code:
profile MyProfile
{
CaptionML = ENU='My Profile';
Enabled = true;
ProfileDescriptionML = ENU='This is my sample profiles';
Promoted = true;
RoleCenter = 9022;
Customizations = Configuration1; Configuration2;
}
The Customizations property identifies the page customization objects used by the profile.
Profile extension files
Customizations made to extension-based profiles are exported to a profile extension file. This file includes a profileextension object that specifies two types of information, depending on the changes:
- Properties that specify metadata like, the CaptionML, ProfileDescriptionML, and RoleCenter.
- References to configuration files that define page customizations.
For example, let's say you changed the description and customized the Customer List page for the Business Manager profile that is provided by the Base Application extension. The profile package would then contain a folder named BUSINESS MANAGER and the file BUSINESS MANAGER.ProfileExt.al. This file will contain code similar to the following code:
profileextension BUSINESSMANAGER_1 extends "BUSINESS MANAGER"
{
CaptionML = ENU='Business Manager';
Enabled = true;
ProfileDescriptionML = ENU='My changed functionality for managers in charge of keeping the business viable by determining product and company direction.';
Promoted = false;
RoleCenter = 9022;
Customizations = Configuration3;
}
Configuration3 is a reference to a page customization file for the Customer List page. For more information, see the next section.
Page customization files
Page customizations made to user-created profiles and extension-based profiles are exported to AL files that include a pagecustomization object. This object defines each modification to the page. Referring to the examples above, the zip file would include three files in two different folders:
- MYPROFILE\Business Manager Role Center.PageCust.al
- MYPROFILE\Customer List.PageCust.al
- BUSINESS MANAGER\Customer List.PageCust.al
The files would include code similar to the following code:
MYPROFILE\Business Manager Role Center.PageCust.al
pagecustomization Configuration1 customizes "Business Manager Role Center"
{
layout
{
modify(Control16)
{
Visible = false;
}
}
}
MYPROFILE\Customer List.PageCust.al
pagecustomization Configuration2 customizes "Customer List"
{
layout
{
modify("Balance (LCY)")
{
Visible = false;
}
}
}
BUSINESS MANAGER\Customer List.PageCust.al
pagecustomization Configuration3 customizes "Customer List"
{
layout
{
modify("Balance Due (LCY)")
{
Visible = true;
}
}
}
Creating a profile package for import
After you make modifications to exported profiles, profile extensions, and page customizations, you'll have to create the profile package before you can import the changes.
The profile package doesn't have to contain the same files that were originally exported. But it must contain the app.json and profile.json files. Otherwise, you can't import the package. To create the profile package, just compress the files into a zip folder.
Related information
Developing extensions
AL development environment
Page object
Page extension object
Page extension properties