Introduction

This guide deals with all the information related to the administration of VOCBENCH as a Web Application System.

What this guide does not contain

This guide assumes that the reader has already installed VocBench and has read the related Installation Guide.

This guide does not include any information related to the management of projects, concept schemes, their configuration etc.. it is a system administration guide.

System Configuration

As explained in the Installation Guide, for convenience of the administrator, VocBench can be configured through the UI at its first start. However, parameters may need to be changed later, or simply errors may need to be fixed.

All the VocBench configuration parameters are setup using the property file “config.properties”. It is located under WEB-INF/classes folder of the uncompressed vocBench.war file.

Here follows a series of properties which need to be setup only once. In general, these properties should have been already prepared by the developer before packaging the VB war file. In any case, we list them here for completeness:

- CFG. VERSION: This value matches the value under the "version" field of the "ontology_info" table in the administration DB.
  Scope: if we specify 2.0 in the property file, VB will show only those ontology in the vocbench which have 2.0 value.
  Default: This property should be 2.0 by default

- CFG. DISPLAYVERSION: Specifies which version you want to display in the VocBench UI.
  Default: This property should be 2.0 by default.
- CFG. MODE: specifies the deployment mode for the VOCBENCH
  VALUES: can have these three values:
  - DEV: for Development
  - PRO: for production
  - SANDBOX: for sandbox
- # DATABASE PROPERTIES
  - CFG.DB.CONNECTIONURL = jdbc:mysql://localhost:3306/<administrator_database_name>?requireSSL=false&useUnicode=true&characterEncoding=UTF-8
  - CFG.DB.USERNAME = your MySQL username for the account devoted to VB
  - CFG.DB.PASSWORD = your MySQL password for the account devoted to VB

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).

- # MAIL PROPERTIES
  - CFG.MAIL.HOST =smtp.gmail.com (smtp adress or IP number)
  - CFG.MAIL.PORT =465 (smtp port)
  - CFG.MAIL.USER =agrovoc@gmail.com (user for login )
  - CFG.MAIL.PASSWORD =xxxxx (user password)
  - CFG.MAIL.FROM =aims@fao.org (from email address)
  - CFG.MAIL.FROM_ALIAS =VocBench Admin
  - CFG.MAIL.ADMIN =agrovoc@gmail.com (admin email address for approval)
  - CFG.MODELCLASS: set value as below to use Semantic Turkey:
    org.fao.aoscs.model.semanticturkey.STManager
  - CFG.MANDATORY.DEFINITION.NAMESPACES = Add namespaces which requires mandatory definition's source and link (For multiple namespaces use semicolon ";" as a separator)
  - CFG.CODETYPE: set CODETYPE to “http://aims.fao.org/aos/agrovoc/AgrovocCode” if you want to set Agrovoc Code. Set it to empty if you are not installing VocBench for managing Agrovoc
  - CFG.CUSTOMDATATYPE: Add custom data types can be added via this parameter. To add multiple data types use semicolon ";" as a separator. For Agrovoc, add http://aims.fao.org/aos/agrovoc/AgrovocCode

Behind the Scenes Configuration

The above information is related to operations which can be performed at the lower levels of the VB technology stack, by directly invoking Semantic Turkey Services, or by writing on the DB. These operations should thus be normally not necessary, though in some cases, understanding what's happening behind the scenes may help..

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.

Then from a web browser paste the following URLs and wait for their relative responses:

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

This action may take a while, as Semantic Turkey is importing the definition of OWL, SKOS and SKOS-XL dictionaries. This is done only the first time the project is being created. You should see an XML reply on the browser (and in the STServer console if proper logging is activated) once the request is satisfied.

The first time that you run Semantic Turkey on a given project, you have to import the ontology: agrontology.owl (you need an internet connection!), containing all the domain properties used in AGROVOC and other FAO concept schemes. This is the service call:

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

This action takes a while, as Semantic Turkey will download the agrontology and, recursively, other ontologies imported by it, such as VOAF and Dublin core. You can check news on the console, if proper logging is activated.

Check if the import is successful by running query below:

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

Add namespace prefix for imported agrontology vocabulary.

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

Check added namespace mapping in the list by running query below.

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