ApplicationCop on ALCops

DrillDownPageId and LookupPageId must be defined for tables used in list pages (AC0001)

Mon, 01 Jan 0001 00:00:00 +0000

When a table is used as the source for a list page, users expect to be able to drill down into records and open lookups in a consistent and predictable way. The DrillDownPageId and LookupPageId table properties define which pages are used for these interactions.

Without these properties, the Business Central client cannot provide the expected navigation experience, potentially confusing users and breaking standard UX patterns.

Example

The following table is used by a list page but does not define both required properties:

Single-field primary key requires the NotBlank property (AC0002)

Mon, 01 Jan 0001 00:00:00 +0000

In tables that define a primary key consisting of a single field of type Code or Text, the primary key field must explicitly set the NotBlank property. This ensures that empty values cannot be used as primary keys, which would violate database integrity principles.

Explicitly declaring NotBlank makes the design intent clear and prevents runtime errors when attempting to insert records with blank primary key values.

A code fix is available for this diagnostic.

Set NotBlank property to false when No. Series TableRelation exists (AC0003)

Mon, 01 Jan 0001 00:00:00 +0000

When the ‘No. Series’ TableRelation is present on the table, assigning the primary key might occur after inserting the record, which could cause an error due to the NotBlank property.

Number series functionality in Business Central allows records to be inserted with an empty primary key value initially, with the actual value being assigned afterward through the number series logic. Setting NotBlank to true on such fields prevents this pattern from working correctly.

Confirm() must be implemented through the Confirm Management codeunit (AC0004)

Mon, 01 Jan 0001 00:00:00 +0000

Direct calls to Confirm() bypass the safeguards and features provided by the Confirm Management codeunit in the System Application. Using Confirm Management ensures automatic validation of IsGuiAllowed(), prevents runtime failures in non-GUI contexts, and allows explicit control over the default response (true or false).

The Confirm Management codeunit centralizes confirmation dialog handling and provides a consistent, testable pattern across the application.

A code fix is available for this diagnostic.

Example

The following code uses the built-in Confirm method directly:

GlobalLanguage() must be implemented through the Translation Helper codeunit (AC0005)

Mon, 01 Jan 0001 00:00:00 +0000

Direct use of GlobalLanguage() leads to verbose, error-prone code and often requires manual state management, hardcoded language IDs, or duplicated logic. The Translation Helper codeunit from the Base Application centralizes global language handling by automatically preserving and restoring the previous language, supporting both LanguageId and LanguageCode, and allowing a safe reset to the default application language without hardcoding values such as 1033.

This pattern ensures that language switches are always properly cleaned up and prevents side effects in multi-language scenarios.

Use the Page Management codeunit instead of invoking Page.Run directly (AC0006)

Mon, 01 Jan 0001 00:00:00 +0000

Direct calls to Page.Run bypass the centralized logic provided by the Page Management codeunit. Using Page Management improves correctness and extensibility by automatically resolving the appropriate page based on record context, table relationships, and configuration.

The Page Management codeunit provides a single point of control for page selection logic, making it easier to extend and customize page navigation behavior across the application.

A code fix is available for this diagnostic.

Install and Upgrade codeunits should have Access set to Internal (AC0007)

Mon, 01 Jan 0001 00:00:00 +0000

Install and Upgrade codeunits are intended for lifecycle execution only and are not designed to expose reusable APIs. Declaring them as Public unnecessarily broadens their surface area and increases coupling between extensions.

Making these codeunits internal ensures they are only accessible within the extension that defines them, preventing external dependencies on implementation details that are meant to run only during installation or upgrade.

A code fix is available for this diagnostic.

DataPerCompany must be explicitly set on table objects (AC0008)

Mon, 01 Jan 0001 00:00:00 +0000

In projects where company data isolation matters, table objects must explicitly define the DataPerCompany property. Relying on implicit defaults makes the data scope unclear and can lead to incorrect assumptions about whether data is shared across companies or stored per company.

Explicitly declaring this property ensures that the design intent is clear and documented in the code, preventing data isolation issues in multi-company environments.

Note: This rule is disabled by default. Enable it in your project’s .editorconfig or ruleset file if you want to enforce explicit DataPerCompany declarations.

The Caption of permissionset objects should not exceed the maximum length (AC0009)

Mon, 01 Jan 0001 00:00:00 +0000

PermissionSet captions should remain within a defined maximum length (30 characters) to avoid issues in translated captions. When no MaxLength or Locked subproperty is specified, translations can exceed the intended limit and cause inconsistent or truncated UI labels.

