Workflow descriptors file

The schema-companion to the Workflows & scheduling task guide. This file is the registry that makes a workflow available in the UI. This page is the generated field list.

At a glance

Purpose : Registers each workflow so FEWS can offer and schedule it — the link between “the workflow file exists” and “the workflow can run.”

Folder : Config/RegionConfigFiles/

Root element : <workflowDescriptors> (version="1.0", required)

References : Workflow files by workflowFileName (defaults to the descriptor id).

Minimal example

Config/RegionConfigFiles/WorkflowDescriptors 1.00 default.xml

<?xml version="1.0" encoding="UTF-8"?>
<workflowDescriptors xmlns="http://www.wldelft.nl/fews" version="1.0">
  <workflowDescriptor id="ForecastRiver" name="River Forecast"
                      visible="true" forecast="true">
    <description>Import, transform, and export the river forecast</description>
    <workflowFileName>ForecastRiver</workflowFileName>
    <schedulingAllowed>true</schedulingAllowed>
  </workflowDescriptor>
</workflowDescriptors>

Field reference

Auto-generated from workflowDescriptors.xsd. Descriptions are the schema's own annotations.

Element <workflowDescriptors>

Attributes

Attribute	Use	Notes
version	required	fixed: 1.0.

Elements

Element	Type	Cardinality	Description
workflowDescriptor	WorkflowDescriptorComplexType	required · repeats
rootNode	RootNodeComplexType	optional	Since 2019.01 Configuration of the workflow tree. This tree is displayed in ManualForecast dialog. If no tree is configured, ManualForecast shows the workflows in a simple list
node	GroupNodeComplexType	optional · repeats	Since 2019.01 Nodes than can be referenced with nodeId in the tree configured with rootNode

WorkflowDescriptorComplexType

Attributes

Attribute	Use	Notes
id	required
stateWorkflowId	optional	Deprecated and obsolete since 2016.01, the general adapter export state activity is resolved in the workflow. The workflow that is delivering the states.
name	optional
visible	optional	default: true.
forecast	optional	default: true.
waitWhenAlreadyRunning	optional	default: false. Prevents two tasks running this workflow at the same time
allowApprove	optional	default: true. Indication whether the Approve-flag in ManualForecastDialog must be enabled or disabled. In Operator-Client system is this flag always disabled and unchecked.
allowEnsembleMemberSelection	optional	default: false. Indication whether an ensemble selection can be made in ManualForecastDialog. An ensemble selection will run the workflow only for the specified ensemble member indices
autoApprove	optional	default: false. Indication whether the Approve-flag in ManualForecastDialog must be checked or unchecked, when selecting a workflow. In Operator-Client system this flag is always disabled and unchecked.
autoSetSystemTime	optional	default: false. When a workflow is finished, the system time is automatically set to the T0 of that workflow.
showWarningInLogCompletion	optional	default: false. Report whether warning messages were logged during the execution of the workflow
onlyCheckThresholdsOfChangedSeries	optional	default: false. Indicate if threshold check should only be performed on series that where changed during current workflow.

Elements

