1. Introduction

IB Entity is a framework library for Business Central that allows you to define integration entities for serializing and deserializing data in JSON or XML format. The app allows you to map Business Central tables, fields, and relationships to external data structures, applying rules and transformation functions. The app pages support configuration, testing, and import/export of entity structures.

1.1 Recipients

The manual is intended for application consultants, key users, and functional developers who are familiar with the Business Central data structure (tables, fields, keys, and relationships).

1.3 Conventions and terms

The following terms are used in the document:

2. Basic concepts

2.1 Area

An Area groups entities by functional domain. The main fields are Code and Description. Entity Count is a calculated counter of the entities associated with the Area.

2.2 Entity

An Entity represents an integration model tied to a Business Central table. The main fields are Code, Area, Table No., Table Name/Caption, and Serialization Type (JSON or XML).

Behavior options (deserialization and record handling):

XML metadata (only if Serialization Type = XML):

2.3 Entity Property

A Property defines a property of the entity: it can be a single table field or a related record (serialized as an object or array). Properties are processed in order of Priority (typically multiples of 100).

Main fields:

Advanced fields and controls (if any): skipValidate, forceModify, RegularExpression, IsPartOfPrimaryKey, Namespace/isAttribute (XML only).

2.4 Entity Relation

Relationships define filters between a related record property and the related table. Each relationship specifies the related table and field and how the filter is calculated.

2.5 Parameter

Parameters manage Name/Value pairs for functions and serialization/deserialization operations. The Type field can be Input, Output, or Protected; Classification helps organize the parameters.

2.6 Transformation

Transformation rules (Model Code, Transformation Type, From, To) are used by the TRANSFORMATION function to convert values from one domain to another (e.g. external/internal codes).

2.7 Types of Source Type

Field: Maps a single table field.

RecordAsArray: Serializes a set of linked records as an array.

RecordAsObject: Serializes a single linked record as an object.

InjectValues: Serializes a linked record and embeds its properties into the parent object, using Serialized Name as a prefix.

3. Pages and functions

The IB Entity app pages allow you to configure entities, manage properties and relationships, and test payloads. Page names may vary slightly depending on your locale; this manual uses the draft names.

3.1 Area List

List of areas (Area) with Code, Description and Entity Count.

Main fields:

• Code
• Description
• Entity Count (calculated)

Actions:

Entity: Opens the list of entities filtered for the selected area.

3.2 Entities (Entity List)

List of configured entities. View Area, Code, Table No., Table Name, and Serialization Type.

Main fields:

• Area
• Code
• Table No.
• Table Name
• Serialization Type (JSON/XML)

Actions:

• Create entity from table: Select a BC table, create the entity, and automatically add properties for all fields in the table.
• Export: Exports the structure to Entities.json (entities, properties, relationships, and parameters).
• Import: Imports a structure from a JSON file in the format generated by Export.

3.3 Entity Card

Entity detail tab. Allows you to set table, serialization type, and behavior options, as well as manage properties on subpages.

Main fields:

• General: Code, Area, Table No., Table Name/Caption, Record Count.
• Serialization Type: JSON or XML.
• Enabled Actions: Enable Delete, Disable Insert, Disable Modify.
• Deserialization: Skip OnInsert Trigger, Skip OnModify Trigger, Delay until Priority.
• XML Group (XML only): Element Name/Namespace, EntitySet Name/Namespace.

Actions:

• Validate: Verifies an input payload and displays the result.
• Serialize: Serializes a selected table record to JSON/XML.
• Simple Serialize (JSON only): Serializes the record ignoring any configured properties.
• Get: Retrieves a record using the PK fields configured in the properties (IsPartOfPrimaryKey).
• Deserialize: Creates/modifies a record from an input payload.
• Add Fields as Properties: Adds properties from selected fields.

3.4 Entity Properties (ListPart)

Subpage of the Entity Card that displays the list of properties and allows you to configure mappings, functions, relationships, and parameters.

Main fields:

• Priority
• Source Type
• Source No.
• Source Entity Code
• Serialized Name
• Function
• IsPartOfPrimaryKey
• skipValidate / forceModify / RegularExpression

Actions:

• Relation: Configures relationship filters (for RecordAsArray/Object/InjectValues only).
• Function Parameters: Manages the parameters of the selected function.

3.5 Entity Relations

Page to manage filters between the main table and the linked table for a related record type property.

Main fields:

• Related Table No.
• Related Field No.
• Relation Type (CONST/FIELD/FILTER)
• Relationship Value