Setting an explicit MaxLength constraint or marking the caption as Locked ensures that translated captions do not break the UI or cause display issues.

A code fix is available for this diagnostic.

All application objects must be covered by a PermissionSet (AC0010)

Mon, 01 Jan 0001 00:00:00 +0000

Every application object in an extension must be explicitly granted permissions through at least one permission set or permission set extension, defined in AL or XML. This ensures that when the extension is deployed, users with the appropriate permission sets can access all functionality.

Without explicit permission coverage, objects may be inaccessible to users, leading to runtime errors or broken functionality even though the objects are technically deployed.

Example

The following table is not covered by any permission set:

Captions must be defined on user-facing objects and controls (AC0011)

Mon, 01 Jan 0001 00:00:00 +0000

All user-facing application objects and controls must explicitly define a Caption to ensure a consistent, accessible, and localizable user interface. Captions provide users with meaningful labels for pages, fields, actions, and other UI elements.

Without explicit captions, the Business Central client may fall back to object names or technical identifiers, resulting in a poor user experience and making localization impossible.

Example

The following page action is missing a Caption:

page 50100 MyPage
{
 actions
 {
 area(Processing)
 {
 action(MyAction) // A user-facing object or control is missing a Caption. [AC0011]
 {
 trigger OnAction()
 begin
 end;
 }
 }
 }
}

To fix this, add a Caption property:

Integration events must not be declared in codeunits with Access set to Internal (AC0012)

Mon, 01 Jan 0001 00:00:00 +0000

Integration events are designed to be consumed by extensions and therefore must be accessible outside the defining app. When an IntegrationEvent is declared in a codeunit with Access = Internal, the event cannot be subscribed to by extensions, rendering it ineffective.

If the event is intended for internal use only within the same app, it should be declared as an InternalEvent instead.

A code fix is available for this diagnostic.

DropDown and Brick fieldgroups must be defined (AC0013)

Mon, 01 Jan 0001 00:00:00 +0000

Table objects must explicitly define both the DropDown and Brick fieldgroups. These fieldgroups control how records are displayed in dropdown lists and tile views throughout the Business Central client.

The DropDown fieldgroup determines which fields are shown when users select records from a lookup, while the Brick fieldgroup defines the tile representation used in certain UI contexts.

Note: This rule is disabled by default. Enable it in your project’s .editorconfig or ruleset file if you want to enforce fieldgroup definitions.

ToolTip must end with a dot (AC0014)

Mon, 01 Jan 0001 00:00:00 +0000

End ToolTips with a dot to keep phrasing consistent and clearly separated from surrounding UI text. This follows the Business Central user assistance model and ensures a professional, polished appearance.

Consistent punctuation in ToolTips improves readability and makes the UI feel more cohesive.

Example

The following field has a ToolTip without a trailing dot:

table 50100 MyTable
{
 fields
 {
 field(1; MyField; Integer)
 {
 ToolTip = 'Specifies the value'; // ToolTip must end with a dot. [AC0014]
 }
 }
}

To fix this, add a dot at the end:

ToolTip should start with Specifies (AC0015)

Mon, 01 Jan 0001 00:00:00 +0000

For field ToolTips, the Business Central user assistance model expects the text to start with the verb ‘Specifies’ to describe what the field represents. This convention provides a consistent voice and format across all field documentation.

Starting with ‘Specifies’ helps users quickly understand the purpose of a field in a standardized way.

Example

The following field has a ToolTip that doesn’t start with ‘Specifies’:

table 50100 MyTable
{
 fields
 {
 field(1; MyField; Integer)
 {
 ToolTip = 'The field value.'; // ToolTip should start with the verb 'Specifies'. [AC0015]
 }
 }
}

To fix this, rewrite the ToolTip to start with ‘Specifies’:

Do not use line breaks in ToolTip (AC0016)

Mon, 01 Jan 0001 00:00:00 +0000

The Business Central user assistance model does not support formatting in ToolTips. Line breaks are not rendered and make the ToolTip harder to read. Keep ToolTips as a single, continuous sentence.

Line breaks in ToolTips can cause display issues and result in unpredictable rendering across different clients and contexts.

Example

The following field has a ToolTip with line breaks:

table 50100 MyTable
{
 fields
 {
 field(1; MyField; Integer)
 {
 ToolTip = 'Specifies the value.\This is a second line.'; // ToolTip text must not contain line breaks. [AC0016]
 }
 }
}

To fix this, remove the line break and keep the text as a single sentence:

ToolTip should not exceed 200 characters (AC0017)

Mon, 01 Jan 0001 00:00:00 +0000

