Ontorion™ (5.4.*) Help

Thank you for choosing Ontorion . Below you will find basic information about this product.

  1. Introduction
  2. How to Install Ontorion
    1. Installing Ontorion
    2. Registering Licence
  3. Starting Ontorion Server
    1. With Database Endpoint on a Local Machine
    2. With Database Endpoint on a Remote Machine
  4. Ontorion WebAccess
    1. Starting Ontorion Access - Method 1: Standalone version
    2. Starting Ontorion Access - Method 2: IIS Server deployment (advanced users)
    3. Creating a new database
    4. Common Actions
      1. Database settings
      2. Import
      3. Export
      4. Edit
      5. Ask
      6. Web SPARQL
    5. Ontorion Module Management
    6. User Management
  5. Accessing Ontorion from Fluent Editor
  6. Ontorion WCF Deployment
    1. ClientSelfHost
    2. OntorionClientWCFTest
    3. WebAccess host in IIS
  7. Ontorion WCF Service
  8. Active Rules
    1. Active Rules - Install Processor
  9. Graph Database Management
    1. Virtuoso
      1. Installation
      2. Create and Manage Virtuoso Windows Services
      3. Virtuoso Conductor - the HTTP Browser-based Virtuoso Administration Tool
    2. Graph Management using Ontorion CMD

Introduction

Ontorion™ is Distributed Knowledge Management System with Natural Language interfaces (CNL) and built-in rules engine. It is compatible with OWL2 and SWRL and can be hosted in Cloud or On-Premise environment. Ontorion consists of four components: the Ontorion Server, Ontorion SDK, SDK documentations and examples, and Ontorion WebAccess. The Ontorion Server and the Ontorion SDK have been divided in order to ensure elasticity of use. In this way it is possible to develop a Client Application using only Ontorion SDK and ensure scalability by deploying the Ontorion Server on the cloud.

 

How to Install Ontorion

