Docs

Apps

App configuration (XML/JSON)

Reference for the configuration behind an app: the XML structure and schema version, what saving preserves, the JSON representation and schema exposed through MCP, and an element reference.

Everything configured in the app editor is stored as one configuration document per app. It is stored as XML and exposed as typed JSON through the MCP server. This page is a reference for people and agents who read or write that configuration directly. For what the settings mean, follow the links to the conceptual pages: Datasets, Workspaces and components and Actions.

Ways to access the configuration#

Route Read Write Format
App editor yes yes graphical
Edit XML (Redigera XML) in the app menu (⋯) yes yes XML
MCP: load_complete_app_config, search_app_config yes (v1 and v2 plans) JSON
MCP: patch_app_config, overwrite_complete_app_config, create_app_with_config yes (v2 plans only) JSON

The admin editor reads and writes the XML through these endpoints:

Operation Endpoint
Read GET /api/admin/plans/{planId}/apps/{appId}/xml
Save POST /api/admin/plans/{planId}/apps/{appId}/xml
Validate POST /api/admin/appconfig/validate/xml and …/xml/configvalidated

Internal endpoints

The admin endpoints above belong to the internal API used by the editor. They are not part of the public, supported REST API and may change without notice. To read and write app configuration programmatically, use the MCP server (see JSON representation via MCP).

Before editing by hand#

Saving is not round-trip#

When a configuration is saved, the server does not store the submitted XML as it is. It parses it into the configuration model, serialises the model to new XML, and then patches the new XML with selected parts of the old one. That patch list contains exactly one path today:

/App/Config/Datasets/DataSet/Styles

(Styles is a legacy dataset styling block with no editor. The model only reports that it exists.)

Consequences:

  • Anything the model does not read is dropped on the next save: XML comments, custom or unknown attributes, formatting and element order that the model does not preserve.
  • Attributes that are only read by the legacy app engine, such as AllowPartialUserFlow and AggregationExpression, and the old Konstrukt_Std_* component types, are not read by the current model and do not survive.
  • A hand edit is kept only if it is expressed in elements and attributes that the model reads. Check the result by reading the configuration back after saving.

Component errors are found late#

The XML validation schema is deliberately open around <Component>, because it cannot vary the allowed content by the Type attribute. An error inside a component is therefore only found when the configuration is deserialised, and the message has no line or column number. Change one component at a time.

What is not in the configuration#

The app's name, description, status and some access flags are stored on the app record, not in the configuration. The Name and Description attributes on <App> that appear in the XML validation schema are not read. They would only be stale copies.

In practice:

  • copying the XML from one app to another does not copy the name or description;
  • through MCP, name and description are parameters of create_app_with_config, not part of the JSON.

Schema version and migrations#

The root element carries SchemaVersion. The current version is 1.50. When a configuration is read it is migrated step by step (1.39 → 1.42 → 1.45 → 1.452 → 1.48 → 1.50), followed by migrations that depend on the plan version. These migrations convert dataset expressions and remove legacy action components in v2 plans. Always write the current version.

XML structure#

<App SchemaVersion="1.50">
  <Config>
    <Datasets>
      <DataSet Id="1" Name="Budget">                   <!-- 1..n -->
        <Groupings><Initial><Grouping … /></Initial></Groupings>
        <ValueTypes SortById="false" SortingMethod="Natural">
          <ValueType Value="Amount" Aggregation="Sum" SpreadValue="0" Condition="…">
            <ExcludedDimensionValueDefaults>
              <Code DimensionId="Project" Value="0" />
            </ExcludedDimensionValueDefaults>
          </ValueType>
        </ValueTypes>
        <InitialValues Enabled="true"><Set …>…</Set></InitialValues>
        <LockedValues Enabled="true"><Set>…</Set></LockedValues>
        <Filters><Filter>…</Filter></Filters>
        <Expressions><Dimensions DimensionId="…"><Expression … /></Dimensions></Expressions>
        <DataTypes … />
        <InheritRowLevelAccess EnableDimensionBasedAccess="true" ReadOnly="false" />
      </DataSet>
    </Datasets>
  </Config>
  <Workspaces>
    <Workspace Id="1" Name="Budget entry" Hidden="false">   <!-- 1..n -->
      <Filter>…</Filter>
      <ActionComponents>…</ActionComponents>
      <Layout Type="MultiPage|Matrix">…</Layout>
      <PlanData Value="Selected" UsePlanName="false" />
      <References><Reference Id="12" Selected="true" /></References>
      <DataTypeSortOrder>…</DataTypeSortOrder>
      <ValueTypes>…</ValueTypes>
      <ValueTypeSortOrder>…</ValueTypeSortOrder>
    </Workspace>
  </Workspaces>
  <Access Locked="false" Enabled="true" AccessListId="3" />
