BCCL Documentation
Index

Running Custom Codeunits

The RUNCODEUNIT task allows you to execute custom AL codeunits in Business Central directly from the BCCL command line or through Service Tasks. This provides an extensibility point for running custom business logic, maintenance routines, or specialized data processing that goes beyond the built-in BCCL operations.

Overview

BCCL includes several built-in tasks (GETDATA, PUTDATA, DELETEDATA, etc.), but sometimes you need to run custom logic. The RUNCODEUNIT task passes execution to a specified AL codeunit, giving it full access to the Business Central environment.

Basic Usage

Command Syntax

BCCL -t runcodeunit -s codeunit=50000

Parameters

Parameter Description
-t runcodeunit Specifies the RUNCODEUNIT task
-s codeunit=NNNNN The ID of the codeunit to execute

How It Works

When you run a codeunit through BCCL:

  1. BCCL sends a request to the BC web service specifying the codeunit number
  2. The BCCL Management codeunit routes the request to the RUNCODEUNIT handler
  3. The handler invokes the specified codeunit
  4. The codeunit receives the task context (the BCCL Request record) with all parameters
  5. The codeunit processes the request and can return data via the response
  6. BCCL receives and displays the response

Use Cases

Custom Data Processing

Run specialized data transformations or calculations that are not covered by standard BCCL operations:

BCCL -t runcodeunit -s codeunit=50100

Business Workflow Triggers

Trigger business processes such as:

  • Posting batches of documents
  • Running year-end procedures
  • Recalculating prices or discounts
  • Generating reports

Maintenance Routines

Execute maintenance operations:

  • Data cleanup procedures
  • Index rebuilding
  • Cache refreshing
  • Configuration updates

Custom Report Generation

Generate custom reports and retrieve the output through BCCL.

Upload and Download Tasks

BCCL provides two additional tasks that complement RUNCODEUNIT for scenarios involving binary data:

UPLOAD Task

The UPLOAD task sends binary data (files) to custom codeunits, reports, or XMLports in Business Central:

BCCL -t upload -i datafile.xlsx -s codeunit=50200

This is useful when your custom codeunit needs to process an uploaded file.

DOWNLOAD Task

The DOWNLOAD task retrieves binary output (such as generated reports or files) from completed Service Tasks:

BCCL -t download -s taskid=MYTASK-001 -o report.pdf

The object type and output format are configured on the Service Task:

Setting Options
Object Type Report, Codeunit, XMLport, Query
Output Type PDF, CSV, XML, HTML, Excel, Word

Extending BCCL with Custom Task Types

Beyond running individual codeunits, you can register entirely new task types in BCCL by subscribing to the OnRegisterExtraTaskType integration event.

Registration

In your custom AL extension, subscribe to the initialization event:

[EventSubscriber(ObjectType::Codeunit, Codeunit::"BCCL Initialization Hgd", 'OnRegisterExtraTaskType', '', false, false)]
local procedure RegisterMyTask(var BCCLRequestTask: Record "BCCL Request Task Hgd")
begin
    BCCLRequestTask.Init();
    BCCLRequestTask.Task := 'MYCUSTOMTASK';
    BCCLRequestTask.Description := 'My Custom Task';
    BCCLRequestTask.Codeunit := 50300;
    BCCLRequestTask.Parameters := 'param1,param2';
    if BCCLRequestTask.Insert() then;
end;

Using Custom Tasks

Once registered, your custom task appears in the BCCL task list and can be invoked like any built-in task:

BCCL -t mycustomtask -s param1=value1 param2=value2

Integration Events

BCCL exposes several integration events that you can subscribe to for extending functionality:

Event Purpose
OnBeforePutData Custom logic before data import
OnAfterPutData Custom logic after data import
OnBeforeInsertRecord Modify records before insertion
OnAfterInsertRecord Post-processing after insertion
OnBeforeModifyRecord Modify records before update
OnAfterModifyRecord Post-processing after update
OnFunctionCall Handle custom mapping functions
OnRegisterExtraTaskType Register new task types

These events allow you to extend BCCL behavior without modifying the core extension.

Service Task Configuration

To run codeunits through Service Tasks (instead of CLI):

  1. Create a new Service Task
  2. Set Task to the desired operation
  3. Set Object Type to Run to Codeunit
  4. Set Object No. to your codeunit ID
  5. Assign an agent
  6. Set status to Ready

The agent will execute the codeunit and report results back to BC.

Tips and Best Practices

  • Test custom codeunits thoroughly in a sandbox environment before production use
  • Use meaningful return values so BCCL can report success or failure
  • Log important operations within your codeunit for audit trail
  • Use the upload/download tasks for file-based operations
  • Register custom task types for operations that will be used repeatedly
  • Subscribe to integration events for lightweight customizations that do not need a full custom task