Skip to content

Instructions for Human Interaction with a WRES Web service

Jump to bottom
HankHerr-NOAA edited this page Jul 25, 2024 · 6 revisions

Table of Contents

For instructions on interacting with a WRES web-service through the command-line or via scripts or software, see Instructions for Programmatic Interaction with a WRES web-service. These instructions are for a human user to interact with the WRES web-service mostly through a browser.

1. POST the Evaluation Job

To execute the WRES evaluation project through a web-service and gather the outputs, manually, do the following:

Import the appropriate WRES web-service certificate authority .pem file into the web client to be used to run WRES.

To prepare for execution, an HTTP client must be used to make requests to the web interface of the WRES. That client can be on any machine, so long as that machine can find and access the WRES web-service. For a browser to access the web interface, the appropriate certificate authority .pem file, necessary to authenticate the service, must first be trusted by importing a the web-service CA .pem file into the browser to be used to access the web-service. This is, most likely, already the case. However, if that appears to not be the case, see your system administrator.

a) Use a browser to navigate to the WRES web-service landing page.

The URL to use will be provided by the WRES web-service system administrator.

b) Fill in the fields of the web interface.

In the Evaluation project configuration full text field, specify the project declaration, which could be copied-and-pasted from a local file.

c) Click Submit.

A webpage will be displayed stating that your job has been received for processing. The link below the title provide access to more information about the run. The following is a text example of what the web page will look like:

Evaluation job {job identification number} has been received for processing.

See /job/{job identification number}

The {job identification number} is a randomly selected number assigned to the job and will vary from run-to-run.

Clicking on the job link at the bottom of the page will display a web page titled, “How to proceed with job [job identification number] using the WRES HTTP API.” The URL of that web page will be referred to as the {job location URL} below. For example,

https://.../job/5298919962598457902

where ... is the omitted WRES web-service URL. Within the page will be provided four links:

  • /job/{job identification number}/status: This link will be to a page displaying the status of the run, either IN PROGRESS, COMPLETED_REPORTED_SUCCESS, COMPLETED_REPORTED_FAILURE, or others.
  • /job/{job identification number}/output: Once the output is completed, this link will be to a web page that lists the output of the run.
  • /job/{job identification number}/stdout: This link will be to a page displaying the log output of the run.
  • /job/{job identification number}/stderr: This link will be to a page displaying error output of the run, if any.

NOTE: Make sure to record the {job location URL} or otherwise ensure its available for when you perform Steps g and h, below.

2. Monitor the Evaluation Job Status

To view the status, click on the “status” link, described above. The resulting web page will not automatically refresh; to update the status, click refresh on your browser. Do not download any output until the run is completed, and only if the status is reported as COMPLETED_REPORTED_SUCCESS; see below If the run is not successful, then check the log output and error output for an indication of the error. If it is something that can be corrected by the user, do so, and submit the job again, but only after performing Step h, below, to ensure the failed job’s output is removed. If it cannot be readily corrected, then contact the WRES team as described at the bottom of this page.

NOTE: When reporting issues related to an evaluation using a WRES web-service, provide the {job identification number} to the support team. You can then quote aspects of the information provided in the log output or error output as needed in your problem description. Do not perform Step 6d, below, for the job with the reported {job identification number}. The output may help the WRES team investigate the issue.

3. Obtain the WRES Output Verification Statistics

The WRES execution will yield verification statistics with output generated in formats that can include CSV files, image PNG files, and NetCDF files. To download the output verification statistics, do the following:

a) On your local system, create a directory to contain the output that will be gathered.

The directory can be created anywhere.

b) Download the latest WRES web-service certificate authority .pem file to the output directory or identify where the file already exists on your system.

The web-service administrator should be able to provide you the appropriate CA .pem file.

c) Download the output files.

To do so, you can either manually download them by clicking links provided in the output page,

.../job/{job identification number}/output

or you can programmatically download the files.

Example of Programmatic Download Using curl

This example consists of setting a jobLocation variable and then using that variable within a curl command. The commands to perform are as follows and must be executed within the output directory created above (once the jobLocation is set, the curl command can be copied-and-pasted to the command line):

jobLocation={job location URL}   # The job location URL noted in Step c, above.
for resource in $(curl --cacert [web-service CA .pem] --header "Accept: text/plain" $jobLocation/output); do echo $resource; curl --cacert [web-service CA .pem] -o $resource $jobLocation/output/$resource; done

NOTE: Other tools than curl can be used; just be sure to access the URL, {job location URL}/output, to acquire the output.

4. Close the Evaluation and Cleanup After Yourself

Only perform this step after you have downloaded all outputs needed. If you have reported a bug related to the job, do NOT perform this step!

To close the evaluation and cleanup after yourself, using the same jobLocation variable defined above, execute this curl command:

curl -i -X DELETE --cacert [web-service CA .pem] $jobLocation/output

Again, other commands can be used to post the "DELETE" request. This is a signal to the WRES web-service that your software (or you, using a browser) is finished GETing the evaluation data and that the web-service may clean up evaluation output data.

What if I need to report an issue related to a particular WRES web-service evaluation?

If a problem is encountered and you will report it to the web-service admin, DO NOT PERFORM THE CLEAN UP IN STEP 4. Also, report the job identification number of job location URL to the service administrator.

The WRES Wiki

Home

Clone this wiki locally