Element	Type	Cardinality	Description
description	string	optional
workflowFileName	idStringType	optional	Defines the root workflow config file that should be started. By default, the config file name equals the workflow id. Multiple descriptors can share the same config file by using properties. The config file is used as template and the $key$ are replaced by the property values. The properties are replaced in all references found in the config files of child workflows and modules.
inputWorkflowId	idStringType	optional · repeats	Since 2018.02 Id of the workflow that delivers input time series for this workflow. Input workflow Id's are used to provide an overview of the interconnection between the various workflows
timeZone	timeZoneGmtStringType	optional	TimeZone used for all time steps without time zone referenced in this workflow. It is also used to generate threshold event log messages. It is not used when importing or exporting time series.
allowSelection	boolean	optional
cardinalTimeStep	TimeStepComplexType	optional	Specifies the time step for entering the date/time for the specific workflow. If omitted, the default cardinalTimeStep as specified in Explorer.xml will be used
minForecastLength	TimeSpanComplexType	optional	Since 2016.02. Minimum forecast length that can be specified by the user
maxForecastLength	TimeSpanComplexType	optional	Since 2016.02. Maximum forecast length that can be specified by the user
stateSelection	StateSelectionComplexType	optional	Default state selection used in the general adapter. Configuration in general adapter is ignored. This state selection can be overruled by task properties (manual forecast dialog)
shiftAllExportedStatesToTime0	boolean	optional	Forces that all models within this workflow start at time0
runExpiryTime	CalendarTimeSpanComplexType	optional	Used for runs of simulated timeseries to override expiry time from global properties DEFAULT_EXPIRY_DAYS. When timeseriesets expirytime is also configured, the minimum of runExpiryTime and the timeSeriesSets expirytime is used. Obsolete for import data since 2017.01.
schedulingAllowed	boolean	optional	Option that indicates if OC can schedule this workflow
maxSchedulingPeriod	TimeSpanComplexType	optional	Maximum allowed scheduling period
defaultSchedulingPeriod	TimeSpanComplexType	optional	Default scheduling period
minSchedulingInterval	TimeSpanComplexType	optional	Minimum allowed scheduling interval
maxNumberRuns	int	optional	Maximum number of runs allowed to be scheduled
viewPermission	string	optional	Set a permission to control who can view this workflow.
runPermission	string	optional	Set a permission to control who can run this workflow
approvePermission	string	optional	Set a permission to control who can approve this workflow
deletePermission	string	optional	DeletePermission determines which users have permission to delete taskRuns from this workflow in the ForecastDialog. DeletePermission also determines which users have permission to change the expiry times of taskRuns from this workflow in the ForecastDialog.
deleteByCreatorAllowed	boolean	optional	DeleteByCreatorAllowed determines if the user who created a taskRun from this workflow can delete it in the ForecastDialog. Also determines which users have permission to change the expiry times of taskRuns from this workflow in the ForecastDialog.
enabledModifierGroups	EnabledModifierGroups	optional
maxEnsembleParts	positiveInteger	optional	Determines in how many parts at most the workflow can be split up to run in parallel for ensembles. Ensembles will only be split up if this element is specified and the number specified is larger than 1.
waterCoachDelay	CalendarTimeSpanComplexType	optional	Prevents simulated forecasts becoming available too early in water coach mode. The forecasts are finished in real life at time zero plus delay. The delay includes the run time and the time0 shift. When a forecast is scheduled at 7:00 am with a time0 of 0:00 am and the runs takes approximately an hour you should specify an delay of 8 hours. For external forecasts the delay is configured in the moduleInstanceDescriptors.xml
timeOut	TimeSpanComplexType	optional	Timeout for a workflow on the ForecastingShell. Default is 4 hours. Since 2018.02 this option is to be used instead of the master-controller chaser grace time which was removed.
approvalEventCode	logEventCodeStringType	optional	approvalEventCode is user configured event code that is logged upon approving a forecast, instead of default event code “DataStore.NewCurrentRun” approvalEventCode make it possible to log different approval event codes per workflow, so that different actions can be triggered by Master-Controller after approving particular forecast(s)
whatIfTemplateId	idStringType	optional	Since 2021.01. Id of the whatIfTemplate which is connected to this node
whatIfScenarioRequired	boolean	optional	Since 2025.01. If this option is set to true, the user can only start a workflow if a what-if scenario is defined.
moduleConfigProperties	PropertiesComplexType	required	Same as properties, but element name is deprecated and obsolete since properties are also applied in workflow config files and not only in module config files
properties	PropertiesComplexType	required	These properties can be referenced in workflow and module config files with $key$, similar to global properties. $key$ is resolved by first searching in the properties defined in the workflow files defined and than in the workflow descriptor of the running task and after that in the moduleConfigFileProperties defined in the the region config and at last in the global properties in the region home
editableProperty	string	optional · repeats	Since 202401 (WebOC only). List of properties which are editable in the WebOc

RootNodeComplexType

Element	Type	Cardinality	Description
node	TreeNodeComplexType	required · repeats	Nodes that wil be shown as top level nodes in the ManualForecast dialog

GroupNodeComplexType

Attributes

Attribute	Use	Notes
id	required	Id of the node

TimeStepComplexType

Time step, There are 5 valid combinations of attributes. id, unit+[multiplier]+[divider]+[timeZone], times+[timeZone] + monthDays+[timeZone] ([]=optional)

Attributes

Attribute	Use	Notes
id	optional	Id of the time step. You can reference time steps defined in the regionConfig/timeSteps.xml. Only specify the id attribute when referring to a predefined time step. In the regionConfig/timeSteps.xml the time steps list both the id and the attributes that define the time step
label	optional	Short name for the time step which is shown to the user when he can choose one from a list.
unit	optional
divider	optional
multiplier	optional
times	optional	Defines the time step by a list of times without dates, e.g. "10:00 23:00"
minutes	optional	Since 2017.02. Defines the time step by a list of minutes (with prefix 0 for single digits), e.g. "05 25" which results in times 0:05, 0:25, 1:05, etc.
daysOfMonth	optional	Defines the time step by a list of days of month, use "01 11 21" for a decade time step
monthDays	optional	Defines the time step by a list of dates, e.g. ""--03-01 --06-01 --09-01 --12-01" for the meteorological seasons
timeZone	optional

Elements

