Record handlers

A record handler enables customizations for a specific table of an internal document through interfaces.

The following interfaces expose data manipulation when a RECORDGENERATOR activity runs:

Default record handlers

Three record handlers are available out of the box:

Create a custom Record Handler

Usage

Use this task when you want to override one or more triggers that run during record generation.

Prerequisites

The following prerequisites are required:

• Experience developing in Microsoft Dynamics 365 Business Central AL.

• Basic understanding of Business Integration Solutions.

• A development license.

Steps

1. Create a new codeunit and implement one to five interfaces:

   codeunit 50000 YourCustomHandler implements BISIOnBeforeProcessRecord, BISIOnInsertRecord, BISIOnModifyRecord, BISIOnDeleteRecord, BISIOnAfterProcessRecord
   {
       var
           // All procedures required by the implemented interfaces must be created.
           // If you only need to hook into OnInsert, put your logic there and let the
           // Base Connector handle the rest.
           BaseConnector: Codeunit "TIC Table Connector Base"
       procedure OnBeforeProcessRecord(var Rec: RecordRef): Boolean
       begin
           exit(BaseConnector.OnBeforeProcessRecord(rec));
       end;
       procedure OnInsertRecord(var Rec: RecordRef): Boolean
       begin
           // Add your logic for inserting a record here.
           Rec.Field(YourTable.FieldNo(YourFieldNumber)).Value('New value');
           exit(BaseConnector.OnInsertRecord(rec));
       end;
       procedure OnModifyRecord(var Rec: RecordRef): Boolean
       begin
           exit(BaseConnector.OnModifyRecord(rec));
       end;
       procedure OnDeleteRecord(var Rec: RecordRef): Boolean
       begin
           exit(BaseConnector.OnDeleteRecord(Rec));
       end;
   }
   

2. Create an enum extension that extends BISRecordHandler. If you already have one, skip to the next step:

   enumextension 50000 YourEnumExtension extends BISRecordHandler
   {
       ...
   }
   

3. Add a new value in the enum extension that references your custom handler from step 1:

   enumextension 50000 YourEnumExtension extends BISRecordHandler
   {
       value(YourCustomHandlerId; YourCustomHandler)
       {
           Implementation =
               BISIOnBeforeProcessRecord = YourCustomHandler,
               BISIOnInsertRecord = YourCustomHandler,
               BISIOnModifyRecord = YourCustomHandler,
               BISIOnDeleteRecord = YourCustomHandler,
               BISIOnAfterProcessRecord = YourCustomHandler;
       }
   }
   

   Note

   You can also mix and match, use a combination of the custom handler and the base connector. This way you only implement the needed interfaces, and the base connector handles the rest by default. See the example below.

   // Enum extension example
   value(YourCustomHandlerId; YourCustomHandler)
   {
       Implementation =
           BISIOnBeforeProcessRecord = YourCustomHandler,
           BISIOnInsertRecord = "BIS RecordHandler",
           BISIOnModifyRecord = "BIS RecordHandler",
           BISIOnDeleteRecord = "BIS RecordHandler",
           BISIOnAfterProcessRecord = YourCustomHandler;
   }
   // Codeunit handler example
   codeunit 50000 YourCustomHandler implements BISIOnBeforeProcessRecord, BISIOnAfterProcessRecord
   {
       procedure OnBeforeProcessRecord(var RecRef: RecordRef): Boolean
       begin
           // Execute your logic here.
       end;
       procedure OnAfterProcessRecord(var RecRef: RecordRef): Boolean
       begin
           // Execute your logic here.
       end;
   }
   

4. Go to your Record Generator activity setup page and select the Design action for the linked document.

5. On the document design page, select the table node where you want to use the new record handler.

   

Upgrading custom connectors

The following is an example of a legacy custom connector with the OnInsertRecord hook:

codeunit 50000 "DemoCustomConnector"
{
    procedure OnInsertRecord(var Rec: Item): Boolean
    begin
        // Your custom logic
    end
}

To upgrade this connector:

1. Make the custom connector implement BISIOnInsertRecord.

2. Implement the OnInsertRecord(var RecRef: RecordRef) procedure by calling the legacy OnInsertRecord(var Rec: Item), or calling the default BISRecordHandler if the table is not supported by your logic:

   codeunit 50000 DemoCustomConnector implements BISIOnInsertRecord
   {
       procedure OnInsertRecord(var RecRef: RecordRef): Boolean
       var
           Rec: Record Item;
           Result: Boolean;
       begin
           if RecRef.Number() <> Database::Item then
               exit(BISRecordHandler.OnInsertRecord(RecRef));
           RecRef.SetTable(Rec);
           Result := OnInsertRecord(Rec);
           RecRef.GetTable(Rec);
           exit(Result);
       end;
       procedure OnInsertRecord(var Rec: Item): Boolean
       begin
           // Your custom logic
       end
   }
   

   Note

   Make sure to update RecRef again before exiting, using the RecRef.GetTable procedure.

3. Add the codeunit to an enum extension extending BISRecordHandler:

   enumextension 50000 "DemoRecordHandler" extends BISRecordHandler
   {
       value(50000; DemoHandler)
       {
           Caption = 'Demo Record Handler';
           Implementation = BISIOnBeforeProcessRecord = "BIS RecordHandler",
                        BISIOnInsertRecord = DemoCustomConnector,
                        BISIOnModifyRecord = "BIS RecordHandler",
                        BISIOnDeleteRecord = "BIS RecordHandler",
                        BISIOnAfterProcessRecord = "BIS RecordHandler";
       }
   }
   

   Note

   One codeunit can implement several interfaces.

Also see the Custom Connector approach