Working with note-based reminders
Reminders can be set on individual notes in a user’s Evernote account and allow the user to:
- Receive alerts at a pre-determined time. In the official Evernote client applications, these alerts may be local notifications, icon badges, etc. This will vary by application and will include a daily digest email sent by Evernote with a list of all reminders due that day (provided the user has opted into this feature).
- Place one or more notes at the top of a list of notes (the contents of a notebook, results of a search, when browsing a tag — basically any instance in which notes are listed).
This functionality is controlled by three attributes in the
NoteAttributes data structure:
reminderOrder attribute, a long integer value, accomplishes three things:
- Sets a reminder on the note that will be synced to Evernote. All other Evernote applications—as well as third-party applications—will have access to the reminder data.
- Forces the note to appear at or near the top of list of notes (depending on the number of visible notes with the attribute set).
- Controls the position of the note within the visible notes with
The latter effect warrants some additional discussion.
If, for example, a notebook contains 10 notes and three of them have
reminderOrder set, the three notes will be sorted (in descending order) according to the value of
reminderOrder. When set by an official Evernote application, this value will be a Unix timestamp, expressed in milliseconds, indicating when the user marked the note as a reminder. Third-party applications should do likewise when setting the
reminderOrder attribute on a note.
reminderTime value on a note indicates that the user wishes to be reminded of that note at the specified date and time. The alert will be triggered, potentially using a variety of platform-specific notification methods, at whatever date and time is stored in the
reminderTime attribute. This value is a Unix timestamp expressed in milliseconds.
Note that if
reminderTime is set on a note that does not currently have
reminderOrder set, the Evernote service will automatically assign a value to
reminderOrder. It is important, however, to understand how
reminderOrder works and how to set it manually.
When a user marks a note containing a reminder as “done”, this attribute is set to the date and time—also a Unix timestamp expressed in milliseconds—when the user performed that action (and should only be manipulated by third-party developers in the same case). Third-party integrations that make use of the reminders functionality may want to account for “completed” reminders in their UIs.
reminderDoneTime is unset on a note and
reminderTime is still set, the reminder should be re-enabled in the UI.
Third-party integrations that make use of
reminderOrder may support the arbitrary reordering of notes by the user (though, this is fairly advanced functionality and isn’t a requirement for third-party integrations). For example:
If the user is viewing a list of the same three notes described earlier like so:
- Note A (where
reminderOrderis set to 10)
- Note B (where
reminderOrderis set to 20)
- Note C (where
reminderOrderis set to 30)
If the user drags Note A between Note B and Note C, the
reminderOrder value for Note A must be reset to fall between the
reminderOrder values for Note B and Note C. In this case, Note A’s
reminderOrder value should be set to 25 in this case. In practice, the
reminderOrder of the note being moved should be set to the average of the
reminderOrder values of the two surrounding notes.
Manual ordering of notes with
reminderOrder set is an advanced operation; most developers will not need to concern themselves with it unless it is beneficial for their particular integration.
Note: while technically allowed, the simple integers in the above example were used to simplify the illustration of the concept and should be avoided in actual use in favor of actual timestamp values.
The following snippet creates a new note object, sets
reminderTime within the note’s
NoteAttributes structure and creates the note by calling
NoteStore.createNote. The last line of the snippet sets the
reminderDoneTime attribute to the current time, which marks the reminder as “done”:
To search for notes with
reminderOrder (or any other reminder-related attribute) set, you can use an instance of
NoteFilter in conjunction with