Activity Creation

Background

In its simplest form, an activity consists of an actor, a verb, an object, and a target. It tells the story of a person performing an action on or with an object, and perhaps in the context of a target. The Activity data format is very flexible, but the absolute minimum amount of required information is small:

Field Description

content

Field	Description
content	A brief description of the activity. You can include HTML markup, as well as replacement variables such as`${@actor}` and `${@target}` in the text, which will be replaced by the display name of the corresponding object. Use one of the following structural patterns as a guide: [actor] [verb]. [actor] [verb] [target]. [actor] [verb] [target] [noun]. Examples: `${@actor} posted` will produce something like "John Smith posted" `${@actor} answered ${@target}'s question` will produce something like "John Smith answered Jane Doe's question". Brevity is the key here. Avoid making your `content` field any longer than 200 characters, because it will look unbalanced next to other stream updates in the activity stream.
title	A short text string that will be displayed in bold above the content. It will be rendered as a hyperlink to the application that generated this activity.

A brief description of the activity. You can include HTML markup, as well as replacement variables such as${@actor} and ${@target} in the text, which will be replaced by the display name of the corresponding object. Use one of the following structural patterns as a guide:

[actor] [verb].
[actor] [verb] [target].
[actor] [verb] [target] [noun].

Examples:

${@actor} posted will produce something like "John Smith posted"
${@actor} answered ${@target}'s question will produce something like "John Smith answered Jane Doe's question".

Brevity is the key here. Avoid making your content field any longer than 200 characters, because it will look unbalanced next to other stream updates in the activity stream.

title

A short text string that will be displayed in bold above the content. It will be rendered as a hyperlink to the application that generated this activity.

The verb field is optional, and will be set to "post" if not included. If you include your own verb, you can reference it with a replacement variable like this: ${verb}. We will learn more about the substitution expressions in the examples below.

By convention, Jive uses the object.summary field to contain a description of the object that is longer than the top level content field described above. Generally, this field will not be visible at the initial display of the activity, but will be made visible when the user clicks on an "expand" or "show more" control.

Creating an Activity Stream Entry

