Getting Started

Here is a quick guide to getting WOFpy up and running.

Installation

Follow the steps below to install WOFpy and its prerequisites on a Windows computer.

  1. Install Python 2.7. The 32-bit installer is recommended.
  2. Add the Python folder to your Path environment variable.
  3. Install setuptools. This allows the setup script to be run.
  4. Add the Python/scripts folder to your Path environment variable.
  5. Open a command window (run cmd), navigate to the WOFpy folder (with setup.py in it), and enter this command: python setup.py install

The wof package (in the subfolder named wof) is now accessible from any directory.

If you edit code in the wof folder, you may need to run setup.py again to apply the changes to your system.

Database Support

You may need to install additional components to connect to your database. * sqlalhchemy * pydobc (for ODM1_1 using sqlserver and ODM2) * msqldb (for ODM1_1 using mysql) * ODM2API (for ODM2 example) * other database drivers: postgres, sqllite, mysql.

PIP Installs

TBD: ONCE a Package is created and packaged. pip install WofPy

If you are using ODM, or ODM2, then you need to run the extras (ODM1, or ODM2) pip install WofPy -e .[ODM2]

Running the Examples

Example services are included with WOFpy. Each example consists of data, Data Access Objects (DAOs), models, and the service definition. The examples are located in the examples folder.

The general procedure for each example is to set up any required data connections, use Python to run the runserver.py script, and test the service using a Web browser or other client application. The script should print service endpoint URIs in the window used to execute the script.

When testing is complete, you should stop the service. For example, if you started the service using a command window in Windows, you can stop the service by pressing CTRL+C in the command window.

Note

These examples are run in debug mode for demonstration purposes. In a production environment, you would use something like IIS or Apache to manage the service.

The examples are described in more detail below.

Barebones SQLite Example

This example is located in the examples/flask/barebones folder.

This example shows how to access a very simple SQLite database located in the LCM_Data subfolder. The database only has three tables in it: one for sites, one for variables, and one for data values. The remaining information required for WaterML is read from a config file.

Follow the steps below to run this example.

  1. In the examples/flask/barebones folder, edit the value of the openPort variable in runserver_LCM.py to match an open port on your computer, if necessary. Then save and close the file.
  2. Open a command window in the examples/flask/barebones folder and enter: python runserver_LCM.py
  3. In your command window you should see a message indicating that the service is running along with instructions for accessing the service.

Comma Delimited File Example

This example is located in the examples/flask/csv_server folder.

This example shows how to access data from comma delimited (CSV) files in the csv subfolder. One CSV file contains the time series values, while another contains descriptions of observations sites.

Follow the steps below to run this example.

  1. In the examples/flask/csv_server folder, runserver_csv.py Then save and close the file.
  2. Open a command window in the examples/flask/csv_server folder and enter: python runserver_csv.py
  3. In your command window you should see a message indicating that the service is running along with instructions for accessing the service.

SWIS SQLite Example

This example is located in the examples/flask/swis folder.

This example shows how to access a more complicated SQLite database based on early designs of the Texas Water Development Board’s Surface Water Information System (SWIS) database.

Follow the steps below to run this example.

  1. In the examples/flask/swis folder runserver_swis.py t
  2. Open a command window in the examples/flask/swis folder and enter: python runserver_swis.py
  3. In your command window you should see a message indicating that the service is running along with instructions for accessing the service.

ODM 1.1 SQL Server Example

This example is located in the examples/flask/odm_1_1 folder.

This example shows how to access CUAHSI Observations Data Model (ODM) databases in Microsoft SQL Server. The example uses the Little Bear River ODM 1.1 example database from the HIS website at http://his.cuahsi.org/odmdatabases.html.