The user assistance model recommends keeping ToolTips short (about 200 characters including spaces) so users can scan them quickly. The UI can render longer ToolTips, but longer text reduces scannability and consistency.

Concise ToolTips improve the user experience by providing essential information without overwhelming the reader.

Example

The following field has a ToolTip that exceeds the recommended length:

table 50100 MyTable
{
 fields
 {
 field(1; MyField; Integer)
 {
 ToolTip = 'Specifies the value that is used for this particular field and contains a very long description that exceeds the recommended maximum length of 200 characters, which makes it harder for users to quickly scan and understand the purpose of this field.'; // ToolTip exceeds the recommended maximum length of 200 characters. [AC0017]
 }
 }
}

To fix this, shorten the ToolTip to focus on essential information:

Empty captions should be locked (AC0018)

Mon, 01 Jan 0001 00:00:00 +0000

When a Caption property is intentionally left empty, it should always be marked with Locked = true. An empty caption without locking is still extracted into translation files, resulting in meaningless entries that waste translator time and bloat translation resources.

Marking empty captions as locked makes the design intent explicit and prevents unnecessary translation overhead.

A code fix is available for this diagnostic.

Example

The following table field has an empty caption without the Locked property:

Reserve Enum value zero (0) for empty value (AC0019)

Mon, 01 Jan 0001 00:00:00 +0000

Zero (0) should be reserved as the empty Enum value. Business Central stores Enums as integers and does not support null; new records (and existing records after adding a field via table extension) default to 0, which makes non-empty meaning at 0 ambiguous.

By reserving 0 as an empty sentinel value, you ensure that default record states are clearly distinguished from intentional enum selections.

Example

The following enum assigns a meaningful value to 0:

Labels suffixed with Tok must be locked (AC0020)

Mon, 01 Jan 0001 00:00:00 +0000

Labels ending with the suffix ‘Tok’ represent tokens: hardcoded, non-translatable values. Such labels must explicitly have the Locked property set to true to prevent translation.

The ‘Tok’ suffix is a widely-adopted naming convention in Business Central AL development to indicate that a label contains a technical identifier, API constant, or other value that should never be translated.

A code fix is available for this diagnostic.

Example

The following label is suffixed with ‘Tok’ but not locked:

Locked Label must have a suffix Tok (AC0021)

Mon, 01 Jan 0001 00:00:00 +0000

A label with the Locked property set to true is explicitly marked as non-translatable and represents a hardcoded value. To make this intent explicit and consistent, locked labels must be suffixed with ‘Tok’.

This naming convention helps developers immediately recognize that a label contains a technical value that should not be translated, improving code readability and maintainability.

Note: This rule is disabled by default. Enable it in your project’s .editorconfig or ruleset file if you want to enforce the ‘Tok’ suffix convention for all locked labels.

Empty Enum value should not have a Caption property specified (AC0022)

Mon, 01 Jan 0001 00:00:00 +0000

Enum values with an empty name act as sentinel or placeholder values in Business Central. These values are not selectable, not accessible from AL code, and never displayed in the client.

Defining a Caption for an empty enum value is meaningless since the caption will never be shown or used. Removing it reduces clutter and makes the design intent clearer.

Example

The following enum has an empty value with a Caption:

Enum value must have non-empty Caption to be selectable in the client (AC0023)

Mon, 01 Jan 0001 00:00:00 +0000

Enum values with a non-empty name are intended to be selectable and visible in the Business Central client. If the Caption is empty, the value is hidden from the UI, leading to unexpected behavior and incomplete user interaction.

Every selectable enum value must have a meaningful Caption so users can see and choose it in the UI.

Example

The following enum value has a name but an empty Caption:

enum 50100 MyEnum
{
 value(1; MyValue)
 {
 Caption = ''; // The enum value 'MyValue' has an empty Caption and will not be shown or be selectable in the client. [AC0023]
 }
}

To fix this, provide a meaningful Caption:

Event publisher methods should not be public (AC0024)

Mon, 01 Jan 0001 00:00:00 +0000

Event publisher methods are intended solely to raise events within the extension that defines them. When declared as public, they can be called by external dependency apps, which is a design smell and breaks the intended event-driven pattern. Additionally, public event publishers are treated as part of the public API, meaning their parameter signature cannot be extended in the future without introducing breaking changes.

Declaring event publishers as local or internal ensures they can only be raised within the defining extension while still allowing external extensions to subscribe to the events.

Use the (CR)LFSeparator from the Type Helper codeunit (AC0025)

Mon, 01 Jan 0001 00:00:00 +0000