3.6 Transformation List

Manages the transformation rules used by the TRANSFORMATION function.

Main fields:

• Model Code
• Transformation Type
• From
• You

3.7 Additional Info

Support page used in three modes: LIST (Name/Value parameters), INPUT (paste JSON/XML payload), WEB (display formatted results).

Main fields:

• LIST: Name, Value, Type, Classification
• INPUT: free text
• WEB: formatted output

4. Operating procedures

Recommended configuration flow:

Create an Area to group entities.

From the 9WAYS Entities page, use Create entity from table or create a new entity manually.

Set Table No. and Serialization Type (JSON/XML).

Add properties from table fields or create manual properties with Priority and Source Type.

For RecordAsArray/Object/InjectValues: Set Source No., Source Entity Code, and define relationships.

If necessary, apply a Function to the property and fill in the parameters in Function Parameters.

Configure any rules in the Transformation List.

Run Validate, Serialize, or Deserialize to test the mapping.

4.1 Creating an Area

1) Open Area List. 2) Create a new record and fill in the Code and Description. 3) Save.

4.2 Creating an Entity from a Table

1) Open 9WAYS Entities. 2) Select Create entity from table. 3) Select the table to map. 4) Verify that the entity has been created and that the properties (Fields) have been generated for the table fields.

Tip: After automatic generation, remove unnecessary properties and rename Serialized Name to be consistent with the external contract (e.g. camelCase).

4.3 Adding properties and configuring priorities

Properties are processed in ascending order of priority. Use stepped values (e.g., 100, 200, 300) to leave room for future entries.

To map a field:

1. Set Source Type = Field.
2. Select Source No. (field).
3. Check the Serialized Name and change it if necessary.
4. If the field contributes to the primary key, enable IsPartOfPrimaryKey.
5. To map a related record:
6. Set Source Type = RecordAsArray (collection) or RecordAsObject (single) or InjectValues (injection).
7. Set Source No. with the related table.
8. Set Source Entity Code to the detail entity.
9. Open Relation and define the connection filters (CONST/FIELD/FILTER).

4.4 Defining relationships

Relationships determine which records in the related table are included/searched relative to the parent record. Use FIELD when the filter value comes from the parent record (e.g., key linking), CONST for fixed values, and FILTER for more complex expressions.

Example (conceptual): Link document lines to header using FIELD on the parent record's document number.

4.5 Using functions and parameters

A Function allows you to transform the value into output or interpret the input into deserialization. Select the function in the property and fill in the parameters in Function Parameters.

Typical usage examples:

• FORMAT: Format dates and numbers according to an agreed-upon standard.
• FIXED: Set a constant value in the payload.
• TRANSFORMATION: Convert a value according to a mapping table (Transformation List).
• REGEX: Validate a value against a regular expression.

4.6 Test (Validate / Serialize / Get / Deserialize)

Test actions are located in the Entity Card and allow you to quickly verify that the mapping is correct.

Example JSON payload (indicative):

Note: The Get action requires that the properties that make up the table's primary key are marked with IsPartOfPrimaryKey.

4.7 Import / Export (Entities.json)

Export generates an Entities.json file that includes entities, properties, relationships, and parameters. Import allows you to recreate the configuration in another environment (e.g., from DEV to TEST/PROD).

Best practices:

Version export files in a repository or document library.

Run the import in a test environment and validate with Serialize/Deserialize before using it in production.

If there are differences in table IDs or numbering between versions, check the table and field references after import.

5. Available functions

The available functions depend on the serialization type (JSON or XML). Below is a list of the main parameters in the draft.

5.1 Property Functions (JSON)

5.2 Property Functions (XML)

6. Operational notes and troubleshooting

6.1 Important checks

Source Entity Code is required for properties of type RecordAsArray, RecordAsObject, and InjectValues.

IsPartOfPrimaryKey is read from the table and is used by the Get action to find the record.

Delay until Priority allows you to postpone the insertion of the record until the indicated priority.

Skip OnInsert/OnModify avoids trigger execution during deserialization.

RegularExpression enables additional validation on the field value.

6.2 Common problems

6.3 Checklist before go-live

Perform Export of the configuration and save it as a baseline/version.

Run Serialize and Deserialize tests on real-world cases (records with required fields, records with related records).

Check the Skip OnInsert/OnModify and Delay until Priority options according to your business logic.

Validate TRANSFORMATION rules and edge cases (unmapped values).