Erik's ToolBox Documentation
Index

Batch Processing Usage

Introduction

This guide walks you through each step of the batch processing wizard in Erik's ToolBox for Business Central. The wizard is a seven-step process (Steps 0 through 6) that guides you from initial setup through to execution. By following these instructions, you can perform bulk data modifications safely and efficiently without writing custom code.

Before you begin, ensure that you have the SUPER role assigned to your user account. Without this permission level, you will not be able to access the batch processing wizard or execute any batch processes.

Accessing the Wizard

To open the batch processing wizard, navigate to the Batch Processing page in Business Central. You can reach this page through the Erik's ToolBox menu or by searching for "Batch Processing" in the Business Central search bar.

Once the page opens, you are at Step 0 and ready to begin configuring your batch process.

Step 0: Welcome

What You See

The welcome page displays the current company context and provides an introduction to the batch processing workflow. You will see the company name prominently displayed so you can confirm you are working in the correct environment.

What Actions Are Available

  • Confirm the company context and proceed to Step 1.
  • Review the company name to ensure you are not accidentally working in a test or production environment when you intend to be in the other.

What to Configure

There is no configuration required at this step. Your primary task is to verify that the company displayed is the one where you want to make changes.

Tips and Warnings

  • Always double-check the company name before proceeding. Batch processing changes are applied to the company shown on this page, and modifying records in the wrong company can have significant consequences.
  • If you need to switch companies, close the wizard, change your company context in Business Central, and reopen the wizard.

Step 1: Select Table

What You See

Step 1 presents you with a list of available tables in your Business Central environment. You can browse or search through the tables to find the one that contains the records you want to modify.

What Actions Are Available

  • Browse the list of tables.
  • Search for a specific table by name or number.
  • Select the table you want to work with and proceed to Step 2.
  • Go back to Step 0 if you need to change the company context.

What to Configure

Select the target table for your batch process. This is the table whose records you will be filtering and modifying in the subsequent steps. The table selection is stored in the Batch Processing table as part of the process configuration.

Tips and Warnings

  • Make sure you select the correct table before proceeding. While you can go back and change it later, doing so will reset any filters or field selections you have already configured.
  • If you are unsure which table contains the data you want to modify, use the Business Central page inspection tool (Ctrl+Alt+F1) on the relevant page to identify the source table.
  • Some system tables may not be suitable for batch modifications. Exercise caution when selecting tables that are critical to system operations.

Step 2: Apply Filters

What You See

The filter configuration page shows the fields available in the table you selected in Step 1. You can define one or more filter conditions to narrow down the records that will be affected by the batch process. A record count is displayed so you can see how many records match your current filter criteria.

What Actions Are Available

  • Add filter conditions on any field in the selected table.
  • Combine multiple filters to create precise selection criteria.
  • Preview the record count to verify your filters are targeting the correct set of records.
  • Clear filters to start over.
  • Proceed to Step 3 or go back to Step 1.

What to Configure

Define the filter criteria that determine which records will be included in the batch process. Filter definitions are stored in the Batch Processing Filters table. You can filter on any field in the selected table using standard Business Central filter syntax, including:

  • Exact values (e.g., DOMESTIC)
  • Ranges (e.g., 10000..20000)
  • Wildcards (e.g., SALES)
- Multiple values (e.g., `10000 20000 30000`)
  • Not equal (e.g., <>BLOCKED)

Tips and Warnings

  • Always check the record count after applying filters. If the count is higher or lower than expected, review your filter criteria carefully.
  • Use the preview to verify that the filtered records are the ones you actually want to modify. A small mistake in a filter can lead to unintended changes across many records.
  • When in doubt, start with more restrictive filters and gradually broaden them. It is safer to process fewer records correctly than to accidentally include records that should not be changed.
  • If you are working with a large table, complex filters may take a moment to evaluate. Be patient while the record count updates.

Step 3: Select Fields

What You See

The field selection page displays the fields available in the table you selected in Step 1. You can choose one or more fields that you want to modify as part of the batch process.

What Actions Are Available

  • Browse the list of available fields for the selected table.
  • Select the field or fields you want to modify.
  • Review the data type and current properties of each field.
  • Proceed to Step 4 or go back to Step 2.

What to Configure

Choose the specific field or fields that will be updated by the batch process. The fields you select here will be the ones for which you define new values in Step 4.

Tips and Warnings

  • Be deliberate about which fields you select. Modifying primary key fields or fields that participate in table relations can have cascading effects throughout the system.
  • If you are modifying a field that has validation logic (such as a field that triggers OnValidate code), be aware that the batch process may invoke that logic for each record. This can affect performance and may trigger side effects.
  • Consider the data type of the field you are selecting. The replacement values you define in Step 4 must be compatible with the field's data type.

Step 4: Set Values

What You See

The value configuration page shows the fields you selected in Step 3 and provides input areas where you can define the new values or replacement rules for each field.

What Actions Are Available

  • Enter the new value for each selected field.
  • Define replacement rules if you are performing a find-and-replace operation.
  • Review the current values and the proposed new values side by side.
  • Proceed to Step 5 or go back to Step 3.

What to Configure

For each field you selected in Step 3, define what the new value should be after the batch process runs. Depending on the field type and the nature of your change, you may:

  • Set a fixed value that will be applied to all matching records.
  • Define a replacement pattern where a specific existing value is replaced with a new value.
  • Specify a blank value to clear the field across all matching records.

