Ontorion SDK (5.4.*) Help

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

  1. Introduction
  2. Ontorion CMD
    1. Load script using OntorionCMD
    2. Connecting to Ontorion Server
    3. Connecting to Ontorion Server via WCF Endpoint
    4. OntorionCMD autocomplete functionality
    5. Database configuration
  3. Ontorion API
    1. Using API by Rerencing DLL Library
    2. Using API by Connecting to Ontorion WCF Endpoint
    3. Documentations for Ontorion API
  4. Ontorion WCF Service
  5. CNLClientUtils - Autocomplete Functionality

Introduction

Ontorion Standard Development Kit (SDK) is a development environment for building client applications using Ontorion as a server.  It comprises three components : OntorionCMD, Ontorion API, and a Self-host Application.

OntorionCMD

The OntorionCMD is a command line interface to Ontorion. By using this tool, you can manage the Ontorion server locally or remotely and you will have access to most of the functionalities of the OntorionSDK. To run OntorionCMD, you just need to search in Start -> OntorionCMD or you can find it in you Ontorion installation folder and then execute sdk\bin\OntorionCMD.exe. By default the OntorionCMD will search for Ontorion locally thus if you want to connect to a remote Ontorion you will need to specify some command line parameters:

To see all the possible options for starting OntorionCMD, just run OntorionCMD.exe -h as shown below. After you have started the console, you can type "help" and all the commands currently available will be displayed. Commands will be auto-completed while writing if pressing the "tab" button.


Load script using OntorionCMD

To start script run OntorionCMD.exe with parameter: -l "location where is the script"

Also you can use parameters:

To loads script from a file in OntorionCMD use command LoadScript:

Contents of a file Script.txt:

                #listDatabases
                listDatabases
                #createDatabase test "http://cognitum.eu/namespace/test#"
                createDatabase test "http://cognitum.eu/namespace/test#"
                #listDatabases
                listDatabases
            
Lines starting with # will be considered comments.

Connecting to Ontorion Server

Below shows how to connect to the Ontorion Server directly by using OntorionCMD.

Connecting to Ontorion Server via WCF Endpoint

You can also connect to the Ontorion Server through the Ontorion WCF endpoint.

While connected to the WCF endpoint, users are allowed to execute most of the functionalities offered by the Ontorion SDK.



[NOTE]
If OntorionCMD is not executing normally due to the license-related issues, you need to install Ontorion license through the following steps described here.

Once you are connected to the Server, you can see all the possible commands provided in OntorionCMD by typing the command help.

To see all the possible commands that contain some word, type these word, for example type database.

OntorionCMD autocomplete functionality

Autocomplete functionality is a convenient feature as the process of writing command. To use this functionality run and login to OntorionCMD.exe, then write something, for example get and click key TAB. To go to next command, which starts with the word "get" use again key TAB.

Database configuration

Ontorion API

The Ontorion API is a complete set of client libraries to communicate with the Ontorion Server. Using this API allows you to exploit all the possibilities offered by the Ontorion Server.
There are two ways to use the API - 1. Referencing DLL library or 2. connecting to Ontorion WCF Endpoint.

Using API by Rerencing DLL Library

To use the Ontorion API, simply start with referencing the Ontorion.Client.dll library as below.

using Ontorion.Client;

Then, you create an instance of the library. The way how to do this differs depending on whether you prefer to connect to the Ontorion Server directly or through the WCF Endpoint.

To connect to the Ontorion Server directly, create your OntorionClient instance as below. The string[] endpoints parameter will tell the library what are the endpoints on which the Database backend is listening (default is localhost).

Ontorion.Client.IOntorionClient serv = new Ontorion.Client.OntorionClient(endpoints);

After creating an OntorionClient instance connect to Ontorion using user account:

if (!serv.Connect(username, password))
        throw new Exception("Cannot connect to Ontorion");

