View model mapping

The Model Mapping page allows an administrator to define how data from a file dataset maps to a class library model. From a single page, you select a data source, choose a dataset within that data source, configure properties at the data source, dataset, and column levels, and define the columns that the register import and validation processes rely on.

The page is organized into three sections — Data Source, Dataset, and Columns — that you move through in sequence. A collapsible Data Preview pane is available while you work in the Dataset and Columns sections for you to review sample data from the selected dataset.

The page opens in one of two modes:

• Edit mode (default): Opens an existing data source and dataset mapping for editing. All three sections are available immediately.

• Create mode: Used to create a new mapping. The Dataset section is enabled only after a data source is selected, and the Columns section is enabled only after both a data source and a dataset are selected.

Header

The header is displayed at the top of the page and includes the following:

• Title: Shows the mapping context as Mapping - Model Identifier, where the value is the class library identifier for the model being mapped.

• Back button (arrow_back): Returns to the model details page. If you have unsaved changes, a confirmation dialog is shown first.

• Save button (save): Validates and saves the mapping. The button is disabled when the data source or dataset name fields are invalid, or when any column has a validation error.

Section navigation

Three section tabs let you move between the parts of the mapping. The active section is highlighted, and each tab controls whether the following sections are available:

• Data Source: Always available.

• Dataset: Available immediately in edit mode. In create mode it is enabled only after a data source is selected.

• Columns: Available immediately in edit mode. In create mode it is enabled only after both, a data source and a dataset, are selected.

Data source section

The Data Source section is where you choose the data source and configure its properties.

Select a data source

• In create mode, the Select Datasource dropdown lists the available data source names. Selecting a data source loads its properties in the Add Property drop-down list.

• In edit mode, the selected data source name appears as a read-only heading and cannot be changed.

If the data source has been marked as deleted, its heading shows a Deleted tooltip, and saving is blocked until the deletion is published.

Changing the data source in create mode while you have pending changes shows a confirmation dialog, because switching data sources clears the current dataset and column configuration. Select Continue to switch, or Cancel to keep the current data source.

Add a property

1. Select Add Property to add a data source property.

2. Type to filter the list of available property names, or open the drop-down list to browse them.

   Selecting a property adds a new row to the property list below with an empty value.

Edit properties

Each property is displayed as a row containing:

• Property Name: A read-only field identifying the property.

• Property Value: An editable field. For properties that accept a fixed set of values, the value is a drop-down list of the available options. For free-form properties, the value is a text or numeric input (text values accept up to 1024 characters).

• Expression Builder: Opens the Expression Builder dialog so you can compose an expression.

• Delete (delete): Removes the property from the mapping.

When validation highlights a required value that has not been provided, the field shows the hint Field cannot be empty.

Data source validation

If validation fails when you save, the section shows an error summary with the message Please correct the highlighted field(s). and highlights the fields that need attention. Correct the highlighted values and save again.

Dataset section

The Dataset section is where you select the dataset within the selected data source and configure its properties.

Select a dataset

• In create mode, a Select Dataset drop-down lists the datasets available for the selected data source. If no datasets are available, you must add one first.

• In edit mode, the selected dataset name is shown as a read-only heading. If the dataset is linked from another dataset, the source path is shown for reference.

Changing the dataset while you have pending changes displays a confirmation dialog, because switching datasets clears the current dataset and column configuration. Select Continue to switch, or Cancel to keep the current dataset.

Dataset without an uploaded file

If the selected dataset has no uploaded file, a warning is shown, No uploaded file found for this dataset, you will not be able to validate against sample data. You can still configure the mapping, but the Data Preview pane cannot show sample data and column mappings cannot be validated against actual file content.

Adding and editing properties

The Add Property field and the property rows behave the same as in the Data Source section, add a property from the available list, edit its value through a text, numeric, or dropdown field, open the Expression Builder for creating expression, and remove a property with the delete action.

Dataset-level properties commonly include the identifier mapping (ID column or ID expression), the class mapping (class column, class expression, or class default), attribute mapping columns, and file layout values such as the header row and first data row, which are populated from the uploaded file when one is available.

