Activity Use Cases

Objects of type Activity are used for several different purposes in the Jive Core API.

 

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:

FieldDescription
actorThe Jive person that performed the activity that triggered this activity stream entry.
contentA textual summary of this activity, generally following the format "actor verb object" or "actor verb object target".
jive.collectionOpaque 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.
objectThe 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.
providerInformation about the Jive instance within which this activity occurred.
targetGenerally, the place containing the Jive object described by the object field.
titleThe subject (for a content object) or name (for a place) of the Jive object described by the object field.
updatedDate 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.
urlURL to an HTML representation of the Jive object described by the object field.
verbAn 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:

FieldDescription
jive.readFlag indicating whether or not this inbox entry has already been read.
jive.updateREST 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.collectionReadFlag 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.updateCollectionREST 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:

FieldDescription
jive.stateDescription 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.actionLinksArray 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.