Including installing Ontorion itself, there are three things required to be installed in order as listed below. Note that if you skip any one of these three, Ontorion will not be executed.

  1. The database backend (currently Apache Cassandra, click here for Windows and here for Linux. The current version of Ontorion is compatible only with 2.0.x version of Cassandra (Tested with Cassandra 2.0.17 here for Windows and here for Linux).
  2. Ontorion
  3. Ontorion License should be obtained and registered.

Instructions for installing Ontorion and its license will be following in the below section.

Installing Ontorion

You can install Ontorion by running Ontorion installer package (.msi). As you run it and move on by clicking 'Next' button, you will encounter below screen.

As listed in Introduction, there are four components of Ontorion you can install. Ontorion Server is mandatory, but the rest is optional. You can set your preference of installation of them by :  left clicking combobox on the left > select an option of your preference.

Another option you can choose is to whether to install Ontorion as Windows Service, which allows Ontorion to start itself automatically when the Windows OS starts up. To speficy this, simple check/uncheck below checkbox.

After the settings, click 'Next' to start installation.

Registering License

The Ontorion license restricts the maximal number of concurrently executed tasks by the Ontorion Server. Every Ontorion Executor deployment can run up to N concurrent tasks. License is also restricted by time - after specified time, license will expire. Please contact us to have more information about licensing of just for a Demo of Ontorion functionalities.

Method 1: Global licensing

NOTE: Registering a new license will permanently erase the license which was already registered (if it exists).

This guide will show you how to register multiple servers connected to the same Database backend. To install license in this way, follow below steps:

  1. Prepare file with license. It has to contain only the license key obtained from Cognitum. Valid extension of that file is .lic.
  2. Localize OntorionCMD.exe. By default it is located in C:\Program Files (x86)\Cognitum\Ontorion Server + SDK - Developer\sdk\bin
  3. Run OntorionCMD.exe with the following parameters
    • -r <path_to_license> - Specify the path to the file with license from point 1.
    • -e <ontorion_server_endpoint> - Address of Ontorion Server to be registered.

Below shows the example of registering license to localhost. If your license is valid, you will see the message telling you to launch Ontorion Executor to complete the registration. If your Executor is already running, restart it.

After (re-)launching Ontorion Executor, if your license is successfully registered, it will print your license information as below after the registration.

If something goes wrong during the registration, an exception message will be displayed in the console.
Registering in this way will save the license key in the database, so all Ontorion Executors that will be executed after registration will share this key.


Method 2: Local licensing

NOTE: This license will be checked only if there is no global license stored in the Database backend.

  1. Prepare file with license. It has to contain only the license key obtained from Cognitum. Valid extension of that file is .lic. Set name of that file to "ontorion_server.lic".
  2. Copy file from point 1 to the catalog with OntorionExecutor.exe. By default it is located in C:\Program Files (x86)\Cognitum\Ontorion Server + SDK - Developer\bin
  3. Repeat step 2 on every OntorionExecutor machine.

Using this method won't save any license information into Cassandra, so every time when Ontorion Executor launches it will look for the license key in its catalog.


Starting Ontorion Server

To start Ontorion Server you need to run OntorionExecutor.exe (in INSTALL_LOCATION\bin\OntorionExecutor.exe). Then Ontorion Executor will start Ontorion Server as well as to connect to the Database which the Server can use. By specifying a parameter option, you can connect to the database that is either on a local machine or on a remote one.   

With Database Endpoint on a Local Machine

Run OntorionExecutor.exe with no parameters. (default case)


With Database Endpoint on a Remote Machine

Run OntorionExecutor.exe with the following parameters

If you would like to have a verbose output, use the switch -v in any of the above cases.

[NOTE]
If OntorionExecuter.exe is not running, check if the requirements are set, including registering Ontorion license.

 

Ontorion Web Access

NOTE: the default administrative username(login) and password is admin/admin. This needs to be changed immediately after installing Ontorion using a strong password.

Ontorion Web Access is a management tool provided for enhanced interaction with Ontorion as an alternative to OntorionCMD. Functionalities such as creating, manipulating and querying databases are provided through an intuitive graphical interface.

Starting Ontorion Access - Method 1: Standalone version

To start Web Access, simply run Start Web Access.exe in INSTALL_LOCATION\Ontorion Web Access\Start Web Access.exe. By default it is set to connect to Ontorion on your localhost to port 8080.
If you prefer to change these options, follow the below steps.

To change port :

  1. Open WebAccess.config in INSTALL_LOCATION\Ontorion Web Access\WebAccess.config .
  2. Change port numbers on <binding protocol="http"> and <binding protocol="https"> under <site name="Ontorion.WebAccess" id="1">, and save the file.
  3.           

To change endpoint address :

  1. Open Web.config in INSTALL_LOCATION\Ontorion Web Access\Web Access Site Content\Web.config .
  2. Change value on <add key="ONTORION_ENDPOINTS"> as below, and save the file.

          

Once you execute Start Web Access.exe with the desired setting, a web browser will open with the log-in page to the Ontorion. 

[NOTE]
If a message box appears: "Could not find IIS Express." after executing Ontorion Web Access.exe, there are two solutions for each case.
  1. Click Install button.
  2. Follow the IIS Express installation steps.
  1. Click Browse button.
  2. Select the folder where is installed IIS Express

 

Starting Ontorion Access - Method 2: IIS Server deployment (advanced users)

If you prefer to deploy Web Access application on your IIS server we provide Web Deployment package for the application,
Follow the below steps:

[NOTE]
  1. If you cannot see 'Deploy' menu, check if all the required (especially Web Deployment Tool and Web Deploy) are installed.
  2. If You use 64-bit operating system,then enable a 32-bit Applications Pool. To change these parameter, follow the below steps:
    • Open IIS Management.
    • On the Connections panel, expand the server node and click Application Pools.
    • Right click on your application pool and select Advanced Settings....
    • Change Enable 32-bit Application to True.
    • Click OK to finish.
  3. If you see an error message as below on the browser.......

    Server Error in '/' Application.

    Configuration Error

    Description: An error occurred during the processing of a configuration file required to service this request. Please review the specific error details below and modify your configuration file appropriately.

    Parser Error Message: It is an error to use a section registered as allowDefinition='MachineToApplication' beyond application level. This error can be caused by a virtual directory not being configured as an application in IIS.

    Source Error

    Line 26:  <customErrors mode="Off" />
    Line 27:  <compilation targetFramework="4.0" />
    Line 28:  <authentication mode="Forms">
    Line 29:  <forms loginUrl="~/Account/Login" protection="All" timeout="25" />
    Line 30:  </authentication>

    .... follow these steps and refresh the browser :  Open IIS Manager. -> Expand  'Sites' on the left. -> Find 'WebAccess' folder under your application and right click. -> Select 'Convert to Application'.

  4. If there are any issues caused by that ssl is not enabled, follow instructions in this guide , until you reach ‘Configure WCF Service for HTTP Transport Security’ (don’t do that part).
  5. If you see this message: Could not initialize the Ontorion Client. Please check the inner exception for more details.:
    • Check the config page Web.config in INSTALL_APPLICATION_LOCATION\WebAccess\Web.config.

    • To check where is INSTALL_APPLICATION_LOCATION, follow the below steps:
      • Open IIS Management.
      • Right click on the site where is deployed WebAccess, then click Explore.
    • Change value on <add key="ONTORION_ENDPOINTS">,and save the file.

 

Creating a new database

After logging-in to WebAccess, first you will see a list of databases in the server. To create a new one, click in the "New Database.." button:



Then you will be redirected to a new page where you need to provide a name and a namespace for the new database.



Once you've created a database you will have access to its contextual menu "Common Actions" as shown in the screen below. 



Common Actions

The "Common Actions" menu, lists the operations that are allowed over the ontologies. Here is a brief description of the main functionality:

 



 

Ontorion Module Management

As previously introduced, Ontorion Server WebAccess allows to save, download, refresh and clear the module concerning the knowledge of interest. In this help entry we are going to demonstrate some of the features provided by the interface.

In this example, an ontology shown below is saved in a database. Then a change will be made in this ontology, for example, deleting a sentence 'Every branch is a plant-part.'.

Once you have performed this operation, click Save, you will be acknowledged with the modifications made to the ontology in a pop-up window:



Once you click Save your changes will be pushed to Ontorion.

User Management

NOTE: The default administrative username(login) and password is admin/admin. This needs to be changed immediately after installing Ontorion using a strong password.

In WebAccess you can manage users that have access to databases and users' management.

You can add a new user by clicking Create user in the Manage Server part.

Then you will see the following form where you can add a new user.

After you created the user, you can come back to Manage Server view, select the user for whom you want to change properties and then click Manage user.

Then a form like below will appear in which you can add access to the user to already existing databases or change the role of the user for the whole Ontorion.

Currently there are three possible roles :

And three database accesses :

Accesing Ontorion from Fluent Editor

Ontorion can be also accessed from Fluent Editor. The best place to learn about Fluent Editor and Ontorion interaction is the Fluent Editor online help at Fluent Editor - Ontorion Mode.

Ontorion WCF Deployment

ClientSelfHost

To host WCF solution in console application:
  1. Copy ONTORION_LOCATION\sdk\bin\App.config file to the folder with ClientSelfHost dlls.
For more information check out Ontorion SDK documentation.

OntorionClientWCFTest

To test WCF services use ONTORION_LOCATION\sdk\samples\OntorionServiceDemoApp\ application.
  1. Start Ontorion Server.
  2. Start WCF service (hosted on IIS, running by ClientSelfHost or Ontorion.Client).
  3. In OntorionClientWCFTest right click on Service References and select Add Service Reference. In Address write WCF service address, click Go and Ok.
  4. Run application.
For more information check out Ontorion SDK documentation - Case 2. Configure Ontorion WCF Endpoint using Visual Studio.

WebAccess host in IIS

In order to run WCF services by WebAccess, application must host them in IIS.
  1. Host application in IIS.
  2. Configure IIS.
  3. Run your application: In IIS right click on your application and select: Manage application -> Browser.

Ontorion WCF Service

NOTE: If you have not configured a WCF Service, go to section Ontorion WCF Deployment.

There are basically two ways in which a client can access Ontorion: one is by directly connecting to the Ontorion Server or through a WCF service. Web Access hosts an Ontorion WCF service and by clicking on the "Ontorion WCF Service endpoint" link in red square below you we see information regarding this service:



Then you will be redirected to a new page that explains the steps to follow in order to use the WCF service. The link in red square is the connection string to get access to the service at client side:


Active Rules

Active rules is a mechanism Ontorion provides for executing custom imperative code in C# upon meeting certain criteria described as SWRL rules. Likewise we provide some mechanism to deal with the nature of distributed enviroments through a set of core built-ins. To illustrate the use of Active Rules, we will walk you through an example. We will use Fluent Editor for the task of editing, but all operations can be also performed through WebAccess itself. We start by creating the ontology (that can be downloaded here), whose content is as in the screenshot below:



This example describes a scenario about some head-hunting rules and some users. Once a task arrives, an email is sent to the user whose skills match the requirements from the task and acknowledge the system. This ontology can be exported to Ontorion using the method described at the beginning of this section. To start commiting task to the system we need to update the knowledge in the ontology. To do so, you need to connect to the Ontorion server and commit the changes:




The task we will commit to the Ontorion database requires C++ programming skills. We describe this with the following sentences:

 

Now, when we commit the changes we can get into the Agent logs (By clicking in the Agent log click in the "Common Actions" menu of the ontology):

 

The result will look as in the screenshot below:

 

Active Rules - Install Processor

A function installProcessor is for installing a library with methods which can be used by agents.
How to utilize it is demonstrated as follows : 
  1. Prepare a project for creating a C# class library (.dll).
    Example content of the project HelloAgentWorld:
         using System;
        using System.Collections.Generic;
        using System.Linq;
        using System.Text;
        using System.Threading.Tasks;
    
        namespace HelloAgentWorld
        {
            public class Main
            {
                dynamic ctx;
            
                public Main(dynamic ctx) 
                {
                    this.ctx = ctx; 
                }
    
                public void Hello()
                {
                    // this is a message you will see in the Ontorion console
                    ctx.WriteMessage("Hello from the agent world!");
                    // this is a message that will be written in Ontorion
                    ctx.WriteDebugMessage("Hello from the agent world...!");
                }
            }
        }                    

  2. Compile the created project in Release mode:
    • Right-click on project name, then select Properties.
    • In Debug tab change parameter Configuration to Release.

  3. Open Onotrion CMD.
  4. Type installProcessor <name> <path>:
    • <name> - name of assembly namespace.
    • <path> - path to catalog with library, and its dependencies.

    E.g:

    NOTE: In the folder there should be the library you want to install together with all needed dependencies. Furthermore the namespace given to the installProcessor command should be the same as the one in your library.

  5. Create a new CNL file, which uses the library methods.(Hello()).
    Example:


  6. Export this CNL file to Ontorion, you can do this using FluentEditor or use importFile method via OntorionCMD.

    After exporting, you will see a message from agents in Ontorion Executor:

To uninstall the library with methods for agents, use a command uninstallProcessor <name>. This will remove all versions of given library:
E.g:

Graph Database Management

In Ontorion you can use two different graph databases:

Virtuoso

Installation Virtuoso server

To install Virtuoso server, follow below steps:
  1. Download Virtuoso server from here. Make sure to install the stable version that is compatible with your OS.
  2. For the VOS Binary Distribution for Windows, the Microsoft Visial C++ Redistributable Package should be installed. This can be downloaded from links on here.
  3. Unzip Virtuoso server into the C:/Program Files/ (or C:/Program Files (x86)/ for a 32-bit Virtuoso on 64-bit Windows) directory.
  4. Create a new system system enviroment variable called VIRTUOSO_HOME:
  5. If php.ini file is misisng,please download a copy of this file, and manually place it in the %VIRTUOSO_HOME%/database directory.
  6. Add the string below to the end of existing 'Path' variable under 'System variables':
    ;%VIRTUOSO_HOME%/bin;%VIRTUOSO_HOME%/lib
  7. Reboot your Windows.

Create and Manage Virtuoso Windows Services

  1. Start a CMD session as a Windows Administrator.
  2. Create a new Windows Service with the following command:
    cd %VIRTUOSO_HOME%/database
    virtuoso-t +service create +instance "New Instance Name" +configfile virtuoso.ini
  3. Start the created Service by command line:
    virtuoso-t +instance "Instance Name" +service start 
    or from Windows Service Manager:
    Start-> Control Panel -> Administrative Tools -> Services or Component Services. It will be listed as Virtuoso_[Instance Name].

Virtuoso Conductor - the HTTP Browser-based Virtuoso Administration Tool

The Virtuoso Conductor is a HTTP-based administration tool, included by default in all Virtuoso instances. It can be accessed through the URL:

The default administrator username(login) and password are both dba. We recommend changing the password immediately to secure your database.
By default, the Virtuoso server will listen for HTTP connections at TCP port 8890, and for SQL data access (via iSQL, ODBC, JDBC, OLE DB, ADO.NET, etc.) at TCP port 1111. These ports may be changed by editing the virtuoso.ini(location:%VIRTUOSO_HOME%/database/) file.

Graph Management using Ontorion CMD

Ontorion CMD Option: For more information on how to use Ontorion CMD, check out Ontorion SDK documentation