Overview

Metadata

Operational guide to the framework metadata with focus on client-side and server-side application effects.

Scope

  • Types covered: table, column, menu, custom actions, table/column authorizations, table/column styles, condition groups.
  • UI origin: forms opened from the metadata-editor (menus Metadati and Metadati correlati).
  • Runtime transport: MetaService.* endpoints via AsmxProxy.

Screenshot Reference (Metadata Editor)

  • metadata-editor-table: table metadata form.
  • metadata-editor-columns: column metadata form (insert/edit).
  • metadata-editor-custom-actions: table custom actions form.
  • metadata-editor-auth-table: table authorizations form.
  • metadata-editor-auth-column: column authorizations form.
  • metadata-editor-styles-table: table styles form.
  • metadata-editor-styles-column: column styles form.
  • metadata-editor-condition-groups: condition groups form.
  • metadata-menu-management: metadata menu management list.

Runtime Flow

  • MetaService.getTableMetadata: loads table + columns + metadata relations.
  • MetaService.getFlatRecordData: uses metadata to compose queries, filters, sorting, and paging.

Contextual Metadata-editor

The contextual metadata-editor allows you to quickly open and edit metadata directly from the operating context (current grid/form/action), without having to manually navigate through all the technical routes of the metadata menu.

  • Goal: reduce the number of steps for targeted interventions on table, column, and related configurations.
  • Practical advantage: the focus stays on the entity in use, with quick access to the most frequent options.
  • Recommended use: incremental maintenance during functional testing and UI/runtime tuning.

Reference Screenshots

  • manual__metadata_context_editor__01.png: opening the contextual editor and quick access to metadata sections.
  • manual__metadata_context_editor__02.png: operational detail of the contextual flow with guided editing.

Table Metadata (_metadati__tabelle)

Routing and storage

  • md_route_name: datasource logical route. Client: builds URL/hash route and datasource binding. Server: metadata/table lookup and query generation.
  • md_nome_tabella: physical table/view name. Client: transparent in UI. Server: main SQL target.
  • md_schema_name: DB schema. Client: no direct impact. Server: qualifies the SQL object.
  • md_conn_name: metadata connection name. Client: no direct impact. Server: connection selection (e.g. DataSQLConnection).
  • md_db_name: target database. Client: no direct impact. Server: query/scaffolding routing.

CRUD operations and UI

  • md_editable: enables record editing. Client: edit buttons/modal. Server: update logic gate.
  • md_insertable: enables record insertion. Client: add button/insert form. Server: insert logic gate.
  • md_deletable: enables record deletion. Client: delete command visible/usable. Server: delete logic gate.
  • md_detail_action: enables detail view. Client: detail action in grid. Server: no direct SQL effect.
  • md_clonable: enables cloning. Client: clone button. Server: clone logic + optional cloneDefinition.
  • md_inline_edit: inline editing in grid. Client: cell/row editor. Server: same sync/update pipeline.
  • md_edit_popup: edit in popup. Client: UX choice modal vs inline. Server: unchanged.

Query, filters, paging

  • md_server_side_operations: delegates sorting/filtering/paging to the server. Client: sends FilterInfo, SortInfo, PageInfo. Server: composes dynamic query.
  • md_pageable: enables pagination. Client: pager active. Server: applies limit/offset or cursor policy.
  • md_pagesize: default page size. Client: pager initial value. Server: TOP/OFFSET or batch cursor.
  • md_sortable: enables sorting in UI. Client: sortable headers. Server: ORDER BY only if requested/allowed.
  • md_default_filter: initial filter. Client: preloads filter. Server: merges into WHERE clause, in AND even when the user filters are combined with OR.
  • md_disabilita_filtri: disables filter panel. Client: hides filter bar. Server: reduces available runtime filters.
  • md_show_record_count: requests total record count. Client: page X of Y. Server: COUNT(*) (or alternative policy via props bag).

