Overview

The Admin Interface API exposes most of the functionality that is available in the Admin Interface GUI using a RESTful API where resources like systemstatus, logs, tasks etc. can be accessed.

In the examples that follow, the URL: localhost:8080/api/ is being used. This URL will differ per installation.

Authentication and Authorization

When using the Admin Interface API it’s important to follow the following flow:

  • Login to start a session

  • Pass session id to every request

  • Logout to stop session

Login

The login endpoint should be used to start a session with the Admin Interface API. Basic Authentication should be used with the username and access key as registered in the admin interface.

In the following example the user aiuser with access key 8bafr_cZWXaRKppOFssJgNmgYCC8kPWFajmBGi6E is used to login using basic authentication.

$ curl -v -u aiuser:8bafr_cZWXaRKppOFssJgNmgYCC8kPWFajmBGi6E 'http://localhost:8080/api/v1/login'

When authentication is successful a session id is generated called JSESSIONID. The session is returned by the login api and is also written as a cookie in the response. The session is invalid if not used for 10 minutes or more. A maximum of 30 active sessions is allowed.

Session

When calling api endpoints, the session id should be passed as a cookie. In the following example the system status is requested by passing the session id.

$ curl -v --cookie "JSESSIONID=DEAC2C697393C636AEEC22EAEBDCCAB0" 'http://localhost:8080/api/v1/systemstatus'

Note that when used in a typical web application the cookie is automatically passed with each request.

CSRF

Since 2020.02 the security of the Admin Interface API has been strengthened by requiring a CSRF (Cross Site Request Forgery) header or parameter when using API calls that change the state of the database. This means for all POST, DELETE and PATCH api calls, a dedicated request parameter or header is required.

When using the login api, a CSRF header is sent in the response that looks as follows:

X-CSRF-HEADER: X-CSRF-TOKEN
X-CSRF-PARAM: _csrf
X-CSRF-TOKEN: 7f4acee4-9053-4249-b756-ccf5aa1dc5b5

This tells the api clients to pass the CSRF token using the header named: "X-CSRF-TOKEN" or the request parameter named: "_csrf".

Logout

When done using the API it is recommended to logout the session to free all resources. If not explicitly called, the session will invalidate after 10 minutes. In case the API is used periodically, for example to display status information every 5 minutes, it is recommended to reuse the session token. In that case the logout endpoint should not be used.

$ curl -v --cookie "JSESSIONID=DEAC2C697393C636AEEC22EAEBDCCAB0" 'http://localhost:8080/api/v1/logout'

Monitoring

The admin interface is a session based web application. When monitoring tools are used or a load balancer that will check if the Admin Interface is alive, it is important to use a method that will not create a new session with each request. It is recommended to use the version web page for this. This is a public webpage that will not create a session:

$ curl 'http://localhost:8080/version' -i -X GET

System Status

Get system status

The systemstatus resource can be used to get status about the live system.

Example request

$ curl 'http://localhost:8080/api/v1/systemstatus' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 4890

{"statusDate":1548848408175,"forecastingShellServersStatus":0,"forecastingShellServersStatusDescription":"OK","masterControllers":[{"mcId":"roadmapmc00","status":0,"statusDescription":"OK","statusDetails":null,"mcStatus":40,"mcStatusDescription":"Fully operational.","mcStatusDetails":null,"pendingTasks":0,"runningTasks":0,"activeUsers":0,"lastHeartBeat":1548848399132,"lastHeartBeatTimeFormatted":"30/01/2019 11:39","softwareVersion":"MasterController:stable_2018.02 (80682)","schemaVersion":"db schema version","dbVersion":"PostgreSQL 9.6","remoteMc":false,"mcSynchronization":{"remoteMcId":"roadmapmc00","status":"Disabled","statusCode":-2,"summary":"MCSynch roadmapmc00, last heartbeat=never, last table=null, last synchLevel=-1, last maxAgeMillis=0, last successful synch start time=never, last failed time= never, this month: inserted bytes=0 B, inserted rows=0, inserted failed rows=0, updated bytes=0 B, updated rows=0, updated failed rows=0, duration=0s, down duration=0s, total: inserted bytes=0 B, inserted rows=0, inserted failed rows=0, updated bytes=0 B, updated rows=0, updated failed rows=0, duration=0s, down duration=0s","synchStatistics":null},"fssGroups":[{"fssGroupId":"linux","fssGroupName":"Linux","description":"Linux group","priority":0,"allowUnMapped":true,"readyCount":1,"maxAwakeCount":1,"maintenanceRunning":false,"statusCode":0,"statusDescription":"OK"}],"alive":true,"statusUnknown":false,"statusOk":true,"statusFailed":false,"statusFailedOver":false},{"mcId":"roadmapmc02","status":0,"statusDescription":"OK","statusDetails":null,"mcStatus":40,"mcStatusDescription":"Fully operational.","mcStatusDetails":null,"pendingTasks":0,"runningTasks":0,"activeUsers":0,"lastHeartBeat":1548848399132,"lastHeartBeatTimeFormatted":"30/01/2019 11:39","softwareVersion":"MasterController:stable_2018.02 (80682)","schemaVersion":"db schema version","dbVersion":"Oracle 12.1","remoteMc":true,"mcSynchronization":{"remoteMcId":"roadmapmc02","status":"Enabled","statusCode":1,"summary":"MCSynch roadmapmc02, last heartbeat=Wed Jan 30 11:39:45 GMT 2019, last table=ConfigRevisionSets, last synchLevel=-1, last successful synch start time=Wed Jan 30 11:39:38 GMT 2019, last failed time= never, this month: inserted bytes=14 MB, inserted rows=22041, inserted failed rows=0, updated bytes=115 MB, updated rows=22041, updated failed rows=0, duration=6h 23m 30s, down duration=3s, total: inserted bytes=16 MB, inserted rows=25927, inserted failed rows=0, updated bytes=115 MB, updated rows=935857, updated failed rows=0, duration=6h 35m 18s, down duration=7s","synchStatistics":null},"fssGroups":[{"fssGroupId":"windows","fssGroupName":"Windows","description":"Windows group","priority":0,"allowUnMapped":true,"readyCount":1,"maxAwakeCount":1,"hibernate":"Azure","maintenanceRunning":false,"statusCode":-1,"statusDescription":"Failed"}],"alive":true,"statusUnknown":false,"statusOk":true,"statusFailed":false,"statusFailedOver":false}],"forecastingShellServers":[{"fssId":"2460","mcId":"roadmapmc00","fssGroupId":"windows","status":105,"statusDescription":"Init Data Store","taskRunStatus":"C","taskRunStatusDescription":"Complete","workflowId":"workFlowId","runningWorkflowId":"runningWorkflowId","taskRunId":"unknown","dispatchTime":1548848407235,"dispatchTimeFormatted":"30/01/2019 11:40","heartbeatTime":1548848407235,"heartbeatTimeFormatted":"30/01/2019 11:40","hostName":"dw-024.xtr.intra","hostSlotCount":3,"memoryMB":4095,"indexAtHost":1,"cpu":2.0,"directory":"/opt/fews/fss/1","remoteMc":false,"fssGroupMaintenanceRunning":false,"statusUnknown":false,"statusOk":true,"statusFailed":false}],"masterControllerComponents":{"mcStatusExpired":false,"taskRunnerStatusCode":0,"rollingBarrelStatusCode":0,"systemAlerterStatusCode":0,"taskRunnerStatusDescription":"OK","rollingBarrelStatusDescription":"OK","rollingBarrelSummary":"last successful rolling barrel start time=Wed Jan 30 11:39:44 GMT 2019, this month: startedCount=4081, failed=0, failed run=0, duration=10m 2s, down duration=0s, expired=0, extended=0, total: started=9365, failed=23, success=9338, duration=13m 26s, down duration=0s, expired=0, extended=0","systemAlerterStatusDescription":"OK","rollingBarrelStatistics":null},"synchronizationStatus":[{"remoteMcId":"roadmapmc02","status":"Enabled","statusCode":1,"summary":"MCSynch roadmapmc02, last heartbeat=Wed Jan 30 11:39:45 GMT 2019, last table=ConfigRevisionSets, last synchLevel=-1, last successful synch start time=Wed Jan 30 11:39:38 GMT 2019, last failed time= never, this month: inserted bytes=14 MB, inserted rows=22041, inserted failed rows=0, updated bytes=115 MB, updated rows=22041, updated failed rows=0, duration=6h 23m 30s, down duration=3s, total: inserted bytes=16 MB, inserted rows=25927, inserted failed rows=0, updated bytes=115 MB, updated rows=935857, updated failed rows=0, duration=6h 35m 18s, down duration=7s","synchStatistics":null}]}

