SMART Data Template
Extension - SMART Data Template
The SMART Data Template extension is an add-on for Microsoft Dynamics 365 Business Central that allows flexible configuration of data mapping and transformation. The extension enables the creation of templates with multiple tables, mappings, and expressions for automating integration, reporting, and data export — without code changes.
Key Features:
- Definition of data templates with any number of tables (as variables).
- Configuration of mapping codes and expressions for value calculation.
- Support for both single and repeating (line-based) structures.
- Flexible setup of filters and relationships between tables.
- Automation of export, integration, and reporting.
SMART Data Template allows you to configure complex data selection and transformation logic through the user interface. You define which tables to use, how they are related, what data to extract, and how to calculate or transform it — without writing code.
- Templates group all settings for a scenario.
- Tables serve as variables and context for data selection.
- Mappings define which data to output.
- Expressions describe how to calculate each mapping.
- Filters control which records to include and how tables are related.
This approach enables business users and consultants to automate data flows, reporting, and integrations flexibly and efficiently.
To use a data template, the following configuration steps must be performed.
How it works
Read this once and the five setup pages stop being five unrelated lists.
A data template answers one question for the app that calls it: given one record — the record it hands in — what are the values of my named mapping codes? Everything in the setup serves that sentence.
Data tables are variables. Each line of Data Template Tables is a variable of type Record: a Business Central table, plus the rule that decides which record of it the template works with. One variable is the root — the record the calling app hands in, which is why it is not filtered. Every other variable is resolved from its parent data code: its Linked Field row takes the value of a field of the parent record, so a child follows its parent instead of being looked up on its own. A variable can also stand alone and be pinned by a constant filter, which is how a fixed master record (a company bank account) is referenced. A variable marked Repeating is read line by line instead of resolving to one record. The Structure pane on the Data Templates, Data Template Tables and Data Template pages draws that tree, so the hierarchy does not have to be read from the Parent Data Code column line by line.
Mapping codes are what comes out. Each line of Data Template Mapping is one named value the calling app asks for by name. A mapping code that is not repeating is calculated once, against the record that was handed in. A repeating one is calculated once per line of its repeating data table, and its variables are re-resolved for that line — so a mapping code on the lines table gives one value per line, and a mapping code that reads a related record gives that line's related record.
Expressions are the formula. Each line of Data Template Expression contributes one value — a
constant, a field of a variable, the value of another mapping code, or one value folded over a whole
record set — and its Operation says how that value is combined with the result of the rows above
it. The rows are folded strictly from top to bottom, without operator precedence: 2 + 3 * 4 is
20, not 14.
At runtime, in this order: the non-repeating variables are resolved from the root downwards, the non-repeating mapping codes are calculated, and then each repeating data table is read line by line with its own mapping codes calculated per line. A variable that finds no record leaves its fields empty, raises an error, or falls back to its default value, depending on On Missing Record. Finally each value passes the second formatting stage — the Data Type of the mapping code — and the calling app receives text it does not have to interpret.
Reading the Formula column
The Formula column on Data Template Mapping (and the Formula field above the rows on Data Template Expression) renders all expression rows of one mapping code as a single line, so that a formula can be read without opening it:
| In the formula | Means |
|---|---|
"text" |
a constant (Type = Const) |
[TABLE.Field] |
a field of the variable TABLE (Type = Field) |
{CODE} |
the value of the mapping code CODE (Type = Data) |
Sum([TABLE.Field]) |
an aggregate over the record set of TABLE (Type = Aggregate) |
Count(TABLE) |
an aggregate that counts records and reads no field |
Join([TABLE.Field], ", ") |
an aggregate that joins values with a separator |
Sum(TABLE.{CODE}) |
an aggregate over the calculated values of a repeating mapping code |
RULE(...) |
a transformation rule applied to that row only |
& |
the row is appended (Operation = Concat) |
+ - * / |
the row is added, subtracted, multiplied, divided |
?? |
the row is appended only when the result so far is empty (If empty) — a fallback |
?& |
the row is appended only when the result so far is not empty (If not empty) |
( ... ) |
the top-to-bottom order of the fold: ([A] - [B]) - [C], never [A] - ([B] - [C]) |
-> Decimal(2) |
the declared Data Type of the mapping code, when it changes the shape of the value |
#index |
the mapping code has Repeating Index switched on: the value is the line number and the expression rows are ignored |
? |
something is not filled in yet — a missing mapping code, field or aggregation type |
So [SALE_HEADER.Amount Including VAT] - [SALE_HEADER.Amount] is a subtraction of two header fields,
and UPPERCASE([CUSTOMER.Name]) & ", " & [REGION.Code] is a name in upper case followed by a comma
and a post code.
Getting from one level to the next
- Data Templates → choose a template to open the Data Template page, which shows the header, the variables and the mapping codes of that one template in one place, with the structure tree beside them.
- Data Template Tables → Filters opens the filter and join rows of the selected variable. (The Filtered column still opens the same page when you choose its value.)
- Data Template Mapping → Expressions opens the expression rows of the selected mapping code. (Choosing the value of the Formula column still does the same.)
- Every setup page answers F1 with the section of this article that describes it.
1. Creating a Data Template
Page: Data Templates
You need to create a new data template by filling in the following fields:
| Field | Description |
|---|---|
| Code | Unique identifier of the template. |
| Description | Description of the template. |
| Type | Choose the template type: Mapping or Record Filter. To export information according to a specific data mapping, choose Mapping type. |
| Source Table ID | ID of the main table. |
| Source Table Name | Name of the main table (auto-filled). |
2. Adding Tables to the Template
For the selected template, you must add tables that will be used as variables (contexts) in the data template.
Page: Data Template Tables (click the Data Tables button on the Data Templates page)
| Field | Description |
|---|---|
| Code | Unique code for the variable table. |
| Description | Description of the table. |
| Table ID | ID of the table in Business Central. |
| Table Name | Name of the table (auto-filled). |
| Is Root | Marks the main table (auto-filled). |
| Repeating | If checked, the table is repeating (line-based). |
| Parent Data Code | Code of the parent table used to retrieve related records. |
| Request Additional Filters | If checked, a filter request page will appear during report generation. |
| Latest | If multiple records match the filters, returns the last record in the sort order below instead of the first one. See the note under Sorting. |
| Sort Field ID | ID of the field the records of this table are read by. 0 keeps the primary key order. |
| Sort Field 2 ID | ID of a second field that breaks ties between records with the same value in Sort Field ID. |
| Sort Order | Ascending or Descending order of the sort field. |
| Max Records | For a repeating table: the maximum number of lines to produce. 0 means no limit. |
| Mandatory | Marks the table as one that must resolve to a record. Switching it on sets On Missing Record to Show Error. |
| On Missing Record | What happens when no record matches: Leave Empty, Show Error or Use Default Value. |
| Default Value | The value returned by every expression on this table when no record is found (only for Use Default Value). |
Sorting the records of a table
By default a table is read in primary key order. Set Sort Field ID (and, when you need a tie-breaker, Sort Field 2 ID) to read it in the order of another field, and use Sort Order to reverse it. For a repeating table this is the order in which the lines appear in the result; for a non-repeating table it decides which single record is picked.
- Not every field can be sorted by. Calculated fields (FlowFields, such as a total that is summed from lines), image and BLOB fields cannot be part of a sort order. If you enter one, the system refuses it immediately and lists fields you can use instead. Fields that begin one of the table's keys are the fastest choice.
Latestfollows this sort order. With no sort field configured, Latest means the last record in primary key order — it does not mean "the newest by date". To get the newest record by date, set Sort Field ID to the date field and switch Latest on.- Sorting also decides the order of the First, Last and Join aggregations (see Aggregating a set of records).
Limiting the number of lines
Max Records caps how many lines a repeating table produces. The system stops reading records once the limit is reached, so it is also a safeguard for very large documents. Two things to know:
- An aggregation over the same table is capped in the same way, so a total always matches the lines that were actually produced.
- The consuming app can ask whether records were left out and refuse to produce an incomplete document. Combine Max Records with Sort Order so that the lines you keep are the ones you want, not an arbitrary selection.
What if nothing is found
A table whose filters match no record produces empty values — that is the default and it has not changed. On Missing Record lets you choose something else:
| Value | Behaviour |
|---|---|
| Leave Empty | Every expression on this table returns an empty value. The document is still produced. This is the default. |
| Show Error | Generation stops with an error naming the template, the table and the filters that were applied, so you can see why nothing matched. |
| Use Default Value | Every expression on this table returns Default Value. |
Default Value applies only when no record was found. If a record was found and the field
you read is simply empty, you get the empty value — not the default. Enter the default in the same
neutral format the template produces elsewhere, for example 1234.56, 2026-08-17 or true.
Note: for a template of type Record Filter, On Missing Record is ignored. That template type answers "do all the required records exist?" and must be able to answer no without stopping the document that is being created.
3. Configuring Table Filters
Define filters for each table to limit or link data. To set filters, on the Data Template Tables page, for the relevant table, go to the Filtered field and fill in the required filters:
| Field | Description |
|---|---|
| Field ID | ID of the field to filter by. |
| Field Caption | Field name (auto-filled). |
| Type | Filter type: Filter or Linked Field. Use Filter to filter records in the current table. Use Linked Field to relate data to the parent table. |
| Filter Value | For entries with type = Filter, specify the value or expression. |
| Linked Field ID | For entries with type = Linked Field, specify the linking field. |
| Linked Field Name | Name of the Linked field (auto-filled). |
Note: The values in the Filter Value field must be entered in the language of the interface from which the report will be run. For example, if the report is executed from the Ukrainian-language interface, all filter values must be specified in Ukrainian.
4. Adding Mapping Codes
Mapping codes are used for variables when generating the report or proceeding the integration.
Page: Data Template Mapping (click the Mapping Data Codes button on the Data Templates page)
| Field | Description |
|---|---|
| Code | Unique code for the mapped variable. |
| Description | Description of the mapping. |
| Repeating | If checked, this mapping is for a repeating table. |
| Repeating Data Table | Code of the repeating table. |
| Data Type | What the calculated value is: Text (the default), Integer, Decimal, Date, DateTime, Time or Boolean. See What the value is below. |
The remaining settings of a mapping code are on the Output Typing pane on the right of the page, which always shows the mapping code that is selected in the list:
| Field | Description |
|---|---|
| Data Type | The same field as in the list, repeated here because the fields below depend on it. |
| Decimal Places | Only for Data Type = Decimal. How many digits are written after the decimal separator, for example 2. The value is rounded to that many places. |
| Format Expression | Optional. A Business Central format string, used exactly as you type it and never translated, for example <Year4>-<Month,2>. It replaces the standard shape of a number, a date, a date/time or a time. |
| Trim | Removes the spaces at the start and at the end of the value, for example when the source field has a fixed length. |
| Empty As Zero | Lets an empty value count as 0 in the arithmetic of this mapping code. Without it, an empty operand stops the calculation with an error. |
What the value is — data types and formatting
Without these settings a mapping code produces text, in a fixed, language-neutral shape: a decimal as
1234.56, a date as 2026-08-17, a Yes/No field as its caption. Every consuming app then has to know
what that text really is, and most of them keep their own copy of that information. Data Type lets
the template say it once.
- Text is the default and changes nothing. A mapping code that was configured before this feature existed produces exactly what it produced before.
- An empty value stays empty whatever the data type is. An empty value is missing data, not a
broken number, so it is never turned into
0and never reported as an error. - Decimal rounds to Decimal Places and then writes exactly that many digits:
1234.5with two places becomes1234.50, and with zero places1235. Rounding is to the nearest value, and a half rounds away from zero (1234.5→1235,-1234.5→-1235). - Integer expects a whole number and refuses a value with decimals. If you want rounding, choose Decimal with Decimal Places = 0 — then the setup says what is happening.
- Date, DateTime and Time are written in the neutral ISO shape (
2026-08-17) whatever language the session runs in, unless Format Expression says otherwise. - Boolean is written as
trueorfalse— never as the Yes/No of the session language. - A value that cannot be read as the declared data type stops the calculation with an error that
names the template and the mapping code. That is the point of declaring the type: the same mistake
used to surface much later, inside the consuming app, which could no longer say which mapping code
was wrong. If a mapping code reads a table whose Default Value is set (see What if nothing is
found), that default has to be readable as the data type too:
N/Aunder Data Type = Decimal is a configuration error. - Trim runs before the data type is applied, so a source field padded with spaces is still readable as a number or a date.
- Empty As Zero is about the operands of
+,-,*and/, not about the result. Without it, an empty operand is a configuration error — which is deliberate, because a silently missing amount is worse than a stopped export. - A mapping code that reads another mapping code (Type = Data) sees its formatted value. So
a mapping code declared as Decimal with two places contributes
1234.50to whatever reads it.
5. Adding Expressions
Each data mapping code must have one or more expressions. Expressions define what data will be output in the report. To add expressions, on the Data Template Mapping page, go to the Expression field of the corresponding mapping code and enter the needed expressions:
| Field | Description |
|---|---|
| Operation | Type of operation (Concat, +, -, *, /, If empty, etc.). Use Concat to retrieve a field value. Use arithmetic operators for calculations. Use If empty to check for empty values and provide a fallback. Use If not empty to check for non-empty values. |
| Type | Expression type (Constant, Field, Data, Aggregate). Use Field to reference a table field; Constant for static values; Aggregate to fold a set of records into one value (see below). |
| Const Value | Specify the constant value if Type is Constant. |
| Linked Table Data | Code of the table from which to retrieve data. |
| Table Name | Name of the related table. |
| Field ID | Field ID in the related table. |
| Field Caption | Field name in the related table (auto-filled). |
| Aggregation Type | Only for Type = Aggregate. How the records are folded: Sum, Average, Count, Minimum, Maximum, First, Last or Join. |
| Aggregation Source | Only for Type = Aggregate. Field aggregates the values of Field ID; Mapping aggregates the calculated values of a repeating mapping code. |
| Aggregation Mapping Code | Only for Aggregation Source = Mapping. The repeating mapping code whose values are aggregated. It must use the same repeating table as Linked Table Data. |
| Separator | Only for Aggregation Type = Join. The text inserted between two values. Defaults to a comma and a space; leave it empty to concatenate without a separator. |
| Transformation Rule | Use if the output value needs to be converted to another format. |
Aggregating a set of records
An expression of Type = Aggregate returns a single value calculated over all records of the table named in Linked Table Data, instead of a value of one record. It is what a document total is made of: without it, only the consuming app can add the lines up, which is impossible for a field of the document header.
The aggregated set is the table variable resolved in the current scope — its own filters plus its link to its parent. Nothing else has to be configured, and that single rule gives both shapes:
- from a mapping code that is not repeating, over the repeating lines table ⇒ a document total (all lines of the document);
- from a mapping code that is repeating, over a table linked to the lines table ⇒ a per-line subtotal (only the records that belong to the line being calculated).
Rules worth knowing before you configure one:
- Sum and Average require a Decimal or Integer field. Any other field type is refused with an error naming the template, the mapping code and the expression line.
- Over an empty set, Sum and Count return
0, and every other aggregation type returns an empty value. Average never fails with a division by zero. - Empty values are skipped by Sum, Average, Minimum, Maximum and Join. First and Last are positional and return the value of the first or last record even when it is empty.
- Count counts records and ignores Field ID.
- First, Last and the order of Join follow the Sort Field ID and Sort Order of the table, and its primary key when no sort field is set (see Sorting the records of a table).
- Max Records of the table also caps the aggregation, so a total always matches the lines that were actually produced.
- Minimum and Maximum compare numbers as numbers and everything else as text. Dates, date/times and times sort correctly, because the engine formats them in the ISO shape.
- The Transformation Rule of the row is applied to the aggregated result, not to each record.
- Aggregation Source = Mapping calculates the repeating table on demand if the engine has not reached it yet. An aggregation that ends up depending on itself is refused with an error that shows the chain of mapping codes.
- Performance: an aggregation reads the records of the set once. If the table already has a FlowField that sums what you need (for example Total Amount on a document header), an expression of Type = Field on that FlowField is faster, because the database answers it from its index.
6. Validating a Template
Validate Template, on the Data Templates list and on the Data Template card, checks the whole configuration of the selected template and lists everything it can find wrong with it — in one run, so that you correct a list instead of finding one mistake per document.
What the check does and does not do:
- It reads configuration and table metadata only. It never reads a business record, so it is safe to run at any time and in any company — and it cannot tell you whether your data matches the filters, only whether the filters themselves are valid.
- It changes nothing. No setup row is created, changed or deleted by a validation run, and nothing is fixed automatically.
- Nothing runs it for you. A template that was never validated still fails for the first time in the calling app.
- One thing it can never check: which apps use this template. This extension has no dependency on the apps that call it and cannot read their setup, so no rule can tell you who refers to a template code or a mapping code. Renaming or deleting either is safe only after you have looked at the calling app's own setup.
Each line of the result is a finding:
| Column | What it is |
|---|---|
| Severity | How much the finding matters — see below. |
| Rule Code | The stable code of the rule that produced it, listed in Rule reference. |
| Message | What is wrong and what to change. |
| Table Code, Mapping Code, Expression Line No. | Which setup row the finding is about. |
Choose Show Row to open that setup row and correct it. The action is disabled for a finding that is about the template as a whole.
Severity
- Error — the template cannot produce a correct result. Most errors stop the whole calculation, not just one value, so the calling app gets nothing at all.
- Warning — the configuration is accepted and probably does not do what it looks like. Read it and decide; nothing blocks you.
- Information — worth knowing. Nothing is broken.
Rule reference
Template
| Rule code | Severity | What it means | How to fix it |
|---|---|---|---|
TPL-MISSING |
Error | The template code no longer exists. | Refresh the list; the template was deleted while the page was open. |
TPL-EMPTY |
Error | The template has no tables and no mapping codes, so it produces nothing. | Add the variable that reads the source table record, then the mapping codes. |
TPL-NO-SOURCE |
Error | Source Table Id is empty, so the template does not say what the calling app hands in. | Enter that table number, for example 112 for Sales Invoice Header. |
TPL-BAD-SOURCE |
Error | Source Table Id is not a table in this database. | Choose an existing table. The app that owned the previous one may be uninstalled. |
TPL-NO-ROOT |
Error | No table of the template is marked as the root, so nothing is resolved from the record handed in. | Enter the source table number in the Table ID of the table that stands for that record; Is Root is set by that validation. |
TPL-ROOT-MISMATCH |
Error | A table is marked as the root but reads a different table than Source Table Id. Is Root is a stored flag and Source Table Id does not re-derive it, so this is what a template looks like after its source table was changed. | Correct that table's Table ID, or make another table the root. |
TPL-ROOT-NOT-SET |
Error | A table reads exactly the source table but is not marked as the root, so the record the calling app hands in is never used. | Enter its Table ID again — the validation of that field sets Is Root. |
TPL-MULTI-ROOT |
Error | More than one table is marked as the root. | Keep one root and change the Table ID of the others. |
TPL-NO-MAPPINGS |
Error | Type is Mapping but there are no mapping codes, so a calculation returns nothing. | Add the mapping codes the calling app asks for, or change the type. |
TPL-FILTER-MAPPINGS |
Warning | Type is Record Filter, so the mapping codes are never calculated. | Delete them, or change the type to Mapping. |
TPL-FILTER-REPEAT |
Information | A Record Filter template contains a repeating table, which the yes/no check ignores. | Nothing has to change. Switch Repeating off if that table was meant to be checked. |
Tables
| Rule code | Severity | What it means | How to fix it |
|---|---|---|---|
TAB-NO-TABLE |
Error | The variable does not say which table it reads. This stops the whole template, including the yes/no answer of a Record Filter template. | Enter a Table ID, or delete the variable. |
TAB-BAD-TABLE |
Error | Table ID is not a table in this database. | Choose an existing table. |
TAB-NO-PARENT |
Warning | The variable is not the root, has no Parent Data Code and no filters, so it resolves to the first record of the whole table. | Add a parent data code with a linked field filter, or a constant filter. Leave it as it is only for a table that has exactly one record, such as Company Information. |
TAB-PARENT-MISSING |
Error | Parent Data Code names a variable that does not exist. | Choose an existing variable, or clear the field. |
TAB-PARENT-CYCLE |
Error | The chain of parent data codes is circular. The message shows the chain. | Break the chain at one of the variables it names. |
TAB-REPEAT-NO-LINK |
Error | A repeating variable names a parent but has no linked field filter, so every record of the table is read for every document. | Add a filter of Type = Linked Field that joins it to the parent record. |
TAB-LATEST-REPEAT |
Error | Repeating and Latest are both on, and they contradict each other. | Switch one off: Latest takes the last record, Repeating takes them all. |
TAB-SORT-FIELD |
Error | Sort Field ID or Sort Field 2 ID does not exist, is disabled, or is a field the database cannot order by — a FlowField, a FlowFilter, or a BLOB or media field. | Choose another sort field, or enter 0 for primary key order. |
TAB-MAX-RECORDS |
Error | Max Records is set on a variable that is not repeating, so the limit is never applied. | Switch Repeating on, or set Max Records to 0. |
TAB-NO-DEFAULT |
Error | On Missing Record is Use Default Value but Default Value is empty. | Enter a default value, or choose Leave Empty. |
TAB-DEFAULT-TYPE |
Error | Default Value cannot be read as the data type of a mapping code that reads this variable. | Enter it in the invariant format of that type (0, 1234.56, 2026-08-17, true), or change the data type of the mapping code. |
Filters
| Rule code | Severity | What it means | How to fix it |
|---|---|---|---|
FLT-FIELD-MISSING |
Error | The filtered field does not exist in the table the variable reads, or it is disabled. | Delete the filter row and enter it again. |
FLT-FIELD-OBSOLETE |
Warning | The filtered field is marked obsolete in Business Central, so an update can remove it. | Filter another field. |
FLT-ORPHAN |
Information | Filter rows belong to a variable that no longer exists. They are never applied, and the setup pages cannot reach them at all, because filters are opened from a variable row. | Choose Show Row on the finding — that is the only way in — and delete them. Or re-create the variable. |
FLT-STALE-TABLE |
Error | The filter row still carries the table of the previous configuration. | Delete the filter and enter it again. |
FLT-STALE-PARENT |
Error | The join still expects the parent table of the previous configuration. | Enter the Table Code of the variable again, which refreshes the stored parent table. |
FLT-LINK-NO-PARENT |
Error | Type is Linked Field but the variable has no Parent Data Code to take a value from. | Enter a parent data code, or change the filter type to Filter. |
FLT-LINK-NO-FIELD |
Error | Type is Linked Field but Linked Field ID is empty. | Enter the field of the parent record whose value the join uses. |
FLT-LINK-BAD-FIELD |
Error | Linked Field ID does not exist in the parent table, or it is disabled. | Choose another linked field. |
FLT-LINK-TYPE |
Error | The two joined fields are of types that cannot be compared, for example a code field joined to an option field. | Join fields of the same type. |
FLT-VALUE-SYNTAX |
Error | Filter Value is not a filter expression that Business Central accepts for that field. Checked on both filter types: on a Filter row the value is the whole filter, on a Linked Field row it is the pattern the parent value is substituted into. The check hands the value to the platform without running the filter, so no record is read. | Correct it, for example to 1000..2000, <>'' or A\|B. |
FLT-PATTERN-TOKEN |
Warning | A Linked Field row has a Filter Value, which is then used as a pattern for the parent value — but it contains no %1, so the parent value is dropped and the join silently matches everything the pattern allows. |
Put %1 where the parent value belongs (<>%1, %1..), or clear Filter Value to join on equality. |
FLT-VALUE-LANGUAGE |
Warning | Filter Value of an option, boolean, date, date/time or time field contains text that depends on the session language — an option caption, Yes/No, or a localized date. The template then stops matching when it runs in another language. | Use a language-independent value: the option number, 1/0, or an ISO date such as 20260817. |
Mapping codes
| Rule code | Severity | What it means | How to fix it |
|---|---|---|---|
MAP-NO-REPEAT-TABLE |
Error | Repeating is on but Repeating Data Table is empty. | Enter the repeating variable whose lines this mapping code produces. |
MAP-BAD-REPEAT-TABLE |
Error | Repeating Data Table names a variable that does not exist or is not repeating. | Choose a variable that has Repeating switched on. |
MAP-INDEX-NOT-REPEAT |
Error | Repeating Index is on but Repeating is off, so nothing is numbered. | Switch Repeating on, or Repeating Index off. |
MAP-NO-EXPRESSIONS |
Error | The mapping code has no expression rows, so its value is always empty. | Add at least one expression row. A Repeating Index mapping code needs none and is never reported. |
MAP-UNREFERENCED |
Information | In a Record Filter template, no expression reads this mapping code and no value ever reaches the calling app. In a Mapping template this is never reported: the mapping codes exist to be read by the calling app, which this extension cannot see, so "no finding" here does not mean "someone uses it". | Delete it, or change the template type. |
MAP-FORMAT-TYPE |
Error | Decimal Places or Format Expression is set on a data type that does not use it. | Clear them, or choose another data type. Decimal places belong to Decimal; a format applies to Integer, Decimal, Date, DateTime and Time. |
MAP-FORMAT-INVALID |
Error | Format Expression is not a format Business Central can apply to the declared data type. | Correct it, for example to <Year4>-<Month,2>. |
Expressions
| Rule code | Severity | What it means | How to fix it |
|---|---|---|---|
EXP-ORPHAN |
Information | Expression rows exist for a mapping code that no longer does. They are never calculated — dead configuration, harmless at runtime. | Delete them, or create the mapping code. |
EXP-CONST-EMPTY |
Error | Type is Const and Const Value is empty, so the row contributes nothing. | Enter the text, or delete the row. |
EXP-NO-TABLE |
Error | Type is Field or Aggregate and Linked Table Data is empty. | Enter the code of the variable to read. |
EXP-TABLE-MISSING |
Error | Linked Table Data names a variable that does not exist in this template. | Choose an existing variable. |
EXP-NO-TABLE-ID |
Error | The row does not carry the table number of its variable at all, so the calculation stops on it. A row reaches this state only through an import: entering the variable code fills the number in. | Enter the variable code again. |
EXP-STALE-TABLE |
Error | The row still reads fields of the table that the variable used to read. | Enter the variable code again, which refreshes the table number stored on the row. |
EXP-NO-FIELD |
Error | The row has to name a field and does not. This stops the whole calculation. | Enter a Field ID. An aggregation of type Count needs none. |
EXP-FIELD-MISSING |
Error | The field does not exist in the table the variable reads, or it is disabled. | Choose another field. |
EXP-FIELD-OBSOLETE |
Warning | The field is marked obsolete in Business Central, so an update can remove it. | Read another field. |
EXP-DATA-EMPTY |
Error | Type is Data but no mapping code is named. This stops the whole calculation. | Enter the mapping code whose value the row reads. Remember that Linked Table Data holds a mapping code when Type is Data. |
EXP-DATA-MISSING |
Error | Type is Data and the mapping code it names does not exist. | Choose an existing mapping code. |
EXP-DATA-CYCLE |
Error | Two or more mapping codes read each other in a circle, so none of them can be calculated. | Break the circle. |
EXP-REPEAT-READS |
Warning | A repeating mapping code reads a mapping code that is calculated once for the whole document, so the same value appears on every line. | Intended in some templates — a document number repeated on each line. Otherwise read a field of the line instead. |
EXP-FIRST-OPERATION |
Warning | The first row of a mapping code uses +, -, * or /, which has nothing to work on; the engine appends the row instead. |
Set Operation to Concat on the first row, or move the row down. |
EXP-DIV-EMPTY |
Warning | The row divides by a value that can be empty or zero, and the calculation then stops with an error. | Make sure the divisor is never empty and never zero, or divide by a constant. |
EXP-RULE-MISSING |
Error | Transformation Rule names a rule that does not exist. | Choose an existing transformation rule, or clear the field. |
EXP-AGG-NO-TYPE |
Error | Type is Aggregate and Aggregation Type is blank. | Choose how the records are folded, for example Sum. |
EXP-AGG-NO-SOURCE |
Error | Type is Aggregate and Aggregation Source is blank. | Choose Field or Mapping. |
EXP-AGG-FIELD-TYPE |
Error | Sum or Average over a field that is not a number. | Aggregate a numeric field, or choose Count, Minimum, Maximum, First, Last or Join. |
EXP-AGG-MAPPING |
Error | Aggregation Mapping Code does not exist, is not repeating, or belongs to a different repeating variable than the one being aggregated. | Choose a repeating mapping code of the same variable as Linked Table Data. |
EXP-AGG-SEPARATOR |
Information | Separator is set on an aggregation that is not Join, and every other type ignores it. | Clear it, or choose Join. |
Other
| Rule code | Severity | What it means | How to fix it |
|---|---|---|---|
INTERNAL |
Error | A rule of the check itself could not be completed — for example because a table belongs to an app that is no longer installed. Every other rule still ran. | The finding says that part of the check is missing, not what is wrong with the template. Report the message it carries. |
7. Moving a Template Between Companies
A data template is a lot of configuration, and it is normally built once and then wanted somewhere else — in another company, on another tenant, in a test database. Three actions on the Data Templates list and on the Data Template card do that: Export Template, Import Template and Copy Template.
What the file is
Export Template writes the selected template to one JSON file: the template header, every variable with its filters, every mapping code with its expression rows. Nothing else — the file contains configuration only, never a single business record, so it is safe to send to a colleague or to attach to a support ticket.
The file is written so that it is readable and comparable:
| Property | What it means for you |
|---|---|
| Everything in one file | One template, complete. There is no second file and no order in which several files must be imported. |
| Table and field numbers, each with its name | The number is what decides, always. The name is written for a reader — a person, or an AI — so that the file says what table 112 and field 22 actually are, and it is ignored completely on import. The names are the untranslated Business Central names, so the same template exports to the same file in any language. |
| Values written out in full | Every setting is in the file, including the ones that are empty, zero or off. What you see is the whole vocabulary of the configuration. |
| No date, no user, no company | Exporting the same template twice produces exactly the same file, so two files can be compared with any text tool to see what actually differs. |
schemaVersion |
The version of the format. See What an older or newer file does below. |
The file is plain text. It can be edited, but the safe way to change a template is to import it and change it in Business Central — the import checks what you hand it, an editor does not.
Importing
Import Template asks for the file, and the template is imported under the code the file carries. If this company already has a data template with that code, you are asked once whether to replace it — answer No and nothing at all happens; answer Yes and the existing template is deleted and the file is written in its place, in one step. Read Before you replace a template below before you answer Yes.
To have the same template twice in one company, import it and then use Copy Template to duplicate it under a second code.
Nothing is written unless everything passes. The import reads the whole file first, then checks that every table and field it names exists in this database, then writes the template, then runs the same check as Validate Template — and if that check finds an error, the whole import is undone. There is no half-imported template: either the template is there and complete, or this company is exactly as it was.
What you get back is a list of findings, in the same page and with the same severities as Validate Template (§6): Error means nothing was imported, Warning means the template was imported and there is something you should know, Information is worth reading once.
Nothing in the template is ever renamed by an import: the template code comes from the file, and the variable codes, the mapping codes and every reference between them are exactly what the file carries.
Before you replace a template
The apps that use a data template refer to it by its code, and their setup lives in extensions that this one does not depend on and cannot read. No check here can tell you who uses a template — which is why the question is asked at all rather than the replacement just happening. Before you answer Yes, look at the calling app's own setup: a mapping code that the file does not have is a value that app will stop receiving.
What an older or newer file does
The format has a version, written as major.minor.
- A newer minor (
1.1where this version reads1.0) imports normally. Settings that this version does not know are ignored. - An older file imports normally too. A setting that is not in it takes its default.
- A different major (
2.0) is refused, with a message naming the version this version reads. Get the file exported again from a Business Central that matches.
Copying a template inside one company
Copy Template creates a complete duplicate under a new code: every variable, filter, mapping code and expression row. It changes nothing inside the template — the variable codes and the mapping codes stay exactly as they are, because they mean the same thing under any template code.
Two things are worth knowing:
- The copy is not checked. That is deliberate: a template is often copied precisely because it is broken and you want somewhere to repair it. Choose Validate Template on the copy when you have finished changing it.
- The new code must be free. A code that is in use is refused, and the template that is there is not touched.
Import rule reference
Every finding an import produces carries one of these codes. The codes of Validate Template (§6) can appear here too: the import runs that check on the template it wrote, and any error of it undoes the import.
| Rule code | Severity | What it means | How to fix it |
|---|---|---|---|
IMP-VERSION |
Error | The file does not say which format version it uses, the version is not readable, or its major is one this version does not know. | Export the file again from a Business Central of the version named in the message. |
IMP-JSON |
Error | Something in the file is missing or is of the wrong kind — a number where a text belongs, a list where a setting belongs. The message names the place inside the file. | Correct the file at that place, or export it again instead of editing it. |
IMP-CODE |
Error | The template code is empty, or a value in the file is longer than the field that holds it. Nothing is shortened, because a shortened code is a different template. | Correct the value in the file, or correct it in the source template and export it again. |
IMP-EXISTS |
Error | The code already exists and the replacement was not confirmed. Nothing was touched. This is also what a scheduled or programmatic import always answers, so that it can never overwrite a template silently. | Import the file again and confirm the replacement, or rename the existing template first. |
IMP-ENUM |
Error | A choice value in the file is one this version does not know — the file comes from a database with an extension that is not installed here, or the value was mistyped. | Install the missing extension, or correct that value in the file. |
IMP-TABLE |
Error | The file names a table that does not exist in this database. Nothing is invented and nothing is imported. | Install the extension that owns that table, or point the template at a table that exists here. |
IMP-FIELD |
Error | The file names a field that the table does not have here. | The same: install what owns it, or correct the field in the source template and export it again. |
8. Usage Scenarios
Scenario 1: Document Data Export
- Create a template for a document (e.g., Sales Invoice).
- Add the document’s main table and its line table as repeating.
- Set up filters to link lines with the header.
- Define mapping codes for header and line fields.
- Add expressions for calculating values (e.g., field concatenation, conditions).
Scenario 2: Data Integration
- Create a template for integration.
- Add all necessary tables (e.g., Customer, Sales Header, Sales Line).
- Use filters to select required records.
- Define mapping codes for integration fields.
- Use expressions to transform the data.
Scenario 3: Custom Reporting
- Create a template for a report.
- Add tables and configure their relationships.
- Define mapping codes for report columns.
- Use expressions for calculated columns (e.g., totals, conditional values).