Templates and rendering

  • md_gridview_template: list rendering template. Client: grid layout override. Server: unchanged.
  • md_rowTemplate: row template. Client: custom row rendering. Server: unchanged.
  • md_filter_template: filter area template. Client: custom filter UX. Server: unchanged.
  • md_detail_template: detail template. Client: detail rendering. Server: unchanged.
  • md_edit_template: edit template. Client: edit form rendering. Server: unchanged.
  • md_ui_grid_conditional_template_condition: alternative template condition. Client: conditional class/template. Server: unchanged.

Security and audit

  • md_grant_by_default: default route visibility. Client: influences UI access combined with auth. Server: authorization fallback.
  • md_record_restriction_key_user_field_list: field(s) for record restriction. Client: user data in filter payload. Server: applies restrictions by user/role.
  • md_user_id_field_name: owner user field. Client: no direct effect. Server: ownership filter.
  • md_logging_enable: logging active. Client: unchanged. Server: populates audit fields.
  • md_logging_*_field_name: audit field mapping. Client: invisible unless columns are exposed. Server: automatic value population.
  • md_has_logic_delete: logical delete. Client: same delete UX. Server: flag update instead of physical delete.

md_props_bag (extra JSON)

  • endpoint: source override (odata/webservice/meta). Client: data-provider uses custom endpoint. Server: changes I/O path.
  • parameters: dynamic request parameters. Client: mapping from filters/route/user context. Server: receives resolved parameters.
  • archetypes.*: archetype-specific options (list, map, scheduler, tree, spreadsheet, carousel, chart, form). Client: specific rendering/behavior. Server: unchanged.
  • groupInfo: client/server grouping. Client: group UI and aggregated headers. Server: GROUP BY query if requested.
  • aggregates: aggregate definitions. Client: footer/KPI. Server: aggregate select.
  • changeTracking: enables client-side change tracking. Client: dirty-state/pending cue. Server: unchanged.
  • client_side_crud: forces client-side CRUD. Client: buffering/local model. Server: batch or deferred sync.
  • queryOptimization.enabled: enables query optimization policy. Client: adapts pager/total handling. Server: optimized query branch.
  • queryOptimization.countPolicy: exact | skipWhenPaged | never | cursor. Client: total pages/next-prev handling. Server: count strategy/cursor.
  • queryOptimization.sqlServerHint: none | recompile. Client: no impact. Server: SQL hint (OPTION (RECOMPILE) when requested).

Deep Clone With relatedRoutes (cloneDefinition)

  • Inline snippet: md_props_bag.cloneDefinition.relatedRoutes: [{"relatedRoute":"orders_rows","relatedIdField":"order_id"}].
  • Client runtime: when md_clonable = true, the clone also passes related routes to dataSrv.clone(...).
  • Server runtime: MetaService.CloneRecord receives relatedRouteToClone and can clone parent + children in a single flow.
  • Typical use: orders + order rows, headers + details, wizard master/detail.

Dynamic Route Parameters (parameters + customizationCallback)

  • Inline snippet: md_props_bag.parameters: [{"Name":"lang","Type":"string","enabled":true,"value":"{{currentUser.lingua.id}}","customizationCallback":"param.mc_show_in_filters=true;"}].
  • Client runtime: parameters are converted to parameterInfo (runtime filter fields) with visibility/editability driven by the parameter.
  • Server runtime: resolved values enter the route pipeline (getFlatRecordData) along with filterInfo/sortInfo/pageInfo.
  • Practical note: customizationCallback allows adapting parameter field behavior without frontend hardcoding.

Assisted Lookup in the Metadata-editor

  • Recommended inline flow: suggestLookup2 -> suggestLookupDefaultFilter -> getLookupListByRoute/getSeletClauseByLookupHierarchy.
  • Client runtime: the contextual editor automatically populates the main mc_ui_lookup_* fields and suggests filter/hierarchical consistency.
  • Server runtime: suggestions rely on MetaService.* endpoints for lookup routes and select clauses.
  • For lookup widget details see Widget Lookup; for contextual lookup/TS code see Widget Code Editor.
  • For the metadata-driven notification scenario see also Notifications (md_props_bag.notifications.triggerRules node).