Creating an activity stream programmatically consists of preparing a JSON object with appropriate fields (as described in the examples below, and then send it to the server. Then, make a POST to /activities, passing in the JSON object that you have prepared.

The sections below describe many use cases for creating activity stream entries of various types.

Simple Activity
Activity With Object References
References to Jive Objects
Grouped Activities
Sending Notifications
Sending Actions

Note that, although Inbox Entries look like activities, there is no direct way to create them through the Activity Stream APIs. Instead, the entries are created as a side effect of creating a Share or Direct Message that includes the recipient, or @mentioning the recipient in a content object.

Stream Update - Simple Activity

Most Jive Apps will use this type of entry to display activity. The stream entry looks very much like a native Jive status update or microblog entry. It flows into the activity stream, and is visible to the entire community.

{
  "title" : "Bessie is leaving us",
  "content" : "John Smith sold Bessie the Cow to Jane Doe for $75.00",
  "verb" : "sold"
}

Stream Update - Activity With Object References

You can produce the same content string with object references. An expression like ${verb}is replaced by the contents of the verb field, while ${object.displayName} navigates to the object field and down to the displayName field inside.

{
  "title" : "Bessie is leaving us",
  "content" : "John Smith ${verb} ${object.displayName} to ${target.displayName} for $75.00",
  "object" : {
    "displayName" : "Bessie the Cow",
    "summary" : "&lt;p>Bessie is a well mannered cow that will give you lots of milk.&lt;/p>",
    "image" : {
      "url" : "http://images.example.com/bessie.jpg"
    }
  },
  "target" : {
    "displayName" : "Jane Doe"
  },
  "verb" : "sold"
}

These substitutions are performed when the activity is initially created, so the replacements will have already been made when you retrieve this activity in an activity stream.

Stream Update - References To Jive Objects

If Jane Doe is a Jive user on this Jive instance, you can pass an id field that contains the URI for this person (retrieved from the resources.self.ref field of the Person object for her). Then, you can use one of the following special macros to reference the Jive representation of each object, which will cause the Jive UI to render this object with appropriate formatting (hyperlinks on the display names, profile popup on people, and so on.

${@actor} - The authenticated person who is creating this activity (populated automatically).
${@generator} - The application that generated this activity (populated automatically.
${@object} - The "object" included in the activity (use the id field inside to include the URI of the corresponding Jive object, if there is one).
${@provider} - The Jive instance where this activity was created (populated automatically).
${@target} - The "target" included in the activity (use the id field inside to include the URI of the corresponding Jive object, if there is one).

When you retrieve an activity that was created with one of these macros, and the corresponding object includes anid field with the URI of the corresponding Jive object, you will see that the entire object has been filled out, including links to the corresponding profile image (if any), as well as a url that links to the HTML representation of this object.

{
  "title" : "Bessie is leaving us",
  "content" : "${@actor} ${verb} ${object.displayName} to ${@target} for $75.00",
  "object" : {
    "displayName" : "Bessie the Cow",
    "summary" : "&lt;p>Bessie is a well mannered cow that will give you lots of milk.&lt;/p>",
    "image" : {
      "url" : "http://images.example.com/bessie.jpg"
    }
  },
  "target" : {
    "id" : "https://example.jiveon.com/api/core/v3/people/1234"
  },
  "verb" : "sold"
}

The feature to reference Jive object IDs works with any Jive object that has an individual URI (people, places, and content objects), and works on the actor, generator, object,provider, and target.

Stream Update - Grouped Activities

Some use cases for generating activity would be perceived as "noisy" by users consuming them, especially if there might be a high volume of very similar messages. To optimize the user experience, Jive offers a way to ask for "similar" activities to be grouped together in a summarized display, where the user is offered a chance to expand the summary to see the individual details if he or she wants to. In order to cause your activities to be grouped in the Jive user interface:

The activities must come from the same application, and also have the same verb value.
Include a jive field (containing Jive-specific extensions) that contains a displayfield with a value of "grouped" (see the example below).

Technically, "must come from the same application" means that the activities must share the same value for the generator field. An app that is creating activity stream entries does not need to worry about this, however; the generator value will be calculated automatically, and is guaranteed to be the same for all activities created by the same application.

Let's take posting photos to a photo gallery. If you have a prolific photographer who posts many pictures, the activity streams of users consuming these activities could get overflowed by a large number of individual entries. This makes a good opportunity to leverage grouping, like this:

{
  "verb" : "Posted to Product Images",
  "jive" : {
    "display" : "grouped"
  },
  "title" : "Photo Album:  Product Images",
  "content" : "Mark 1 Potato Peeler",
  "icon" : {
    "url" : "http://photos.example.com/productImages/icon.png"
  },
  "object" : {
    "displayName" : "Mark 1 Potato Peeler",
    "image" : {
      "url" : "http://photos.example.com/productImages/potatoPeeler.png"
    },
    "objectType" : "image",
    "summary" : "&lt;p>The Mark 1 Potato Peeler has very sharp blades, and other cool features.&lt;/p>"
  },
  "target" : {
    "displayName" : "Product Images Gallery",
    "image" : {
      "url" : "http://photos.example.com/productImages/gallery.png"
    },
    "objectType" : "gallery"
  }
}

Using a strategy of customizing the verb to include the name of the gallery being posted to, all of the activities for the same gallery, posted by the same application, will be grouped in the Jive user interface. If you would prefer to group all postings to any gallery, just use a common verb like "posted" instead.

Sending Notifications

Notifications are messages that can be sent by an App to one or more specific people. These messages are visible only to the targeted people, and surface in the actions page. Notifications will stay on that page until the receiver acknowledges receipt by clicking the "OK" button.

To send a notification, you will first need to acquire the Person object for each person to whom you wish to send the notification. Then, for each of them, acquire the URI for that person by extracting the value of the resources.self.ref field.

The URIs you have accumulated go into a deliverTo field, which is inside an openSocialtop level field (containing Activity Streams extensions defined in OpenSocial 2.5 or later). The remainder of the activity stream entry for a notification looks just like what we have seen above.

{
  "openSocial" : {
    "deliverTo" : [
      "https://example.jiveon.com/api/core/v3/people/2345",
      "https://example.jiveon.com/api/core/v3/people/3456",
      "https://example.jiveon.com/api/core/v3/people/4567"
    ]
  },
  "title" : "Get Ready for Office Remodelling",
  "content" : "A major remodel project is slated to begin next week.",
  "object" : {
    "id" : "https://example.jiveon.com/api/core/v3/contents/1234",
    "summary" : "See the attached document for more information.",
  },
  "verb" : "announced"
}

You should use notifications sparingly; an app that sends too many notifications runs the risk of being perceived as irritating. They are best used when you want the receiver to have to acknowledge. If you are simply telling the person that something happened, it is often best to just create a normal activity, but with an object ortarget field that the receiver is following, so that the receiver will see the activity in a regular or custom activity stream.

Sending Actions

Actions are notifications that also include action links, enabling the user to take action immediately without having to open the application first. They also show up on the Actions page (along with notifications), but can be distinguished by having additional buttons available. When the user clicks one of the buttons, Jive sends an HTTP request to a URL that is configured in the action activity entry.

Create an action just as you would create an activity by using the following JSON in a POST to /activities:

{
  "openSocial" : {
    "actionLinks" : [
      { "caption" : "Yes", "httpVerb" : "POST", "target" : "http://home.example.com/yes" },
      { "caption" : "No", "httpVerb" : "POST", "target" : "http://home.example.com/no" }
    ],
    "deliverTo" : [
      "https://example.jiveon.com/api/core/v3/people/2345",
      "https://example.jiveon.com/api/core/v3/people/3456",
      "https://example.jiveon.com/api/core/v3/people/4567"
    ]
  },
  "title" : "Are You Coming to the Holiday Party?",
  "content" : "We need to get a head count this week.",
  "object" : {
    "id" : "https://example.jiveon.com/api/core/v3/contents/1234",
    "summary" : "See the attached document for more information about this event.",
  },
  "verb" : "announced"
}