search

gbv / paia

Specification of Patrons Account Information API (PAIA)
http://gbv.github.io/paia
15 stars 12 forks source link

Add individual patron messages #64

Closed nichtich closed 6 years ago

nichtich commented 7 years ago

Some library systems support individual message texts for patrons such as "your email could not be delivered", "happy birthday", or "please call us back" etc.

lahmann commented 7 years ago

I agree and think supporting this functionality in PAIA is a great idea. It would be best to get the messages via https://example.org/core/{uri_escaped_patron_identifier}/messages with the response fields message_id (URI), message_content (freeform textfield) and date (datetime). We should also think about being able to dismiss or delete messages by message_id. A scope read_messages (and write_messages for deleting?) might be added as well.

nichtich commented 7 years ago

Well, I more thought of an additional plain text field with a "note" at the patron information endpoint. As far as I understand our library system does not support message dates, ids and information whether a message has been read/deleted. Do you have a backend with more complex messages as described by you?

lahmann commented 7 years ago

Yes, our ILS (Libero) uses messages e.g. to inform a user about requests that got cancelled as the item turned out to be lost (informing the user via email is not possible for that case). As those messages are important to the user they persist until being actively deleted by the user - so, the message_id, the content and a date when the message was sent is the minimal set of fields this functionality would need. Supporting such messages in PAIA would actually complete PAIA's specification for our needs.

nichtich commented 7 years ago

Looks like there are two feature requests. Simple patron notes and multiple messages.

Some questions for data modeling of messages:

lahmann commented 7 years ago
  • Are these messages formatted or plain strings?

As we strip the messages in our middleware from markup, our messages are plaintext, but supporting some markup might be useful for other ILS.

  • Do these messages always have a validated date (datatype) attached to it?

Yes - the date is always datetime.

  • Can one patron have multiple messages at the same time?

Yes.

  • Does the message_id contain any semantics (e.g. message type) or is it just a random identifier to uniquely identify a particular message?

The message_id is some random identifier (might be not random for some ILS).

  • Can messages always be deleted by patrons? Should be also consider library systems that have automatically expiring messages instead of deleting them?

Messages should always be deleteable by patrons (depending on scopes: read_messages, write_messages for deletion). Supporting self expiring messages would certainly not hurt, although I don't know any ILS with such messages. On an afterthought PAIA would not handle deleting the messages if the message expires - so I don't think we need to model this scenario unless we want to support a "was read" flag which gets reported to the ILS.

nichtich commented 7 years ago

Thanks for clarification, looks like a good optional feature. Message languages could be handled via HTTP headers and deletion via HTTP DELETE.

On 13. März 2017 15:41:38 MEZ, "André Lahmann" notifications@github.com wrote:

  • Are these messages formatted or plain strings?

As we strip the messages in our middleware from markup, our messages are plaintext, but supporting some markup might be useful for other ILS.

  • Do these messages always have a validated date (datatype) attached to it?

Yes - the date is always datetime.

  • Can one patron have multiple messages at the same time?

Yes.

  • Does the message_id contain any semantics (e.g. message type) or is it just a random identifier to uniquely identify a particular message?

The message_id is some random identifier (might be not random for some ILS).

  • Can messages always be deleted by patrons? Should be also consider library systems that have automatically expiring messages instead of deleting them?

Messages should always be deleteable by patrons (depending on scopes: read_messages, write_messages for deletion). Supporting self expiring messages would certainly not hurt, although I don't know any ILS with such messages. On an afterthought PAIA would not handle deleting the messages if the message expires - so I don't think we need to model this scenario unless we want to support a "was read" flag which gets reported to the ILS.

-- You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub: https://github.com/gbv/paia/issues/64#issuecomment-286127386

-- Diese Nachricht wurde von meinem Android-Mobiltelefon mit K-9 Mail gesendet.

lahmann commented 7 years ago

Great - language handling via HTTP headers and deletion via HTTP DELETE sounds great as well. Do you need any further assistance to update the specification?

nichtich commented 7 years ago

The messages branch contains a first draft of this feature. Could you provide an example of message list and message deletion with HTTP headers and JSON response?

ndege commented 6 years ago

Hi Jakob, we're still interested in making some progress for this issue. The approach finalizing the branch by adding e.g. examples for messages will lead into an integration at PAIA standard?

nichtich commented 6 years ago

@ndege @lahmann At VZG we don't support this feature so I don't know real-world examples. Could you provide a few? The integration into PAIA standard only requires proofreading and an additional note to return HTTP 501 for unsupported API endpoints.

sebkehr commented 6 years ago

@ndege @nichtich Aside from splitting the specification w.r.t. to the used HTTP verb I added some examples - see #67.

nichtich commented 6 years ago

@lahmann @kese @ndege I created a draft of in branch https://github.com/gbv/paia/tree/notifications. Major changes to the previous drafts:

I can do a release of version 1.3.4 tomorrow before vacation, if needed.

sebkehr commented 6 years ago

@nichtich @ndege @lahmann

I can do a release of version 1.3.4 tomorrow before vacation, if needed.

Yes, we like to see these changes being released asap. Thanks a lot in advance!