</App>

Access holds app access (see Apps). Without it, default access applies.

Recurring idiom: absence, presence, presence with a flag#

Several three-state settings in the editor are encoded by whether an element exists and whether it carries a flag:

Setting Absent Present Present with flag
Workspace filter Unavailable Available Required (IsRequired="true")
Workspace reference Unavailable Available (Selected="false") Default (Selected="true")

Dimension and property rows#

A dataset dimension and a dataset property are both <Grouping> elements:

<!-- a dimension -->
<Grouping Value="Department" SortByDimValueNo="false" SortingMethod="Natural" />

<!-- a property of a dimension -->
<Grouping Value="DimTagNo" DimTagGroupId="101" DimensionId="Account"
          SortByDimValueNo="false" SortingMethod="Natural" DisplayFormatId="4" />

Value="DimTagNo" marks the row as a property. The property is identified by DimTagGroupId together with DimensionId.

Initial values sources#

The expansion source is not written explicitly. It is derived:

XML Source
TakeFromDataSet="true" ValuesInDataset
<Values> present SpecifiedValues
no <Values> AllValuesInDimension

Further rules:

  • DimensionId="ValueTypeId" is the virtual dimension used to select value types.
  • <References><Ids> expands from a reference; only the first <References> element is used.
  • <PlanDataValueTypes><Ids> expands from other value types.
  • ExpandAllValueTypes defaults to true when no value types are listed, otherwise false.
  • Enabled="false" on <InitialValues> or <LockedValues> makes the whole block ignored.
  • DimensionId="DataType" is ignored in both blocks. An empty <Set /> is harmless.

Expressions#

  • <Dimensions DimensionId> says which dimension the expression creates a value on.
  • DimValueNo is the code and DimValueName the display name. An empty name is read as a single space, which is how blank spacer rows are made.
  • Language is Kex (v2 plans) or JavaScript (v1). A missing attribute means JavaScript. On save, the language is set from the plan version.
  • Numerator + Denominator (with an empty Value) marks a LegacyQuot expression. Otherwise Value holds a Standard expression.
  • Writeback attributes: WritebackExpression, WritebackDimValueNo, WritebackSpread, EditPrecision. Older files without WritebackSpread on value-type-dimension expressions are backfilled to Proportional.

Column setting IDs#

<Setting Type="Column"> identifies the column with Value, while <Setting Type="ColumnGroup"> uses Id. The attribute names differ and are easy to mix up. (In JSON both use Id.) Column IDs follow the grammar <axis>[~<code>]:

Pattern Example Column
GROUP_COL_ID the merged grouping column
<DimensionId> Department the dimension's column (or its total column when pivoted)
<DimensionId>~<code> Month~202601 a pivoted column for one dimension value
<DimensionId>_<propertyId> Account_101 a property column
<DimensionId>_<propertyId>~<code> Month_102~01 a pivoted property column
ValueTypeId~<code> ValueTypeId~Amount a pivoted value type column

See Workspaces and components for what the settings do.

Scripts in attributes#

An action's script is stored in the Script attribute, so that whitespace and line breaks are preserved. Escape ", <, > and & as XML entities when editing by hand.

XML and JSON names#

The JSON model uses different names for some XML attributes:

XML JSON GUI
Grouping rows DatasetDimensions[] dimensions matrix
DimTagGroupId DimensionPropertyId property
SortByDimValueNo="true" / "false" SortBy: "Code" / "Name" Sort by
DisplayFormatId DisplayFormatId Display as
IncludeDimValueNo (legacy) DisplayFormatOverride not supported in the current end-user interface
ValueType/@Name NameOverride name override
SpreadValue SpreadOverride Spread
DimValueNo / DimValueName DatasetDimensionValueCode / DatasetDimensionValueName Code / Name
WritebackDimValueNo WritebackExpression.DatasetDimensionValueCode destination
MultiSelect Multiple Multiple
SortById SortBy
Layout/@Type Layout.$type (MultiPage, Matrix) Layout
Component/@Type $type Type
<Variables> VariableInputs Variables

Enumerations are stored by name except where a numeric code is shown in the tables on the conceptual pages (spread, format code, line state, line access, display format).

JSON representation via MCP#

The MCP server exposes the configuration as JSON:

