Changes between Version 11 and Version 12 of SPIDocs

Timestamp:

Sep 16, 2014 11:42:11 AM (10 years ago)

Author:

faber

Comment:

--

SPIDocs

@@ -216 +216 @@
 Many operations in the SPI require a user to agree with the operation before the operation becomes final.  Users who wish to join a project or a circle request permission from the users who own or administer them.  Administrators who wish to add users to their circles request confirmation from the users.  Basically any operation that expands the rights of users requires the users in question to concur.  In order to let users know when such changes are pending or desired, the SPI supports a system for managing short messages available through the `Users` [wiki:SPIDocs#Services service].
 
-''Notifications'' are these short messages.  A notification consists of a the text of the message a unique identifier for the message, and a set of flags.  The valid flags are:
+''Notifications'' are these short messages.  Notifications are sent by the system in response to actions requiring confirmation.  This is not a general inter-user messaging system.
+
+A notification consists of a the text of the message a unique identifier for the message, and a set of flags.  The valid flags are:
 
 ||= Flag Name =||= Meaning =||
@@ -222 +224 @@
 || Read || The user has read this message ||
 
-Flags are specified when a notification is sent and can be set by the receiver as well.
-
+
+Each user has a queue of notifications they can access.  The `getNotifications` operation on the `Users` service returns an array of notifications for an application to display.  Notifications can be filtered by source and by flags.  The flags can be set using the `markNotifications` operation that specifies notifications by unique ID.
+
+Applications will use these operations to:
+
+ * Present a user with a list of pending notifications when a user logs in, or at regular intervals.
+ * Display urgent and other notifications differently.
+ * Allow users to read and respond to notifications by calling avrious SPI operations to confirm pending actions
+ * Search notifications for past actions
+ * Mark notifications as read once viewed and acted upon
+
+Note that users generally cannot send notifications to other users.  Only administrators and testbed actions do this.
+