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
AllowPartialUserFlowandAggregationExpression, and the oldKonstrukt_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.ExpandAllValueTypesdefaults totruewhen no value types are listed, otherwisefalse.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.DimValueNois the code andDimValueNamethe display name. An empty name is read as a single space, which is how blank spacer rows are made.LanguageisKex(v2 plans) orJavaScript(v1). A missing attribute meansJavaScript. On save, the language is set from the plan version.Numerator+Denominator(with an emptyValue) marks aLegacyQuotexpression. OtherwiseValueholds aStandardexpression.- Writeback attributes:
WritebackExpression,WritebackDimValueNo,WritebackSpread,EditPrecision. Older files withoutWritebackSpreadon value-type-dimension expressions are backfilled toProportional.
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 useTypeinstead. - 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 whatload_complete_app_configreturns. - Output can contain
LegacyActionComponents: []on workspaces, which the schema does not define. - Dataset IDs are integers (
"Id": 1on a dataset,"DatasetId": 1on 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.