Activity Use Cases
Objects of type Activity are used for several different purposes in the Jive Core API.
- Activities that have occurred within Jive itself.
- Activities in the Inbox for the requesting person.
- Activities in the Actions for the requesting person.
- Activities that have been inserted by a Jive App (or an associated home server).
The following sections describe how activities are used in each of these cases.
Jive Generated Events
As a byproduct of interacting with Jive, either manually through the UI or programmtically from a Jive App, activity stream entries are automatically generated. Examples of generated activities include:
- Creating a new content object
- Modifying an existing content object
- Commenting on a content object (or replying to a discussion or message)
- Liking a content object or a place
- Posting a new status update
Within each activity, the following fields are used to describe corresponding Jive objects, as follows:
| Field | Description |
|---|---|
| actor | The Jive person that performed the activity that triggered this activity stream entry. |
| content | A textual summary of this activity, generally following the format "actor verb object" or "actor verb object target". |
| jive.collection | Opaque identifier for a collection of related activities, which can optionally be used to create a grouping like you see in the Jive UI. All activities in the same collection will be consecutive, and will have the same value for this field. |
| object | The Jive object that was directly affected by this activity. For Jive content objects, the object.summary field will contain a summarized version of the content. |
| provider | Information about the Jive instance within which this activity occurred. |
| target | Generally, the place containing the Jive object described by the object field. |
| title | The subject (for a content object) or name (for a place) of the Jive object described by the object field. |
| updated | Date and time of the latest update within the collection of activities this activity is part of (see above for more information on the jive.collection field. |
| url | URL to an HTML representation of the Jive object described by the object field. |
| verb | An English verb (prefixed with "jive:" describing what kind of activity is represented by this entry. Example values include:
|
See ActivityObject Type for a description of the subfields for the actor, generator, object, provider, and target fields.
Inbox Entries
If the requesting person has decided to follow a particular content object or place in his or her Inbox, any related activity will may be retrieved and managed via the Inbox Service. Inbox activities will have the same fields as Jive Generated Events, with the following additions:
| Field | Description |
|---|---|
| jive.read | Flag indicating whether or not this inbox entry has already been read. |
| jive.update | REST endpoint for marking inbox entry as read or unread. Perform a POST with an empty body to mark as read, a DELETE with an empty body to mark as unread. |
| jive.collectionRead | Flag indicating whether or not the "Acclaim" entry in the inbox associated with this entry has been read. Only available for activity related to acclaim, e.g. activity with a verb jive:liked indicating another user liked your content. |
| jive.updateCollection | REST endpoint for marking the "Acclaim" inbox entry as read or unread. Perform a POST with an empty body to mark as read, a DELETE with an empty body to mark as unread. Only available for activity related to acclaim. |
Accessing an inbox entry via the Core API does NOT set the read status to true. To do that, perform a POST request with an empty body to the URL given in the jive.update field. To mark an inbox entry as unread, perform a DELETE request to the same URL. In the case of Acclaim, the jive.updateCollection field will be present.
Action Entries
An action entry is an activity stream entry that includes one or more actions that the requesting person can perform. In includes the same fields as Jive Generated Events, with the following additions:
| Field | Description |
|---|---|
| jive.state | Description of the current state of this action. When an action is first created, the state will be awaiting_action. After a particular action has been taken, the state will automatically be updated to one of the other legal values. |
| opensocial.actionLinks | Array of ActionLinks representing individual actions that the requesting person can initiate. If an action link includes a target field, initiating a particular action will cause an HTTP request to be sent to this URI as a side effect. Most actions will include a "Dismiss" action link that acknowledges that the requesting person has seen this action and dealt with it appropriately. |
See Perform Action for how to programmatically initiate a particular action.
The verb field of an action entry may contain a value "jive:notification:xxxxx" or "jive:action:xxxxx" for standard Jive event notifications, and action requests, respectively. There are approximately 40 possible values.
Application Generated Events
In addition to activities created as a byproduct of interacting with Jive, activities of any of the above types can be dynamically inserted into an activity stream by a Jive app, or by the home server associated with a Jive App. See Activity Creation for more information.