Introduction

This document provides detailed installation instructions for configuring and deploying VocBench version 2.0.

This guide is meant to remain as “static” as possible, along different configuration scenarios embracing data and vocabulary updates, changes in the various installation settings etc. For this reason, reference is made to an external wiki page on the google project site of VocBench:

https://code.google.com/p/agrovoc-cs-workbench/wiki/VB2_Installation

In the above wiki page, several configuration parameters have been defined, belonging to the different components which are part of VB2.0. The user may refer to a particular installation configuration presented there, as a series of ATTRIBUTE-VALUE pairs, where ATTRIBUTE is one of the configuration parameters required by the installation and VALUE represents the specific value which will be assigned for that particular configuration. This installation guide will use ATTRIBUTE names which are consistent with those present in the wiki.

The ATTRIBUTE will be explicitly mentioned by wrapping it between {} brackets.

E.g. {OWLIM.TOTAL_CACHE_MEMORY}

The installation package of Vocbench downloadable from its project site, which contains all or most of the components for installing VB2.0, will be referred along the guide as:

INST_PKG

When a file name for an installation component is referred in this guide without further specifying its full path, we are assuming it is in INST_PKG.

Pls contact the authors of this guide if you find any discrepancy in the use of any of the conventions explained above.

Requirements

Third Party Software

  1. Apache Tomcat web server (version 6.0 or higher)

    EXAMPLE: debian:apt-get update; apt-get install sun-java6-jdk apache2 tomcat6 libmysql-java


  2. MySQL database server (version  5.0 or higher)

    EXAMPLE:

  3. OWLIM (Version {OWLIM.VERSION}).

Our Software

Data

  1. RDF Data File {DATA.VERSION}
  2. Administrator Database  {VB.DB.VERSION}

Installation Steps

Setting up the main Software Components

1.  OWLIM Setup    

2.  Semantic Turkey Server Setup

In the directory ST-Server, there are batch files for Windows (.bat) and UNIX (.sh) to launch the server.

A further integration step would ask for VocBench OSGi bundle {ST.VB-BUNDLE.VERSION} to be copied inside the ST-Server directory under folder ST-Server\extensions\service. However, the OSGi bundle already comes packed inside the ST-Server, so perform this only if you get a specific update of the OSGi bundle.


3.  Import the Administrator Database SQL Dump File ({VB.DB.VERSION}) on MySQL Server

EXAMPLE: debian: mysql -u {your.db.user} -p < administrator20.sql

4.  VOCBENCH Setup  (don’t follow this if you have been redirected to this Full Installation guide from the QUICK installation guide, and come back instead to that guide)

Replace administrator_database_name with appropriate VocBench administrator database name, user & password values with the database username and password respectively. Also, the dbConnectionUrl may require further changes if you adopted a specific setup (you know how to handle them in case).

Configuring a specific instance

1.    OWLIM REPOSITORY SETUP and DATA LOADING

and stop before the instruction starting with this text:
“Fill in the fields as required…”  
follow now the specific instructions here below for creating a repository

Also, other than all the “OWLIM.” prefixed properties, consider the {DATA.BASEURL} to be used in the “Base URL” field of the configuration.

