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: `jive:created` - The Jive object described by the `object` field was just created by the person described by the `actor` field. `jive:liked` - The Jive object described by the `object` field was liked by the person described by the `actor` field.

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