Follow the steps below to run this example.

  1. Install Microsoft SQL Server. You can download the free version, SQL Express.
  2. Download the Little Bear River ODM 1.1 database from the HIS website.
  3. Attach the database to SQL Server.
  4. Grant a SQL Server account select privileges on the database. WOFpy will use this account to connect to the database.
  5. Determine the database connection string. lbr_connection_string set to a SQLAlchemy-compatible database connection string for the Little Bear River database, e.g. in a file ending in .connection (eg private.connection or lbr.connection), ‘mssql+pyodbc://webservice:webservice@localhost/LittleBear11?driver=SQL+Server+Native+Client+10.0’``
  6. In the examples/flask/odm_1_1 folder, edit the value of the openPort variable in runserver_odm_1_1.py to match an open port on your computer, if necessary. Then save and close the file.
  7. Open a command window in the examples/flask/odm_1_1 folder and enter:
python runserver_odm_1_1.py
--config=lbr_config.cfg
--connection=lbr.connection

  1. In your command window you should see a message indicating that the service is running along with instructions for accessing the service.

    ODM1Services

ODM 2 SQL Server Example

This example is located in the examples/flask/odm2 folder.

These examples show how to access Observations Data Model (ODM2) databases in PostgreSQL/Mysql Server. The example for ODM2 measurement data uses the Marchantaria Time Series ODM2 PostgreSQL database from the ODM2 github at https://github.com/ODM2/ODM2/tree/master/usecases/marchantariats. And the example for ODM2 timeseries uses Little Bear River Test ODM2 Mysql Database from ODM2 github at https://github.com/ODM2/ODM2/tree/master/usecases/littlebearriver/sampledatabases.