Response structure

Path Type Description

statusDate

Number

Date the system status was checked

masterControllers[].mcId

String

Master Controller ID.

masterControllers[].status

Number

Status of the Master Controller. Possible status codes and their descriptions are: -1 = Unknown, 0 = OK, 1 = failed, 2 = failed over.

masterControllers[].statusDescription

String

Description of the master controller status.

masterControllers[].statusDetails

Null

Since 2022.02. Detailed description of the master controller status.

masterControllers[].mcStatus

Number

Since 2021.01. mcStatus of the Master Controller. Possible codes and descriptions can be found on the public wiki: https://publicwiki.deltares.nl/x/3YNHCg

masterControllers[].mcStatusDescription

String

Since 2021.01. Description of the mcStatus of the Master Controller. Possible codes and descriptions can be found on the public wiki: https://publicwiki.deltares.nl/x/3YNHCg

masterControllers[].mcStatusDetails

Null

Since 2022.02. Detailed description of the mcStatus of the Master Controller.

masterControllers[].pendingTasks

Number

Number of pending tasks,

masterControllers[].runningTasks

Number

Number of running tasks.

masterControllers[].activeUsers

Number

Number of active OC users connected to the master controller.

masterControllers[].lastHeartBeat

Number

Last heartbeat time in milliseconds epoch time GMT-0.

masterControllers[].lastHeartBeatTimeFormatted

String

Formatted version of last heartbeat time in dd/MM/YYYY HH:MM format.

masterControllers[].softwareVersion

String

Software version of the master controller. Not available for remote MCs.

masterControllers[].schemaVersion

String

Schema version of the database. Not available for remote MCs.

masterControllers[].dbVersion

String

Version of the database. Not available for remote MCs.

masterControllers[].remoteMc

Boolean

Indicates if the Master Controller is a remote MC. true or false.

masterControllers[].alive

Boolean

Indicates if the Master Controller is alive.

masterControllers[].statusOk

Boolean

Indicates if the Master Controller status is OK. All components are running fine.

masterControllers[].statusFailed

Boolean

Indicates if the Master Controller is in failed state.

masterControllers[].statusUnknown

Boolean

Indicates if the Master Controller is in an unknown state.

masterControllers[].statusFailedOver

Boolean

Indicates if the Master Controller is in failed over state.

masterControllers[].mcSynchronization.remoteMcId

String

Id of the MC.

masterControllers[].mcSynchronization.status

String

Synchronization status of the MC. The following codes can be returned: 1 = Enabled, -1 = Failed, -2 = Disabled,

masterControllers[].mcSynchronization.statusCode

Number

Synchronization status code.

masterControllers[].mcSynchronization.summary

String

Synchronization summary.

masterControllers[].mcSynchronization.synchStatistics

Null

Since 2022.02. Synchronization statistics if available.

masterControllers[].fssGroups[].fssGroupId

String

Since 2020.02. Id of the FSS Group on this Master Controller.

masterControllers[].fssGroups[].fssGroupName

String

Since 2020.02. Name of the FSS Group on this Master Controller.

masterControllers[].fssGroups[].description

String

Since 2020.02. Description of the FSS Group on this Master Controller.

masterControllers[].fssGroups[].priority

Number

Since 2020.02. Priority of the FSS Group on this Master Controller. The lower the number, the higher the priority. Is used to prioritize the assignment of an FSS if allow unmapped has been specified.

masterControllers[].fssGroups[].allowUnMapped

Boolean

Since 2020.02. Set to true if workflows that are not mapped to any groups are allowed to use the Forecasting Shell Servers that can run in this group.

masterControllers[].fssGroups[].readyCount

Number

Since 2020.02. The minimum number of forecasting shells that are kept awake in this group.

masterControllers[].fssGroups[].maxAwakeCount

Number

Since 2020.02. Limit the number of Forecasting Shells that can be awake for this group. At least one is required.

masterControllers[].fssGroups[].maintenanceRunning

Boolean

Since 2024.01. Set to true if maintenance was enabled on the fss group.

masterControllers[].fssGroups[].statusCode

Number

