Mana central database

Mana is an Open Source Knowledge Base & micro-service platform dedicated to library data.
It's based on crowd-sourcing. Librarians can share, import and comment information, like subscription numbering patterns, book reviews, reports, ... to Mana.
Those data will be available through web services, that can be accessed from outside, not only by Koha (some data that are not tighten to Koha)
== Name ==
Mana is a Maori verb easy to pronounce and write which means to be legal, effectual, binding, authoritative, valid.
== Shared Content ==
For the moment, Mana will centralize the following information :
* subscriptions,
* vendors,
* book reviews & comments
* SQL reports (tighten to Koha)
* https://wiki.koha-community.org/wiki/Category:Shared_resources
== Koha configuration for Mana ==
Ensure your koha-conf.xml has a mana_config parameter inside the <config> block. It might look something like this:
 <mana_config>https://mana-kb.koha-community.org</mana_config>
== System preference ==
There is a system preference 'Mana' listed in the web services preferences.
This system preference allows the librarian to enable or disable the utilization of Mana.
== Subscriptions ==
Subscriptions on Mana are identified by their title, ISSN, EAN and vendor name, and they are all linked with their numbering pattern and its frequency.
=== Share ===
On the subscription management, there is a 'share' button, to propose common information to Mana. An alert message will ask confirmation before sharing then a notification will feedback if the export is well done or not.
File:mana_share1.png|Share button on subscription details page
File:mana_share2.png|Confirmation-ask pop-up
File:mana_share3.png|Notification
=== Import ===
After the first screen of subscription creation, Koha will automatically request Mana if there are some data available for the current bibliographic record. When there are some results from Mana, a notification will be show and the librarians can click on 'Here' to see all the results.
File:mana_sub_import1.png|Notification
File:mana_sub_mport2.png|Mana results pop-up
File:mana_sub_import3.png|Pre-filled inputs
On the Mana results pop-up the librarians choose which subscription model they want to use and it's will pre-filled all the information concerning the numbering pattern and the frequency of the subscription.
Then, they can fill the remaining inputs and make a prediction pattern and, if they want, test another Mana subscription model.
At final, when the librarians click on 'Save subscription', it will create at the same time of the subscription create, the corresponding numbering pattern and frequency.
=== Comment ===
On the serial home page, there is an option 'Search on mana' in the left panel. Librarians can click on it and it displays a serials search page to make a research by title, ISSN, EAN and vendor name on Mana. 
File:mana_sub_comment1.png|Notification
File:mana_sub_comment2.png|Mana research
File:mana_sub_comment3.png|Mana results
Then all the results are listed in a datatable and later it will be possible to the librarian to post a comment on a subscription model.
== Developer's guide ==
=== Routes Documentation ===
==== How to browse resources ? ====
===== Search for a resource GET /:resource.:format =====
This route is part of the mana API service.
It receives a resource name and specific informations related (as hash).
It returns a hash with keys: data, msg and statuscode.
- statuscode 200, no msg, data full => all worked as expected 
- statuscode 500, "Error : [ database error code ], no data => an error occurred on the database.
Criteria for the search are specific for each resource (you don't need to specify all)
- Subscriptions: issn, ean, publishercode, title
- Reading pairs: documentid1, documentid2, idtype1, idtype2
- Reports: query => it will search queries words in field: savedsql, report_name, report_group, notes, id, type
- Resource comments: resource_type, resource_id
example: 
 GET /resource.json?title=KohaMagazine&publishercode=Biblibre 
===== Get a resource through his id GET /:resource/:id.:format =====
This route is part of the mana API service.
It receives a resource name and an id and search in the corresponding table the resource with this id
example: 
 GET /resource/128.json
Returns the resource with the Mana id 128
===== (Needing administrator privileges) get All informations about a resource with id (including security Token) /admin/:resource =====
This route is part of the administration Interface, it returns main the informations stored in base concerning ANY resource stored in base. It returns all fields in a datatable. It returns ALL resources concerned (can necessitate a long time to load).
example 
 GET /resource/128.json
Return the resource with the mana id
You shouldn't call id outside the Mana Interface
==== Managing resources ====
===== Post a new resource: POST /:resource.:format =====
This route is part of the mana API service.
This route creates a new resource with informations specified in parameters. It checks if there are no duplicates and generates a lot of informations in the database.
example:
 POST /reading_pair.json params => { "securitytoken":"wIcA7CljZ3JEBpmQPLPlH1D6bjseeOzM", "documentid2":"67894", "idtype1":"issn", "documentid1":"12344", "idtype2":"ean" }
===== Comment a resource: POST /resource_comment.:format =====
This routes is a specific case of the previous resource.
example:
 POST /resource_comment.json params => { "securitytoken":"wIcA7CljZ3JEBpmQPLPlH1D6bjseeOzM", "":"67894", "message":"this resource is sooooo bad", "resource_type":"subscriptions", "resource_id":"141" }
This route will comment with the message "this resource is sooooo bad" to the subscription number 141.
===== Import bulk /bulk/:resource.:format =====
Only reading pairs can be bulk imported.
This route is part of the mana API service.
It receives a couple of resources formatted as for a single import and store them as a file which will be stored in the database threw 'misc/cronjob/import_from_files.sh'.
 /bulk/:resource.:format 
{ "securitytoken":"wIcA7CljZ3JEBpmQPLPlH1D6bjseeOzM",
 "reading_suggestions : [ 
 { "securitytoken":"wIcA7CljZ3JEBpmQPLPlH1D6bjseeOzM", "documentid1":"issndoc1", "idtype1":"issn", "documentid2":"eandoc2", "idtype2":"ean" }
 { "securitytoken":"wIcA7CljZ3JEBpmQPLPlH1D6bjseeOzM", "documentid1": "eandoc1", "idtype1":"ean", "documentid2":"eandoc2", "idtype2":"ean" }
 { "securitytoken":"wIcA7CljZ3JEBpmQPLPlH1D6bjseeOzM", "documentid1":"isbndoc1", "idtype1":"isbn", "documentid2":"eandoc2", "idtype2":"ean" }
 ]
}
This will store in a file (processed by a import crontab script) the three resources given in the table reaing_suggestions.
===== Increment a field POST /:resource/id.format/increment/:field (tell you a using a resource)=====
This route is part of the mana API service.
This route increment a specific field from a specific resource. The resource is designed with his id, the field is the name of the field in database.
If the number of user is incremented, that means someone imported it recently and is updates the field lastimport
example:
 POST /subscription/128.json/increment/nbofuser