In particular, be sure to check that all the parameters starting with {OWLIM. in the interested configurations have found a match in the entries (with a similar name) in the form, and leave untouched all those form fields which are not specified in the configurations.  
Confirm after all the fields have been filled up, by clicking the “create” button.

 2.   Add the new project to Semantic Turkey

This will be defined in a new version of the guide. If you have installed SemanticTurkeyData in the “Semantic Turkey Server Setup”, it will come with an already configured project for your first install.

Running the System

Running Semantic Turkey

Running Vocbench

  1. Run Tomcat.
  2. Access VB from the browser at:

http://localhost:8080/<vocbench-deployment-name> (Change URL according to your configuration)

Example:

http://localhost:8080/vocbench-2.0

  1. VB has been preconfigured with administrator user. Use following credentials to connect as administrator. Administrators are the super users who can create new users and approve new users.

Administrator User Credentials:

Username: administrator

Password: 111111

In appendix A, there are specific instructions for performing some actions from behind-the-scenes, such as directly configuring a new project from the AdminDB of Vocbench, or creating the project through Semantic Turkey etc…

However, unless you experience some problem, you may follow the instructions in the next sections, which instruct the user on how to create and manage projects through the ST user interface


Project Management

After successful installation of VocBench, Semantic Turkey Server and OWLIM, a project has to be created, configured and populated with data.

The following sections instruct the user on how to create a new project

  1. Project Creation/Deletion
  2. SKOS Concept scheme Management
  3. Ontology Import
  4. Namespace Prefix Mapping Management
  5. Loading pre-existing data
  6. Enabling Indexing

1.   Project creation/deletion

Create new project    

 

 Delete project

 

2.   SKOS Concept Scheme management

3.   Ontology Import

4.   Namespace Prefix Mapping Management

5.   Loading pre-existing data

6.   Enabling indexing

 

Creating a new User

We suppose here that you are both the user and administrator of vocbench (see section 4 on VOCBENCH setup).

To add a new user in VocBench follow these steps:

If you do not receive any email (maybe a misplaced configuration) you need to manually enable the account by modifying the admin DB (see FAQ 1)

 

There is a list of Frequently Asked Questions (FAQs) addressing specific issues related to installation

Appendix A: Behind the Scenes Configuration and Management

Configuring the Administration DB for a new project        

The following steps can be skipped if the new project is created through the VocBench interface.

VocBench stores all the ontologies information in the “Administrator database” under “ontology_info” table. The structure of this table contains various fields. Please ignore the fields: (db_url, db_driver, db_name_ db_password) as the RDF data is no more stored in a database. These fields have been maintained for compatibility with the previous 1.3 version of VB (thus enabling use of the same admin DB with two different versions of VB).

ontology_id: (Auto increment)

ontology_name: <ontology-name> (use {ST.PROJECT.NAME})

ontology_description: <description-of-ontology> (not important)

db_url: null

db_driver: <ST-Server URL>    (e.g. http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer)

db_name: (use {ST.PROJECT.NAME})

db_username: null

db_password: null

ontology_show: 0 for hide and 1 for show  (use 1)

version: <version-number>          (this should be 2.0 for VB2.0 data)

You may check through some explorer tool if the data is already configured in the Administrator Database that you have downloaded. However, these instructions allow you to define a new entry, should you have the system already installed, but in need of setting up a new project/configuration.

Here follows an example for immediately adding an entry to the admin db for a new project.

To connect to different ST server instances, set the value of <db_driver> with different ST server URL.

debian: mysql –u root –p

mysql> Show databases

mysql> Use < administrator database>

mysql> SELECT * FROM ontology_info

 

'1', 'AGROVOC_SKOS_VB_2013-02-05', 'Full Agrovoc', '', 'http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer', 'AGROVOC_SKOS_VB_2013-02-05', '', '', '1', '2.0'

'2', 'AGROVOC-PRODUCTS-AGRONTOLOGY', 'Agrovoc small cut with top concept Products', '', '', '', '', '', '0', '2.0'

 

You will see that ontology with project name 'AGROVOC_SKOS_VB_2013-02-05’ is already configured for VB 2.0. If you want to add new ontology, follow query below.

mysql> INSERT INTO ontology_info

(ontology_name, ontology_description, db_url, db_driver, db_name, db_username, db_password, ontology_show,version) values

(“{ST.PROJECT.NAME}”, "AGROVOC Multilingual Thesaurus", null, “http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer”, “{ST.PROJECT.NAME}”, null,

null, "1","2.0");

Managing a project through Semantic Turkey services   

The following actions (Import ontology, Namespace management) can be skipped as can done via VocBench interface.

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=projects&request=openProject&name={ST.PROJECT.NAME}

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=metadata&request=addFromWebToMirror&baseuri=http%3A%2F%2Faims.fao.org%2Faos%2Fagrontology%23&mirrorFile=agrontology.owl

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=metadata&request=getImports

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=metadata&request=setNSPrefixMapping&prefix=agrontology&namespace=http://aims.fao.org/aos/agrontology%23

http://127.0.0.1:1979/semantic_turkey/resources/stserver/STServer?service=metadata&request=getNSPrefixMappings

Appendix B: OWLIM specific notes

How to use a custom ruleset

OWLIM allows for loading custom rulesets (used for inferencing) instead of the precompiled ones bundled with the OWLIM distribution. In particular, their standard OWL rulesets seem to have some bugs in the axiomatic triples (probably originating from wrong definitions in the OWL RL specifications), thus it may be mandatory to load custom versions of these rulesets. Here follow instructions for loading custom rulesets.

Custom rulesets may be easily loaded by specifying the full path to their file location as a value for the OWLIM configuration parameter: “ruleset” (instead of the code name of the standard ones).

However, while this is pretty straightforward when specifying an OWLIM configuration programmatically, doing this through the Sesame2 workbench is not trivial, as the workbench only allows for pre-defined values (associated to the standard preloaded ruleset).

Here follows the instructions for changing ruleset in Sesame2 workbench

The instructions have been compiled by following the example reported in this post on the OWLIM forum:

http://answers.ontotext.com/questions/996/archive-setting-ruleset-owlim-repository-using-sesame-workbench

PREFIX sys:  <http://www.openrdf.org/config/repository#>    
PREFIX sail: <http://www.openrdf.org/config/repository/sail#>
PREFIX onto: <http://www.ontotext.com/trree/owlim#>
SELECT ?g ?sail ?param ?value
WHERE {
    GRAPH ?g { ?rep sys:repositoryID ?id . }
    GRAPH ?g { ?rep sys:repositoryImpl ?impl . }
    GRAPH ?g { ?impl sys:repositoryType ?type . }
    GRAPH ?g { ?impl sail:sailImpl ?sail . }
    GRAPH ?g { ?sail ?param ?value . }
    FILTER( ?id = "{OWLIM.REPOSITORY_ID}" ) .
    FILTER( ?param = onto:ruleset ) .
}


to check that the parameter is, as expected, the “empty” value that has been selected when creating the repository. Note the use of the OWLIM.REPOSITORY_ID, which you must obviously replace with your OWLIM repository ID.

PREFIX sys:  <http://www.openrdf.org/config/repository#>
PREFIX sail: <http://www.openrdf.org/config/repository/sail#>
PREFIX onto: <http://www.ontotext.com/trree/owlim#>
DELETE { GRAPH ?g {?sail ?param ?old_value } }
INSERT { GRAPH ?g {?sail ?param ?new_value } }
WHERE {
   GRAPH ?g { ?rep sys:repositoryID ?id . }
   GRAPH ?g { ?rep sys:repositoryImpl ?impl . }
   GRAPH ?g { ?impl sys:repositoryType ?type . }
   GRAPH ?g { ?impl sail:sailImpl ?sail . }
   GRAPH ?g { ?sail ?param ?old_value . }
   FILTER( ?id = "{OWLIM.REPOSITORY_ID}" ) .
   FILTER( ?param = onto:ruleset ) .
   BIND( "<directorypathtoyourcustompiefile>/builtin_owl2-rl-fixed.pie" AS ?new_value ) .
}

 

by changing the parameters of the last and the third to last rows in the following way: