GraphDB-Workbench

Version 1 by barry.bishop
on Jul 01, 2013 15:08.

compared with
Current by Desislava Hristova
on Jun 02, 2015 11:34.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (118)

View Page History
\\ *GraphDB-Workbench*
\\
\\
\\
\\ !owlim_logo.png|height=88,width=240!
Semantic Repository for RDF(S) and OWL
\\
\\
\\

*Version 6.0*
*OWLIM-Workbench*
*Version 5.4*
\\
\\
\\
\\
\\
*{_}User Guide{_}*
\\
\\
\\
\\
\\
\\
\\
\\
\\
*Table of Contents*
\\

{toc}

h1. Overview

The OWLIM Workbench is a stand-alone OWLIM server with a built-in web-based administration tool. The user interface is similar to the Sesame Workbench webapp, but with more functionality, most importantly in the area of security and user access roles. Unlike Sesame, where separate server and workbench webapps are deployed, the OWLIM Workbench is a fully functional OWLIM server with a SPARQL endpoint.
The GraphDB Workbench is a our recommended web-based administration tool. The user interface is similar to the Sesame Workbench webapp, but with more functionality. Here are some of the additional features:
* Query monitoring with the possibility to kill a long running query
* Better SPARQL editor based on [http://laurensrietveld.nl/yasgui/]
* Connectors administration(only present in the enterprise edition)

The OWLIM workbench can be used to create OWLIM repositories, load and export data, execute SPARQL queries and updates, manage user accounts and control user access roles. The user interface is built using the Forest framework which provides syntax highlighting for SPARQL and other benefits.
Of course GraphDB Workbench can be used to create GraphDB repositories, load and export data, execute SPARQL queries and updates. The user interface is built using the Forest framework ready to use, bug free components.

The OWLIM Workbench is distributed in several forms, firstly as an executable 'jar' file so that it can be run without any dependency on Tomcat or any other servlet container/application server. It is also packaged as a 'war' file so that it can be deployed alongside other webapps in a servlet container.
The GraphDB Workbench can be found in the distribution as a separate war file. The war file can be deployed with the startup script in the distribution or deployed in a dedicated application server.


h1. Requirements

Java: JRE 1.67 or higher (JDK 1.67 or higher if using custom rule sets)
Tomcat: Version 7 or higher if deployed as a 'war' file

h1. Contents of the distribution
h1. Installation, start-up and shutdown

The OWLIM-Workbench is packaged as a separate zip file from the 'standard' OWLIM-SE plus Sesame zip file. The existing means of deploying OWLIM-SE as described in the [installation section for that distribution|OWLIM-SE Installation] remains unchanged.
To run the GraphDB Workbench as a standalone server, unzip the distribution zip file and execute the startup.sh/.bat script.
For Mac the command line is:
{code:language=bash}
sh startup.sh
{code}

In the OWLIM-Workbench zip file are:
* README.txt - helpful hints on how to run the OWLIM-Workbench
* startup.sh (.bat) - start up script
* shutdown.sh (.bat) - shutdown script
* owlim-workbench.jar - standalone 'runnable' jar file containing the workbench
You can also start the workbench by running the line:

h1. Installation, start-up and shutdown
{code:language=bash}
java -jar graphdb-tomcat.jar
{code}

To run the OWLIM Workbench as a standalone server, unzip the distribution zip file and execute the startup.sh/.bat script. This method of deployment uses the internal [Jetty|http://jetty.codehaus.org/jetty/] server. The OWLIM-Workbench is accessed and administered using a Web browser. If located on the same machine, use a URL such as the following (assuming the default port number):
These methods of deployment use an embedded tomcat server which will deploy the war files in sesame_graphdb directory. The GraphDB Workbench is accessed and administered using a web browser. If located on the same machine, use a URL such as the following (assuming the default port number):

{noformat}
{noformat}

When deployed as a 'war' file, the procedure is the same as deploying any other Web application, i.e. the {{owlim-workbench-x.y.z.war}} {{graphdb-workbench-x.y.z.war}} file must be copied to the servlet container's {{webapps}} directory. In order to access the OWLIM-Workbench GraphDB Workbench use a browser with a URL similar to the following:

{noformat}
http://localhost:8080/owlim-workbench-webapp-x.y http://localhost:8080/graphdb-workbench-webapp-x.y
{noformat}

To gracefully shutdown the OWLIM-Workbench run the shutdown.bat/.sh script if started as a standalone application. If started in a servlet container use the appropriate tools, e.g. with Tomcat then the Tomcat server can be stopped or an individual Web application unloaded using the HTML manager tool.
Shutting down the workbench if you are using the embedded tomcat method can be done with Ctrl-c in the console. If started in a servlet container use the appropriate tools, e.g. with Tomcat then the Tomcat server can be stopped or an individual Web application unloaded using the HTML manager tool.

h1. Login and status if security is enabled

After starting, If you start the workbench with *\-Dsecurity.enabled=true*, the first page presented will be the login page. The default administrator account information is:

{info}
password: *root*
{info}
You are recommended to change the root password as soon as you login for the first time. Go to Admin->Users and choose Edit next to your username. Then change your password. See section [User administration|#GraphDB-Workbench-Useradministration] in the current document.

and you are recommended to change the root password as soon as possible, see below. After logging in, the summary page is displayed that shows: version number, license details, currently selected repository (if any) and user name. If no repository is currently selected then the message 'Please select a repository' is displayed. Click this to get to the repository management page.

h1. Managing repositories
h1. Index page

The repository management page is accessed using the menu bar ADMIN->Repositories. This will display a list of available repositories and their locations as well as the permissions that the logged on user has for each repository.
After logging in, the summary page is displayed that shows: version number, license details, currently selected repository (if any) and user name. If no repository is currently selected then the message 'Please select a repository' is displayed. Click this to get to the repository management page.

An OWLIM-Workbench instance always has at least two repositories: the {{SYSTEM}} repository that holds the Sesame repository configurations and the {{security}} repository that holds user accounts and access rights. A repository can be selected, i.e. made 'current'. by clicking the 'connect' button next to a repository. Subsequent import, export and query evaluation functions will operate against this repository.

h1. Invalid GraphDB License

!add-repo.png|align=center,width=781,height=125!
In order to run the GraphDB Workbench application, you need a valid GraphDB license. By default there is an evaluation license included in the distribution but in case you found out that your license had expired, you have to write to Ontotext for a new one. Once obtained, the recommended way of specifying it is with a java system parameter. Just add the following parameter
{code}
-Dowlim-license=<path-to-graphdb-license>
{code}
to the java process that is responsible for the workbench deployment(tomcat's setenv.sh file or our startup.sh script). Look at [How to setup graphdb license|https://confluence.ontotext.com/display/GraphDB6/GraphDB+FAQ#GraphDBFAQ-HowdoIsetuplicensefilesforGraphDBSEandGraphDBEnterprise] for other methods.

h1. Managing repositories

To create a new repository, click 'add repository'. This will display the configuration page for the new repository where a new, unique ID must be entered. The rest of the parameters are described in the [OWLIM-SE configuration section|OWLIM-SE Configuration] of the user guide.
The repository management page is accessed using the menu bar Admin->Repositories. This will display a list of available repositories and their locations as well as the permissions that the logged on user has for each repository.

It is also possible to use the current interface for creating and accessing a repository on another OWLIM-Workbench instance (on another machine) or at a different location on the same machine. To do this, a new location must be entered for identifying the other OWLIM-Workbench instance (or directory on the current machine):
h2. Adding a location

If we were unable to detect the sesame server(i.e. it is not deployed in the same application server) you will have to connect to the sesame server manually. To do this:



# From admin-repositories click on "Add Location"
# Enter the URL, user and password for a Sesame location
# After you change the current location you can create and browse repositories in the same way as when using a local location
# Enter the URL to a sesame location
# Optionally specify credentials for the sesame location(user and password)
# Optionally add JMX Connection parameters(url and credentials) - this allows you to monitor the resources on the external location and do query monitoring

{info}

!add-location.png|align=center,width=780,,height=367!
For now there is no possibility to manage the graphdb cluster setup through the workbench even if you add jmx connection parameters


{info}



{note}
The JMX connection url is of the form
{code}
service:jmx:rmi:///jndi/rmi://<ip-address>:<port>/jmxrmi
{code}
and the remote process should be started to allow remote JMX connections. Something like the following should work
{code}
-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=<port> -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=<ip-address>
{code}
{note}


It is possible to use the current interface for creating and accessing a repository on another GraphDB Workbench instance (on another machine) or at a different location on the same machine.

!locations.png|border=1,width=781!

h2. Adding a repository

To create a new repository, click 'add repository'. This will display the configuration page for the new repository where a new, unique ID must be entered. The rest of the parameters are described in the [OWLIM-SE configuration section|OWLIMv54:OWLIM-SE Configuration#Sample Configuration] of the OWLIM v54 documentation.


!create-repository.png|border=1,width=772,,height=426!

h2. Selecting a repository

You can make a repository the default connected repository in the repositories view by clicking the 'connect' button next to a repository


!repositories.png|border=1,width=781!

another way(recommended) is to use the dropdown in the top right corner. This will allow you easily change repository while running queries, importing, exporting data in other views.

 !repository-select-dropdown.png|border=1,width=776,,height=429!



h1. Loading data into a repository

After creating and connecting to a repository the following steps can be used to load data. Note that loading data is a two stage process: the data files are first loaded to the server and from there loaded in to OWLIM:
We provide two ways of importing files in the currently selected repository. Both can be accessed from *Data->Import* menu item in the workbench

# Pick a repository to work with from "Repositories in selected location" list and click "Connect"
# Some text on the top of the screen will say "Current repository is REPOSITORY_NAME, located in LOCATION_PATH"
# To load data use the menu bar DATA->Import and choose a file (.rdf, .n3, .nt, .trig, and .trix) - as each file is selected it is added to the list in this page
h3. Basic data load

{warning}
The limitation of this method is that it supports files that are smaller than 50.0 MB.
{warning}

Loading data from the *Upload files* tab is a two stage process: the data files are first uploaded to the workbench and from there loaded in to GraphDB:

# Click on *Select files to upload* and browse a file to upload
# After the files have been selected, click "Start Upload" for individual files or "Upload All" to load all of them
# When the upload is finished a "Load Data" button will appear for each successfully uploaded file. Press this to load files individually or use the "Load All" button for multiple files. After loading a message is displayed with a link to the query page.
# When the upload is finished a "Load Data" button will appear for each successfully uploaded file. Press this to load files individually or use the "Load All" button for multiple files. You will be asked to select a method to load your data:
## SPARQL - import the data in the default context without a base url
## Advanced - provides more options for the import process


!Import-upload.png|align=center,border=1,width=779,,height=201!

!upload.png|border=1,width=781!


!Import-load-data.png|align=center,border=1,width=780,,height=197!
!load.png|border=1,width=781!

h3. Impex method

The impex method allows you to load files with arbitrary size. It has the limitation that the files must be put(symbolic links are supported) in a specific directory(by default {{*$\{user.home\}/owlim-impex/*}}. Look at the *impex.dir* system parameter if you want to tweak the directory location. The directory will be scanned recursively and all files with semantic mime type will be visible in the impex tab.

h1. Executing queries

Access the SPARQL pages using the menu bar *SPARQL->Query*. Above the query editing text area а query templates can be accessed and selected. Clicking on one it will populate the text-area with a SPARQL query that can be edited in place. The query can be freely edited (with syntax highlighting) and namespaces can be added very easily by accessing the list of known namespaces next to the query templates.

A check-box is provided that allows the execution of the query over all RDF statements or just explicit statements. Another check-box controls whether equivalent URIs are expanded. This relates to the use of {{owl:sameAs}} and causes the automatic addition of the pseudo-graph {{FROM <}}{{[http://www.ontotext.com/disable-sameAs]}}{{>}} to the query. This is described in the [special query behaviour section of the OWLIM v54 user guide|OWLIMv54:OWLIM-SE Query Behaviour].

The query is executed by clicking the 'Submit' button, where the results are presented in the results page.
The results page will show the response for your query:

!sparql-results.png|border=1,width=781!

!results_page.png|align=center,border=1,width=779,height=565!
From the results page it is possible to download results as JSON, XML, CSV, or TSV. It is also possible to provide an alternative view of query results by 'viewing as exhibit'. This allows the results to be sorted on each column and provides a summary of values found in each column.


From the results page it is possible to download results as JSON or XML. It is also possible to provide an alternative view of query results by 'viewing as exhibit'. This allows the results to be sorted on each column and provides a summary of values found in each column.

h1. Executing updates

{noformat}

!update.png|border=1,width=781!

!Delete-data.png|border=1!
You can see the result of an update above the text-area.

h1. Exporting data

You can see the result of this update below the text-area.
Data can be exported in several ways and formats.

h1. Export data
h3. Exporting repository or graphs

Data can be exported in several ways and formats.
From the menu bar select *Data->Export* and the data export page will provide options for exporting the whole repository (in several different formats) or specific named graphs (in the same variety of formats). Just click the appropriate format and the download will begin:

h3. Export repository or graphs
\!
!export.png|border=1,width=781!

From the menu bar select DATA->Export and the data export page will provide options for exporting the whole repository (in several different formats) or specific named graphs (in the same variety of formats). Just click the appropriate format and the download will begin:
h3. Exporting query results

!Export.png|align=center,border=1!
SPARQL query results can be exported to JSON, XML, CSV, or TSV from the query results page:

h3. Export query results
!sparql-results-save.png|border=1,width=781!

SPRQL query results can be exported to JSON or XML from the query results page:
h3. Exporting resources

!Export-query.png|align=center,border=1,width=776,height=207!
From the resource description page, it is possible to export the RDF triples that make up the resource description to JSON, JSON-LD, RDF-XML, N3/Turtle and N-Triples:

h3. Export resources
!resource.png|border=1,width=781!

From the resource description page, it is possible to export the RDF triples that make up the resource description to JSON, RDF, N3/Turtle and N-Triples:
h1. Adding new resource

!Export-resource.png|align=center,border=1,width=780,height=361!
To add new resource to the repository go to DATA->Add new resource. It opens a window, where you write the URI of this new resource. Then you can add, change or delete the properties of this new resource.

!resource-new.png|border=1,width=781!


!resource-add-property.png|border=1,width=781!


!resource-edit.png|border=1,width=781!


!resource-trig.png|border=1,width=781!

When you are ready you save the new resource to the repository.

h1. Changing a resource

You can also change the properties of an already stored resource. Click on the Edit button next to the resource namespace. Then you can add, change or delete the properties of this resource.

!Screen Shot 2014-05-23 at 13.40.39.png|border=1,width=781!

(!) Note that you can not change or delete the inferred statements. For more information, see the [FAQ section|OWLIMv54:OWLIM FAQ#Why can't I delete some statements?] of the GraphDB v54 documentation.

!Screen Shot 2014-05-23 at 13.43.09.png|border=1,width=781!


h1. User administration

User management is accessed from the menu bar ADMIN->Users. This page displays a list of users and the number of repositories they have access to. It is also possible to disable security for the entire OWLIM-Workbench instance by clicking the 'disable/enable' button, i.e. all users (even anonymous ones) have read/write access to all repositories.
{info}

!adminitration-users.png|border=1,width=778,height=238!
The user administration is disabled by default. If you want to enable it, run the workbench with *\-Dsecurity.enabled=true*


Clicking 'remove' next to a user name will remove that user and its permissions from the system. Clicking 'create new user' or 'edit' next to an existing user allows a user's properties to be edited. This includes setting their role (administrator or user) and the read/write permission to each repository. The password can also be changed here.
{info}

User Roles are:

* user - user that can read and write according to his permissions for each repository
* admin - user with full access including creating, editing, deleting users.
User management is accessed from the menu bar ADMIN->Users. This page displays a list of users and the number of repositories they have access to. It is also possible to disable security for the entire GraphDB Workbench instance by clicking the 'disable/enable' button, i.e. all users (even anonymous ones) have read/write access to all repositories.

!new-users.png|border=1!
!User_administration.png|border=1,width=781!

Clicking 'create new user' or 'edit' allows a user's properties to be edited.

!users.png|border=1,width=781!

This includes setting their role and the read/write permission to each repository. The password can also be changed here. ANd there is also an option to delete a user.

User Roles are:

* User - user that can read and write according to his permissions for each repository.
* Admin - user with full access including creating, editing, deleting users.
* Information Extraction Expert - user with access only to add new resource page.
* Search Configuration Expert - user user with full access, except for Repositories and Users management.

!Create_user.png|border=1,width=781!

h1. Configuration

In addition to the standard OWLIM GraphDB command line parameters, the OWLIM GraphDB Workbench can be controlled with additional parameters as follows. These should be of this form {{\-Dparam=value}}

|| Parameter || Default || Description ||
| resource.language | 'en' (English) | set the default language with which to filter results displayed in resource exploration |
| resource.limit | 100 | set the limit for the number of statements displayed in the resource view page |
| security.enabled | true | enable/disable security\* |
| sparql.limit | 100 | set the limit for the number of rows of SPARQL query results displayed in the query results page |
| sparql.equivalence | false | enable result expansion over equivalent URIs for SPARQL queries when using the query page |

* will be available in the next release of OWB