Column Metadata (_metadati__colonne)

Identity and presentation

  • mc_nome_colonna: logical field name. Client: field binding in editor/grid/filter. Server: select/update field mapping.
  • mc_real_column_name: physical DB name. Client: normally transparent. Server: actual SQL mapping.
  • mc_display_string_in_view: list caption. Client: column header. Server: no direct impact.
  • mc_display_string_in_edit: form caption. Client: editor label. Server: no direct impact.
  • mc_ordine: display order. Client: field/column order. Server: metadata ordering.
  • mc_ui_column_type: editor type (text, number_*, date, datetime, lookupByID, upload, button, etc.). Client: editor/view widget selection. Server: parsing/filter semantics.

Visibility and behavior

  • mc_hide_in_list: hides in grid. Client: column not rendered. Server: may remain in query if needed.
  • mc_hide_in_edit: hides in edit form. Client: field not editable via form. Server: possible update from callback.
  • mc_hide_in_detail: hides in detail. Client: invisible in detail view. Server: unchanged.
  • mc_hide_in_export: excludes from export. Client: export without field. Server: filtered export select.
  • mc_hide_in_service: excludes from exposed services. Client: unchanged. Server: reduced API serialization.
  • mc_show_in_filters: shows filter in UI. Client: field appears in filter bar. Server: enables criteria on column.
  • mc_disable_sorting: disables column sorting. Client: header not sortable. Server: blocks ORDER BY on field.

Validation and defaults

  • mc_default_value: static default. Client: prefill on insert. Server: fallback when value is missing.
  • mc_default_value_callback: dynamic default. Client: executes callback at runtime. Server: no direct effect.
  • mc_validation_required: required flag. Client: error before save. Server: additional validation if applicable.
  • mc_validation_type: validation type (email, url, creditcard, number, date). Client: standard validation rules. Server: not mandatory, depends on endpoint.
  • mc_validation_pattern: custom regex. Client: pattern check. Server: optional.
  • mc_validation_custom_callback: custom callback. Client: custom validation logic. Server: unchanged.

Lookup and relations

  • mc_ui_lookup_entity_name: lookup metadata route. Client: lookup datasource. Server: join/expand lookup when requested.
  • mc_ui_lookup_dataValueField: lookup id field. Client: value binding. Server: id filter/relation.
  • mc_ui_lookup_dataTextField: lookup description field. Client: combo/grid text. Server: lookup text select.
  • mc_ui_lookup_filter: base lookup filter. Client: restricts combo options. Server: WHERE on lookup route.
  • mc_serverside_operations: server-side lookup operations. Client: paginated search. Server: on-demand lookup paging/filter.
  • mc_ui_pagesize: lookup page size. Client: lookup combo page size. Server: lookup query limit.
  • mc_logic_allow_navigation: enables link from cell to related route. Client: clickable anchor. Server: unchanged.

Custom logic and performance

  • mc_suggest_value_callback: suggest callback. Client: populates suggest/input helper. Server: executed in the callback runtime pipeline.
  • mc_selection_changing_custom_function: pre-change hook. Client: intercepts value change before commit. Server: unchanged.
  • mc_selection_changed_custom_function: post-change hook. Client: cascading reactions in form. Server: unchanged.
  • mc_logic_converter_read_callback: read converter. Client: value format/normalization. Server: unchanged.
  • mc_logic_converter_write_callback: write converter. Client: transformation before save. Server: normalized payload.
  • mc_custom_select_clause: custom select. Client: requires consistent rendering handling. Server: modifies SQL select.
  • mc_custom_join: custom join. Client: expands available data. Server: modifies query FROM/JOIN.
  • mc_props_bag: extra field configuration. Client: advanced editors/JSON schema/suggest. Server: custom rule support.

