A first-access guide to Semantic Turkey

This guide is meant to guide the administrator of Semantic Turkey through the first service invocations, once the system has been installed, in order to create projects, users and to bind them.

General Information

Semantic Turkey functionalities can be invoked by using HTTP GETs or POSTs. The URLs of all services require, by first, the address and port of the machine hosting Semantic Turkey. In the following examples we will assume that the address is http://localhost and that the port is the one set by default for Semantic Turkey: 1979.

Creation of Users

When Semantic Turkey is started for the first time, the directory SemanticTurkeyData (containing information about projects, users and plugins) is created as a sibling directory of the semantic turkey installation, and no user nor project is yet available.

In order to create a user, perform the following POST operation:

http://localhost:1979/semanticturkey/it.uniroma2.art.semanticturkey/st-core-services/Users/registerUser

with the following parameters-values:

email		<email address of the user>
password	<password>
givenName	<given name of the user>
familyName	<family name of the user>

The first user created by this service will be automatically granted the role of administrator. Any user created after the first one will have no role assigned and must be by first approved by the administrator. Their approval of a new user, its binding to a project and the setting of roles for the user in that project will later be performed through another service

Login

Users can login through the this POST:

http://localhost:1979/semanticturkey/it.uniroma2.art.semanticturkey/st-core-services/Auth/login?

with the following parameters:

email                           <email address of the user>
password                        <password>
_spring_security_remember_me    false

Creation of a Project

Users with the proper authorization (only administrators can), are able to create a project through the following POST:

http://localhost:1979/semanticturkey/it.uniroma2.art.semanticturkey/st-core-services/Projects/createProject?

there are several parameters in this service. In the following list we have filled up those requiring a specific value (for instance: "SYSTEM" for "consumer") while we have provided the usual description of the parameter for all those cases where a choice is available. A full description of the service is available on the Projects class in the apidocs

consumer                     SYSTEM         // for now just consider always SYSTEM
projectName                  FirstProject   // actually the name of the project, we ground it to this choice in order to provide consistent examples more ahead
baseURI                      <BaseURI of the dataset modeled in the project>	 // e.g. http://test.it
model                        <the uri of the model>      // the URI of RDFS, OWL or SKOS model (e.g. http://www.w3.org/2004/02/skos/core)
lexicalizationModel          <lexicalization model URI>  // the URI of RDFS, SKOS or SKOS-XL models for labels (e.g. http://www.w3.org/2008/05/skos-xl)
historyEnabled               [true|false]                // if true, history is enabled
validationEnabled            [true|false]                // if true, validation is enabled
repositoryAccess	         {"@type":"CreateLocal"}     // various configurations are possible, this will create a dataset managed locally by RDF4J APIs
coreRepoID                   FirstProject_core
supportRepoID                FirstProject_support  

// the following two configurations depend on the chosen repositoryAccess. More details in the service descriptions, for now just copy these configurations

coreRepoSailConfigurerSpecification	{"factoryId":"it.uniroma2.art.semanticturkey.plugin.impls.repositoryimplconfigurer.PredefinedRepositoryImplConfigurerFactory","configType":"it.uniroma2.art.semanticturkey.plugin.impls.repositoryimplconfigurer.conf.RDF4JNativeSailConfigurerConfiguration","properties":{"forceSync":"false","tripleIndexes":"spoc, posc","directTypeInference":"false","rdfsInference":"false"}}

supportRepoSailConfigurerSpecification	{"factoryId":"it.uniroma2.art.semanticturkey.plugin.impls.repositoryimplconfigurer.PredefinedRepositoryImplConfigurerFactory","configType":"it.uniroma2.art.semanticturkey.plugin.impls.repositoryimplconfigurer.conf.RDF4JNativeSailConfigurerConfiguration","properties":{"forceSync":"false","tripleIndexes":"spoc, posc","directTypeInference":"false","rdfsInference":"false"}}

creationDateProperty         <property to be used for the creation date metadata for each created resource>       // it is optional and can be omitted, will default to dct:created
modificationDateProperty     <property to be used for the modification date metadata for each modified resource>  // it is optional and can be omitted, will default to dct:modified

Approval of a User

Every user created after the administrator has to be activated. Only the Administrator can activate new users.

To activate a new user, after being logged as Administrator, do the following POST:

http://localhost:1979/semanticturkey/it.uniroma2.art.semanticturkey/st-core-services/Users/enableUser

with the following parameters:

email    <email address of the user>
enabled  true

Assignment of a User to a Project

Once users have been activated, in order for them to access a project, the Administrator or a Project Manager need to grant them a role for the desired project

To grant a role to a user for a given project perform the following GET:

http://localhost:1979/semanticturkey/it.uniroma2.art.semanticturkey/st-core-services/Administration/addRolesToUser?projectName=<project_name>&email=<user_email>&roles=<list_of_roles>

where:

<project_name> the name of the project the user is assigned to
<user_email> is the email identifying the user assigned to the project
<list_of_roles> the roles that will be assigned to the user for the specified project. Available standard roles are: rdfgeek, ontologist, thesaurus-editor, validator, lexicographer, mapper and projectmanager

Assignment of a language to a User for a specific Project

To assign one or more editing languages (a list of languages for which the user is authorized to edit content) to a user for a given project, perform the following POST:

http://localhost:1979/semanticturkey/it.uniroma2.art.semanticturkey/st-core-services/Administration/updateLanguagesOfUserInProject?

with parameters:

			
projectName     <name of the project>
email           <email address of the user>
languages       <list of languages assigned to the user>

Calling other services

This page offered an overview of the first serviced to be invoked in Semantic Turkey in order to create the administrator, other users, projects and to activate users and assign them to projects. The full list of services available in Semantic Turkey is available through the javadocs. In order to please check this page