Since 2020.02. Status code of the group. 0 = OK, -1 = Failed. If the configured minimum number of forecasting shells that are kept awake in a group is less than the actual number of forecasting shells, that group is considered failed.

masterControllers[].fssGroups[].statusDescription

String

Since 2020.02. Status Description of the FSS group. Can be OK or Failed. If the configured minimum number of forecasting shells that are kept awake in a group is less than the actual number of forecasting shells, that group is considered failed.

masterControllers[].fssGroups[].hibernate

String

Since 2023.02. Only set if configured. If set the FSS supports hibernation. For example: Azure.

forecastingShellServersStatus

Number

Since 2019.02. Status of the Forecasting Shell Servers. Possible values are: 0 = OK, -1 = Failed.

forecastingShellServersStatusDescription

String

Since 2019.02. Description of the Forecasting Shell Servers status. Typically OK or Failed.

forecastingShellServers[].fssId

String

Forecasting Shell ID.

forecastingShellServers[].mcId

String

Master Controller ID.

forecastingShellServers[].fssGroupId

String

Forecasting Shell Group ID.

forecastingShellServers[].fssGroupMaintenanceRunning

Boolean

Since 2024.01. Set to true if maintenance was enabled on the fss group of this FSS.

forecastingShellServers[].status

Number

Status of the Forecasting Shell.

forecastingShellServers[].statusDescription

String

Status Description of the FSS. For the different status codes, please see: https://publicwiki.deltares.nl/x/rogsC

forecastingShellServers[].taskRunStatus

String

Task Run Status. Possible status codes are: S = Scheduled, P = Pending, R = Running, I = Invalid, F= Failed, C = Complete, A = Complete, B = Partly Complete, T = Terminated, D = Partly Successful. The status will be set to null if there is no last Task Run Status or if the status is unknown.

forecastingShellServers[].taskRunStatusDescription

String

Description of the Task Run Status.

forecastingShellServers[].workflowId

String

Workflow id of the task that was last run on this FSS.

forecastingShellServers[].runningWorkflowId

String

Workflow id of the task that is currently running on this FSS.

forecastingShellServers[].taskRunId

String

Taskrun id of the last task that was run on this FSS.

forecastingShellServers[].dispatchTime

Number

Time the last workflow was dispatched on this FSS in milliseconds epoch time GMT-0.

forecastingShellServers[].dispatchTimeFormatted

String

Formatted time the last workflow was dispatched in dd/MM/YYYY HH:MM format.

forecastingShellServers[].heartbeatTime

Number

The last time the FSS gave a heartbeat in milliseconds epoch time GMT-0.

forecastingShellServers[].heartbeatTimeFormatted

String

Formatted time the FSS gave a heartbeat in dd/MM/YYYY HH:MM format.

forecastingShellServers[].hostName

String

Hostname of the FSS.

forecastingShellServers[].hostSlotCount

Number

slot count of the FSS. The number of FSS’s that can run on the same host.

forecastingShellServers[].memoryMB

Number

Memory available to the FSS in MB.

forecastingShellServers[].indexAtHost

Number

Index of the FSS on the host. In case only one slot is available the index will be 1.

forecastingShellServers[].cpu

Number

Number of CPUs available to the FSS.

forecastingShellServers[].directory

String

Root folder of the FSS (also known as the region home).

forecastingShellServers[].statusUnknown

Boolean

Since 2019.02. Indicates if a the FSS is in an unknown status.

forecastingShellServers[].statusOk

Boolean

Since 2019.02. Indicates if a the FSS is running OK.

forecastingShellServers[].statusFailed

Boolean

Since 2019.02. Indicates if a the FSS is in failed state.

forecastingShellServers[].remoteMc

Boolean

Since 2020.02. Indicates if a the FSS is owned by a remote MC.

masterControllerComponents.mcStatusExpired

Boolean

Indicates if the mc status is expired.

masterControllerComponents.taskRunnerStatusCode

Number

Task runner status code.

masterControllerComponents.rollingBarrelStatusCode

Number

Rolling barrel status code.

masterControllerComponents.systemAlerterStatusCode

Number

System alerter status code.

masterControllerComponents.taskRunnerStatusDescription

String

Task runner status description.

masterControllerComponents.rollingBarrelStatusDescription

String

Rolling barrel status description.

masterControllerComponents.rollingBarrelSummary

String

Summary of the rolling barrel summary.

masterControllerComponents.systemAlerterStatusDescription

String

System alerter status description.

masterControllerComponents.rollingBarrelStatistics

Null

Since 2022.02. Rolling barrel statistics if available.

synchronizationStatus[].remoteMcId

String

MC ID for which the Synchronization status is given.

synchronizationStatus[].status

String

Synchronization status.

synchronizationStatus[].statusCode

Number

Synchronization status code.

synchronizationStatus[].summary

String

Synchronization status summary.

synchronizationStatus[].synchStatistics

Null

Since 2022.02. Synchronization statistics if available.

Collected System Logs as zip file

The systemstatus/logs/collect resource can be used to collect all log files of the live system.

Example request

$ curl 'http://localhost:8080/api/v1/systemstatus/logs/collect?uuid=myuniqueuuid' -i -X GET

Request parameters

Parameter Description

uuid

Unique identifier that can be used to track the download.

To track the status of the the download, the uuid that has been passed as parameter can be used to call the session/status endpoint:

$ curl 'http://localhost:8080/api/v1/session/status?uuid=myuniqueuuid' -i -X GET

If the download is still in progress, the status will return 'downloading'.

Example response

HTTP/1.1 200 OK
Content-Type: application/zip; charset=utf-8
content-disposition: attachment; filename="CollectedLogFiles-MC00-Stable2021.02-20241120-151801.zip"
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Response structure

The response is a binary zip file of Content-type application/zip

Database Connections

Since 2020.01

The systemstatus/database/connections resource can be used to get information about the used database connections in the live system.

Example request

$ curl 'http://localhost:8080/api/v1/systemstatus/database/connections' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 860