Element	Type	Cardinality	Description
description	string	optional	Optional description of this timeStep. This is not used and is only present for convenience.

TimeSpanComplexType

Attributes

Attribute	Use	Notes
unit	required
divider	optional
multiplier	optional

StateSelectionComplexType

Element	Type	Cardinality	Description
overrulingColdStateModuleInstanceId	idStringType	optional	Since 2017.02. Different module instance id used for finding cold state (when warm state is configured but can't be found, or always when cold state is configured)
coldState	ColdStateComplexType	required	Time independent default module instance state.
warmState	WarmStateComplexType	required	Module instance state for a particular timestamp.
backupWarmStateModuleInstanceId	idStringType	optional	Since 2019.01. Different module instance id used for finding warm state, when original warm state can't be found

CalendarTimeSpanComplexType

Attributes

Attribute	Use	Notes
unit	required
divider	optional
multiplier	optional

EnabledModifierGroups

Element	Type	Cardinality	Description
groupId	idStringType	optional · repeats

PropertiesComplexType

Element	Type	Cardinality	Description
description	string	optional	Optional description (this is never used in the code).
string	StringPropertyComplexType	required
int	IntPropertyComplexType	required
float	FloatPropertyComplexType	required
double	DoublePropertyComplexType	required	Since 2014.01
bool	BoolPropertyComplexType	required
dateTime	DateTimePropertyComplexType	required	Since 2014.01

TreeNodeComplexType

Attributes

Attribute	Use	Notes
name	required	Name of the node

ColdStateComplexType

Element	Type	Cardinality	Description
groupId	idStringType	optional	ID of the group of cold states to be used within the task run. If not specified default cold state will be used.
fixedStartTime	DateTimeComplexType	required	Absolute start time of the coldstate. Since 2012_02, used via upload in Admin Interface.
startDate	TimeSpanComplexType	required	Relative date of the cold state to the time0 of the taskrun.

WarmStateComplexType

Element	Type	Cardinality	Description
stateSearchPeriod	RelativePeriodComplexType	required	Time window used to search for a warm state. If no warm module instance state could be found the default cold state will be used instead.
searchForTransientStates	boolean	optional	A state run should not start with a transient state, default is true, set to false for state runs
transientStateExpiryTime	CalendarTimeSpanComplexType	optional	Expiry time of imported states with a time after the warm the state search period. These states should on be used by state runs.
coldStateTime	RelativeTimeComplexType	optional	When no warm state is found the default cold state is used. The time is a relative time against t0. By default the start time of the state search period is used.
insertColdState	boolean	optional	Deprecated, for backward compatibility only.

StringPropertyComplexType

Attributes

Attribute	Use	Notes
key	required
value	required

Elements

Element	Type	Cardinality	Description
description	string	optional	Optional description (this is never used in the code).

IntPropertyComplexType

Attributes

Attribute	Use	Notes
key	required
value	required

Elements

Element	Type	Cardinality	Description
description	string	optional	Optional description (this is never used in the code).

FloatPropertyComplexType

Attributes

Attribute	Use	Notes
key	required
value	required

Elements

Element	Type	Cardinality	Description
description	string	optional	Optional description (this is never used in the code).

DoublePropertyComplexType

Attributes

Attribute	Use	Notes
key	required
value	required

Elements

Element	Type	Cardinality	Description
description	string	optional	Optional description (this is never used in the code).

BoolPropertyComplexType

Attributes

Attribute	Use	Notes
key	required
value	required

Elements

Element	Type	Cardinality	Description
description	string	optional	Optional description (this is never used in the code).

DateTimePropertyComplexType

Attributes

Attribute	Use	Notes
key	required
date	required
time	required

Elements

Element	Type	Cardinality	Description
description	string	optional

DateTimeComplexType

Attributes

Attribute	Use	Notes
date	required
time	optional

RelativePeriodComplexType

Defines a moving period in time. The start and end time are relative time to a certain time.

Attributes

Attribute	Use	Notes
start	required
end	required
startOverrulable	optional	default: false. When the running module (e.g. general adaptor) has exported a state the state time is used instead of the specified start time. This option is only available during a (forecast) run.
endOverrulable	optional	default: false. When a forecast length is specified (e.g. in the manual forecast dialog) the time 0 + forecast length is used instead of the specified end time This option is only available during a (forecast) run.
unit	required

Elements

Element	Type	Cardinality	Description
description	string	optional

RelativeTimeComplexType

Defines a time relative to T0.

Attributes

Attribute	Use	Notes
value	required
unit	required

Elements

Element	Type	Cardinality	Description
description	string	optional	Optional description with additional comments. This is never used in the code.

See also

• Task guide: Workflows & scheduling
• Reference: Workflow file
• Schema: workflowDescriptors.xsd