Skip to content

Sample Dynamic Mapping Codeunit

Codeunit 5138174 "SIM_DPS Sample Dyn. Mapping CU" demonstrates how custom AL logic can provide a value to a Simova CORE data mapping used by Business Portals.

The codeunit uses SIM_CORE Temp Table as its source table. The data-mapping engine passes the execution context through this temporary record, runs the selected function, and consumes the value written to Dyn Mapping Return Value.

When to use a mapping codeunit

A normal data-mapping line obtains a value from a field, constant, filter, or predefined function. Use a line of type CODEUNIT when the returned value requires custom AL logic, for example:

  • Combining values from multiple records.
  • Applying business-specific calculations or formatting.
  • Resolving a value that cannot be expressed through standard mapping lines.
  • Returning a portal-specific label or status derived from the source record.

For an introduction to creating mapping headers and lines, see Creating Data Mappings.

Function discovery and dispatch

When the parameter lookup runs the codeunit, Rec.Param is empty. OnRun therefore uses GETFUNCTIONS and returns Execute in Rec."Function List".

AL
'GETFUNCTIONS':
    Rec."Function List" := 'Execute';

During normal mapping execution, CORE copies the configured Execute Codeunit Param into Rec.Param. The sample dispatches the value Execute to its public Execute procedure.

To provide additional functions, add each function name to the comma-separated Function List and add a matching branch to the case statement.

Execution context

The relevant SIM_CORE Temp Table fields are:

Field Purpose
RecID Identifies the source record for the current mapping execution.
Company Identifies the Business Central company in which the mapping is evaluated.
Param Contains the configured function name, such as Execute.
Function List Returns the functions offered by the codeunit during setup.
Dyn Mapping Return Value Returns the result to the mapping engine as text.

The return field is Text[250]. Convert dates, decimals, option values, and other data types to an appropriate text representation before assigning the result.

Sample behavior

The sample implementation returns the fixed text THIS RETURN WILL BE SHOWN ON PAGE. This confirms that the codeunit was called and that its result reached the data mapping, but it does not yet derive a value from the source record.

AL
ParamRecordSIMCORETempTable."Dyn Mapping Return Value" := 'THIS RETURN WILL BE SHOWN ON PAGE';

The declared LocalRecordId is never assigned before LocalRecordRef.Get(LocalRecordId). Consequently, that statement does not load the record represented by the mapping context and has no effect on the returned sample value.

A customer-specific implementation should use ParamRecordSIMCORETempTable.RecID, optionally open the record in ParamRecordSIMCORETempTable.Company, validate its table number, and then calculate the return value.

Configuration

To use this sample pattern:

  1. Open CORE Data Mapping and create or open the mapping used by the Business Portals field.
  2. Add a mapping line and set Type to CODEUNIT.
  3. Set Execute Codeunit to codeunit 5138174 or to the object ID of the customer-specific copy.
  4. Open the Execute Codeunit Param lookup and select Execute.
  5. Assign the data-mapping code to the relevant Business Portals dataset field, field mapping, placeholder, or other setup that consumes a CORE data mapping.
  6. Test the mapping with representative records and companies.

The codeunit must be included in the permission sets used by the executing Business Central user or service account. The standard sample is already included in the Business Portals administrator and user permission sets.

Implementation considerations

Before adapting the sample for production, consider the following points:

  • Keep TableNo = "SIM_CORE Temp Table"; CORE passes the mapping context through Rec.
  • Read the source record ID from Rec.RecID instead of using an uninitialized local RecordId.
  • Respect Rec.Company when the mapping can run across companies. Use RecordRef.Open with the intended company where required.
  • Check RecID.TableNo before interpreting the record as a specific table.
  • Validate missing records and return a deliberate empty value or a clear error according to the mapping requirement.
  • Keep the result within the 250-character limit of Dyn Mapping Return Value.
  • Format values consistently because CORE consumes the return as text and may later convert it for the target field.
  • Avoid user-interface calls, confirmations, or page actions because mappings can execute in web-service and background contexts.
  • Ensure the codeunit has only the read permissions necessary for the source data it accesses.

Complete sample code

AL
codeunit 5138174 "SIM_DPS Sample Dyn. Mapping CU"
{
    TableNo = "SIM_CORE Temp Table";

    trigger OnRun()
    var
        LocalParamText: Text;
    begin
        LocalParamText := 'GETFUNCTIONS';

        if (Rec.Param <> '') then
            LocalParamText := Rec.Param;

        case LocalParamText of
            'Execute':
                Execute(Rec);

            'GETFUNCTIONS':
                Rec."Function List" := 'Execute';
        end;
    end;

    procedure Execute(var ParamRecordSIMCORETempTable: Record "SIM_CORE Temp Table")
    var
        LocalRecordRef: RecordRef;
        LocalRecordId: RecordId;
    begin
        if LocalRecordRef.Get(LocalRecordId) then;

        ParamRecordSIMCORETempTable."Dyn Mapping Return Value" := 'THIS RETURN WILL BE SHOWN ON PAGE';
    end;
}