{"databaseConnections":{"numberOfDatabaseConnections":100,"maxNumberOfDatabaseConnections":1000,"numberOfFewsDatabaseConnections":98,"maxNumberOfFewsDatabaseConnections":900},"operatorClientConnections":{"numberOfOperatorClientConnections":5,"maxNumberOfOperatorClientConnections":40},"forecastingShellServerConnections":{"numberOfForecastingShellServerConnections":4,"maxNumberOfForecastingShellServerConnections":16},"serviceConnections":{"numberOfServiceConnections":1,"maxNumberOfServiceConnections":100},"webServicesConnections":{"numberOfWebServicesConnections":15,"numberOfWebServices":3,"maxNumberOfWebServicesConnections":15},"masterControllerConnections":{"numberOfMasterControllerConnections":8,"maxNumberOfMasterControllerConnections":8},"adminInterfaceConnections":{"numberOfAdminInterfaceConnections":3,"maxNumberOfAdminInterfaceConnections":11}}

Response structure

Path Type Description

databaseConnections.numberOfFewsDatabaseConnections

Number

Number of FEWS database connections. This is equal to the maximum number of database connections minus 100 minus the Other Components Connections.

databaseConnections.maxNumberOfFewsDatabaseConnections

Number

Maximum number of FEWS database connections. This is equal to the maximum number of database connections minus 100.

databaseConnections.numberOfDatabaseConnections

Number

Number of database connections used by Delft-FEWS.

databaseConnections.maxNumberOfDatabaseConnections

Number

Maximum number of database connections that can be used by Delft-FEWS.

operatorClientConnections.numberOfOperatorClientConnections

Number

Number of Operator Client database connections used by Delft-FEWS.

operatorClientConnections.maxNumberOfOperatorClientConnections

Number

Maximum number of Operator Client database connections that can be used by Delft-FEWS. Each Operator Client uses 4 database connections

forecastingShellServerConnections.numberOfForecastingShellServerConnections

Number

Number of Forecasting Shell Server Database Connections that are used by Delft-FEWS.

forecastingShellServerConnections.maxNumberOfForecastingShellServerConnections

Number

Maximum number of Forecasting Shell Servers database connections that can be used by Delft-FEWS. Each FSS can use a maximum of 4 Database connections.

serviceConnections.numberOfServiceConnections

Number

Number of Other Database Connections that are used by Delft-FEWS.

serviceConnections.maxNumberOfServiceConnections

Number

Maximum number of Other Database Connections that are used by Delft-FEWS.

webServicesConnections.numberOfWebServices

Number

Number of Web Services instances.

webServicesConnections.numberOfWebServicesConnections

Number

Number of Web Services Database connections. Each Web Services instance uses 5 database connections

webServicesConnections.maxNumberOfWebServicesConnections

Number

Maximum Number of Web Services Database connections.

adminInterfaceConnections.numberOfAdminInterfaceConnections

Number

Number of Admin Interface Database connections.

adminInterfaceConnections.maxNumberOfAdminInterfaceConnections

Number

Maximum Number of Admin Interface Database connections.

masterControllerConnections.numberOfMasterControllerConnections

Number

Number of Master Controller Database Connections. In a single MC system a master controller uses 8 database connections

masterControllerConnections.maxNumberOfMasterControllerConnections

Number

Maximum Number of Master Controller Database Connections.

Logs

The logs resource is used to retrieve and search log messages.

List logs

A GET logs request that will list, filter and sort log messages.

Example request

$ curl 'http://localhost:8080/api/v1/logs?draw=1&start=0&length=100&order%5B0%5D%5Bcolumn%5D=1&order%5B0%5D%5Bdir%5D=asc&entryDateFrom=1549834108000&entryDateTo=1550093313000&level=INFO&acknowledged=All&source=FS%25205%2520ukeafffsmc00%253A000026752%2509&code=TaskRun.Completed&text=Task&build=81204&taskRunIds=roadmapmc00:003803615' -i -X GET

Request parameters

Parameter Description

draw

Unique sequence number that can be used to order asynchronous api requests.

start

Start index of the requested result.

length

Length index of the requested result.

order[0][column]

Index of the first column that should be used for sorting the results. The following indexes can be used: 0 = Code, 1 = Entry Time, 2 = Level, 3 = Source, 4 = Text, 5 = Build . Currently only sorting on one column is supported. For example, to sort on the entryDateFrom field, the order[0][column] parameter has to be set to 1.

order[0][dir]

Direction the first column should be sorted. Value is either asc (ascending) or desc (descending). For example: order[0][dir]=asc.

entryDateFrom

Date after or equal to the moment the log entry was added in milliseconds epoch time GMT-0. So for example: 1549834108000 = Sunday 10 February 2019 21:28:28 GMT-0.

entryDateTo

Date before or equal to the moment the log entry was added in milliseconds epoch time GMT-0. So for example: 1549834108000 = Sunday 10 February 2019 21:28:28 GMT-0.

level

Filters on log level. Allowed values are: INFO, WARNING, ERROR and FATAL.

source

Source of the log level, for example the forecasting shell id.

code

Code of the log. For example: TaskRun.Completed

build

Build number of the component that entered the log.

text

Text of the log.

taskRunIds

Task Run id of the log. This parameter can be used more than once.

acknowledged

Filter acknowledged log events. Allowed values are: 'All', 'Unacknowledged' and 'Acknowledged'

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 249

{"draw":0,"recordsTotal":100,"recordsFiltered":100,"logs":[{"logEntryId":1,"taskRunId":"taskRunId 1","code":"Code 1","entryTime":1732115887948,"level":"INFO","source":"source 1","text":"Text","build":1234,"componentId":"mc1","eventAcknowledged":1}]}

Response structure

Path Type Description

logs[].logEntryId

Number

id of the log entry

logs[].taskRunId

String

task run id of the log entry

logs[].code

String

log code.

logs[].entryTime

Number

time the log was entered in the database.

logs[].text

String

Text of the log message.

logs[].level

String

Loglevel: DEBUG, INFO, WARN, ERROR or FATAL.

logs[].source

String

Source of the log.

logs[].build

Number

Build number of the FEWS version the log message was generated with.

logs[].componentId

String

Component id that logged the event.

logs[].eventAcknowledged

Number

Indicates if log event was acknowledged. Set to 1 if the event was acknowledged.

draw

Number

unique identifier of request.

recordsTotal

Number

Total number of records available.

recordsFiltered

Number

Total number of records after filtering.

Acknowledge logs

A POST logs/acknowledge request that will acknowledge all passed logEntries.

Since 2020.02 the CSRF parameter or header is required

Example request

$ curl 'http://localhost:8080/api/v1/logs/acknowledge?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5&logEntries=1%7CNLRIMC00:006283806&logEntries=2%7CNLRIMC00:006283806' -i -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded'

Request parameters

Parameter Description

_csrf