Avoid manually creating helper methods or assigning character values (e.g., Char := 10 or Text[1] := 10) to define line feed (LF) or carriage return (CR) variables. Instead, use the LFSeparator and CRLFSeparator constants provided by the “Type Helper” codeunit from the Base Application.

Using the centralized Type Helper constants ensures consistency, improves code readability, and reduces duplication.

Example

The following code manually assigns the LF character:

codeunit 50100 MyCodeunit
{
 procedure MyProcedure()
 var
 LineFeed: Char;
 begin
 LineFeed := 10; // Use the (CR)LFSeparator from the "Type Helper" codeunit from the Base Application to define a line feed (LF) or carriage return (CR) variable. [AC0025]
 end;
}

To fix this, use the Type Helper codeunit:

Explicitly set AllowInCustomizations for excluded fields (AC0026)

Mon, 01 Jan 0001 00:00:00 +0000

Fields that are not included on pages can still be exposed through page customizations. To avoid unintended visibility or customization behavior, the AllowInCustomizations property must be set explicitly for such fields.

This ensures that developers consciously decide whether omitted fields should be available for user customizations, preventing accidental exposure of internal or deprecated fields.

Example

The following table field is not exposed on any page and lacks the AllowInCustomizations property:

Use the Tok suffix for token labels (AC0027)

Mon, 01 Jan 0001 00:00:00 +0000

When a label value is identical to its name, the label represents a fixed token rather than translatable text. Such labels must use the ‘Tok’ suffix to make this intent explicit.

Token labels typically contain technical identifiers, API paths, or other values that mirror their variable name and should not be translated.

Example

The following label has a value identical to its name but lacks the ‘Tok’ suffix:

codeunit 50100 MyCodeunit
{
 var
 ApiVersion: Label 'ApiVersion', Locked = true; // Label 'ApiVersion' represents a token but does not use the required 'Tok' suffix. [AC0027]
}

To fix this, add the ‘Tok’ suffix:

Table field must define a ToolTip (AC0028)

Mon, 01 Jan 0001 00:00:00 +0000

It is better to apply the ToolTip property on the table field instead of the page field. When a page field has a ToolTip but the underlying table field does not, the ToolTip is duplicated across every page that uses the field, leading to maintenance overhead and inconsistency.

Defining the ToolTip on the table field ensures that all pages using the field automatically inherit the same ToolTip, promoting consistency and reducing duplication.

Duplicate ToolTip between page and table field (AC0029)

Mon, 01 Jan 0001 00:00:00 +0000

When both a page field and its underlying table field define the same ToolTip value, the page field’s ToolTip is redundant and should be removed. The ToolTip defined on the table field will automatically be inherited by all pages using the field.

Removing duplicate ToolTips reduces maintenance overhead and ensures consistency across all pages that use the field.

Example

The following page field and table field have identical ToolTips:

table 50100 MyTable
{
 fields
 {
 field(1; MyField; Integer)
 {
 ToolTip = 'Specifies the value.';
 }
 }
}

page 50100 MyPage
{
 SourceTable = MyTable;

 layout
 {
 area(Content)
 {
 field(MyField; Rec.MyField) // The ToolTip property of page field 'MyField' and its table field 'MyField' have the same value and therefore the page field's ToolTip can be removed. [AC0029]
 {
 ToolTip = 'Specifies the value.';
 }
 }
 }
}

To fix this, remove the ToolTip from the page field:

Use return value for better error handling (AC0030)

Mon, 01 Jan 0001 00:00:00 +0000

Database read methods, like Record.Get(), returns a boolean indicating whether the record was successfully retrieved. Failing to use this return value can lead to uncaught errors, poor error handling, and a lack of actionable feedback for users when something goes wrong.

By checking the return value, you can provide meaningful error messages, implement fallback logic, or prevent downstream code from executing with invalid data.

Example

The following code discards the return value of a database read method:

Informs the user that there are missing permission to access tabledata (AC0031)

Mon, 01 Jan 0001 00:00:00 +0000

Whenever the code performs data access, the containing object should include the Permissions property to allow the user to run the code with indirect permissions.

This is especially important when the table access is restricted to indirect access trough the users license. For example indirect write on ledger entry tables, or indirect read on the table Sent Emails

Example

For procedure calls the following statements will raise this info:

// Insert
MyTable.Insert();

// Modify
MyTable.Modify();
MyTable.Rename();

// Read
MyTable.Find();
MyTable.FindFirst();
MyTable.FindLast();
MyTable.FindSet();
MyTable.IsEmpty();

// Delete
MyTable.Delete();
MyTable.DeleteAll();

On Reports and Queries each dataitem as to have read permissions