BCCL Documentation
Index

Mass Update

The MASSUPDATE task lets you apply the same set of field values to multiple records in a single operation. Instead of importing a file with one row per record, you provide a single row of values and a view filter that selects which records to update. BCCL then iterates through every matching record and applies your values to each one.

When to Use Mass Update

Mass update is ideal when you need to change one or more fields to the same value across a batch of records. Common scenarios include:

  • Changing posting groups -- Reassigning Customer Posting Group or General Business Posting Group for a range of customers.
  • Updating status fields -- Setting a blocked status, a classification code, or a responsibility center across many records at once.
  • Bulk corrections -- Fixing data entry errors where the same wrong value was applied to a set of records.
  • Standardizing data -- Applying a default value to records that are missing a particular field value.

If you need to apply different values to each record, use the PUTDATA task instead.

How It Works

The MASSUPDATE task combines three inputs:

  1. A view filter (-s view=...) that selects which records to update.
  2. An input file (-i) containing exactly one record with the field values to apply.
  3. A mapping file (-m) that maps input columns to Business Central fields.

BCCL reads the single record from your input file, finds all records matching the view filter, and modifies each one by assigning the values from your input record.

Required Parameters

Parameter Description
-t massupdate Specifies the MASSUPDATE task
-s table=N The Business Central table number to update
-s view=WHERE(...) A view filter selecting which records to update
-i filename Path to the input file containing exactly one data record
-m mapping.json Path to the mapping file

All three settings parameters, the input file, and the mapping file are mandatory. BCCL will return an error if any of them are missing.

Preparing the Input File

The input file for MASSUPDATE must contain exactly one data record. This is the critical difference from PUTDATA, which can contain many records. If your input file contains more than one record, BCCL will reject it with an error:

MASSUPDATE can only be called with a single record in the dataset.

CSV Example

Create a CSV file named massupdate.csv with a header row and a single data row:

postgrp,genbus
"DOMESTIC","STANDARD"

This file defines two values: a posting group column mapped to "DOMESTIC" and a general business posting group column mapped to "STANDARD".

JSON Example

You can also use a JSON input file. The JSON array must contain exactly one object:

[
  {
    "postgrp": "DOMESTIC",
    "genbus": "STANDARD"
  }
]

Creating the Mapping File

The mapping file tells BCCL which Business Central fields correspond to your input columns. You can generate a starting mapping file with the MAPPING task and then edit it to include only the fields you want to update.

Example Mapping File

[
  {
    "FieldNo": 21,
    "FieldName": "Customer Posting Group",
    "MappedName": "postgrp",
    "Validate": true
  },
  {
    "FieldNo": 54,
    "FieldName": "Gen. Bus. Posting Group",
    "MappedName": "genbus",
    "Validate": true
  }
]

Mapping File Fields

Field Description
FieldNo The Business Central field number
FieldName The field name (for your reference, not used by BCCL)
MappedName The column name in your input file that maps to this field
Validate When true, BCCL calls the field's Validate trigger after assignment
CreateRelatedStub When true, auto-creates a stub record if the related table value does not exist
Function An optional function expression for computed values

Validation Settings

Setting "Validate": true on a field ensures that Business Central validation logic runs when the value is assigned. This is important for fields where changing the value triggers downstream logic, such as posting groups that recalculate related setup records.

If validation is not needed and you want a simple value assignment, set "Validate": false or omit the property.

Running a Mass Update

Basic Command

bccl -t massupdate -s table=18 "view=where(No.=filter(C007*))" -i massupdate.csv -m mass-map.json

This command:

  1. Targets the Customer table (table 18).
  2. Selects all customers whose No. starts with C007.
  3. Reads the single-record input from massupdate.csv.
  4. Uses mass-map.json to map CSV columns to Business Central fields.
  5. Applies the values from the input record to every matching customer.

Understanding the Response