Dataset validation

When you save with a dataset selected, the section validates the dataset configuration. If validation fails:

• An error summary is displayed with the message "Please correct the highlighted field(s)." (or a more specific message where one applies).

• A "Show details" toggle is displayed. Expanding it lists the specific field issues — for example, a required identifier that is missing or a value that is not one of the allowed options.

• The affected fields are highlighted so you can locate and correct them.

Columns section

The Columns section is where you manage the columns that participate in the mapping.

Filter columns

Use the Filter columns field to narrow the table by column name or by property key and value. A clear action is displayed while filter text is present, and the table updates as you type.

Add a column

The Add Columns control offers two ways to add a column:

• Add New Column: Opens a manual entry field. Enter a column name and confirm to add it. The name must be unique, must not begin with the reserved xml prefix, and must not contain the characters < > & @ # / \ , :. If the name is invalid, the message Invalid character(s) is shown; if the name already exists, the message Column\AssetName\ already exists. Please choose a different column. is shown.

• Select an available dataset column: Adds the chosen column from the dataset so you can configure its properties.

Reviewing and Editing Columns

The columns table lists each column with its name and a set of property chips showing the configured key and value for each property. Selecting a column opens its property list, where you add, edit, and remove properties using the same property rows described for the other sections. Removing a property chip removes that property from the column.

Deleting a column

Selecting the delete action on a column displays a confirmation dialog with the message Are you sure you want to delete the column \"AssetName\"? This action cannot be undone. Select Delete to mark the column as deleted, or Cancel to keep it. A newly added column that has not been saved is removed immediately, while a previously saved column is marked as deleted and removed on save.

Loading more columns

Columns are loaded in batches of 30. When more columns are available, a Load More button is displayed. Selecting it retrieves the next batch and adds it to the table. A loading indicator is displayed while the next batch is retrieved.

Expression builder

The Expression Builder is a dialog for composing an expression for a property value. It is available from the value field of free-form properties in the Data Source, Dataset, and Columns sections through the Σ action. For more detailed information on Expression Builder refer to View expression builder.

Data preview

The Data Preview pane is shown while you work in the Dataset and Columns sections. It is collapsed by default; expanding it retrieves and shows a sample of rows from the selected dataset so you can confirm that your mapping matches the source data.

• If sample data is available, it is shown in a scrollable table.

• If the dataset has no uploaded file or no rows, a message indicates that no preview data is available.

• If the sample data cannot be retrieved, an error message describing the problem is shown.

The preview is cleared when you change the data source or dataset, and is retrieved again the next time you expand the panel.

Saving the mapping

Select Save to validate and persist the mapping. Saving runs the data source and dataset validations described above and, when everything passes, saves the configuration.

• Success: The confirmation Mapping saved successfully! is shown.

• Validation failure: The relevant section is shown with its error summary, the invalid fields are highlighted, and the save does not proceed until you correct them.

Deleted data source or dataset

If you save while the data source is marked deleted, a dialog is displayed with the message This datasource has been marked deleted. You will need to publish first the changes before re-adding it. The equivalent message for a deleted dataset is This dataset has been marked deleted. You will need to publish first the changes before re-adding it. Publish the pending deletion before re-adding the item.

Save errors

If the mapping cannot be saved because required identifiers are missing, the message Cannot save datasource. Missing class library id/handle or datasource id. is shown. Other save failures display the error returned by the service. Each error message includes a close action so you can dismiss it after reading.

Remove a property

Selecting the delete action on a property row displays a confirmation dialog with the message Are you sure you want to delete the property \"AssetName\"? This action cannot be undone. Select Delete to mark the property for removal, or Cancel to keep it. The property is removed permanently when you save the mapping.

Leave with unsaved changes

Selecting Back while you have unsaved changes displays a confirmation dialog with the message You have unsaved changes. Leaving will discard your work. Please click Save to resume your work later. Do you want to continue?. Select Leave to discard your changes and return to the model details page, or Cancel to stay on the page and continue working. Save the mapping first if you want to keep your changes.

Status messages reference