52°North SOS Tutorial for v3.x

How to install, deploy and use the 52°North Sensor Observation Service 4.x is described here.

The installation, deployment and use of the 52°North Sensor Observation Service 3.x is described in the following sections. It depends on the current SVN trunk version (3.6.x) of the 52°North SOS. The downloadable source and binary releases (http://52north.org/downloads/sensor-web/sos 52north download page) have their own installation guides, shipped with the package.

It can be that this tutorial is not up-to-date with the current SVN trunk version of the 52°North SOS, but we are keen to keep it up-to-date.

The current 52°North SOS 3.x implements the OGC SOS implementation specification version 1.0.0 (OGC 06-009r6) and the some operations of the OGC SOS 2.0 standard (OGC 12-006 ) (both available at http://www.opengeospatial.org/standards/sos).

The 52°North SOS supports the three SOS 1.0.0 core operations GetCapabilities, GetObservation and DescribeSensor as well as the additional operations GetFeatureOfInterest, GetFeatureOfInterestTime, GetObservationById and GetResult. If you want to insert measurements using the SOS interface, you can use the operations of the transactional profile (RegisterSensor and InsertObservation) which are also supported by the SOS implemenation.

The supported operations of SOS 2.0 are GetCapabilities, GetObservation, DescribeSensor and GetFeatureOfInterest.

First Step: Identify the data, which should be provided by your 52°North SOS instance

The most important step when installing and providing a sensor observation service, is to identify the data items you want to publish and to map this onto the datamodel and concepts used by the 52°North SOS. A detailed discussion could be found on the SosDataModeling site.

Second Step: Download and install the required software

Downloading the required Software

This tutorial is based upon the following software:

Java SDK 6.0: You can download the Java SDK at http://java.sun.com/javase/downloads/index.jsp.

Apache Tomcat 6.0 or higher: The Apache Tomcat could be downloaded at http://tomcat.apache.org/download-60.cgi. Some hints on Apache Tomcat installation using Windows 7 (64 Bit) can be found at the side ApacheTomcatWindows

Apache Maven 2.2.1 or higher: Download Apache Maven from http://maven.apache.org/download.html and follow the instuructions given there.

PostgreSQL DBMS 8.4 or higher: The PostgreSQL database management system could be downloaded at http://www.postgresql.org/download/.

Postgis 1.4 or 1.5: The PostGIS spatial extension could be found at http://www.postgis.org/download/.

Installing PostreSQL and PostGIS

• Install PostgreSQL as descibed in the PostgreSQL manual available at http://www.postgresql.org/docs/manuals/
• Install PostGIS as descibed in the PostGIS documentation available at http://postgis.org/documentation/

Creating a PostGIS Database and SOS table structure

• Use the pgAdmin III – Tool. Start and connect to the database with pgAdmin (in Windows XP: Start > Programms > PostgreSQL x.x > pgAdmin III). The following window appears:

Figure 1:

• You find your „!PostgresSQL Database Server 8.x“ in the upper left corner of the window. Right click on the „!PostgresSQL Database Server x.x“ and choose „Connect“ in the pop up menu. Type in the name and password of the superuser you have chosen in the installation steps. Now the red cross over the icon of the server disappears and you are connected to the server.

Figure 2:

• When you right click on “databases” choose “new databases”. In the opening window (Figure 3) you can create the new database for your SOS (e.g. SosDatabase) typing the needed information and set the “template” field to “template_postgis”.

Figure 3:

• Now click on the button „Execute common SQL query“ in the toolbar. The query window of pgAdmin III appears.
• Click the „Open file“ button and navigate to the db-folder of your zip file. Open the file datamodel_postgres83.sql. The SQL statements now appear in the query field.

Figure 4:

• Now click the „Execute query“ button to execute the table. In the lower field appears the message „Query was succesfull.“ The tables are created now.
• Close the pgAdmin.

Third Step: Downloading and installing the SOS

Downloading the SOS

• You can check out the currrent sources from the SVN repository as described in the SvnSos.

Configuration of the pom.xml (optional)

• Open the main pom.xml-file in the SOS folder and edit the properties in the <properties> section. In Table 1 all changeable properties from the pom.xml are listed.

Property	Description
The following properties must (MANDATORY), can (OPTIONAL) be changed.
conf.sos.name	Name of SOS, change to your preferred name (OPTIONAL)
conf.sos.buil.properties	Default path and name for the build.properties file, can be set to a customized file (OPTIONAL)
project.build.sourceEncoding	Source encoding during build process !!! DO NOT CHANGE !!!
n52.common.xml.version	Version definition of the used 52N common XML dependenvies !!! DO NOT CHANGE !!!

• Save changes.

Configuration of the build.properties (required)

This section is currently not up to date. Please read the section 3.5 in the Installation guide of the sources.

• Open the build.properties file in SOS and edit the properties followed by
  #############################################################
  ##SOME OF THE FOLLOWING PROPERTIES HAVE TO BE CHANGED!!! ##
  #############################################################
  The properties followed by
  ####################################################################
  ##FOLLOWING PROPERTIES ONLY TO BE CHANGED FOR ADVANCED USERS!!! ##
  ####################################################################
  are for advanced users.
  The properties in the build.properties look like the following example:

      property.name = value

In Table 2 all changeable properties from the build.properties are listed. At the beginning of the table, you find properties you have to change (MANDATORY) or you can change (OPTIONAL).

Property	Description
The following properties must (MANDATORY), can (OPTIONAL) be changed.
conf.sos.ds.connectionstring	The connection string to your database. (e.g. jdbc:postgresql://localhost:5432/SosDB for PostgreSQL)(MANDATORY)
conf.sos.ds.user	The user name for your access to the database server (MANDATORY).
conf.sos.ds.password	The password for your access to the database server (MANDATORY).
conf.sos.service.url	URL of SOS web application, change if not localhost:8080. This URL is set in the testClient. (MANDATORY)
The following properties are for advanced users
conf.sos.supported.versions	Select the supported version(s)Select the supported version(s) 0 = SOS 1.0.0 and SOS 2.0 (default) 1 = only SOS 1.0.0 2 = only SOS 2.0 (ADVANCED)
conf.sos.configFile.path	Path to the configuration files for extended modules with additional properties (ADVANCED)
conf.sos.configFile.map	Configuration files and the file identifier (List: IDENTIFIER FILENAME;IDENTIFIER2 FILENAME2; ...) (ADVANCED)
conf.sos.enableAdminApi	Enable/Disable the admin API (default true) (ADVANCED)
conf.sos.getObs.maxResults	Maximum number of GetObservation results (0 or blank for unlimited) (ADVANCED)
conf.sos.response.compression.minSize	Minimum size of a response which should be compressed if supported by client (default = 1048576) (ADVANCED)
conf.sos.ds.daofactory	In the profiles section. Profile with id with-deploy. Class name of the data access object factory, including the package name (e.g. org.n52.sos.ds.pgsql.PGSQLDAOFactory).The SOS realizes the data access object pattern and therefore uses a factory for the data access objects. Change this only if you are an advanced user and you are using another data source! (ADVANCED)
conf.sos.capabilitiesCacheControler	Class of capabilities cache controller (ADVANCED)
conf.sos.capabilitiesCacheUpdateIntervall	Capabilities Cache Update Interval in minutes (0 = no automatic update) (ADVANCED)
conf.sos.ds.driver	The database jdbc driver (e.g. for PostgreSQL org.postgresql.Driver) Change this if you use another database system.(ADVANCED)
conf.sos.ds.initcon	Initial number of connections of the connection pool the SOS uses. It is not recommended to change this.(OPTIONAL)
conf.sos.ds.maxcon	Maximal number of connections of the connection pool the SOS uses. It is not recommended to change this.(OPTIONAL)
conf.sos.listeners	Comma separated list of the request listeners which are implemented (without white space!). Change this only if you have implemented further request listeners to support further operations. Following listeners are implemented GetCapabilitiesListener GetObservationListener GetObservationByIdListener DescribeSensorListener DescribeFeatureTypeListener DescribeObservationTypeListener GetResultListener GetFeatureOfInterestListener GetFeatureOfInterestTimeListener InsertObservationListener RegisterSensorListener (ADVANCED)
conf.sos.sensordir	The directory where the SensorML documents for each sensor (procedure) are stored. Change this only, if you want to store them in another directory. (ADVANCED)
conf.sos.10.omEncoder	SOS 1.0.0 Implementation of IOMEncoder used to encode observations (has to be reimplemented, if new observation types should be supported) (ADVANCED)
conf.sos.10.gmlEncoder	SOS 1.0.0 GMLEncoder implementation (implementation of IGMLEncoder) (ADVANCED)
conf.sos.10.featureEncoder	SOS 1.0.0 FeatureEncoder implementation (implementation of IFeatureEncoder) (ADVANCED)
conf.sos.10.owsEncoder	SOS 1.0.0 OWSEncoder implementation (implementation of IOWSEncoder) (ADVANCED)
conf.sos.10.postRequestDecoder	SOS 1.0.0 HttpPostRequestDecoder implementation (implementation of IhttpPostRequestDecoder) (ADVANCED)
conf.sos.10.getRequestDecoder	SOS 1.0.0 HttpGetRequestDecoder implementation (implementation of IhttpGetRequestDecoder) (ADVANCED)
conf.sos.10.requestDecoder	SOS 1.0.0 RequestEncoderimplementation (implementation of IRequestEncoder) (ADVANCED)
conf.sos.10.getResponseEncoder	SOS 1.0.0 ResponseEncoder implementation (implementation of IResponseEncoder) (ADVANCED)
conf.sos.10.sensorMLEncoder	SOS 1.0.0 SensorMLEncoder implementation (implementation of ISensorMLEncoder) (ADVANCED)
conf.sos.10.sensorMLDecoder	SOS 1.0.0 SensorMLDecoder implementation (implementation of ISensorMLDecoder) (ADVANCED)
conf.sos.showFullOperationsMetadata4Observations	Property indicates, whether OperationMetadata for GetObservation in GetCapabilities response contains only property names or property names and allowed values for FeatureOfInterest, Procedure and ObservedProperty(default = true) (ADVANCED)
conf.sos.showFullOperationsMetadata	Property indicates, whether OperationMetadata in GetCapabilities response contains only property names or property names and allowed values (default = true) (ADVANCED)
conf.sos.skipDuplicateObservations	Property indicates whether duplicate observations should be skipped silently when inserted by batch (default = true) (ADVANCED)
conf.sos.gmlDateFormat	gml date format: yyyy-MM-dd'T'HH:mm:ssZ (ADVANCED)
conf.sos.characterEncoding	Character encoding for response documents (ADVANCED)
conf.sos.10.srs.prefix	SOS 1.0.0 prefix URN for the spatial reference system (ADVANCED)
conf.sos.supportsQuality	Property indicates, whether SOS supports quality informations in observations or not; (default := false) (ADVANCED)
conf.sos.switchCoordinatesForEPSG	property keeps a list of all EPSG codes for which the SOS has to switch coordinates from long/lat to lat/long; PostgreSQL users please read the important note in section 4! (ADVANCED)
conf.sos.foiEncodedInObservation	Property indicates, whether SOS encodes the complete FOI-instance within an Observation instance or just the FOI id; (default := true) (ADVANCED)
conf.sos.foiListedInOfferings	Property indicates, whether to include list of FOI IDs in offerings (default = true) (ADVANCED)
conf.sos.childProceduresEncodedInParentsDescribeSensor	Property indicates, whether the SOS encodes the complete sensor description of a child procedure in the parent procedure description (default = false) (ADVANCED)
conf.sos.result.lease	Time of lease for result template in getResult operation (in minutes) (ADVANCED)
conf.sos.result.tokenseperator	Token seperator in result element (ADVANCED)
conf.sos.result.tupleseperator	Tuple seperator in result element (ADVANCED)
conf.sos.result.decimalSeperator	Decimal separator in result element (ADVANCED)
conf.sos.result.nodatavalue	No data value for result string containing the values in common observation and getResult response (ADVANCED)
conf.sos.capabilities.acceptformats	Accepted formats for capabilities (ADVANCED)
conf.sos.capabilities.sections	Allowed sections in a GetCapabilities request (ADVANCED)
conf.sos.logger.fileappender.filepath	Location where the log files should be stored (OPTIONAL)
conf.sos.logger.fileappender.filename	Name of the log file (OPTIONAL)
conf.sos.logger.level	The level which determines which log messages will be written into the log file. The standard is INFO. Below is a listing which levels are possible. It is not recommended to change the level. ERROR WARN INFO DEBUG TRACE (OPTIONAL)
conf.sos.logger.history.max	Define how many history log files should be stored (OPTIONAL)
conf.sos.supportDynamicLocation	Indicator of support for dynamic locations as spatial values (default=false). (ADVANCED)
conf.sos.dynamicLocation.observableProperty	Definition of the observable property for dynamic locations. Must be set if conf.sos.supportDynamicLocation=true. (ADVANCED)
conf.sos.setFoiLocationDynamically	Indicator for dynamic location setting of featureOfInterest. If true, conf.sos.supportDynamicLocation=true must be true (default=false). (ADVANCED)
conf.sos.prefix.default.offering	The default prefix for an auto generated offering (if not defined in RegisterSensor request) (ADVANCED)
conf.sos.prefix.default.procedure	The default prefix for an auto generated procedure (if not defined in RegisterSensor request) (ADVANCED)
conf.sos.eachProcFirstLatest	Indicator for the used GetFirst/GetLatest operation (default = false) (ADVANCED)
conf.sos20.om2Encoder	SOS 2.0.0 Implementation of IOMEncoder used to encode observations (has to be reimplemented, if new observation types should be supported) (ADVANCED)
conf.sos20.gml321Encoder	SOS 2.0.0 GMLEncoder implementation (implementation of IGMLEncoder) (ADVANCED)
conf.sos20.featureEncoder4SosV2	SOS 2.0.0 FeatureEncoder implementation (implementation of IFeatureEncoder) (ADVANCED)
conf.sos20.owsEncoder4SosV2	SOS 2.0.0 OWSEncoder implementation (implementation of IOWSEncoder) (ADVANCED)
conf.sos20.postRequestDecoder	SOS 2.0.0 HttpPostRequestDecoder implementation (implementation of IhttpPostRequestDecoder) (ADVANCED)
conf.sos20.getRequestDecoder	SOS 2.0.0 HttpGetRequestDecoder implementation (implementation of IhttpGetRequestDecoder) (ADVANCED)
conf.sos20.sensorMLEncoder	SOS 2.0.0 SensorMLEncoder implementation (implementation of ISensorMLEncoder) (ADVANCED)
conf.sos20.srs.prefix	SOS 2.0.0 prefix URN for the spatial reference system (ADVANCED)

In the following table 3 the properties for the service identification and service provider information are listed. These information are displayed in the Capabilities document.

Property	Description
Serivce identification information
conf.sos.capabilities.identification.title	Service title(OPTIONAL)
conf.sos.capabilities.identification.abstract	Service abstract(OPTIONAL)
conf.sos.capabilities.identification.keywords	Service keywords as lsit, separated by comma. Dynamically set as single keywords by the SOS.(OPTIONAL)
conf.sos.capabilities.identification.servicetype	Service tpye(OPTIONAL)
conf.sos.capabilities.identification.fees	Service fees(OPTIONAL)
conf.sos.capabilities.identification.accessconstrains	Access constraints information(OPTIONAL)
conf.sos.serviceidentificationfile	Path to the service identification file. The previous values are set in the file during the build process.(OPTIONAL)
Service provider information
conf.sos.capabilities.provider.name	Provider name(OPTIONAL)
conf.sos.capabilities.provider.site	Provider web page(OPTIONAL)
conf.sos.capabilities.provider.individual.name	Contact person(OPTIONAL)
conf.sos.capabilities.provider.position.name	Position of the contact persion(OPTIONAL)
conf.sos.capabilities.provider.phone	Phone number(OPTIONAL)
conf.sos.capabilities.provider.address	Address(OPTIONAL)
cconf.sos.capabilities.provider.city	City(OPTIONAL)
conf.sos.capabilities.provider.zip	ZIP code(OPTIONAL)
conf.sos.capabilities.provider.state	State(OPTIONAL)
conf.sos.capabilities.provider.country	Country(OPTIONAL)
conf.sos.capabilities.provider.email	eMail address(OPTIONAL)
conf.sos.serviceproviderfile	Path to the service provider file. The previous values are set in the file during the build process.(OPTIONAL)

• Save changes

Building the web application

In the following subsections we will define the capabilities skeleton and the sensor descriptions. As final step we will create the web application.

Provide Sensor-Descriptions

This step can be skipped if you want to use only the example sensor "Ifgi-sensor-1" which comes with the SOS installation

• Create an SensorML instance document for each sensor. Refer to the SensorML specification 1.0.1 (Botts 2007) for further information on SensorML.
• Store the instance documents in the web/WEB-INF/conf/sensors directory of your SOS directory.
• Make sure that the names of the documents are the same as the last part of their URNs. These URNs correspond to the procedure Ids in our data model (e.g. Name the SensorML file „ifgi-sensor-1a.xml“ if the URN is „urn:ogc:def:procedure:ifgi-sensor-1a“).
• The maven-script will copy the sensor descriptions to the [Tomcat Home]/webapps/[webapp.name]/WEB-INF/conf/sensors directory. If the sensor description has to be modified, change the SensorML document in the
• LOOK OUT!
  The sensors described in the SensorML documents are not directly registered in the SOS. To register the Sensors insert your data (mainly the procedures) into the database (for the examples execute the file test.sql (SOS/db) in the pgAdmin as described in chapter 3.4) and reload the SOS (e.g. Tomcat HTML-manager).

[Tomcat Home]/webapps/[webapp.name]/WEB-INF/conf/sensors directory.

• Ifgi-sensor-1.xml is an example sensor description for a simple water level station.

build the web application

• Assume your main directory of your local SOS repository ist C:\SOS
• Open a command line and go to the project's folder
• Type the following command line expression:
  • mvn install
  • if the building fails, proceed to the TroubleShooting page.
• The SOS is build and the WAR file is located in [SOS_HOME]\52n-sos-service\target\SOS_NAME.war, e.g. C:\SOS\52n-sos-webapp\target\52n-sos-webapp.war .

Deploy the web application

• Make sure that your Tomcat and your Postgres are started.
• Navigate to the Tomcat Manager, e.g. http://localhost:8080/manager/html.
• Scroll down to the section “WAR file to deploy” and select the WAR file to install, i.e. the file your created in section "build the web application".
• Click on “deploy”. The new service instance will be shown in the application list.

Forth Step: Testing the SOS

This step is to perform some requests on the SOS to test if it is working properly. The GetCapabilities-Request is the only request which is possible to be sent via HTTP GET- and HTTP POST-Request. The SOS-Webclient (see below) is attached to enable POST Request to the SOS. Make sure that you have executed the file test.sql in the pgAdmin.

Capabilities-Request via HTTP GET

• Open your browser. Type in http://localhost:8080/52n-sos-webapp/sos?REQUEST=GetCapabilities&SERVICE=SOS&ACCEPTVERSIONS=1.0.0
• The capabilities response document is now shown in your browser.
• You can extend the request above through appending the optional parmeters SECTIONS, ACCEPTFORMATS and UPDATESEQUENCE. Look at the SOS specification for more details.

Capabilities Request via HTTP POST

• Open your Internet Browser (e.g. Mozilla Firefox). You can find the SOS Test Client under http://localhost:8080/52n-sos-webapp/testClient.html. (Make sure that your Apache Tomcat is running)
• Open the GetCapabilities.xml file from the xml folder of your SOS directory with an editor.
• Copy the content into the Request field of the SOS Test Client.

Screenshot of the SOS test client for capabilities request:

• Click the „Send“-Button. The capabilities response xml-document is now shown in your browser.

Sending Generic Requests

You can send a any requests to the SOS via HTML POST with different types of software. Some examples are:

• the Firefox Add-on Poster
• the software SoapUI
• HTTP clients in the programming language of your choice, such as Java (without any libraries see here), Python or the command line using cURL

When you use a 52North SOS, you can most easily use the test client form available at http://your-server.tld/your-webapp-name/, for example http://sensorweb.demo.52north.org/52nSOSv3.2.1/, as described above.

Other tests

• You can try the other xml request files in the xml-folder analogous to the HTTP Post based GetCapabilities request.

Update from older SOS version.

To update the SOS from an older release, you have to update the SOS database schema. Run the following sql scripts (located in SOS/db/changes) in PostgreSQL for you SOS database.

• del_trigger_and_unused_offering_columns.sql
• update_DB_for_new_valueTypes.sql
• del_observation_offering.sql

then you can undeploy you old SOS version and deploy the new one.

-- CarstenHollmann - 30 Mar 2010