copyConfigRecordById

Creates a deep copy of a configuration record. This function can be used to duplicate entire records including their related child records. brixxbox uses the "Cascade Copy" flag of grid controls to determine which referenced records should be copied.

Syntax

app.copyConfigRecordById(configName, id, additionalValues)

Parameters

Parameter	Type	Description
configName	String	The name of the configuration (app) from which to copy the record
id	Number/String	The ID of the source record to be copied
additionalValues	Object	(Optional) JSON object containing field values to be modified in the target record

Return Value

Returns the newly created record object if the operation is successful, or null if unsuccessful or if the provided ID is invalid.

Description

The copyConfigRecordById method creates a complete copy of an existing record from a configuration, including related child records based on the "Cascade Copy" settings. It's particularly useful when you need to duplicate complex records with multiple related items, such as orders with order lines.

You can optionally provide an additionalValues object to modify specific fields in the copied record. This is useful for updating date fields, status fields, or any other field that should have different values in the copy.

Examples

Basic Copy

// Create an exact copy of order #1376
let newOrder = app.copyConfigRecordById("customerOrder", 1376);

Copy with Modified Values

// Copy order #1376 with today's date and reset quantities
let newOrder = app.copyConfigRecordById("customerOrder", 1376, {
    cordOrderDate: new Date(),
    cordlnOrderQuantity: "1",
    cordlnDeliveredQuantity: null
});

Copy and Display the New Record

// Inside an event handler like "onClick" of a "Duplicate" button
let productId = app.getFieldValue("selectedProductId");
let newProduct = app.copyConfigRecordById("product", productId);
    
if (newProduct) {
    // Load the newly created product
    app.loadAndDisplayRecordById(newProduct.id);
    app.showMessage("Product Duplicated", "A copy of the product has been created.");
}

Common Use Cases

• Duplicating complex business objects like orders, quotes, or invoices
• Creating templates from existing records
• Creating new versions of records while preserving the original
• Reusing existing data structures without manual data entry

Technical Details

• If the provided ID is null, empty, or '0', the method returns null without attempting to copy.
• Child records are copied based on "Cascade Copy" settings defined in the app designer.
• The new record will have a new unique ID assigned by the system.