README.md 5.87 KB
Newer Older
Matthias Tietz's avatar
Matthias Tietz committed
1
2
3
# TISAF
## Terminology-Service zur interdisziplinären, semantischen Annotation von Forschungsdaten
##### (terminology service for interdisciplinary & semantic annotation of research data)
matthias@staffbase.com's avatar
matthias@staffbase.com committed
4

Matthias Tietz's avatar
Matthias Tietz committed
5
### Installation/Setup
Matthias Tietz's avatar
Matthias Tietz committed
6
0. install apache2, clone this repo into /var/www/html
Matthias Tietz's avatar
Matthias Tietz committed
7
1. change [config.ttl](config.ttl), [resource/js/tisaf.js](resource/js/tisaf.js) constants to your productive host name etc.
Matthias Tietz's avatar
Matthias Tietz committed
8
2. follow https://github.com/NatLibFi/Skosmos/wiki/InstallTutorial 
Matthias Tietz's avatar
Matthias Tietz committed
9
(hints: on debian 10, you need to install openjdk-11 instead of 8 seems not to be available out-of-the-box, also `apt install php libapache2-mod-php` and `apt install php7.3-xsl php7.3-intl php7.3-mbstring` need to be used - adapt 7.2 with your php version)
10

Matthias Tietz's avatar
Matthias Tietz committed
11
12
#### Fuseki Security
By default, on http://<host>:3030 the fuseki admin interface is visible, but data can only be read or written by localhost with default config.
Matthias Tietz's avatar
Matthias Tietz committed
13
14
To make that double sure, you can start Fuseki with `./fuseki-server --localhost` or `service fuseki start --localhost`.
An even better solution would be to "hide" the host port 3030 completely to the outside world, e.g. with proxying or something similar.
Matthias Tietz's avatar
Matthias Tietz committed
15

Matthias Tietz's avatar
Matthias Tietz committed
16
### Import TISAF-specific terminologies
Matthias Tietz's avatar
Matthias Tietz committed
17
18
- optional: import [tisaf terminology](resource/terminologies/tisaf.ttl)
- !!! [tisaf tags terminology](resource/terminologies/tisaf-tags-v4-skosified.ttl) -> needed for tagging of terminologies (and optionally also concepts - TODO)
Matthias Tietz's avatar
Matthias Tietz committed
19

20
The **tags terminology** is a hard depenecy of the TISAF service, and **should** be imported with terminology shortName (aka Vocabulary-ID) = `tags`.
Matthias Tietz's avatar
Matthias Tietz committed
21
You need to use the cmd line tools for a new TISAF installation (e.g. `/opt/fuseki/bin/s-put http://localhost:3030/skosmos/data http://www.tisaf.de/tags/ tisaf-tags-v6-skosified.ttl`) or you can use the own TISAF importer  (see below).
Matthias Tietz's avatar
Matthias Tietz committed
22
23

### Import external terminologies
Matthias Tietz's avatar
Matthias Tietz committed
24
1. download rdf(s), owl or other skos file (e.g. .ttl)
Matthias Tietz's avatar
Matthias Tietz committed
25