All methods in the API are written to be used in an asyncronous way. Thus almost all methods are splitted between methodName() and methodNameResult() functions. The first function adds a task to the Ontorion Server queue while the second one returns null until the result is obtained. For example, it is possible to insert a series of CNL sentences in the database by writing:

            // ADD INPUT CNL STRINGS TO THE KEYSPACE
            string[] toInput = new string[] { "John is a man.","John has-name equal-to 'Johnatan'.", "John has-age equal-to 15.",
                    "John likes Paula.","Paula is a woman.", "Eli is a human-being.","Every man is a human-being.","Every woman is a human-being."
                    ,"Every human-being must have-name (some string value).","Every man must have-field (some string value)."
                    ,"Every human-being is a thing.","Every working-human-being is a human-being."
                    ,"Every thin-man is a man.","Every high-man is a man.","Every thin-woman is a woman.","Every high-woman is a woman.",
                    "Part: sim-card.","Comment:'SMS-TO-OTHER-OPERATOR'."};
            string[] toDel = new string[] { };
            Guid jobID = serv.SaveChanges(KEYSPACE, toInput, toDel);
            while (!serv.IsProcessCompleted(jobID))
            {
                TimeSpan elapsed = DateTime.Now - now;
                Console.WriteLine("Waiting for process " + jobID + " to complete for " + elapsed.Seconds + " seconds");
                System.Threading.Thread.Sleep(1000);
                if (elapsed.Seconds > 10)
                    Console.WriteLine("################# Is OntorionExecutor running?");
            }
            Console.WriteLine("Saved information in " + KEYSPACE + " database");
            

This demonstration is based on a sample project in sdk\samples\OntorionDemoApp1. For better understandings it's recommanded to take a look at the project by opening OntorionDemoApp1.csproj.

Using API by Connecting to Ontorion WCF Endpoint

Another way to use Ontorion API is to connect to a WCF endpoint through which you can reference API.  There are two ways to connect to this WCF endpoint. :


Case 1. Configure Ontorion WCF Endpoint by code

In order to connect to a WCF Service by code, you just need to create an instance of WCFHelper and connect to the WCF service through it. 

                Ontorion.Client.WCF.WCFHelper wcfHelp = new Ontorion.Client.WCF.WCFHelper(); 
                Ontorion.Client.IOntorionClient serv = wcfHelp.CreateWCFService(OntorionEndpoint, username, password);
[NOTE]
It is generally useful to keep a reference to the ChannelFactory channel factory created during this procedure. A reference to this channel factory is in wcfHelp.OntorionChannelFactory.


Case 2. Configure Ontorion WCF Endpoint using Visual Studio

To understand how to connect to an Ontorion WCF endpoint using the Ontorion API, you can open the OntorionServiceDemoApp provided with the Ontorion SDK installation (in sdk\samples\OntorionServiceDemoApp\) and open the OntorionServiceDemoApp.csproj. This project is a console application (very similar to the OntorionDemoApp1 example) where most of the functionalities offered by Ontorion SDK are used.
By default this example has no service defined. So in order to make it work, right click in References and click 'Add Service Reference'.

add service reference.

In the window that will show, add in Address text box the https address you have been given (it generally ends with .svc) and click 'Go'.

Service reference window

Then change the namespace to OntorionService and click Ok. NB: If your Ontorion WCF service has not been certified, you will see a certificate warning when clicking Go, in this case click Yes.

certificate warning

Now open the Program.cs file and add your username and password instead of "yourUserName" and "yourPassword". NB: If your server has a certificate, you need to change the System.Net.ServicePointManager.ServerCertificateValidationCallback to a real server certificate (by default we are accepting all certificate).

Program.cs sample

At this point all is set up and you only need to Start the application to see the Ontorion SDK in action.

A complete example is present in the sdk/samples folder.

Documentations for Ontorion API

Full documentations for Ontorion API users are located in sdk\docs\Ontorion Client Documentation.chm. From the left tree, click Ontorion.Client -> IOntorionClient interface. You will see the list of the entire library methods with the description and usage for each.

The terminology naming the client methods looks like this:

The IOntorionClient interface include the following methods:

Categories of methods Method name Description
User management ChangePassword Change old password to new password for specific user.
(Inherited from IUserManager.)
Connect Connect user to Ontorion. Validate user.
(Inherited from IUserManager.)
CreateUser Creates user. Size of letter in username is not forgotten. Username is make lower.
(Inherited fromIUserManager.)
DeleteAccessToDatabase Delete access for every users to this database.
(Inherited from IUserManager.)
DeleteUser Deletes user from system.
(Inherited from IUserManager.)
Disconnect() Disconnect the current logged user.
(Inherited from IUserManager.)
Disconnect(String) Disconnect specific user. Throw exception if user that you want to disconnect is not currently logged in.
(Inherited from IUserManager.)
Dispose Dispose all resources.
(Inherited from IUserManager.)
GetLoggedInUsername Return logged in user name.
GetAdmins Get all users in master role.
(Inherited from IUserManager.)
GetUserAccess Gets access level to specific database for specific user.
(Inherited from IUserManager.)
GetUserRole Gets specific user role in system.
(Inherited from IUserManager.)
GetUsers Gets users from system.
(Inherited from IUserManager.)
GetUsersAccessForDbName Gets list of Users and access level for them to specific database.
(Inherited from IUserManager.)
IsUserExist Checks if specific user exist.
(Inherited from IUserManager.)
RemoveUserAccess Remove user access to database.
(Inherited from IUserManager.)
ResetPassword Resets user password and set new one. Only for admin.
(Inherited from IUserManager.)
SetUserAccess Sets access level for specific user to specific database.
(Inherited from IUserManager.)
SetUserRole Sets list access levels to databases for users.
(Inherited from IUserManager.)
SetUsersAccess Sets list access levels to databases for users.
(Inherited from IUserManager.)
GetDbNamesAccessForUser Gets list of dbNames and access level to them for specific user.
(Inherited from IUserManager.)
IsLoggedIn() Return if user is logged in.
IsLoggedIn(String) Return if user is logged.
     
