CUAHIS-HIS
RSS

Navigation





Quick Search
»
Advanced Search »

PoweredBy



Introduction

The CUAHSI Observations Data Model (ODM) is a schema for storing hydrologic observations time series data. Scientists apply the schema to create an Observations Database (OD) for their data. To assist scientists in publishing their OD data, CUAHSI has developed an OD web service. This document explains how to install and configure an OD web service for your OD.

Requirements

Software:
  • Micosoft Windows XP or 2003
  • IIS with ASP.Net
  • .Net 2.0 Framework
  • SqlServer Express, or SQL Server Database that service can connect to

Data:
Personnel:
  • User with administrator account

Procedure

This section describes the steps required to set up the service. For the advanced user, each section begins with a description of what is being done. If you understand the description, you may proceed on your own. For users who need more information than the short description, step-by-step instructions follow the description.

Preparing the Application for use

Prior to using the web application, you will need to determine the following information.
Network - Site Vocabulary, Vocabulary - Variable Vocabulary
In order to differentiate different ODM instances, the ODM databases should be defined by a unique acronym. The CUAHSI web services call this acronymn, the network. We define a network as a set of sites with observations of variables contained within a single observations database. A network prefix is submitted with queries to the web service. Information for a site is retrieve using a parameter containing "NETWORK:SiteCode" A network has a set of variable codes, associated with it's observations. We call this set of variable codes a vocabulary. Often the network and vocabulary will be the same. But network and vocabulary may be different if a set of networks share a common variable vocabulary. Information on about a variable is retrieve using a parameter 'VOCABULARY:VariableCode'

Basic Application Settings (appSettings) in web.config
application settingdescription
networkNetwork is a set of observations within a single observations database. This will also have a common vocabulary. This brief code refers to the observation network to which your database pertains. The code should be brief, and contain no space, colons or slashes. The network prefixes requests to the web services for site information, eg Network:SiteCode
vocabularyvThe vocabulary refers to the vocabulary in the database from which the variable code are drawn. If
Menu Name for GetValuesThe “GetValuesName” can be used by applications as hint of what to call your network in a menu. It should be a brief name (<25 characters). This is a hint for client to display with the series catalog information.
Example HTML PageThis is the page that will have the examples of you data.
database connection stringConnection string for your database. See SQL Server Database Connection String, below for details.

Installation

There are two installation options
The zip file version can be used to create multiple IIS web applications. This method is described in the manual installation section, in the advanced section.

Select your installation method
After installation, you will need to do two steps in order to prepare the application for use:
  1. create a page that contains some example data
  2. Input some application configuration parameters.



SQL Server Database Connection String

The connection string defines the connection to your database. Internally, the connection is called “ODDB”. A good reference on connection strings is ConnectionStrings.com

Example SQL Server Configuration Strings for connectionStrings in web.config
TypeConnectionString
Inside app_dataData Source=.\SQLEXPRESS;Integrated Security=true;User Instance=true;AttachDbFilename=|DataDirectory|{FILENAME};Database={DATABASE_NAME}
local fileData Source=.\SQLEXPRESS;Integrated Security=true;User Instance=true;AttachDbFilename={PATH_TO_FILE}{FILENAME};Database={DATABASE_NAME}
local databaseData Source=.\SQLEXPRESS;Integrated Security=true;Database={DATABASE_NAME}
remote using windows authenticationData Source={HOSTNAME};Integrated Security=true;Database={DATABASE_NAME}
Remote using SQL Server authenticationData Source={HOSTNAME};Database={DATABASE_NAME};user={User};password={password}

Note: In the connection string, replace the items in brackets with your actual items (do not include the brackets):
  • {HOSTNAME} – the computer’s name hosting the database, e.g., DatabaseComputer
  • {DATABASE_NAME} – e.g., MyOD
  • {PATH_TO_FILE} – e.g., c:\Databases\
  • {FILENAME} – e.g., MyDatabase.mdf

Application configuration via the configuration web page

This will only work from the local host. Manual editing of the web.config file is described in the Manual editing of the web.config file section, below.
  1. go to http://localhost/FOLDER NAME FOR YOUR SERVICE/Configure.aspx
  2. input values
  3. Click OK
  4. Click Test Database Connection



Test the Application

Now you’re ready to test the application. Open a browser, and navigate to your localhost\Service folder, and invoke some calls for testing. We will do the steps below:
  1. Test the basic database connectivity
  2. Test the basic parameters using the web form