Tool Purpose
get_app_config_schema describe the configuration types: without types the root and every type name; with types (["WorkspacePage", "MatrixLayout"]) each type's properties, which are required, the $type of each variant and the types they refer to
search_app_config find parts of a configuration with a JSONPath ($..MainComponent) or JSON Pointer; each match returns its pointer
load_complete_app_config read a whole configuration (v1 and v2 plans)
patch_app_config change parts of a configuration with a JSON Patch (v2 plans only)
overwrite_complete_app_config replace a whole configuration (v2 plans only)
validate_complete_app_config validate a configuration without saving (v1 and v2 plans)
create_app_with_config create an app with name, description and configuration in one call (v2 plans only)
delete_app permanently delete an app
list_apps list apps in a plan (id is a GUID, plus name and description)

Reads return the configuration together with an etag. Pass it as ifMatch to patch_app_config or overwrite_complete_app_config, and the write is rejected if someone changed the configuration in the meantime.

patch_app_config takes an RFC 6902 JSON Patch array (add, remove, replace, move, copy, test) plus merge, which applies a JSON Merge Patch at a position and leaves unnamed properties alone. Positions are JSON Pointers from search_app_config, or a JSONPath that matches exactly one position. The whole patch is applied together: if one edit fails, nothing is saved. dryRun: true validates and reports the changes without saving.

[{"op": "test",  "path": "/Workspaces/0/Name", "value": "Budget entry"},
 {"op": "merge", "path": "/Workspaces/0", "value": {"Name": "Budget input"}}]

Prefer search_app_config and patch_app_config to reading and rewriting the whole configuration; configurations can be large. Use replace, not merge, when changing the $type of a node, so that properties of the old type do not survive.

The JSON is described by a JSON Schema (draft 2020-12) with 153 definitions. Its root is AppConfigModel with the required members Id, PlanId, Datasets, Workspaces and Access. Read the types you need with get_app_config_schema: the full schema is about 123,000 characters, too large for most agents to use. It is also published as the MCP resource konstrukt://schema/app-config, for clients that can attach resources.

When a configuration does not match the format, validate_complete_app_config, patch_app_config, overwrite_complete_app_config and create_app_with_config show the expected shape of the type in the error: its properties, which are required, and the valid $type values.