Upload and button

  • isImageUpload, isDBUpload, isMultipleUpload: upload strategy. Client: upload widget preview/multi file. Server: blob/path persistence.
  • allowed_file_types, max_file_size: upload limits. Client: pre-upload file validation. Server: final validation.
  • customUploadHandlerPath: custom upload handler. Client: custom endpoint. Server: dedicated upload pipeline.
  • mc_button_caption: custom column-type button label. Client: action button caption. Server: unchanged.
  • mc_button_action: button action callback. Client: action execution on click. Server: optional custom API call.
  • mc_button_visibility_condition: conditional button visibility. Client: show/hide action per record. Server: unchanged.

Menu Metadata (_metadati__menu)

Main properties

  • mm_id: menu item id. Client: tree/menu identity and DnD ordering. Server: PK for update/reorder/nest/remove.
  • mm_parent_id: parent menu. Client: hierarchical structure. Server: persisted nesting.
  • mm_ordine: visual order. Client: deterministic menu order. Server: reorder update.
  • mm_display_string_menu: UI label. Client: menu item text. Server: presentation metadata.
  • mm_uri_menu: associated route/url. Client: hash route navigation. Server: no direct SQL.
  • md_id: link to metadata route. Client: menu->feature relation. Server: also used in route authorization checks.
  • mm_is_visible_by_default: default visibility. Client: item visible unless restricted. Server: fallback if no specific rule exists.
  • mm_icon: menu icon. Client: icon rendering. Server: presentation metadata.
  • mm_props_bag: menu JSON extensions. Client: custom menu behavior. Server: optional.

Table Custom Actions (_Metadati_Custom_Actions_Tabelle)

  • Id: action id. Client: menu/action list key. Server: PK.
  • md_id: target table. Client: actions tied to the current route. Server: filter by metadata route.
  • button_caption: button text. Client: action toolbar/row label. Server: presentation metadata.
  • button_template: button template. Client: custom action rendering. Server: unchanged.
  • button_image: button icon/image. Client: UI iconography. Server: unchanged.
  • tooltip: action hint. Client: hover help. Server: unchanged.
  • action_callback: execution callback. Client: invoked on click. Server: can trigger endpoint calls.
  • disable_callback: enable/disable callback. Client: dynamic enable/disable. Server: unchanged.
  • md_action_type: action type (toolbar/row/context). Client: action position. Server: functional mapping. Values supported by the suggester (MetaService.suggestTableActionCallback):

- 0 navigation, 1 method.call (AsmxProxy), 2 generate.file, 3 export (xls/pdf), 4 call.stored,

- 5 approve, 6 parametric.dialog, 7 client sync, 8 client async, 9 show route payload,

- 10 upload — opens a file picker (XLS/XLSX/CSV); the backend (UploadHandlerCustom + metaQuery.UploadToDynamicTable) creates/populates a SQL table with dynamic columns derived from the file headers, then runs a stored procedure with @TableName, @UserId, @RowCount. Suggester params: target_table (SQL table name), target_stored (stored name), target_mode (replace = DROP + CREATE + INSERT, default; truncate = CREATE IF NOT EXISTS + TRUNCATE + INSERT; append = CREATE IF NOT EXISTS + INSERT). Since 1.7.13 the action is reserved to administrators (superadmin role).

  • ordine: visual priority. Client: action ordering. Server: order persistence.

Table Authorizations (_Metadati_Utenti_Autorizzazioni_Tabelle)

  • muat_id: rule id. Client: rule selection/edit. Server: PK.
  • md_id: target table. Client: current route scope. Server: rule filter.
  • ruolo_id: target role. Client: rule per role. Server: enforcement by role.
  • utente_id: target user. Client: per-user override. Server: enforcement by user.
  • muat_view: view permission. Client: route/menu hidden if denied. Server: data access block.
  • muat_edit: edit permission. Client: edit buttons disabled/hidden. Server: update block.
  • muat_insert: insert permission. Client: hide add/new. Server: insert block.
  • muat_delete: delete permission. Client: hide delete. Server: delete block.
  • muat_override_record_restriction: record restriction override. Client: can change dataset visibility. Server: bypasses record-level restrictions.

