34 WhatIf Templates - WhatIf Editor

As of 2021.01 the new WhatIf functionality is being introduced with the intention to remove the outdated WhatIf functionality by 2024. This new WhatIf functionality uses WhatIfTemplates which can be populated in the WhatIf Editor, i.e. the display to create whatif-instances that can be applied to a workflow. The new WhatIf functionality works in 2021.01 and 2021.02 only in Stand-Alone, while from 2022.01 onwards all features work also on live systems.

		<explorerTask name="WhatIf">
			<predefinedDisplay>what if editor</predefinedDisplay>
			<toolbarTask>true</toolbarTask>
			<menubarTask>true</menubarTask>
			<loadAtStartup>true</loadAtStartup>
		</explorerTask>

The connection between WhatIfs-instances and workflows is (as of 2022.01) established via the WorkflowDescriptors, where a <whatIfTemplateId> can be defined (one of the last elements).

Note: this is a non-backward compatible change from 2021.02 and earlier releases where the connection between workflows and WhatIfTemplates was defined in the Topology.xml.

	<workflowDescriptor id="Test_WhatIfSettings" name="Test_WhatIfSettings" forecast="true" visible="true" autoApprove="true">
		...
		<whatIfTemplateId>test_whatif</whatIfTemplateId>
	</workflowDescriptor>

What-ifs are by default non-approved runs, unless the user puts a check in the approve checkbox of the GUI.

You can use the IFD-config option <enableAutoApprove> to bring the auto approve button to the attention of the user.

        <node id="run_whatif_properties" name="wf1 t1 Properties">
            <workflowId>Test_WhatIfSettings</workflowId>
			<enableAutoApprove>false</enableAutoApprove>

The WhatIf Editor uses the whatifTemplates.xsd schema. This schema allows the configuration of a whatif-template, which is used in the WhatifEditor GUI to allows the specification of properties and modifiers to be applied in a whatif-instance. Multiple whatIfTemplate.xml files are supported as long as their prefix is WhatIfTemplates_....xml and no duplicate identifiers are used across the files. Identifiers defined in one xml-file can be used in another xml-file.

Properties can be specified directly (string, int, double, boolean) or by selection from an enumeration or by selection from a configuration file (e.g. moduledataset, module parameter file).
Note: if a whatif-property is used as a key in a time series set, this time series set has to be simulated forecasting.

Modifiers can be specified per modifierType. The actual behaviour of the modifier depends on the setting of <whatIfModifierType> element for this modifierType, as explained in detail in the ModifierTypes.xml:

1. always apply in workflow (default)
2. apply according to creation method (since 2022.02)
3. apply modifier if referenced in a what-if workflow
4. never apply in a what-if workflow (i.e. always apply unless running a workflow with a whatif attached)

    <timeSeriesModifier id="modify_timeseries_only_applied_in_whatif" name="Modify time series (only applied in whatif)">
        <whatIfModifierType>apply if referenced in what-if workflow</whatIfModifierType>
        <timeSeries>....

The whatIfTemplates-schema

<?xml version="1.0" encoding="UTF-8"?>
<whatIfTemplates xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/whatIfTemplates.xsd">
</whatIfTemplates>

The whatifTemplates-schema contains two main sections:

• valueTypes: to specify the kinds of properties and their limitations
• whatifTemplates: to compose which properties and modifiers can be specified in the template. whatifTemplates can be nested (but not unlimited in the GUI)

valueTypes

valueTypes define the kind of properties that can be associated to a whatIfTemplate. Each valueType has a number of attributes with at least an id (required) and an optional default value. Additional attributes depend on the valueType. By allowing multiple valueTypes of the same kind, different display behaviour can be accommodated (e.g. different min/max.ranges for numeric properties).

Attribute id refers to the identifier used to connect this value type to the property in the whatIfTemplate.

Optional attribute default refers to the default value incoporated in the whatIf-instance and shown in the display.

enumeration

The valueType enumeration results in a string-property value. The enumeration will list the items available in the dropdown box of the WhatIfEditor.

Required attribute code refers to the value which is stored when this option is chosen.

Optional attribute label refers to the Caption of this value in the display.

If no default value is defined the first item will be shown as selected value in the display.

configFile

The valueType configFile results in a string-property value refering to a moduleDataSet-file, a moduleParameterFile or a coldState-file. Based on the search pattern the Configuration (either available in the database or the file system) will be queried for items to populated the dropdown box of the WhatIfEditor.

