[FOLIO-738] design a backend module for storing notes Created: 24/Jul/17  Updated: 12/Nov/18  Resolved: 07/Aug/17

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: New Feature Priority: P2
Reporter: Jakub Skoczen Assignee: Heikki Levanto
Resolution: Done Votes: 0
Labels: core, sprint19
Remaining Estimate: Not Specified
Time Spent: 1 day, 3 hours
Original estimate: Not Specified

Issue links:
Blocks
blocks STCOM-59 Notes v1 Closed
Relates
relates to MODNOTES-1 implement a backend module for storin... Closed
Sprint:

 Description   

As described in STCOM-59 Closed we need a way to attach "notes" to various records in the system (users, items, etc). In the simplest form "note" is a piece of plain text, eventually it may include things like mentions or tiriggers.

Proposed solution:

1. Specify 'notes' API resources (endpoints) using RAML and JSON Schema.
2. Create a new FOLIO module, mod-notes, that allows for CRUDing note records. mod-notes should be implemented as a standard RMB module
3. Each note record contains a piece of text, createdDate, updatedDate, creatorId of the authoring user, and a link (path + UUID) to the record it attaches to
3. It should be possible to query notes for a given object (using the full link, or just path or just the UUID) and for a given users (using creatorId e.g to display all notes by a given user)
4. Permissions: standard permissions to Create/Read notes, user-specific permissions (can be modelled as self endpoint) to Update/Delete notes created by the current user

Note: there user stories talk about the ability to mark notes that the user have read, but we consider this capability to be related to notifications (which are are individual to each user) rather than notes.



 Comments   
Comment by Heikki Levanto [ 26/Jul/17 ]

Some small comments about not to do, at least yet.

  • Notifications when new notes appear should be handled by the notification service, which is separate from this
  • Although notes could be attached to other notes, we probably don't want to go there, that can get messy in the UI.
  • At some point we may need more complex access flags to notes (private notes only visible for the creating user, locked notes that can not be edited without special permissions, etc). But not yet.
  • We may want to consider keeping editing history of a note, in some future version. For now, updateDate and UpdateUser should be sufficient

Some comments on the access permissions

  • A note is visible for any user who can see the base object, and has permission to view notes
  • A note can be edited or deleted by any user who can edit the base object, and has permission to to edit notes
  • A note can be created by any user who can see the base note, and has permission to post notes
  • A user can list and view all notes he has created if he has permission to see notes.
Comment by Heikki Levanto [ 28/Jul/17 ]

A note object should contain

  • id of the note itself
  • link to the item the note belongs to. Relative URL like "/users/12345"
  • text of the note. Can be fairly large. No special formatting (yet?)
  • creatorId UserId who created the note.
  • createdDate Timestamp when the note was created
  • updatedBy UserId of the last person to update the note
  • updatedDate Timestamp of the last update

There seems to be no need to store the ID of the referred object, we can use truncation query on the link field (link endswith /12345). If needed for indexing and performance, it can be added later, and hidden from the user.

Comment by Heikki Levanto [ 28/Jul/17 ]

The API should be fairly regular CRUD API with endpoints

  • /notes for creating, updating, deleting, listing, and getting notes.
  • /notes/_self for listing and getting notes created by the current user

Selecting what notes to get is done by the usual cql querying

Comment by Jakub Skoczen [ 28/Jul/17 ]

Heikki, it's worth noting that we are working on a generic meta-data section for thing like createdDate and createdBy, see: FOLIO-592 Closed . I think you should use it in your schema.

Comment by Heikki Levanto [ 28/Jul/17 ]

Right, using a standard metadata section makes a lot of sense.

Comment by Marc Johnson [ 28/Jul/17 ]

Ok, I'm going to share my reflection of this, to see if I understand it:

  • Notes are related to a single record
  • They are related by a path (relative to the root Okapi URL I'm assuming)

The process a client would go through to find the notes for a record (e.g for an item with ID 12345):
1. Determine a path for a record (presumably based upon a template, e.g. /items/id but might be based upon removing the base): /items/12345
2. Use that path in a CQL request like /notes?query=link=/items/12345 (I haven't escaped this for clarity)

Given that we have representations of records addressable via different paths, e.g. users at /users/12345 or /bl-users/12345, or items /inventory/items/id and /item-storage/items/id which is the canonical path that all notes should be related to?

Comment by Heikki Levanto [ 28/Jul/17 ]

Good question. I can see two ways out: Either the note belongs to /users/12345, and users-bl will fetch the notes too. Or the note belongs to the thing the UI is displaying, users-bl/12345, and the UI is responsible for fetching the notes when it wants to display them. I lean a little towards the latter, but am not at all sure of all the implications.

Comment by Heikki Levanto [ 31/Jul/17 ]

Discussed on our team-1 meeting, and decided to go by the storage link for now, and hope for the UI component being able to fetch its own notes.

Comment by Heikki Levanto [ 01/Aug/17 ]

Design going in parallel with implementation ( MODNOTES-1 Closed )

Generated at Thu Feb 08 23:07:58 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.