Database management DeleteAccessToDatabase Delete access for every users to this database
(Inherited from IUserManager.)
ChangeDatabaseConfiguration Function used to change the configurations of the database.
CreateDatabase Create a new database with namespace (for RDF) default_namespace. It creates the new database only if it didn't existed, otherwise nothing is changed. It throws an exception when the Database exists.
CreateDatabaseIfNotExists Does the same thing as CreateDatabase(String, String, GraphBackend, Int32) but does not throw an exception when the database already exists.
DropDatabase Removes the database from the database only if it exists.
GetDatabaseConfiguration Get the current configuration for database dbName.
GetDatabases List the databases found in the database.
GetDefaultNamespace Returns the default namespace of the database by finding it in the database configuration table.
GetDbNamesAccessForUser Gets list of dbNames and access level to them for specific user.
(Inherited from IUserManager.)
GetGraphDatabaseConfiguration Get the global configuration config for the graph database graphDb.
GetKnowledgeVersion Retrieves the version of the knowledge in dbName.
GetKnowledgeVersionAfterJob Retrieves the knowledge version on which jobId has been executed.
IsDatabaseExist To understand if a database exist.
ResetGraphDatabaseConfiguration Resets the global configuration config for the graph database graphDb to the default values.
SetGraphDatabaseConfiguration Sets the global configuration config for the graph database graphDb.
GetLastLog Get last log in date for specific database.
(Inherited from ILogManagerReader.)
GetLogs Iterator for logs. Logs are sorted descending by create date.
(Inherited from ILogManagerReader.)
GetLogStartingAt
ReadLogs(String, DateTimeOffset, Nullable<Int32>, Nullable<DateTimeOffset>) Reads logs from database. Logs are sorted descending by create date.
(Inherited from ILogManagerReader.)
ReadLogs(String, Int32, Int32, DateTimeOffset, Nullable<DateTimeOffset>) Reads logs from database. Logs are sorted descending by date. The results returned by ReadLogs are constrained by the pageIndex and pageSize parameters. The pageSize parameter identifies the maximum number of Logs objects to return in the List.The pageIndex parameter identifies which page of results to return, where 0 identifies the first page. For example, if 13 logs were in the database for the application, and the pageIndex value was 1 with a pageSize of 5, the logs list returned would contain the sixth through the tenth logs returned. Range is (sinceDateTimeLog;toDateTimeLog> (left open, right closed).
(Inherited from ILogManagerReader.)
     
Process management ActiveJobsInProcess
ActiveStatusOfProcess
CancelJobInProcess
CancelProcess
CancelOrphantJob  
GetAgentsMessages Returns messages generated by agents for given period of time.
GetKnowledgeVersionAfterJob Retrieves the knowledge version on which jobId has been executed.
InstallProcessor Installs dll with methods used by the Agents.
IsProcessCompleted To understand if a process has been completed.
StatusOfJobInProcess  
StatusOfOrphantJob  
StatusOfProcess  
UninstallProcessor Uninstalls given dll with additional methods used by Agents.
     
SPARQL FormatSparqlQuery Adds to the incipit of a sparql query common prefixes and the : prefix associated to the database.
GetSparqlQueryEndpointResult Return the results of the SPARQL query as a string when the process is finished.
GetSparqlQueryGraphAskResult Get the
GetSparqlQueryGraphSelectResult Return the results of the SPARQL query as a SparqlResult instance when the process is finished.
GetQueryForSentence Translate a CNL sentence to a SPARQL query.
SparqlQueryEndpoint Execute a SPARQL query against the RDF database. To decode the result use GetSparqlQueryEndpointResult(Guid).
SparqlQueryGraphAsk Execute SPARQL query against RDF graph contained in the database. To decode the result use GetSparqlQueryGraphAskResult(Guid).
SparqlQueryGraphSelect Execute a SPARQL query against the RDF database. To decode the result use GetSparqlQueryGraphSelectResult(Guid).
Knowledge management AddAnnotations Adds annotations to the database given in DbName.
AddMapping Adds new prefix to namespace mapping/mappings for given database.
DescribeInstances  
DescribeInstancesFast
DescribeInstancesResult
DescribeProperty Describe the property given as a parameter. It will search for all instances and concepts related with this property.
DescribePropertyResult
FetchNext Fetches next page of results - in fact - a Guid of the next job, which also can be fetched. Not all client methods uses paging, to find the full list of methods which supports it, refer to manual.
FindLabelsStartingAt  
GetAllMappings Returns all prefix to namespace mappings for given database.
GetAnnotationsForSignature Get the annotations associated to a list of cnl entities.
GetAnnotationsForSignatureResult Get the annotation result.
GetAttributes Get the attributes associated to an instance.
GetAttributesResult Get the instance description.
GetConfigurationDetails  
GetConstraints Returns all modality requirements. To process results call GetConstraintsResult(Guid).
GetConstraintsFast  
GetConstraintsResult Returns all the modality requirements.
GetDomainOrRole Get the domain for the roles specified or the role for the domain. Depending on the byRole variable, this function can answer to two questions: 1) which concept is in the domain of a particular role (byRole = true) or 2) which role has a particular concept in his domain (byRole = false)
GetInstances Get the instance names matching a CNL Query, e.g. “an application that servers Customer-1” : {“Application-1”}.
GetInstancesFast Get the instances matching the concepts in concepts.
GetInstancesResult Return the instances found in the database when the process is finished.
GetKnowledgeVersion Retrieves the version of the knowledge in dbName.
GetKnowledgeVersionAfterJob Retrieves the knowledge version on which jobId has been executed.
GetMappingsForCnl Returns all namespace/prefix mappings extracted from given CNL sentences/entities./>.
GetReadModuleResult Return the module as a vector of strings when the process is finished.
GetReadModuleResultWithSentenceType Return the module in this case, each sentence is grouped into the StatementType.
GetRoles Get the roles associated to an instance.
GetRolesResult Get the instance description.
GetRangeOrRole Get the range for the roles sepcified. Depending on the byRole variable, this function can answer to two questions: 1) which concept is in the range of a particular role (byRole = true) or 2) which role has a particular concept in his range (byRole = false).
GetRuleGraph Function to retrieve the graph of the rules stored in Ontorion
GetRuleGraphResult Function to retrieve the result of a job start with GetRuleGraph.
GetStatements Returns all statements currently stored in given Ontorion database.
GetStatementsOfType Returns all statements of given StatementType, currently stored in given Ontorion database.
GetSubconcepts Get the subconcepts for a given concept or instance.
GetSubconceptsFast Get the subconcepts for a given concept or instance.
GetSubconceptsResult Return the subconcepts found in the database when the process is finished.
GetSubjectByAnnotation Returns a subject of a given annotation in given language.
GetSubProperties Get the subProperties of a given property.
GetSubPropertiesResult Return the subProperties found in the database when the process is finished.
GetSuperConcepts Get the superconcepts for a given concept or instance.
GetSuperConceptsFast Get the superconcepts for a given concept or instance.
GetSuperConceptsResult Return the superconcepts found in the database when the process is finished.
ReadModule Get the module in the database that contains the signatures given. To decode the result use GetReadModuleResult(Guid).
RemoveAllMappings Removes all prefix to namespace mappings from given database.
RemoveMapping Removes given prefix to namespace mapping/mappings for given database.
SaveChanges Insert into the database toAddLogic and delete toDelLogic.
SaveChangesDL Insert into the database toAddLogic and delete toDelLogic where both of them should be in DL. Optionally you can specify the defaultNamespace that will be used for all entities that have no prefix defined.
SaveChangesEN Insert into the database toAddLogic and delete toDelLogic where both of them should be in EN. To specify the defaultNamespace that will be used for all entities that have no prefix defined you should use the Namespace: sentence.
     