Tips and Warnings

  • Verify that the values you enter are valid for the field's data type. Entering a text value for a numeric field, or a value that exceeds the field's maximum length, will cause errors during execution.
  • If you are replacing a value rather than setting a fixed value, make sure the replacement pattern is specific enough to avoid unintended matches.
  • Consider the impact of the new values on downstream processes. For example, changing a posting group field may affect how transactions are posted in future operations.
  • If you need to apply complex transformation logic that cannot be expressed as a simple value replacement, consider using the advanced AL code approach described later in this guide.

Step 5: Preview

What You See

The preview page displays a summary of the batch process you have configured. You can see the target table, the applied filters, the fields being modified, and the proposed new values. The page also shows the records that will be affected, allowing you to verify the changes before committing them.

What Actions Are Available

  • Review the complete configuration of the batch process.
  • Inspect individual records that will be affected.
  • Verify the before-and-after values for each field being modified.
  • Proceed to Step 6 to execute the process.
  • Go back to any previous step to make adjustments.

What to Configure

There is no additional configuration at this step. This is a review-only step designed to give you confidence that the batch process is set up correctly.

Tips and Warnings

  • Take your time reviewing the preview. This is your last opportunity to catch mistakes before changes are applied to your data.
  • Pay close attention to the record count and the proposed changes. If anything looks unexpected, go back to the relevant step and make corrections.
  • If the number of affected records is large, consider running a smaller test batch first by applying more restrictive filters. After verifying the results, you can then run the full batch.
  • Check that you are comfortable with the scope of changes. Once you proceed to Step 6 and execute the process, the changes will be applied immediately.

Step 6: Execute

What You See

The execution page provides the final confirmation prompt and, once you confirm, displays the progress of the batch process as it runs. You can see how many records have been processed, how many remain, and whether any errors have occurred.

What Actions Are Available

  • Confirm and execute the batch process.
  • Monitor progress as the process runs.
  • Review the results after execution completes.

What to Configure

No additional configuration is needed. You simply confirm that you want to proceed, and the system executes the batch process using the configuration you defined in the previous steps.

Tips and Warnings

  • Once you confirm execution, the process begins immediately. There is no pause or undo button during execution.
  • For large record sets, the process may take several minutes. Do not close the page or navigate away while the process is running.
  • After execution completes, review the results summary to confirm that the expected number of records were modified.
  • All changes are recorded in the Batch Processing History table and individual record modifications are logged for audit purposes. You can review these records on the Batch Processing History page.

Advanced Usage

Using AL Code with SetLibrarySource()

For complex transformations that go beyond simple value replacements, you can provide custom AL code to the batch processing engine using the SetLibrarySource() function. This function accepts AL code as a parameter and passes it to the Batch Processing Management codeunit for execution.

When you use SetLibrarySource(), the batch processing engine applies your custom code to each record that matches the filters defined in Step 2. This allows you to implement conditional logic, perform calculations, look up values from related tables, and handle other complex scenarios that the standard wizard steps cannot accommodate.

After configuring the AL code with SetLibrarySource(), you call RunTheProcess() to execute the batch process. The execution follows the same safety protocols as a standard wizard run, including history tracking and record-level logging.

When to Use AL Code

Consider using SetLibrarySource() when:

  • The new value depends on a calculation involving other fields in the same record.
  • You need to look up values from a different table to determine the correct replacement.
  • The transformation logic varies based on conditions that cannot be expressed with simple filters and fixed values.
  • You need to update multiple related fields in a coordinated manner.
  • The change involves formatting, parsing, or other string manipulation operations.

Best Practices for AL Code

  • Test your AL code on a small subset of records before running it against the full dataset.
  • Include error handling in your code to gracefully manage records that cannot be processed.
  • Keep your code focused on the transformation logic. The batch processing engine handles record iteration, filtering, and history logging.
  • Document your code so that other administrators can understand what the transformation does if they review the history later.

Combining Filters for Precise Record Selection

The filter system in Step 2 supports combining multiple filter conditions to create highly specific record selections. You can filter on any combination of fields in the selected table, and the filters are applied using AND logic, meaning a record must match all filter conditions to be included.

For example, if you want to update records where the customer posting group is "DOMESTIC" and the balance is greater than zero, you would apply a filter on the customer posting group field with the value DOMESTIC and a filter on the balance field with the value >0.

You can also use the standard Business Central filter operators to create more nuanced selections:

- Use the pipe character (` `) to match any of several values on the same field.
  • Use the range operator (..) to select records within a numeric or date range.
  • Use the wildcard character (*) for partial text matching.
  • Combine these operators within a single filter to create precise criteria.

Running in a Specific Company Context

Batch processing always runs in the company context that is active when you open the wizard. If you need to perform batch processing in multiple companies, you must close the wizard, switch to the target company in Business Central, and reopen the wizard for each company.

This design is intentional. By requiring you to explicitly confirm the company context in Step 0, the wizard reduces the risk of accidentally modifying data in the wrong company. If you are performing the same batch process across multiple companies, consider documenting your filter and value settings so you can quickly reconfigure the wizard for each company.

Troubleshooting

The Wizard Does Not Open

If you cannot access the Batch Processing page, verify that you have the SUPER role assigned to your user account. Without this role, the page will not be accessible.

Filters Return Unexpected Record Counts

If the record count in Step 2 does not match your expectations, review each filter condition carefully. A common mistake is applying a filter on the wrong field or using incorrect filter syntax. Clear all filters and reapply them one at a time to identify which filter is causing the discrepancy.

Execution Takes Too Long

For very large record sets, execution may take significant time. If the process appears to be running slowly, consider whether the table has validation triggers that are being invoked for each record. You may also want to break the batch process into smaller batches by applying more restrictive filters and running multiple passes.

Errors During Execution

If errors occur during execution, the process will log the errors and continue with the remaining records where possible. After execution completes, review the history and error logs to identify which records could not be processed and why.