Changes between Version 9 and Version 10 of NewTestbedAPISpec

Timestamp:

Jul 26, 2013 10:57:22 AM (11 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ -229 +229 @@
 A notification is a short message from another user or the testbed asking a user to take an action (add someone to a project, update a password before expiration) or communicating other information to the user (testbed downtime, etc).  A web interface will want to present these to a user.
 
+Each notification has a set of flags that define its state.  Currently there are 2
+
+ * '''READ''' bit 0 (low order bit) true if the user has read the notification
+ * '''URGENT''' bit 1 true if the testbed considers this urgent information
+
+The user is free to change this state using the markNotifications call.  Note that notifications are per-user.  A user who clears the READ or URGENT bit does not clear the bit for other recipients of the notification.
+
  
  * '''Service:''' Users
@@ -236 +243 @@
    * FirstDate - an optional date.  If present only show notifications after that date
    * LastDate - an optional date.  If present only show notifications before that date
-   * OnlyUnread - a flag. If true, show only unread notifications
+   * Flags - a 32-bit integer of flags. Only notifications that match the flags state after the mask is applied are returned
+   * Mask - A 32-bit mask of the bits to consider in the flags field.
  * '''Return Values:'''
    * A list of responses each containing
      * ID - a 64-bit integer identifying the notification
-     * IsRead - a flag indicating that the message has been read by this user
+     * Flags - the message state
      * Sent - the date the notification was issued
      * Text - the text of the notification
 
-The filtering variables are all applied if given.  If OnlyUnread is true and FirstDate and LastDate are both given, only unread notifications between those dates are returned.
-
- * '''Service:''' Users
- * '''Operation:''' markNotificationsRead
+The filtering variables are all applied if given.
+
+The mask and flags variable define the state a user is searching for.  If a bit is set in both mask and flags, only messages with that bit set are returned.  Similarly if a bit is clear in flags and set in mask, only messages with that bit clear will be returned.
+
+To be concrete: a user who wants to retrieve all unread messages (urgent or not) should send a flags field with the READ bit clear and a mask with the READ bit set.  To retrieve only unread urgent messages, the flags should have READ clear and URGENT set, and both READ and URGENT set in the mask.
+
+
+ * '''Service:''' Users
+ * '''Operation:''' markNotifications
  * '''Input Parameters:'''
    * Userid - the user's identity to gather notifications
-   * Notifications - an array of 64-bit integers, the notifications to mark read
+   * Ids - an array of 64-bit integers, the identifiers of the notifications to mark
+   * Flags - a 32-bit integer of flags to change. Notifications will have their flags field set to the value in this field if the corresponding mask bit is set.
+   * Mask - A 32-bit mask of the bits to consider in the flags field.
+ * '''Return Values:'''
+   * None
+
+Administrators can send notifications, for example to announce testbed events.  The call to do so is:
+
+ * '''Service:''' Users
+ * '''Operation:''' sendNotifications
+ * '''Input Parameters:'''
+   * Users - a list of uids to receive the notification
+   * Projects - a list of projects to receive the notification.  All users in the project will receive it
+   * Flags - the initial notification state for each user
+   * Text - the content of the notification
  * '''Return Values:'''
    * None