Column Authorizations (_Metadati_Utenti_Autorizzazioni_Colonne)

  • muac_id: rule id. Client: rule selection/edit. Server: PK.
  • mc_id: target column. Client: field-level scope. Server: field permission filter.
  • ruolo_id: target role. Client: per-role policy. Server: field enforcement.
  • utente_id: target user. Client: per-user override. Server: user enforcement.
  • muac_editable: field editability. Client: field readonly/disabled. Server: field update hardening.
  • muac_validation_required: required override. Client: contextual field validation. Server: data semantic consistency.

Table Styles (_Metadati_UI_Stili_Tabelle)

  • must_id: style rule id. Client: rule tracking. Server: PK.
  • md_id: target table. Client: grid route scope. Server: route rule filter.
  • must_attribute_name: CSS class to apply. Client: class added to the row. Server: metadata.
  • must_attribute_value: JS callback/condition that returns a boolean. Client: decides whether to apply the class. Server: metadata (no SQL evaluation).

Column Styles (_Metadati_UI_Stili_Colonne)

  • musc_id: column style rule id. Client: rule tracking. Server: PK.
  • musc_attribute_name: style class/attribute. Client: cell/column style. Server: metadata.
  • musc_attribute_value: static value. Client: direct style/attribute application. Server: metadata.
  • musc_attribute_value_callback: dynamic callback. Client: conditional style per record/cell. Server: metadata.

Condition Groups / Items / Actions

  • CG_Id: condition group. Client: logical rule cluster. Server: conditional metadata structure.
  • CI_Id: single condition. Client: runtime formula/operator evaluation. Server: used in business policies.
  • CAG_Id: conditional action group. Client: action bucket linked to conditions. Server: execution orchestration.
  • CAI_Id: action item. Client: runtime action triggers. Server: can affect API-side update/flow.
  • FK_*: relationship keys between group/item/action. Client: consistent navigation in the editor. Server: metadata relational integrity.

Cross-cutting Client/Server Effects

  • Client:
  • dynamic component rendering (list, form, map, chart, etc.) from metadata.
  • UI enable/disable states consistent with authorizations.
  • custom validations and callbacks in edit/filter/grid.
  • Server:
  • dynamic query composition (SELECT, WHERE, ORDER, paging/cursor).
  • route/table/column permission enforcement.
  • auditing and record-level restrictions.

Dates and time zones in the write APIs

