Reminders

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: reminderTime, reminderOrder and reminderDoneTime.

reminderOrder

Setting the reminderOrder attribute, a long integer value, accomplishes three things:

1. 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.
2. 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).
3. Controls the position of the note within the visible notes with reminderOrder set.

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

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

reminderDoneTime

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.

If reminderDoneTime is unset on a note and reminderTime is still set, the reminder should be re-enabled in the UI.

Reminder Reordering

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 reminderOrder is set to 10)
• Note B (where reminderOrder is set to 20)
• Note C (where reminderOrder is 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.

Sample Code

The following snippet creates a new note object, sets reminderOrder and 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 NoteStore.findNotesMetadata: