Page tree
Skip to end of metadata
Go to start of metadata

The basic usage of the Admin Interface REST API is explained here. For a complete list of available API functions, please refer to the Admin Interface itself.

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 -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 15 minutes or more.

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 15 minutes.

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

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;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 4078

{"statusDate":1548848408175,"forecastingShellServersStatus":0,"forecastingShellServersStatusDescription":"OK","masterControllers":[{"mcId":"roadmapmc00","status":0,"statusDescription":"OK","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"},"alive":true,"statusFailedOver":false,"statusOk":true,"statusFailed":false,"statusUnknown":false},{"mcId":"roadmapmc02","status":0,"statusDescription":"OK","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"},"alive":true,"statusFailedOver":false,"statusOk":true,"statusFailed":false,"statusUnknown":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,"statusOk":true,"statusFailed":false,"statusUnknown":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"},"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"}]}

Response structure

PathTypeDescription

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 code.

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.

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[].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.

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.

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

ParameterDescription

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-20201013-090945.zip"
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 343

{"databaseConnections":{"numberOfDatabaseConnections":10,"maxNumberOfDatabaseConnections":100},"operatorClientConnections":{"numberOfOperatorClientConnections":5,"maxNumberOfOperatorClientConnections":40},"forecastingShellServerConnections":{"numberOfForecastingShellServerConnections":4},"serviceConnections":{"numberOfServiceConnections":1}}

Response structure

PathTypeDescription

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.

forecastingShellServerConnections.numberOfForecastingShellServerConnections

Number

Number of Forecasting Shell Server database connections that are used by Delft-FEWS.

serviceConnections.numberOfServiceConnections

Number

Number of Services connections that are used by Delft-FEWS.

Logs

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

List logs

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&source=FS%25205%2520ukeafffsmc00%253A000026752%2509&code=TaskRun.Completed&text=Task&build=81204&taskRunIds=roadmapmc00:003803615' -i -X GET

Request parameters

ParameterDescription

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.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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":1602573049697,"level":"INFO","source":"source 1","text":"Text","build":1234,"componentId":"mc1","eventAcknowledged":0}]}

Response structure

PathTypeDescription

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 acknowledge.

draw

Number

unique identifier of request.

recordsTotal

Number

Total number of records available.

recordsFiltered

Number

Total number of records after filtering.

Acknowledge logs

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

Request parameters

ParameterDescription

_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

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

ParameterDescription

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;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 686

{"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":null,"taskStatus":"status","latestTaskRunDispatchTime":0,"latestTaskRunStatus":"status","latestTaskRunTime":null,"latestTaskRunScheduledTime":null,"latestTaskRunCompletionTime":null,"runOnFailover":0,"approve":null,"taskRepeatTime":null,"currentForecastDispatchTime":1583151306,"currentForecastDispatchTimeBackgroundColor":"#ff0000","failoverPolicy":"RUN_DUTY"}],"remoteMcAvailable":true,"whatIfAvailable":true,"tagAvailable":true}

Response structure

PathTypeDescription

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

Null

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

tasks[].latestTaskRunScheduledTime

Null

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

tasks[].latestTaskRunCompletionTime

Null

Latest Task Run status of the task

tasks[].endTime

Null

Last time a task should be scheduled

tasks[].runOnFailover

Number

Can the task run in failover mode

tasks[].approve

Null

Should the forecast be approved

tasks[].taskRepeatTime

Null

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;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

PathTypeDescription

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, F=Failed, I=Invalid, P=Pending, R=Running, S=Scheduled, T=Terminated

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.

Files

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

Import Status

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;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 305

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

Response structure

PathTypeDescription

importStatus[].mcId

String

mcId of the import.

importStatus[].dataFeed

String

Name of the imported data feed.

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.

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 Config Management patch, a Base Build, a Server Configuration file and a Delft-FEWS configuration.

Upload Configuration Manager patch .jar file

The POST configmanagement/cmpatch resource can be used to upload a Delft-FEWS Configuration Manager patch 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/cmpatch?_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/cmpatch?_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

PathTypeDescription

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

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

PathTypeDescription

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

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

PathTypeDescription

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
Content-Disposition: attachment; filename="masterControllerConfig-13/10/2020 09:09:54.xml"
Content-Length: 630
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

<?xml version="1.0" encoding="UTF-8"?> <mc xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/mc.xsd" xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <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>

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 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.

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

PathTypeDescription

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


  • No labels