Custom Actions

Custom Actions (Action Type 8, Enum Value 8) provide extensibility for scenarios that require custom AL code execution when business rules trigger. While most business requirements can be satisfied using the built-in action types (Error, Message, Email, Assign, etc.), some organizations have unique requirements that demand custom programming logic. Custom Actions bridge the gap between no-code business rule configuration and full-code AL development by allowing developers to write AL code that executes automatically when specific business rule conditions occur. This section explains when Custom Actions are appropriate, how developers implement them, and how administrators configure them.

15.1 When to Use Custom Actions

Custom Actions are appropriate when business requirements cannot be satisfied using standard action types and require custom programming logic.

Appropriate Use Cases for Custom Actions

Complex Calculations Beyond Formula Capabilities: When validation or automation logic requires calculations that cannot be expressed in QUALIA Rule Engine formulas (for example, iterative algorithms, recursive calculations, statistical functions, or complex mathematical models), Custom Actions allow developers to implement the logic in AL code.

Integration with External Systems via APIs: When business rules should trigger API calls to external systems (for example, sending data to CRM platforms, querying external inventory systems, submitting transactions to payment gateways, or triggering external approval workflows), Custom Actions provide the integration point.

Multi-Step Database Operations: When business requirements involve complex multi-step database operations across multiple tables with transaction management, error handling, and rollback logic, Custom Actions provide the control and flexibility needed.

Custom Validation Logic with External Dependencies: When validation requires accessing external resources, files, web services, or databases beyond Business Central, Custom Actions enable these integrations.

Specialized Business Logic Unique to Your Organization: When your organization has proprietary algorithms, specialized industry calculations, or unique business logic that represents competitive advantage or intellectual property, Custom Actions keep this logic encapsulated in AL code.

When NOT to Use Custom Actions

Requirements Satisfied by Standard Actions: If the requirement can be met using Message, Error, Email, Assign, or other standard action types, use the standard action rather than Custom Actions. Standard actions are easier to configure, easier to maintain, and less likely to cause technical problems.

Simple Field Assignments or Calculations: Custom Actions require developer involvement and AL code maintenance. If the requirement is simply assigning field values or performing calculations, use Assign actions instead.

One-Time or Infrequent Requirements: Custom Actions require development effort. If the requirement occurs rarely or represents a one-time need, consider whether manual processing or alternative approaches would be more cost-effective than custom development.

15.2 Prerequisites for Custom Actions

Permission Set Requirement

Users or user groups must be assigned the QUA Advanced Workflow UnLicensed permission set. This permission set grants the necessary permissions to execute Custom Actions. Without this permission set, Custom Actions will not execute even if the business rule and AL code are configured correctly.

Developer Requirements

Implementing Custom Actions requires:

• AL development skills and Business Central extension development knowledge

• Access to Business Central development environment (Visual Studio Code with AL Language extension)

• Understanding of event subscriber patterns in AL

• Knowledge of Business Central table structures and business logic

• Testing and debugging capabilities

Deployment Requirements

Custom Action AL code must be:

• Packaged as a Business Central extension (.app file)

• Deployed to the Business Central environment

• Compiled and published successfully

Without proper deployment, Custom Actions will fail silently when business rules attempt to execute them.

15.3 Developer Guide: Implementing OnCustomAction Event Subscribers

This section provides guidance for AL developers implementing Custom Action logic.

Event Subscription Pattern

QUALIA Rule Engine publishes an OnCustomAction event when Custom Actions execute. Developers create event subscriber codeunits that listen for this event and execute custom logic.

Event Signature (Conceptual - verify exact signature in QUALIA Rule Engine codeunits):

[IntegrationEvent(false, false)]
procedure OnCustomAction(
    ActionCode: Code[20];
    RecRef: RecordRef;
    var Handled: Boolean;
    var ErrorText: Text
);

Parameters:

• ActionCode: The custom action code configured in the business rule. Allows one subscriber to handle multiple custom actions by checking the ActionCode parameter.

• RecRef: A RecordRef containing the trigger record (the record that caused the business rule to execute). Provides access to all field values.

• Handled: Boolean that the subscriber sets to TRUE if it successfully handled the action. If FALSE, QUALIA Rule Engine may log an error or warning.

• ErrorText: If the custom logic encounters errors, populate this text variable with an error message. QUALIA Rule Engine may display this message to users.

Example Event Subscriber Implementation:

codeunit 50100 "Custom Action Handler"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"QUA Check Validations", 'OnCustomAction', '', false, false)]
    local procedure HandleCustomAction(
        ActionCode: Code[20];
        RecRef: RecordRef;
        var Handled: Boolean;
        var ErrorText: Text)
    var
        SalesHeader: Record "Sales Header";
        Customer: Record Customer;
        CreditCheckResult: Boolean;
    begin
        // Handle specific custom action codes
        case ActionCode of
            'CREDIT_CHECK':
                begin
                    // Get the trigger record (Sales Header)
                    RecRef.SetTable(SalesHeader);
                    
                    // Perform custom credit check logic
                    if Customer.Get(SalesHeader."Sell-to Customer No.") then begin
                        CreditCheckResult := PerformExternalCreditCheck(Customer);
                        
                        if not CreditCheckResult then begin
                            ErrorText := 'External credit check failed. Cannot proceed with order.';
                            Handled := true;
                            exit;
                        end;
                    end;
                    
                    Handled := true;
                end;
                
            'API_NOTIFY':
                begin
                    // Call external API
                    SendAPINotification(RecRef);
                    Handled := true;
                end;
        end;
    end;
    
    local procedure PerformExternalCreditCheck(Customer: Record Customer): Boolean
    begin
        // Implementation of external credit check API call
        // Returns true if credit check passes
    end;
    
    local procedure SendAPINotification(RecRef: RecordRef)
    begin
        // Implementation of API notification
    end;
}