Matthias Tietz's avatar
Matthias Tietz committed
26
27
28
29
30
31
2. Transform input data
- a) skos file:
  - use [Skosify](https://github.com/NatLibFi/Skosify/) with e.g. `skosify file.owl --o output.ttl --label "my terminology lalbel"` (or rdf/xml file as input etc.)
- b) owl/rdf/rdfs file:
  - use [Skosify](https://github.com/NatLibFi/Skosify/) with e.g. `skosify file.owl -c examples/dctype.cfg --o output.ttl --label "my terminology lalbel"`
- c) MADS file ([Example](http://id.loc.gov/vocabulary/mencformat.html))
Matthias Tietz's avatar
typo    
Matthias Tietz committed
32
  - use [rdfonto2skos](https://github.com/matthiastz/rdfonto2skos) (fork from Skosify) with e.g. `python skosify.py file.owl -c examples/mads2skos.cfg --o output.ttl --label "my terminology lalbel"`
Matthias Tietz's avatar
Matthias Tietz committed
33

Matthias Tietz's avatar
Matthias Tietz committed
34
35
36
37
38
39
3. Load data: 
- a) via cmd line
  - info [here](https://github.com/NatLibFi/Skosmos/wiki/InstallTutorial#load-data)
  - cmd: `/opt/fuseki/bin/s-put http://localhost:3030/skosmos/data <uri> output.ttl`
- b) via Fuseki Web GUI (localhost:3030)
  - go to [Fuseki Web GUI](http://localhost:3030/dataset.html?tab=upload&ds=/skosmos)
Matthias Tietz's avatar
Matthias Tietz committed
40
41
  - select graph name & input ttl file
  - click upload
Matthias Tietz's avatar
Matthias Tietz committed
42
43
44
- c) via TISAF Web GUI (http://example.com/tisaf/import)
 - follow the import form
 - **recommended**: use [Skosify](https://github.com/NatLibFi/Skosify/) for your input skos rdf file
Matthias Tietz's avatar
Matthias Tietz committed
45
 - for **faster import** use file.rdf (mime type `application/rdf+xml`) instead of Turtle (.ttl) - XML is faster to parse, TTL better to read ;)
Matthias Tietz's avatar
Matthias Tietz committed
46
47
 - select & upload that skos rdf file
 - you can skip the next step (4. config.ttl), but make sure config.ttl is writable by apache2/TISAF: [see import.md](docs/import.md)
Matthias Tietz's avatar
Matthias Tietz committed
48

Matthias Tietz's avatar
Matthias Tietz committed
49
50
51
You will now have inserted your terminology in your Fuseki triple store as a separate graph, but won't see any data in the GUI nor can you query data via the rest api.
So you have to apply the following configuration step:

Matthias Tietz's avatar
Matthias Tietz committed
52
53
4. change config.ttl to add an entry for the new terminology, e.g.: (minimum)
```
Matthias Tietz's avatar
Matthias Tietz committed
54
:terminology-id a skosmos:Vocabulary, void:Dataset ;
Matthias Tietz's avatar
Matthias Tietz committed
55
56
57
58
59
60
    dc:title "my terminology title"@en ;
    skosmos:shortName "terminology short name (used for gui dropdown)";
    dc:subject :category_name ;
    void:uriSpace "uri";
    skosmos:language "en";
    skosmos:defaultLanguage "en";
Matthias Tietz's avatar
Matthias Tietz committed
61
    void:sparqlEndpoint <http://localhost:3030/skosmos/sparql> ; # adapt to your sparql endpoint
Matthias Tietz's avatar
Matthias Tietz committed
62
    skosmos:sparqlGraph <uri> .
Matthias Tietz's avatar
Matthias Tietz committed
63
64
```

Matthias Tietz's avatar
Matthias Tietz committed
65
#### tisaf uri migration
Matthias Tietz's avatar
Matthias Tietz committed
66
67
68
69
70
71
72
We now have imported external data into our TISAF app/namespace. In order to build up **own TISAF specific internal identifiers** in the form of
URIs, you have 2 options:

1. use `/import` (Web GUI preferred) for the whole import process (contenxt: see above steps), the tisaf uri migration will be done fully automatically!
(see [RestController import function](./controller/RestController.php))

2. use the  the [tisafUriMigration script](./tisafUriMigration.php) manually (set the correct terminology id parameter there)
Matthias Tietz's avatar
Matthias Tietz committed
73
74


Matthias Tietz's avatar
Matthias Tietz committed
75
76
77
78
79
80
81
82
### Maximum file size
PHP will upload the given input files from /import to a temporary dir/file.
In order to get the import functionality fully working, adapt the `upload_max_filesize` attribute in your php.ini config file.
E.g.:
``` 
upload_max_filesize = 25M # original: 2M
post_max_size = 30M # post_max should be a bit bigger; original: 8M
```
Matthias Tietz's avatar
Matthias Tietz committed
83
Sync the values between the frontend part in [tisaf.js](resource/js/tisaf.js) and your php.ini.
Matthias Tietz's avatar
Matthias Tietz committed
84
85
And do not forget to: `sudo service apache2 restart`.

Matthias Tietz's avatar
Matthias Tietz committed
86
Btw, this can also be the fix if you get the error `Input file was not uploaded correctly. Please check the name, size and file type...`
Matthias Tietz's avatar
Matthias Tietz committed
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

### Adding/changing translations ([see GitHub doc](https://github.com/NatLibFi/Skosmos/wiki/Translation))

Example: you have a new translation in **lang=de**, with following data:
```
# save that content in resource/translations/skosmos_de.po
msgid "Extended Search" # id of the translation
msgstr "Erweiterte Suche" # concrete value
```

Then you have to transform the data, so it gets read by the app:

```
cd resource/translations
sh trans_script
```

In case you have problems with access rights on the files, then you may want to change that too. See [docs/import.md](docs/import.md) for an example.

Matthias Tietz's avatar
Matthias Tietz committed
106
107
----

Matthias Tietz's avatar
Matthias Tietz committed
108
For more documentation please lookup [/docs](./docs).