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

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 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.

• 

  Share button on subscription details page

• 

  Confirmation-ask pop-up

• 

  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.

• 

  Notification

• 

  Mana results pop-up

• 

  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.

• 

  Notification

• 

  Mana research

• 

  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

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