CSRF token required for POST requests

logEntries

One or more logEntries. A logEntry contains the logEntryId and the taskRunId of the log event separated by a vertical bar. For example a log event with logEntryId=1 and taskRunId=NLRIMC00:006283806 should be passed as a logEntries parameter as follows: 1|NLRIMC00:006283806

Tasks

The task resource is used to retrieve and search tasks.

List tasks

A GET task request that will list all tasks. Optional parameters can be used to filter and sort the results.

Example request

$ curl 'http://localhost:8080/api/v1/tasks/scheduled?draw=1&start=0&length=100&order%5B0%5D%5Bcolumn%5D=description&order%5B0%5D%5Bdir%5D=asc&hideOneOffTask=false&hideFinishedTask=false&hideScheduledTask=false&showCurrentForecastDispatchTime=true' -i -X GET

Request parameters

Parameter Description

hideOneOffTask

Filter option to hide one-off tasks. Default is false.

hideFinishedTask

Filter option to hide finished tasks. Default is false.

hideScheduledTask

Filter option to hide scheduled tasks. Default is false.

showCurrentForecastDispatchTime

Since 2020.01. Filter option to show the current forecast dispatch time. The currentForecastDispatchTimeBackgroundColor will be returned as well if configured using the ForecastManagement.xml configuration. Default is false.

draw

Unique sequence number that can be used to order asynchronous api requests.

start

Start index of the requested result.

length

Length index of the requested result.

order[0][column]

Name of the first column that should be used for sorting the results.

order[0][dir]

Direction the first column should be sorted. Value is either asc (ascending) or desc (descending).

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 703

{"draw":1,"recordsTotal":100,"recordsFiltered":100,"tasks":[{"taskId":"1","description":"Task1","workflowId":"workflow1","whatifId":"whatifid1","whatifName":"whatifname1","tag":"tag1","mcId":"MC01","priority":0,"interval":"week","nextDueTime":0,"endTime":1583161306,"taskStatus":"status","latestTaskRunDispatchTime":0,"latestTaskRunStatus":"status","latestTaskRunTime":20000,"latestTaskRunScheduledTime":1583151306,"latestTaskRunCompletionTime":1583181306,"runOnFailover":0,"approve":0,"taskRepeatTime":10000,"currentForecastDispatchTime":1583151306,"currentForecastDispatchTimeBackgroundColor":"#ff0000","failoverPolicy":"RUN_DUTY"}],"remoteMcAvailable":true,"whatIfAvailable":true,"tagAvailable":true}

Response structure

Path Type Description

tasks[].taskId

String

id of the task

tasks[].whatifId

String

whatifId of the task

tasks[].whatifName

String

whatifName of the task

tasks[].tag

String

tag of the task

tasks[].mcId

String

mc id of the task

tasks[].priority

Number

priority of the task

tasks[].interval

String

interval of the task

tasks[].nextDueTime

Number

Next due time in milliseconds of the task

tasks[].taskStatus

String

status of the task

tasks[].latestTaskRunDispatchTime

Number

Latest Task Run dispatch time of the task, the time the task was actually scheduled

tasks[].latestTaskRunStatus

String

Latest Task Run status of the task

tasks[].latestTaskRunTime

Number

Latest Task Run Time, duration of the last run task in milliseconds

tasks[].latestTaskRunScheduledTime

Number

Latest Task Run scheduled time. The time the task was scheduled to run

tasks[].latestTaskRunCompletionTime

Number

Latest Task Run status of the task

tasks[].endTime

Number

Last time a task should be scheduled

tasks[].runOnFailover

Number

Can the task run in failover mode

tasks[].approve

Number

Should the forecast be approved

tasks[].taskRepeatTime

Number

Repeat time of the task

tasks[].description

String

The description of the task.

tasks[].workflowId

String

The workflow id of the task.

tasks[].failoverPolicy

String

The failover policy ot the task. Only relevant for multi MC systems. Default is RUN_DUTY.

tasks[].currentForecastDispatchTime

Number

Since 2020.01. Dispatch time of the current forecast (most recent approved forecast).

tasks[].currentForecastDispatchTimeBackgroundColor

String

Since 2020.01. Current forecast dispatch time background color. Based on the ForecastManagement.xml configuration.

draw

Number

unique identifier of request.

recordsTotal

Number

Total number of records available.

recordsFiltered

Number

Total number of records after filtering.

remoteMcAvailable

Boolean

Are there any remote MCs available in the response. Can be used to filter out the mcId column.

whatIfAvailable

Boolean

Are there any whatIf scenario’s available in the resonsponse.

tagAvailable

Boolean

Are there any tags available in the response.

List Task Runs

The tasks/{taskid}/taskruns resource is used to get all taskruns for a specified task id.

Example request

$ curl 'http://localhost:8080/api/v1/tasks/ukeafffsmc00:0005697/taskruns' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 736

{"draw":1,"recordsTotal":2,"recordsFiltered":2,"taskRuns":[{"taskRunId":"ukeafffsmc00:000454201","taskId":"ukeafffsmc00:000219891_00000002","description":"Description 1","workflowId":"Calculate_CWI ","scheduledDispatchTime":1570708408,"taskDispatchTime":1570708408,"completionTime":1570713408,"fssId":"1","fssHostName":"myhost","fssDirectory":"/opt/fews/fss/1","status":"Complete","runTime":5000},{"taskRunId":"ukeafffsmc00:000454148","taskId":"ukeafffsmc00:000219891_00000002","description":"Description 1","workflowId":"Calculate_CWI ","scheduledDispatchTime":1570708408,"taskDispatchTime":1570708408,"completionTime":1570714408,"fssId":"2","fssHostName":"myhost","fssDirectory":"/opt/fews/fss/2","status":"Complete","runTime":6000}]}

Response structure

Path Type Description

taskRuns[].taskRunId

String

id of the taskRun task

taskRuns[].taskId

String

id of the task

taskRuns[].description

String

Description of the taskRun

taskRuns[].workflowId

String

WorkflowId of the task

taskRuns[].fssId

String

Id of the forecasting shell server this task was run on

taskRuns[].fssHostName

String

Hostname of the forecasting shell server this task was run on

taskRuns[].fssDirectory

String

Directory (region home) of the forecasting shell server this task was run on

taskRuns[].status

String