Points to know:

  • Polymorphism uses $type (layouts, components, grid axes, settings, filters, expressions, row-level access, action components, variables). Component filter items and presentation-rule value conditions use Type instead.
  • Several fields are polymorphic (chart axes, action targets). Guessing their shape can produce a configuration that parses but silently omits data.
  • The model may contain implementation-specific details, and its structure is not guaranteed to be stable across versions. Always read the schema from the server rather than relying on a copy.
  • Colours are serialised without a leading # ("Light": "1F9AAD"), although the schema text describes them as hex with #. Follow what load_complete_app_config returns.
  • Output can contain LegacyActionComponents: [] on workspaces, which the schema does not define.
  • Dataset IDs are integers ("Id": 1 on a dataset, "DatasetId": 1 on a component). Component IDs are strings. Earlier versions of the format used strings for dataset IDs as well; a string now fails with The JSON value could not be converted to System.Int32.
  • The root Id (the app's GUID) is required, also when creating an app.
  • Reads return empty collections explicitly ("Expressions": [], "ColumnSettings": [] …).
  • MCP has no tool for renaming an app, changing its description or copying it.

A minimal configuration, for orientation only (validate against the schema before use):

{
  "Id": "…", "PlanId": 30,
  "Datasets": [{
    "Id": 1, "Name": "Budget",
    "DatasetDimensions": [
      {"DimensionId": "Account", "SortBy": "Code", "SortingMethod": "Natural"},
      {"DimensionId": "Month", "SortBy": "Code", "SortingMethod": "Natural"}
    ],
    "ValueTypes": {"SortBy": "Name", "SortingMethod": "Natural",
                   "Items": [{"ValueTypeId": "Amount", "Aggregation": "Sum", "SpreadOverride": 0}]},
    "RowLevelAccess": {"$type": "Inherit", "EnableDimensionBasedAccess": false, "ReadOnly": false}
  }],
  "Workspaces": [{
    "Id": 1, "Name": "Budget entry", "Hidden": false,
    "Filters": [{"$type": "ValueType"}, {"$type": "DataType"}],
    "ActionComponents": [],
    "DataTypes": {"PlanData": {"Value": "Selected", "UsePlanName": false}},
    "ValueTypes": {},
    "Layout": {"$type": "MultiPage", "Pages": [{
      "HideInPageSelector": false,
      "MainComponent": {
        "$type": "Grid", "Id": "1", "Name": "Budget", "DatasetId": 1,
        "RowTotal": "Left", "AutoSizeStrategy": "Default", "HideHeader": false,
        "EnableColumnTotals": true, "EnableUserConfig": true, "EnableComments": true,
        "Groupings": [],
        "Intermediaries": [{"$type": "Dimension", "DimensionId": "Account",
                            "Settings": {"$type": "Intermediary", "EnableEdit": false}}],
        "Pivots": [{"$type": "Dimension", "DimensionId": "Month",
                    "Settings": {"$type": "Pivot", "SortDirection": "Ascending"}}]
      }}]}
  }],
  "Access": {"Locked": false, "Enabled": true}
}

For agents

The safe editing order (get_app_config_schema → get → modify → validate → set → read back) and the known pitfalls — enum codes, $type versus Type, colours without #, silently removed icons — are in the Agent guide.

Element reference#

Element (XML) JSON Purpose Key attributes See
App AppConfigModel root SchemaVersion Apps
Access Access app access Locked, Enabled, AccessListId Apps
DataSet Datasets[] dataset Id, Name Datasets
Grouping DatasetDimensions[] dimension or property in the dataset Value, DimTagGroupId, DimensionId, SortByDimValueNo, SortingMethod, DisplayFormatId Datasets
ValueTypes/ValueType ValueTypes.Items[] value type in the dataset Value, Name, Aggregation, Condition, SpreadValue Datasets
ExcludedDimensionValueDefaults/Code ExcludedDimensionValueDefaults defaults for excluded dimensions DimensionId, Value Datasets
InitialValues/Set InitialValues[] expansion rule Enabled, ExpandAllValueTypes, TakeFromDataSet Datasets
LockedValues/Set LockedValues[] lock rule Enabled Datasets
Filters/Filter DatasetFilter dataset filter DimensionId, DimTagGroupId, codes Datasets
Expressions/Dimensions/Expression Expressions[] computed dimension value DimValueNo, DimValueName, Aggregation, Format, Precision, Language, OmitNullRows, Value, Writeback* Datasets
InheritRowLevelAccess / LimitRowLevelAccess RowLevelAccess row-level access EnableDimensionBasedAccess, AccessListId, ReadOnly Datasets
Styles (HasStyling) legacy dataset styling; preserved, not editable this page
Workspace Workspaces[] workspace Id, Name, Hidden Components
Workspace/Filter Filters[] filter row IsRequired, Message, Max, AllRequired, RequiredComponent Components
PlanData, References/Reference, DataTypeSortOrder DataTypes data types offered Value, UsePlanName, Id, Selected Components
Workspace/ValueTypes, ValueTypeSortOrder ValueTypes value type names and order Id, Name Components
Layout Layout layout Type Components
Page Pages[] page in a multi-page layout Hidden Components
MatrixComponent, Location Components[], Location component placement X, Y, Width, Height, Hidden Components
LayoutSettings Settings grid layout styling Spacing, BackgroundColor(DarkMode), BorderColor(DarkMode) Components
Component AppComponent component Id, Name, Type, HideHeader Components
Grid Filters/Set Filters[] component filter Mode, Filter/@Type Components
Grid column Setting ColumnSettings[] column settings Type, Value / Id, Width, Pinned Components
Rule PresentationRules[] presentation rule Enabled, NameIndex, DefaultRuleKey, Name, style attributes Components
MetricComparison Compare metric comparison Type, Mode, colours Components
ActionComponentGroup ActionComponentGroup group of actions Id, Name, Description Actions
ActionComponent ActionComponent action Id, Name, RunButtonLabel, HideInSidebar, Script Actions
Variables/Text, Numeric, Dimension, Property VariableInputs[] action variables Identifier, Name, type-specific attributes Actions
LegacyActionComponents legacy actions; removed in v2 plans Actions

Presentation rule attributes#

NameIndex is a random number from 0 to 19, set when a rule is created or copied. It only picks a placeholder name for the rule's preview in the editor. It has no other meaning. Default rules have NameIndex="-1" and a DefaultRuleKey. The name shown is Name if set, otherwise the label of the default rule key, otherwise the placeholder name.

Colour attributes come in pairs, FontColor / FontColorDarkMode and BackgroundColor / BackgroundColorDarkMode. In JSON they are grouped as Styles.FontColor.{Light,Dark}.

Schema enum values not covered here

The JSON Schema defines some enum values (for example additional line states and line access 0) that are internal or legacy and are deliberately not described in these docs. Do not use values that are not listed on the conceptual pages.