Settings and other SetOrdering Sets the order in which Ontorion commands results will be returned.
SetDefaultPageSize Sets the default page size. To disable paging set it to -1. Not all client methods uses paging, to find the full list of methods which supports it, refer to manual.
GetDefaultPageSize Gets the default page size. Not all client methods uses paging, to find the full list of methods which supports it, refer to manual.
GetOntorionClientVersion Get Ontorion Client Version.
GetOrdering Gets current ordering manner of Ontorion commands results. By default ordering is set to Ordering.None.
IsClientCompatible Function to understand if this service is compatible with the OntorionClient that is connecting to it.
IsOntorionServerReady Check if the Ontorion Server is ready for connections and if the Client and Server versions are compatible.
ToOwl Translates to OWL the cnlsentences given as an argument.



Ontorion WCF Service

It is also possible to use OntorionWCFServiceHost application to host locally an Ontorion WCF service. This is particularly useful when experimenting with the WCF service and to set up a full development environment locally. In order to do this, the utility OntorionWCFServiceHost.exe in sdk/bin is present.

The OntorionWCFServiceHost options:

This utility creates a self-hosted service with which it is possible to communicate via SOAP. To run this utility, type (n.b.: administrator priviledges are needed): OntorionWCFServiceHost.exe -u http://yourdomain... where your yourdomain should be the endpoint on which you want the service to listen. In order to implement the same behaviour in a program, it is enough to copy App.config (is located: INSTALL_LOCATION\sdk\bin\App.config) file to folder with dll and write:

                Ontorion.Client.OntorionClient client = new Ontorion.Client.OntorionClient(endpoints);
                Uri baseAddress = new Uri(@"http://127.0.0.1:8181/OntorionService");
                System.ServiceModel.ServiceHost host = new System.ServiceModel.ServiceHost(typeof(Ontorion.Client.OntorionClient), baseAddress);

                System.Configuration.Configuration config = Ontorion.Client.WCF.WCFHelper.GetConfigFile();
                Ontorion.Client.WCF.WCFHelper.AddBindings(_host, config, baseAddress);
                Ontorion.Client.WCF.WCFHelper.AddBehaviors(_host, config);

                host.Open();

                Console.WriteLine("The service is ready at {0}", baseAddress);
                Console.WriteLine("Press Enter to stop the service.");
                Console.ReadLine();

                // Close the ServiceHost.
                host.Close();
                

where your baseAddress should be the endpoint on which you want the service to listen. The string[] endpoints parameter will tell the library what are the endpoints on which the database backend is listening (default is localhost).

Ontorion.CNLClientUtils - Autocomplete Functionality

Autocomplete functionality is a convenient feature as the process of writing queries are automatically supported based on the retrieved data from connected database and correct CNL syntax rules, which leads to generating correct queries and avoiding syntax errors. Autocomplete functionality is supported through Ontorion.CNLClientUtils.dll. To understand how to use it, you can run and look through the example project AutocompleteExample.

First, in order to try running this project you need to set Ontorion configurations in AutocompleteExample\Web.config file in accordance with Ontorion database you wish to connect to.

Then open the file ServerHelper.cs. On the bottom a method 'GetAutoComplete' is showing how it utilizes autocomplete method, calling it through an instance 'Ontorion.CNLClientUtils.Instance'. Basically this is the way how you call the method.

This 'GetAutoComplete' method is used in this application project by a method GetTextHints in HomeController.cs file.

To see how this application works, simply run it and start typing in the textbox. You will see autocomplete functionality works as below.