Status code of the task run. The following status codes are available: A=Complete (Approved), B=Partly Complete (Partly Approved), C=Complete, D=Partly Successful, E=Partly Completed, F=Failed, G=Partly Completed (Approved), I=Invalid, K=Amalgamated Keep Metadata, M=Amalgamated, P=Pending, R=Running, S=Scheduled, T=Terminated, Y=Partly Amalgamated

taskRuns[].scheduledDispatchTime

Number

The scheduled time the task should be dispatched

taskRuns[].taskDispatchTime

Number

The actual time the task was dispatched

taskRuns[].runTime

Number

The total time the task has been running. The taskDispatchTime is used as starting point

taskRuns[].completionTime

Number

The time at which the task to completed.

draw

Number

unique identifier of request.

recordsTotal

Number

Total number of records available.

recordsFiltered

Number

Total number of records after filtering.

List Module Run Times

The tasks/moduleruntimes resource is used to get all expected runtimes for workflows per module instance id. The list can optionally be filtered by workflowId.

Only workflows of scheduled tasks that contain module instance descriptors that have been configured with updateModuleRunTimesOnCompletion enabled, will be available in this end point. The expected start time of a module is calculated based on the scheduled next due time and the expected pending duration time. The expected end time of a module is calculated based on the scheduled next due time, the expected pending duration time and the expected running time. For triggered tasks, the expected start time en end time won’t be available until the task is actually started.

Example request

$ curl 'http://localhost:8080/api/v1/tasks/moduleruntimes?workflowId=Workflow%201' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 484

{"draw":1,"recordsTotal":2,"recordsFiltered":2,"moduleRunTimes":[{"mcId":"MC00","workflowId":"Workflow 1","moduleInstanceId":"Module Instance A","expectedPendingDuration":10,"expectedRunningDuration":60000,"expectedStartTime":1570708418,"expectedCompletionTime":1570768418},{"mcId":"MC00","workflowId":"Workflow 1","moduleInstanceId":"Module Instance B","expectedPendingDuration":10,"expectedRunningDuration":60000,"expectedStartTime":1570708418,"expectedCompletionTime":1570768418}]}

Response structure

Path Type Description

draw

Number

Unique identifier of request.

recordsTotal

Number

Total number of model run times

recordsFiltered

Number

Total number of filtered module run times

moduleRunTimes[].mcId

String

MC ID

moduleRunTimes[].workflowId

String

Workflow id

moduleRunTimes[].moduleInstanceId

String

The instance id of the module

moduleRunTimes[].expectedPendingDuration

Number

The Expected duration the module will be in the pending state after the workflow has been started

moduleRunTimes[].expectedRunningDuration

Number

Expected duration of the module run

moduleRunTimes[].expectedStartTime

Number

Expected time the module run will start

moduleRunTimes[].expectedCompletionTime

Number

Expected time the module run will be completed

Files

The files/importstatus resource is used to get the status of data feeds.

Import Status

A GET request that will get the import status of all data feeds.

Example request

$ curl 'http://localhost:8080/api/v1/files/importstatus' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 344

{"draw":0,"recordsTotal":1,"recordsFiltered":1,"importStatus":[{"mcId":"MC01","dataFeed":"E2O.Server.Evaporation","taskRunId":"Task01","suspended":false,"directory":"https://wci.earth2observe.eu","lastImportTime":1562532231142,"lastFileImported":"penmanmonteith-agg.nc","filesRead":0,"filesFailed":0,"lastImportTimeBackgroundColor":"#ff0000"}]}

Response structure

Path Type Description

importStatus[].mcId

String

mcId of the import.

importStatus[].dataFeed

String

Name of the imported data feed.

importStatus[].taskRunId

String

Id of the task run

importStatus[].suspended

Boolean

Whether the associated import with matching mcId and data feed are suspended

importStatus[].directory

String

Directory or URL from which the data was imported.

importStatus[].lastImportTime

Number

Last time the import was performed in milliseconds epoch time GMT-0.

importStatus[].lastFileImported

String

Last file name that was imported.

importStatus[].filesRead

Number

The number of files that were read.

importStatus[].filesFailed

Number

The number of files that failed to import.

importStatus[].lastImportTimeBackgroundColor

String

Since 2019.02. Color code to indicate the status of the last import time as configured in the SystemMonitor configuration.

draw

Number

unique identifier of request.

recordsTotal

Number

Total number of records available.

recordsFiltered

Number

Total number of records after filtering.

Export Status

A GET request that will get the export status of all data feeds.

Example request

$ curl 'http://localhost:8080/api/v1/files/exportstatus' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 276

{"exportStatus":[{"mcId":"MC01","dataFeed":"E2O.Server.Evaporation","taskRunId":"Task01","suspended":false,"directory":"Directory","lastExportTime":0,"lastFileExported":"LastFileExported","filesExportedCount":1,"filesFailedCount":0,"lastExportTimeBackgroundColor":"#ff0000"}]}

Response structure

Path Type Description

exportStatus[].mcId

String

mcId of the export.

exportStatus[].dataFeed

String

Name of the exported data feed.

exportStatus[].taskRunId

String

Id of the task run

exportStatus[].suspended

Boolean

Whether the associated export with matching mcId and data feed are suspended

exportStatus[].directory

String

The directory files were exported to.

exportStatus[].lastExportTime

Number

Time the last file was exported.

exportStatus[].lastFileExported

String

Last file exported.

exportStatus[].filesExportedCount

Number

Number of files that were successfully exported.

exportStatus[].filesFailedCount

Number

Number of files that failed to be exported.

exportStatus[].lastExportTimeBackgroundColor

String

Background color for displayed cell of last export time

Config Management

Since 2020.02

The configmanagement resource can be used to configure the Delft-FEWS live system. It can be used to upload a patch, a Base Build, a Server Configuration file and a Delft-FEWS configuration.

Upload Patch .jar file

The POST configmanagement/patch resource can be used to upload a Delft-FEWS patch jar file. The uploaded patch is used by the Master Controller, Config Manager, Forecasting Shell Servers and Operator clients. Sometimes it may be required to use an alternative patch for a specific OC or FSS. In that case an alternative patch.jar can be specified in the otherRootConfigFiles of the clientConfig.xml file. The patch.jar itself should be added to the RootConfigFiles folder of the Delft-FEWS Configuration.

The name of the file parameter should be "file", encoding type should be be multipart/form-data and the use of the _csrf parameter is required.

Example html request

From a web application, a config file can be uploaded as follows:

<form id="upload-form-id" method="POST" enctype="multipart/form-data" action="http://localhost:8080/api/v1/configmanagement/patch?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5">
    <input type="file" name="file"/>
    <input type="submit" value="Upload"/>
</form>

Example curl request

$ curl -v -F file=@patch.jar 'http://localhost:8080/api/v1/configmanagement/patch?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5'

Example http request

When the form is sent, a multipart request is build. A multipart request consists of 2 parts. A multipart/form-data content type with a boundary and the actual form data containing the file.

HTTP Content-Type:

 Content-Type:
 Content-Type: multipart/form-data; boundary=----WebKitFormBoundary2IBqhL2o3MWn7xgV

HTTP Body:

------WebKitFormBoundary2IBqhL2o3MWn7xgV
Content-Disposition: form-data; name="file"; filename="patch.jar"
Content-Type: application/octet-stream


------WebKitFormBoundary2IBqhL2o3MWn7xgV--

Example json response

The response is a json object that will contain a list of errors in case an error occured and the name of the uploaded jar file.

{"errors":[],"fileName":"patch.jar"}

Response structure

Path Type Description

fileName

String

Name of the uploaded file

errors[].status

Integer

Status

errors[].error

String

The error

errors[].message

String

Detailed error message

errors[].timeStamp

String

Time the error occured

errors[].trace

String

Stacktrace of the error if available

Patch file info

Since 2023.02

The GET configmanagement/patch/info resource can be used to get info about the current uploaded patch file.

Example request

$ curl 'http://localhost:8080/api/v1/configmanagement/patch/info' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 136

{"patches":[{"creationUserId":"admin","commentText":"comment","date":1636549629541,"version":"2021.02","build":106458,"type":"stable"}]}

Response structure

Path Type Description

patches[].date

Number

The date of the last uploaded patch.

patches[].version

String

The Delft-FEWS version of the last uploaded patch.

patches[].build

Number

The build version of the last uploaded patch.

patches[].type

String

The build types of the last uploaded patch.

patches[].creationUserId

String

The user that uploaded the latest mc config.

patches[].commentText

String

The comment that was added to the latest mc config upload.

Upload Base Build zip file

The POST configmanagement/basebuilds resource can be used to upload a base build zip file. The name of the file parameter should be "file", encoding type should be be multipart/form-data and the use of the _csrf parameter is required.

Example html request

From a web application, a config file can be uploaded as follows:

<form id="upload-form-id" method="POST" enctype="multipart/form-data" action="http://localhost:8080/api/v1/configmanagement/basebuilds?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5">
     <input type="file" name="file"/>
    <input type="submit" value="Upload"/>
</form>

Example curl request

$ curl -v -F file=@basebuild.zip 'http://localhost:8080/api/v1/configmanagement/basebuilds?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5'

Example http request

When the form is sent, a multipart request is build. A multipart request consists of 2 parts. A multipart/form-data content type with a boundary and the actual form data containing the file.

HTTP Content-Type:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary2ZaiDB3DrK1rO1QA

HTTP Body:

------WebKitFormBoundary2ZaiDB3DrK1rO1QA
Content-Disposition: form-data; name="file"; filename="basebuild.zip"
Content-Type: application/x-zip-compressed


------WebKitFormBoundary2ZaiDB3DrK1rO1QA--

Example json response

The response is a json object that will contain a list of errors in case an error occured and the name of the uploaded zip file.

{"errors":[],"fileName":"basebuild.zip"}

Response structure

Path Type Description

fileName

String

Name of the uploaded file

errors[].status

Integer

Status

errors[].error

String

The error

errors[].message

String

Detailed error message

errors[].timeStamp

String

Time the error occured

errors[].trace

String

Stacktrace of the error if available

BaseBuild files info

Since 2023.02

The GET configmanagement/basebuilds/info resource can be used to get info about the uploaded basebuild files.

Example request

$ curl 'http://localhost:8080/api/v1/configmanagement/basebuilds/info' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 263

{"baseBuilds":[{"name":"fews-development-202302-121196-bin","buildType":"stable","implementationVersion":"2021.02","buildNumber":106458,"date":1692166191314,"isUsedByDescription":"version: 2021.02, build: 122702 Aug3, type: stable","userId":"admin","used":true}]}

Response structure

Path Type Description

baseBuilds[].name

String

File name.

baseBuilds[].buildType

String

The buildType: stable, development.

baseBuilds[].implementationVersion

String

The implementation version. For example: 2021.02.

baseBuilds[].buildNumber

Number

The build number. For example: 106458.

baseBuilds[].date

Number

The date of the upload in milliseconds epoch time.

baseBuilds[].userId

String

The user id of the user that uploaded the basebuild.

baseBuilds[].used

Boolean

Set to true if the basebuild is used by an uploaded patch.

baseBuilds[].isUsedByDescription

String

If the baseBuild is in use, this description indicates how. For example: version: 2021.02, build: 122702 Aug3, type: stable.

Upload Master Controller Configuration XML file

The POST configmanagement/mcconfig resource can be used to upload and download the Master Controller Configuration XML file. The name of the file parameter should be "file", encoding type should be be multipart/form-data and the use of the _csrf parameter is required.

Example html request

From a web application, a config file can be uploaded as follows:

<form id="upload-form-id" method="POST" enctype="multipart/form-data" action="http://localhost:8080/api/v1/configmanagement/mcconfig?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5">
     <input type="file" name="file"/>
    <input type="submit" value="Upload"/>
</form>

Example curl request

$ curl -v -F file=@mc-server-config.xml 'http://localhost:8080/api/v1/configmanagement/mcconfig?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5'

Example http request

When the form is sent, a multipart request is build. A multipart request consists of 2 parts. A multipart/form-data content type with a boundary and the actual form data containing the file.

HTTP Content-Type:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryA9AwoUoMiBpVKdAU

HTTP Body:

------WebKitFormBoundaryA9AwoUoMiBpVKdAU
Content-Disposition: form-data; name="file"; filename="mc-server-config.xml"
Content-Type: text/xml


------WebKitFormBoundaryA9AwoUoMiBpVKdAU--

Example json response

The response is a json object that will contain a list of errors in case an error occured and the name of the uploaded xml file.

{"errors":[],"fileName":"mc-server-config.xml"}

Response structure

Path Type Description

fileName

String

Name of the uploaded file

errors[].status

Integer

Status

errors[].error

String

The error

errors[].message

String

Detailed error message

errors[].timeStamp