Follow the steps below to run this example.

  1. Install PostgreSQL or Mysql Server based on the data use cases.

  2. Download ODM2 database from the ODM2 github at above URLs.

  3. Download the ODM2API (https://github.com/ODM2/ODM2PythonAPI/tree/setup). At src folder, enter this command: python setup.py install.

  4. Determine the database connection string. odm2_connection_string set to a SQLAlchemy-compatible database connection string for the ODM2 database, e.g., ‘postgresql+psycopg2://username:passowkr@hostname:port/db_name’ or, ‘mysql+mysqldb://username:password/db_name’

  5. In the examples/flask/odm2/{measurement|timeseries} folder, edit the value of the openPort variable in runserver_multiple.py|runserver_odm2_measurement.py|runserver_odm2_timeseries.py to match an open port on your computer,

    ODM2Services

CBI External Service Example

This example is located in the examples/flask/cbi folder.

This example shows how to access a Web service provided by the Conrad Blucher Institute (CBI) for the Texas Coastal Ocean Observation Network (TCOON). TCOON is a live network with new values continuously pouring in from sensors along the Texas coast. Data access is provided by a variant of the OGC’s Sensor Observation Service (SOS). We will provide access to the data with a WaterOneFlow service by wrapping the TCOON SOS service with our data access object (DAO) and supporting modules. Because site and variable descriptions do not change frequently in TCOON, we store that information in a local SQLite database. The result is a Web service that uses both a SQLite database and another Web service to provide data to the client. Of course, the client has no idea that this is happening. All the client cares about is that we provide access using a standard WaterOneFlow service and send responses back in WaterML format!

This example requires an internet connection to access the TCOON Web service. To prepare your service, you will make a cache of sites and variables available from TCOON. Then you will run the service.

Follow the steps below to run this example.

  1. Open a command window in the examples/flask/cbi folder and enter: python build_cbi_cache.py
  2. In the command window, enter: python runserver_cbi.py
  3. In your command window you should see a message indicating that the service is running along with instructions for accessing the service.

Multiple Services Example

This example is located in the examples/flask/ folder.

This folder contains a runserver_multiple.py script demonstrating how to run multiple services at once. It uses the barebones and SWIS examples. Follow the steps below to run this example.

  1. In the examples/flask/ folder, edit the value of the openPort variable in runserver_multiple.py to match an open port on your computer, if necessary. Then save and close the file.
  2. Open a command window in the examples folder and enter: python runserver_multiple.py
  3. In your command window you should see a message indicating that the service is running along with instructions for accessing the service.

The services will be run. At start, a set of HTML pages with examples is generated.

The services can be found: * http://127.0.0.1:8080/{network}/rest/1_0 * http://127.0.0.1:8080/{network}/rest/1_1 * http://127.0.0.1:8080/{network}/rest/2 * http://127.0.0.1:8080/{network}/soap/wateroneflow * http://127.0.0.1:8080/{network}/soap/wateroneflow_1_1

Accessing WOFpy REST Web Services for WaterML 1 and WaterML2

Running the examples is a great way to learn the REST syntax for accessing data with WOFpy. The examples create a web page with sample URIs illustrating the required syntax. You can click the URIs in your browser to see the results. The syntax is also described below.

Getting Site Locations

  • GetSites - Returns locations of all sites
  • GetSites?site=network:site_code - Returns location of site with given site code in given network

Discovering What Is Measured at a Site

  • GetSites?site=network:site_code - Returns location of given site and summary of all time series available at the site

Getting Information about Variables

  • GetVariableInfo - Returns descriptions of all variables
  • GetVariableInfo?variable=vocabulary:variable_code - Returns description of variable with given variable code within the given vocabulary

Downloading Time Series Values

  • GetValues?location=network:site_code&variable=vocabulary:variable_code - Returns all data at the given site for the given variable
  • GetValues?location=network:site_code&variable=vocabulary:variable_code&startDate=YYYY-MM-DDThh:mm&endDate=YYYY-MM-DDThh:mm - Returns data at the given site for the given variable intersecting the given time period

Note

The time format is ISO time. You can leave out the time component and just write YYYY-MM-DD. You can specify time zone by appending the offset from Universal Time Coordinates (UTC) in hours to the end of the date string, or by appending Z to indicate UTC. For example, to specify April 5, 2011, 5:00 PM in US Central Standard Time: 2011-04-05T05:00-06

See Wikipedia for more examples.

WaterML 2

  • http://127.0.0.1:8080/{entwork}/rest/2/
  • GetValues?format=wml2&location=network:site_code&variable=vocabulary:variable_code&startDate=YYYY-MM-DDThh:mm&endDate=YYYY-MM-DDThh:mm - Returns data at the given site for the given variable intersecting the given time period in WaterML 2.0 format.

Note

WaterML 2.0 format is only available for GetValues requests.

Accessing WOFpy SOAP Web Services

The SOAP endpoint follows the WaterOneFlow standard, whose method signatures and WaterML responses are described on the HIS website at http://his.cuahsi.org/wofws.html.

WSDL Endpoints: * http://127.0.0.1:8080/{network}/soap/cuahsi_1_0/.wsdl * http://127.0.0.1:8080/{network}/soap/cuahsi_1_`/.wsdl These correspond to SOAP endpoints: * http://127.0.0.1:8080/{network}/soap/cuahsi_1_0 * http://127.0.0.1:8080/{network}/soap/cuahsi_1_1

One of the easiest ways to test the SOAP endpoint is to use the free soapUI program. To test with soapUI:

  1. Install soapUI.
  2. Run WOFpy, perhaps using the csv in the examples.
  3. Start soapUI.
  4. In soapUI, click File, and then click Import Project.
  5. Go to testwofpy-1-1-soapui-project.xml
  6. Expand the example request for GetSites and double-click GetAllSites to open that request.
  7. At the top of the window, there is a menu with url like http://127.0.0.1:8080/txrivers/soap/cuahsi_1_1/ click, select the url for the example, or if you have a new service, [add new endpoint]
  8. Expand WOF11 Soap TestSuite, Double Click Run Test Case
  9. In window, select URL icon. Run
  10. Click the play button to issue the request. A new window should open with the SOAP response showing information about the site.