Best Practices for Custom Action Implementation:

1. Check ActionCode: Always check the ActionCode parameter to ensure your code only executes for actions it is designed to handle.

2. Set Handled: Always set Handled := true when your code successfully processes the action. This confirms to QUALIA Rule Engine that the action executed.

3. Provide Error Messages: If your custom logic detects errors, populate ErrorText with clear, actionable messages for users.

4. Handle Exceptions: Wrap custom logic in try-catch blocks (AL error handling) to prevent unhandled exceptions from crashing business rule execution.

5. Performance Optimization: Custom Actions execute synchronously during transaction processing. Ensure your code executes quickly to avoid user experience problems. If processing is time-intensive, consider asynchronous patterns (job queue entries, background processing).

6. Logging: Implement comprehensive logging within your custom action code to facilitate troubleshooting when problems occur.

15.4 Configuring Custom Actions in Business Rules

Once developers have implemented and deployed custom action event subscribers, administrators can configure business rules to execute those custom actions.

Step 1: Create or Open the Business Rule

1. Navigate to the Business Rules page in Business Central

2. Open the Business Rule Set that should trigger custom AL code

3. Create a new Business Rule or open an existing rule

4. Configure the Condition that determines when the custom action should execute

Step 2: Add a New Custom Action

1. In the Actions section of the Business Rule, create a new action line

2. Set the Action Type field to Custom Actions (this is Action Type 8 in the enum)

3. The new action line is now configured to execute custom AL code when the condition evaluates to TRUE

Step 3: Specify the Action Code

1. In the action line, locate the Action Code field

2. Enter the action code that matches the ActionCode your developer implemented in the event subscriber (for example, CREDIT_CHECK or API_NOTIFY)

3. This code links the business rule to the specific custom logic in the AL codeunit

Step 4: Optional Action Details

Some Custom Action implementations may support additional configuration parameters. If your developer has implemented such functionality:

1. Open the Custom Action Detail card by selecting the Action Code field

2. Enter any configuration values or parameters your custom logic requires

3. Consult with your developer to understand what configuration options are available

Step 5: Test Thoroughly

1. Test in sandbox environment

2. Verify the custom AL code executes when the condition is TRUE

3. Verify the custom logic behaves as expected

4. Monitor for errors or exceptions

5. Verify transaction processing completes successfully

15.5 Example Integration Scenarios

Scenario 1: External Credit Bureau Integration

Requirement: Before allowing high-value sales orders, automatically query an external credit bureau API to verify customer creditworthiness.

Implementation:

• Business Rule Condition: [36:61] is >25000 (Order amount > $25,000)

• Custom Action Code: CREDIT_BUREAU_CHECK

• AL Implementation:

  • Extracts customer information from Sales Header

  • Calls credit bureau API with customer details

  • Parses API response

  • If credit rating insufficient, sets ErrorText to block transaction

  • Logs results to custom audit table

Scenario 2: Automated Inventory Reservation in External Warehouse

Requirement: When sales orders are created, automatically reserve inventory in an external warehouse management system via API.

Implementation:

• Business Rule Condition: [36:1] is '1' (Document Type = Order)

• Custom Action Code: WMS_RESERVE

• AL Implementation:

  • Iterates through sales lines

  • Calls warehouse API to reserve quantities for each item

  • Updates custom fields with reservation IDs

  • If reservation fails, displays error message

Scenario 3: Complex Regulatory Compliance Calculation

Requirement: Validate purchase orders against complex regulatory requirements involving multiple tables, date calculations, and industry-specific formulas.

Implementation:

• Business Rule Condition: [38:10] is 'REGULATED' (Item category = Regulated)

• Custom Action Code: REGULATORY_CHECK

• AL Implementation:

  • Executes multi-step compliance algorithm

  • Queries multiple related tables

  • Performs date-based eligibility calculations

  • Generates compliance score

  • Blocks transaction if compliance requirements not met

15.6 Maintenance and Support Considerations

Documentation Requirements

For each Custom Action implementation, maintain documentation:

• What the custom action does (business purpose)

• What ActionCode it responds to

• What tables and fields it accesses

• What external systems it integrates with (if applicable)

• What error conditions it handles

• Who developed it and when

• How to troubleshoot problems

Version Control

Custom Action AL code should be maintained in source control (for example, Git repositories) to track changes, enable rollback if problems occur, and facilitate team collaboration.

Testing and Deployment

Custom Actions require standard AL development lifecycle practices:

• Unit testing of custom logic

• Integration testing with business rules

• Sandbox testing before production deployment

• Deployment procedures for extensions

• Rollback procedures if problems occur

Monitoring and Troubleshooting

Monitor Custom Action execution:

• Review Validation Log for Custom Action executions

• Implement logging within AL code

• Watch for error patterns

• Monitor performance impact

• Be prepared to disable business rules if custom actions cause problems