Attribute type refers to the type of config file (i.e. module dataset, module parameter, cold state).

Attribute pattern refers to the search pattern to apply.The result will be a list of config files for the dropdown box that meets this search pattern.

Attribute hidePattern option indicates whether the pattern should be stripped from the value shown in the dropdownbox.

Attribute default refers to the default value selected and shown in the dropdown box. Be aware that the default value should account for the hidePattern option. When hidePattern is false, the default should include the full string including the search pattern. When hidePattern is true, the default value should include only the selected postfix.

    <valueTypes>
        <configFile hidePattern="true" id="select_moduledataset" pattern="moduledataset_*" type="module dataset" default="grid_A"/>
        <configFile hidePattern="false" id="select_moduleparfile" pattern="moduleparfile_fixed_*" type="module parameter" default="moduleparfile_fixed_base"/>

If no default value is defined the first item will be shown as selected value in the display.

string

The valueType string allows the user to specify any string value they like in a text field.

If no default value is defined the item has an empty value in the display.

int

The valueType int allows the user to specify any string value they like in a text field.

Optional attribute min specifies the minimum value accepted in the display.

Optional attribute max specifies the maximum value accepted in the display.

double

The valueType double allows the user to specify any string value they like in a text field.

Optional attribute min specifies the minimum value accepted in the display.

Optional attribute max specifies the maximum value accepted in the display.

bool

The valueType bool allows the user to turn on/off a checkbox value.

whatIfTemplateId (since 2022.01)

 The valueType whatIfTemplateId allows the user to specify that input series to this whatif run need to come from another whatif run. A typical use case is a situation where one wants to choose from a set of computed hydrological inflow scenarios to select a specific (climate/weather) scenario as an input to a 'light' reservoir or water quality model to investigate various intervention strategies.

This is deviation of default Delft-FEWS behaviour where a workflow always uses simulated series of the Current run. By referencing a whatif to be used as input, the timeseries of this (approved) whatif run will be selected, neglecting the Current run. Please note that, due to code complexity, this feature is explicitly not intended to inherit whatif content (i.e. property values and modifier values) from one whatif-template into another template.

dateTime

The valueType dateTime is not implemented yet.

whatIfTemplate

The whatIfTemplate section defines the actual whatIfTemplate shown in the display to populate specific whatIf-instances with data values.

Required attribute id refers to the identifier of the whatIfTemplate. This id can be referenced in the Topology to make the connection with a workflow where the whatif can be applied.

Required attribute name refers to the template name (i.e. caption) used in the display.

whatIfExpiryTime (since 2022.01)

The default expiry time of the whatIf can be overruled with the custom expiry time configured in whatIfTemplate with the element ‘whatIfExpiryTime’. This custom expiry time will be used also for the modifiers associated with the whatIf’s created using the whatIfTemplate

properties

Lists all properties to be defined in the whatIf and shown in the display either as text field or dropdown item dependent on the valuetype.

property

Required attribute id is the property-key as applied in the workflow

Optional attribute name is the name/caption as shown in the display.

Required attribute valueTypeId refers to one of the valueTypes defined earlier.

Optional element description which will show as tooltip in the editor (since 2024.01)

modifierType

Identifies the modfierType for which all available committed modifier-instances will be shown in the dropdown box. By default no modifier is selected.

Note: By selecting a modifier-instance a copy of this selected modifier is created which is tightly related to the whatif-instance. Value changes in the original modifier (resulting in a new modifier-instance) will therefore not be reflected in the whatif. To incorporate changed modifier values, the modifier-instance should be reselected in the display to obtain a copy of this new modifier-instance.

whatIfTemplateId

Accommodates nesting of whatIfTemplate sections to bring some structure in the display appearance.

Final note

1. WhatIfTemplate identifiers are stored as part of the whatif-instance, also when archived. Changing whatIfTemplate-identifiers may thus break retrieval of archived whatifs (i.e. no similar as other archive exchanges)
2. The relation between modifiers and whatifs is stored at the modifier side. Exported whatifs are unaware of associated modifiers, although the exported zip-file will include both the whatif.xml and the modifiers.xml if needed.
3. As of 2022.01, a TypicalProfile modifier is introduced to enable full replacement of the legacy whatif-functionality.
4. Attached configuration example demonstrates various alternatives to prepare and utilize properties and modifiers in whatifs.