Test the database connectivity

  1. Open an Internet browser.
  2. In the address bar of the browser, enter the following address:{http://localhost/FOLDER NAME FOR YOUR SERVICE/databasetest.aspx}
  3. Success or failure of test
    • If you see an error, similar to below, fix your configuration string:
      DatabaseTest Error

      DatabaseTest Error

    • If you If you see no errors, the the connectivity to the database is working.
      DatabaseTest success

      DatabaseTest success



Test the basic parameters using a web form

  1. Open an Internet browser.
  2. In the address bar of the browser, enter the following address:
    {http://localhost/FOLDER NAME FOR YOUR SERVICE/}
  3. Input test parameters and see if your service works.

(Optional)

Enable Encrypted Connection String Settings

You can enable encryption of the connection string in the application web.config file. Enabling this will secure the connection parameters from prying eyes. From localhost go to the page: http://localhost/{Your Application}/configure.aspx

Configure logging

Logging uses a codebase called log4net (http://logging.apache.org/log4net/). There are two logs created, 1) a query log (log-data\query-log.txt), and 2) webapp-log.txt. The query-log.txt contains details on the queries, and webapp-log.txt can contain detailed debug information. 1. Server logs are configured to send data to SDSC and write local error information to a directory called log-data. If this directory is not writable or present, then no local error information will be available. To change, open “wateroneflow.logging.log4net” edit the 

<appender name="QueryLogFileAppender" type="log4net.Appender.RollingFileAppender">
    <file value="log-data\query-log.txt" />
<!-.. ->
</appender>

Advanced

Manual Editing of Web.Config

You’ll now edit the Web.Config for the service to give your service a network name and vocabulary, and specify the connection string to your database.

1. In the folder for your web service, locate the Web.Config file, and edit it.
web config 1

web config 1

Note: I’ve used Visual Studio 2005 as my editor in these screenshots.

2. In Web.Config, set the network and vocabulary for your service by editing the appropriate <add> elements. The network refers to the observation network to which your database pertains, such as “NWIS Daily Streamflow”. The vocabulary refers to the framework within which the terms that you use apply, such as “NWIS”. You can leave these as the default value of “ODM” if you wish. The “GetValuesName” can be used by applications as hint of what to call your network in a menu. It should be a brief name (<25 characters). 
	
<add key="network" value="ODM"/>
<add key="vocabulary" value="ODM"/>
<add key="GetValuesName" value="Local OD GetValues" />

3. Edit the connection string for your database. To find the connection string, location the <connectionStrings> element. Then find the <add> element that is a child of <connectionStrings>, which has a name of “ODDB”. This element has an attribute called “connectionString”, which you will edit as follows: a. If database is inside the App_data folder: 
	
<add name="ODDB"	
connectionString="Data Source=.\SQLEXPRESS;	
Integrated Security=true;	
User Instance=true;	
AttachDbFilename=|DataDirectory|[FILENAME];	
Database=[DATABSE_NAME]" providerName="System.Data.SqlClient"/>
b. If database is a local file: 
	
<add name="ODDB" connectionString="Data Source=.\SQLEXPRESS;	
Integrated Security=true;	
User Instance=true;
AttachDbFilename=[PATH_TO_FILE][FILENAME];	
Database=[DATABSE_NAME]" providerName="System.Data.SqlClient"/>
c. If database is a local database: 
	
<add name="ODDB" connectionString="Data Source=.\SQLEXPRESS;	
Integrated Security=true;	
Database=[DATABSE_NAME]" providerName="System.Data.SqlClient"/>
d. If database is remote: 
	
<add name="ODDB" connectionString="Data Source=[HOSTNAME];	
Integrated Security=true;
Database=[DATABSE_NAME]" providerName="System.Data.SqlClient"/>
Note: In the connection string, replace the items in brackets with your actual items (do not include the brackets):
  • [HOSTNAME] – the computer’s name hosting the database, e.g., DatabaseComputer
  • [DATABASE_NAME] – e.g., MyOD
  • [PATH_TO_FILE] – e.g., c:\Databases\
  • [FILENAME] – e.g., MyDatabase.mdf

4. Save and close Web.Config

Create BasicData.htm and Edit

A file is included with appended to the web service description page when that page is viewed with an Internet browser. By default, the page "BasicData.htm" gives information about your service, such as example parameters that can be used for testing the service. Edit this page to describe your service and data.

  1. Copy BasicData_Example.htm to BasicData.htm
  2. Edit BasicData.htm. You may put whatever content you like in this file.
  3. Save and close BasicData.htm.

As an example, I edited BasicData.htm to show how to retrieve data from the sample OD.mdf database included with GenericODws.zip.

basicDatahtml

basicDatahtml

Troubleshooting

Issues are with the database, and the ASP.Net configuration

If you get an error that says XXX when you attempt to go to the { http://localhost/FOLDER NAME FOR YOUR SERVICE/ } That is most likely a permissions problem, go through steps in Set Folder Permissions and the IIS Manager

If you get an error when try to use the web service, then it is probably a database issue.

Set Folder Permissions

You must set permissions for the folder so that the appropriate accounts have enough control to make the service work. The permissions you are setting are:

  • [Your Service Folder]: Everyone - Read
  • [Your Service Folder]: ASPNET - Full Control
  • [Your Service Folder]:IIS_WPG - Modify
  • [Your Service Folder]\App_Data: Network_Service - Full Control

1. In Windows Explorer, right click on the web service folder, and click Sharing and Security.
Menu

Menu


2. Click the Security tab.



3. Set the following permissions: a. Everyone - Read b. ASPNET - Full Control c. IIS_WPG - Modify

If you did not see the group or user name for the above permissions, you will need to add that permission. Steps 4-11 walk you through that process. Otherwise, skip to step 12.

4. Click Add. 5. In the Select Users, Computers, or Groups window, click Advanced.

user dialog

6. In the window that opens, click Locations. 7. In the window that opens, select your computer, and then click OK.

security dialog

security dialog


8. Click Find Now. 9. Scroll to the desired name, highlight it by left clicking on it, and click OK.

location

location


10. Click OK to confirm the user name.

populated users

populated users


11. Set the permissions, and then click Add if there are remaining user names that you need to add.

popualted permissions

popualted permissions


12. Click OK to close the Properties window for your folder. 13. Within your web service folder, navigate to the App_Data folder. 14. In the same manner as above, set permissions for the App_Data folder as follows: a. Network_Service - Full Control

populated permissions network

populated permissions network


15. Click OK to close the Properties window.

ScrewTurn Wiki version 3.0.1.400. Some of the icons created by FamFamFam.