Rule for date and date/time columns in MetaService.insertRecord, updateRecord, batchRecord and in the import. The same rule applies to grid filters (range bounds included), pivot filters and the optimistic concurrency check (__original). This is a closed decision (user, 19/10/2026).

  • Columns without a time zone: SQL Server datetime, datetime2, smalldatetime, date; MySQL datetime, timestamp, date; PostgreSQL timestamp, date; Oracle DATE, TIMESTAMP, TIMESTAMP WITH LOCAL TIME ZONE. A value with Z or an offset is an instant and becomes the server's local time (same instant): this is how the form writes, without an offset, and how the values already in the DB are stored. A value without an offset is stored as is.
  • Columns with an offset: SQL Server datetimeoffset, PostgreSQL timestamptz / timestamp with time zone, Oracle TIMESTAMP WITH TIME ZONE. The value is stored with its own offset, with no conversion; without an offset it counts as UTC. PostgreSQL stores the instant and normalizes it to UTC (it shows it in the session time zone), Oracle keeps the offset. The form, the scheduler and the spreadsheet write the browser's local time with its offset on these columns (same instant); a value that already has an offset, such as the one read, is sent unchanged.
  • MySQL has no offset type: timestamp is handled like datetime. Oracle TIMESTAMP WITH LOCAL TIME ZONE is handled like datetime. On these two types the DB reads the written local time in the session time zone: the DB session time zone must be the server's.
  • The type is recognized through mc_db_column_type: columns with an offset have datetimeoffset. On existing installs a migration at boot moves PostgreSQL timestamptz and Oracle TIMESTAMP WITH TIME ZONE columns to datetimeoffset in the metadata. The migration runs only once (recorded in _wuic_data_migrations): a column set back to datetime by the administrator stays that way on later restarts. If a column is skipped (the route's connection cannot be checked at boot) the migration is not recorded and logs a WARN at every boot, as long as the column is still undecided.
  • Grid filters: the lib sends a date-only value as the browser's local day (yyyy-MM-dd), a date/time without time zone as the browser's local time without offset (as the grid shows it), and on a column with an offset the local time with the browser's offset. The server takes the day as it is (no more +1h correction); an instant (older clients, ...T22:00:00.000Z) becomes the server's local time and its date is taken. The same format applies to the XLS export (also from the toolbar), to the filters written in the URL (links, page reload, saved state) and to the link from the grid to the report; an instant as text (older links) on a date or date/time column is sent as the browser's local day or time, like the Date it came from.
  • Text that is not ISO 8601 answers 400 errors.input.date_not_iso (the import also reads the server culture format, see Import).

Examples with the server in Rome (UTC+2 in October):

Column typeValue sentValue stored
SQL Server datetime2 / datetime / smalldatetime2026-10-13T12:00:00Z2026-10-13 14:00:00
SQL Server date2026-10-13T23:30:00Z2026-10-14
MySQL datetime2026-10-13T14:30:00+05:002026-10-13 11:30:00
MySQL timestamp2026-10-13T12:00:00Z2026-10-13 14:00:00
PostgreSQL timestamp2026-10-13T14:30:002026-10-13 14:30:00
Oracle DATE / TIMESTAMP / TIMESTAMP WITH LOCAL TIME ZONE2026-10-13T12:00:00Z2026-10-13 14:00:00
SQL Server datetimeoffset2026-10-13T14:30:00+05:002026-10-13 14:30:00 +05:00
SQL Server datetimeoffset2026-10-13T14:30:002026-10-13 14:30:00 +00:00
PostgreSQL timestamptz2026-10-13T14:30:00+05:002026-10-13 09:30:00+00
Oracle TIMESTAMP WITH TIME ZONE2026-10-13T14:30:00+05:002026-10-13 14:30:00 +05:00

Screenshot

metadata-integration / metadata context editor detail
metadata-integration / metadata context editor detail
metadata-integration / metadata context editor main
metadata-integration / metadata context editor main
metadata-integration / metadata-editor-auth-column-edit-popup
metadata-integration / metadata-editor-auth-column-edit-popup
metadata-integration / metadata-editor-auth-column
metadata-integration / metadata-editor-auth-column
metadata-integration / metadata-editor-auth-table-edit-popup
metadata-integration / metadata-editor-auth-table-edit-popup
metadata-integration / metadata-editor-auth-table
metadata-integration / metadata-editor-auth-table
metadata-integration / metadata-editor-columns-edit-popup
metadata-integration / metadata-editor-columns-edit-popup
metadata-integration / metadata-editor-columns
metadata-integration / metadata-editor-columns
metadata-integration / metadata-editor-condition-groups-edit-popup
metadata-integration / metadata-editor-condition-groups-edit-popup
metadata-integration / metadata-editor-condition-groups
metadata-integration / metadata-editor-condition-groups
metadata-integration / metadata-editor-custom-actions-edit-popup
metadata-integration / metadata-editor-custom-actions-edit-popup
metadata-integration / metadata-editor-custom-actions
metadata-integration / metadata-editor-custom-actions
metadata-integration / metadata-editor-styles-column-edit-popup
metadata-integration / metadata-editor-styles-column-edit-popup
metadata-integration / metadata-editor-styles-column
metadata-integration / metadata-editor-styles-column
metadata-integration / metadata-editor-styles-table-edit-popup
metadata-integration / metadata-editor-styles-table-edit-popup
metadata-integration / metadata-editor-styles-table
metadata-integration / metadata-editor-styles-table
metadata-integration / metadata-editor-table-edit-popup
metadata-integration / metadata-editor-table-edit-popup
metadata-integration / metadata-editor-table
metadata-integration / metadata-editor-table
metadata-integration / metadata-menu-management-edit-popup
metadata-integration / metadata-menu-management-edit-popup
metadata-integration / metadata-menu-management
metadata-integration / metadata-menu-management