When the operation completes, BCCL returns a JSON response indicating how many records were updated:

{
  "Table": 18,
  "Updated": 10
}

The Updated count reflects how many records were successfully modified. If a record cannot be modified (for example, due to a validation error when ValidateOnModify is active), it is skipped and not included in the count.

Advanced Options

Using Functions in the Mapping

You can use function expressions in your mapping file to compute values dynamically rather than reading them from the input file. For example, the DimensionFromSet() function can update dimension values:

{
  "FieldNo": 480,
  "FieldName": "Dimension Set ID",
  "MappedName": "Department",
  "Function": "dimensionfromset(DEPARTMENT)"
}

Validate on Modify

By default, BCCL uses the ValidateOnModify setting from the request record. If your Business Central logic requires that the OnModify trigger fires for each updated record, ensure this is enabled. You can control this behavior through the request configuration.

Stub Record Creation

If your mass update changes a field that references another table (such as changing a Customer Posting Group to a value that does not yet exist), you can set "CreateRelatedStub": true in the mapping. BCCL will automatically create a minimal stub record in the related table before assigning the value.

Step-by-Step Example

This example updates the Customer Posting Group and General Business Posting Group for all customers in the C007 number series.

Step 1: Generate a Mapping File

bccl -t mapping -s table=18 -o customer-mapping.json

Step 2: Edit the Mapping File

Open customer-mapping.json and keep only the fields you want to update. Rename the MappedName values to short, convenient column names:

[
  {
    "FieldNo": 21,
    "FieldName": "Customer Posting Group",
    "MappedName": "postgrp",
    "Validate": true
  },
  {
    "FieldNo": 54,
    "FieldName": "Gen. Bus. Posting Group",
    "MappedName": "genbus",
    "Validate": true
  }
]

Step 3: Create the Input File

Create massupdate.csv with exactly one data row:

postgrp,genbus
"DOMESTIC","STANDARD"

Step 4: Run the Mass Update

bccl -t massupdate -s table=18 "view=where(No.=filter(C007*))" -i massupdate.csv -m mass-map.json

Step 5: Verify the Result

The response confirms how many records were updated:

{
  "Table": 18,
  "Updated": 10
}

Safety Considerations

Mass updates modify live data and cannot be automatically undone. Follow these practices to minimize risk:

  • Use specific filters. Always craft your view filter to target only the intended records. Avoid overly broad filters that could match records you did not intend to change.
  • Test with a narrow filter first. Before running a mass update on a large set, test with a filter that matches just one or two records. Verify the results in Business Central before expanding the filter.
  • Enable validation. Set "Validate": true on fields where Business Central logic should run. This catches invalid values before they are written.
  • Back up your data. For large-scale updates, consider exporting the current values with the GETDATA task before running the update. This gives you a reference to restore from if needed.
  • Review the Updated count. Compare the returned Updated count against the number of records you expected to change. A mismatch may indicate that some records were skipped due to errors.

Integration Events

For AL developers, the MASSUPDATE codeunit publishes several integration events that let you hook into the mass update process:

Event When It Fires
OnBeforeMassUpdateData Once, before any records are processed
OnBeforeMassUpdateRecord Before each individual record is updated
OnBeforeModifyRecord Immediately before Ref.Modify() is called
OnAfterModifyRecord Immediately after a successful Ref.Modify()
OnAfterMassUpdateRecord After each individual record is processed
OnAfterMassUpdateData Once, after all records have been processed

These events allow you to add custom validation, logging, or additional processing logic around the mass update.

Tips and Best Practices

  • Keep your input file to exactly one record. If you need to apply different values to different records, use PUTDATA instead.
  • Always generate your mapping file from the MAPPING task and then trim it down, rather than writing it from scratch. This ensures accurate field numbers.
  • Use verbose mode (-v) when troubleshooting to see detailed request and response information.
  • For critical data, run a GETDATA export before the mass update so you have a backup of the original values.