Logbook feature tracker

[puiterwijk]

This issue is intended as a tracker for the idea and implementation of the logbook feature.
My current idea was:

• Add Logbook interface to /api/event, which will contain the current set of logbook entries
• A photo type for /api/upload, which takes a photo which then gets stored on the server. This endpoint would return a Photo ID.
• A logbook-entry type for /api/upload, with fields for subject, message, senior_only, photos and notify. notify would have a value of "nobody", "senior" or "everyone". On finish, the server may notify the people requested about the new logbook entry (but whether this is implemented depends on the server).
• A logbook-viewed type for /api/upload, with a field for entryID, which would make the server mark that the user viewed a particular logbook entry.

The Logbook interface for /api/event would contain a list of logbook entries, where each has fields for entry ID, subject, message, senior_only, photos and viewedBy. Where the viewedBy value is a list of userTokens who have viewed the entry, possibly filtered by the server.

What do you think?

[beverloo]

Thank you for thinking about this! Some thoughts:

• Rather than separating the photo and logbook-entry upload types, maybe combine them? I suspect that the idea is to support multiple photos, but in the past few years I've seen that being necessary ~twice, in which case multiple entries could be created instead.

• Not strictly a technical point, but what do we actually get by recording who viewed an entry? It used to be a forcing function to get people to read it, but nowadays with the portal we can just make the menu icon be more annoying, e.g. by adding a badge.

• As a technical point, if we do want to keep track of viewed state, we can just keep it local to the User. Maybe store the time-of-last-read-entry rather than per-entry state?

• Let's skip notifier settings in v0? I haven't even started implementing push notifications yet, or the service worker, so there's such a chain of dependencies for that to become useful that we can do it later.

[puiterwijk]

• The idea of separating photo and logbook-entry was indeed to allow for multiple photos, but "multiple" can also be 0. It would be an easier way to determine that an item had no photo attached. But I could also just return a hasPhoto boolean, and have the photo that's stored if there's one have the same filename as the logbook entry ID.

• The reason I wanted to record on the server whether a user has viewed an entry would be to allow this information to be synced to multiple devices the user has.

• If we're not going to notify, maybe it's an idea to add a "priority" field, with "High priority" and "normal", where the former would be things people need to know about early (i.e. you'd normally notify them). In that case, storing per entry whether they watched it would become somewhat more important, as a volunteer might read high prio items while walking between shifts, and the rest later.

[beverloo]

• The idea of separating photo and logbook-entry was indeed to allow for multiple photos, but "multiple" can also be 0. It would be an easier way to determine that an item had no photo attached. But I could also just return a hasPhoto boolean, and have the photo that's stored if there's one have the same filename as the logbook entry ID.

The photo field can just be null in that case, right?

• The reason I wanted to record on the server whether a user has viewed an entry would be to allow this information to be synced to multiple devices the user has.

That's fair, but we can achieve the same with a single timestamp. It'd have to be based on the Volunteer object, since User (i.e. /api/login) is cached indefinitely.

• If we're not going to notify, maybe it's an idea to add a "priority" field, with "High priority" and "normal", where the former would be things people need to know about early (i.e. you'd normally notify them). In that case, storing per entry whether they watched it would become somewhat more important, as a volunteer might read high prio items while walking between shifts, and the rest later.

That seems fine. My gut feel is that it'd primarily be for presentational purposes however, in reality I doubt anyone is going to come back to read things later.

[puiterwijk]

• The idea of separating photo and logbook-entry was indeed to allow for multiple photos, but "multiple" can also be 0. It would be an easier way to determine that an item had no photo attached. But I could also just return a hasPhoto boolean, and have the photo that's stored if there's one have the same filename as the logbook entry ID.

The photo field can just be null in that case, right?

Right, I forgot to write down that my idea was to have the client use a configured photo URL prefix, and just add the logbook entry ID and a .jpg to get a URL.
I guess I could also just return a photo URL value in the logbook entry and have the server retain full flexibility in where to store them.

• The reason I wanted to record on the server whether a user has viewed an entry would be to allow this information to be synced to multiple devices the user has.

That's fair, but we can achieve the same with a single timestamp. It'd have to be based on the Volunteer object, since User (i.e. /api/login) is cached indefinitely.

• If we're not going to notify, maybe it's an idea to add a "priority" field, with "High priority" and "normal", where the former would be things people need to know about early (i.e. you'd normally notify them). In that case, storing per entry whether they watched it would become somewhat more important, as a volunteer might read high prio items while walking between shifts, and the rest later.

That seems fine. My gut feel is that it'd primarily be for presentational purposes however, in reality I doubt anyone is going to come back to read things later.

Okay, this sounds fair. In that case I'm also wondering whether we still need a "Subject" for the entries, or just use an abbreviated version of the message in the list, as my thought there was that people could select based on the subject whether or not to read the item now.

[beverloo]

The photo field can just be null in that case, right?

Right, I forgot to write down that my idea was to have the client use a configured photo URL prefix, and just add the logbook entry ID and a .jpg to get a URL.
I guess I could also just return a photo URL value in the logbook entry and have the server retain full flexibility in where to store them.

Yeah, I'd keep it flexible and up to the server. That's consistent with our other APIs.

Okay, this sounds fair. In that case I'm also wondering whether we still need a "Subject" for the entries, or just use an abbreviated version of the message in the list, as my thought there was that people could select based on the subject whether or not to read the item now.

My preference would be to not implement anything until we know we need it, so let's take it out, see how the bare version works, and add it if it makes sense?

[puiterwijk]

The photo field can just be null in that case, right?

Right, I forgot to write down that my idea was to have the client use a configured photo URL prefix, and just add the logbook entry ID and a .jpg to get a URL.
I guess I could also just return a photo URL value in the logbook entry and have the server retain full flexibility in where to store them.

Yeah, I'd keep it flexible and up to the server. That's consistent with our other APIs.

Okay, this sounds fair. In that case I'm also wondering whether we still need a "Subject" for the entries, or just use an abbreviated version of the message in the list, as my thought there was that people could select based on the subject whether or not to read the item now.

My preference would be to not implement anything until we know we need it, so let's take it out, see how the bare version works, and add it if it makes sense?

Sounds fine, will do that!
I'll try write the API in the API.md reference file, and send that as a PR shortly.

[puiterwijk]

PR for API documentation in #17.

[beverloo]

This feature is too late for AnimeCon 2019 unfortunately.