This will increment the number of users of the subscription 128 </pre>
===== Delete a resource - /delete/:resource.:id =====
This route shouldn't be used outside the Mana Interface
This route is part of the mana administration.
It deletes a resource designated with his id
 /delete/report.:150
This will delete the report number 150
==== Authenticate on database ====
Mana KB uses security tokens to authenticate you on the database
===== Get a token POST /getsecuritytoken =====
This route is part of the mana registration service on database.
This is one of the two only post methods which can be called without security token.
It stores personnal informations in the database and generate a security Token which is used to counter spam.
It sends an e-mail to the user with the address $manaddress/registration?id=$token in order to let him validate the account.
example: 
 /getsecurityToken
{ "firstname":"Anakin", "lastname":"Skywalker", "email":"anakin.skywalker@deathstaremail.com"} 
This will create a security token and send a confirmation email to the mail anakin.skywalker@deathstaremail.com
The mail provides a link to the following route
===== Confirm a security token (step 1/2) /registration =====
This route is part of the Mana registration service on database.
It is always called with a token in the URL.
This route calls a template in charge of:
 - displaying all informations which will be shared with mana
 - check through a google captcha that the user is human.
 - call the second part of the registration.
example: 
 /registration?id=myToken
This will show the informations stored in the database concerning the token myToken, check you are human and coll following route
===== Confirm a security token (step 2/2)
This route is part of the mana registration service on database.
This is one of the two only post methods which can be called without security token (the other is getsecuritytoken)
It is called with the token and a captcharesult. This route checks the authenticity of the captcha result and eventualy activates the token if it works.
example: 
 /registration?id=myId
This will activate the token setting the registration date up.
== References ==
RFC : https://wiki.koha-community.org/wiki/SharingDatasBetweenKohas_rfc
Tasks of the project : https://trello.com/b/BslL6i9p/mana-biblibre
Server source code : https://gitlab.com/koha-community/koha-mana
Client source code integrated in Koha : http://git.biblibre.com/biblibre/kohac/commits/koha-mana
written by Morgane Alonso, intern at BibLibre and by Baptiste Wojtkowski, intern at Biblibre
Category:External_applications