String

Time the error occured

errors[].trace

String

Stacktrace of the error if available

Download Master Controller Configuration XML file

The GET configmanagement/mcconfig resource can be used to download the current Master Controller Configuration XML file.

Example request

$ curl 'http://localhost:8080/api/v1/configmanagement/mcconfig' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
Content-Disposition: attachment; filename="2024_11_20_15_18_MC00_mcConfig.xml"
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 627

<?xml version="1.0" encoding="UTF-8"?>
<mc xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews" xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/mc.xsd">
    <mcId>MC00</mcId>
    <logging>
        <debugEnabled>false</debugEnabled>
        <rollingTotalSizeMB>5</rollingTotalSizeMB>
        <queryMinimalExecutionTime unit="hour" multiplier="1"/>
        <logEntryExpiryTime unit="day" multiplier="5"/>
        <windowsEventLogEnabled>false</windowsEventLogEnabled>
        <linuxSyslogFacility>local6</linuxSyslogFacility>
    </logging>
</mc>

Master Controller Configuration info

Since 2023.02

The GET configmanagement/mcconfig/info resource can be used to get info about the current uploaded mc config file.

Example request

$ curl 'http://localhost:8080/api/v1/configmanagement/mcconfig/info' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 135

{"mcConfigs":[{"creationUserId":"admin","commentText":"comment","lastModificationTime":1636549629541,"changedByAdminInterface":false}]}

Response structure

Path Type Description

mcConfigs[].lastModificationTime

Number

The time step of the last uploaded.

mcConfigs[].creationUserId

String

The user that uploaded the latest mc config.

mcConfigs[].commentText

String

The comment that was added to the latest mc config upload.

mcConfigs[].changedByAdminInterface

Boolean

Will be set to true if any changes using the Admin Interface results in changes to the mc config.

Delft-FEWS Configuration info

Since 2023.02

The GET configmanagement/fewsconfig/info resource can be used to get info about the current uploaded mc config file.

Example request

$ curl 'http://localhost:8080/api/v1/configmanagement/fewsconfig/info' -i -X GET

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 105

{"fewsConfigs":[{"creationUserId":"admin","commentText":"comment","lastModificationTime":1636549629541}]}

Response structure

Path Type Description

fewsConfigs[].lastModificationTime

Number

The time step of the last uploaded.

fewsConfigs[].creationUserId

String

The user that uploaded the latest fews config.

fewsConfigs[].commentText

String

The comment that was added to the latest fews config upload.

Upload Delft-FEWS Configuration zip file

The POST configmanagement/fewsconfig resource can be used to upload a Delft-FEWS configuration zip file. An optional description can be set using the "description" parameter. The name of the file parameter should be "file", encoding type should be multipart/form-data and the use of the _csrf request parameter is required. When using a description, the description fields should be the first part of the multipart post. Directories in ModuleDataSets or ColdStateFiles ending with ".zip" will be uploaded as zip files. This is to facilitate the integration with version control systems.

Example html request

From a web application, a config file can be uploaded as follows:

<form id="upload-form-id" method="POST" enctype="multipart/form-data" action="http://localhost:8080/api/v1/configmanagement/fewsconfig?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5">
    <input type="text" name="description"/>
    <input type="file" name="file"/>
    <input type="submit" value="Upload"/>
</form>

Example curl request

$ curl -v -F file=@config.zip 'http://localhost:8080/api/v1/configmanagement/fewsconfig?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5'

Example http request

When the form is sent, a multipart request is build. A multipart request consists of 2 parts. A multipart/form-data content type with a boundary and the actual form data containing an optional description and the required zip file.

HTTP Content-Type:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundarygXHJQDccIhgKRTLo

HTTP Body:

------WebKitFormBoundarygXHJQDccIhgKRTLo
Content-Disposition: form-data; name="description"

My config changes
------WebKitFormBoundarygXHJQDccIhgKRTLo
Content-Disposition: form-data; name="file"; filename="config.zip"
Content-Type: application/x-zip-compressed


------WebKitFormBoundarygXHJQDccIhgKRTLo--

Example json response

The response is a json object that will contain a list of errors in case an error occured and the name of the uploaded zip file.

{"errors":[],"fileName":"config.zip"}

Response structure

Path Type Description

fileName

String

Name of the uploaded file

errors[].status

Integer

Status

errors[].error

String

The error

errors[].message

String

Detailed error message

errors[].timeStamp

String

Time the error occured

errors[].trace

String

Stacktrace of the error if available

Download Delft-FEWS Config.zip file

Since 2022.02

The GET configmanagment/fewsconfig resource can be used to download the Delft-FEWS configuration in a zip file.

Example request

$ curl 'http://localhost:8080/api/v1/configmanagement/fewsconfig?uuid=myuniqueuuid' -i -X GET

Request parameters

Parameter Description

uuid

Unique identifier that can be used to track the download.

To track the status of the download, the uuid that has been passed as parameter can be used to call the session/status endpoint:

$ curl 'http://localhost:8080/api/v1/session/status?uuid=myuniqueuuid' -i -X GET

If the download is still in progress, the status will return 'downloading'.

Example response

HTTP/1.1 200 OK
Content-Type: application/zip; charset=utf-8
content-disposition: attachment; filename="Config-MC00-Stable2021.02-20241120-151802.zip"
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Response structure

The response is a binary zip file of Content-type application/zip

System Control

Since 2021.01

The systemcontrol resource can be used to control the Delft-FEWS live system. For example, it can be used to enable or disable the synchronization of a dual MC system.

Enable/Disable MC Synchronization

The POST systemcontrol/mcsynchronization resource can be used to enable or disable the MC synchronization. The _csrf parameter is required.

Example request

$ curl 'http://localhost:8080/api/v1/systemcontrol/mcsynchronization?_csrf=7f4acee4-9053-4249-b756-ccf5aa1dc5b5&mcId=mc00&enabled=true' -i -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded'

Request parameters

Parameter Description

_csrf

CSRF token required for POST requests

enabled

set to 'true' if synchronization should be enabled. Set to 'false' is synchronization should be disabled

mcId

id of the Master Controller for which synchronization should be enabled or disabled

Example response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 47

{"data":[{"enabled":true,"remoteMcId":"mc01"}]}

Response structure

Path Type Description

data[].remoteMcId

String

id of the Master Controller.

data[].enabled

Boolean

Flag to tell if synchronization is enabled for the remote mc id.