Mana central database

From Koha Wiki

Jump to: navigation, search
Home > Documentation > External applications

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 webservices, that can be accessed from outside, not only by Koha (some data that are not tighten to Koha)

Contents

Name

Mana is a Maori verb easy to pronounce and write which mean to be legal, effectual, binding, authoritative, valid.

Shared Content

For the moment, Mana will centralize the following information :


System preference

There is a system preference 'Mana' listed in the web services preferences.

Syspref to enable or disable Mana on Koha

This system preference allow the librarian to enable or disable the utilization of Mana.

Subscriptions

The subscription on Mana are identified by its title, ISSN, EAN and vendor name, and there are all link with its 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.


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.

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 a option 'Search on mana' in the left panel. Librarians can click on it and it's display a serials search page to make a research by title, ISSN, EAN and vendor name on Mana.

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.

Developper'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 occured on the database.

Criteria for the search are specific for each resource 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 nessecite 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 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 : http://git.biblibre.com/biblibre/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

Personal tools