Activity Stream Search
Added by IBM contributorIBM | Edited by Claudia R Elbourn on June 30, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars1 comment

The standard Activity Stream API provides a mechanism for retrieving a stream of events for any given user, filtered by a number of specific criteria. Although this is generally sufficient for the display of most streams of interest, there are occasions when a more complex filter or set of filters are required. Activity Stream Search provides not just this filtering capability but also text search of the Activity Stream along with the identification (and filtering by) topics of interest present in the submitted activities.

Details


Activity Stream Search provides support for a few additional parameters on top of the standard Activity Stream API.

The response format is the same as the one for standard Activity Stream API requests. There is also an additional response element for facet results.

Note: requests that do not require the search and filtering capabilities provided by Activity Stream Search can be served without using the search index. However, the relation between events and followed topic is kept only in the index, thus one's personal stream will include events related to followed topics only when served using the index. For this, preferSearchIndex=true must be specified (see parameter specification below).

Also note that the following views are not supported by Activity Stream Search (i.e, Activity Stream Search parameters cannot be added to them):

  • Saved events (/@me/@saved/@all)
  • Action Required (/@me/@actions/@all)
  • Notifications (/@me/@responses/@all)

Response format

Responses to Activity Stream Search requests may contain two additional properties on the "connections" object of the feed:

 { 


"startIndex": 0,

"totalResults": -1,

"connections": {

"snapshot": "2012-07-17T12:40:15.254Z",

"isAdmin": "false",

"facets": {

"hot_topics": [

{

"score": 100,

"label": "test",

"id": "test"

},

{

"score": 94.89408697782787,

"label": "connections",

"id": "connections"

}

],

"communities": [

{

"score": 51,

"label": "Cameron Test Community Cars and Racing",

"id": "57080d55-11cd-415e-822d-48e575e4a3bf"

},

{

"score": 43,

"label": "Earth Day Community",

"id": "b7de893f-7b6b-4939-a595-f8e607f8b5da"

}

],

"people": [

{

"score": 132,

"label": "Vincent Burckhardt",

"id": "72353640-8f4a-102b-8b12-99c200cfc5b7"

},

{

"score": 59,

"label": "David A. Brooks",

"id": "a1c651c0-8f0a-1028-9579-db07163b51b2"

}

]

}

}, 
  • snapshot - used for pagination, see details below
  • facets: holds facet results. This is a JSON object, with a property for each requested facet type (facet types for which there was no results will be omitted).
    • The result for each facet type is a JSON array. Each object in the array has the following properties:
      • score: for the people and communities facet, the score is the number of events (in the result set) corresponding to the facet value. For Hot Topics, the score represents the relevance/quality of the facet value. A larger score means that this facet is considered to represent the results well
      • id: for the people and communities facets, this is the person or community ID. For Hot Topics, this is the Hot Topics itself
      • label: for the people and communities facets, this is the person or community name. For Hot Topics, this is the Hot Topics itself
    • The array is sorted by score in descending order
    • Example:

Pagination

Paging through Activity Stream results is done by using the updatedBefore parameter. When requesting page N+1 of the results, the value to be passed as the updatedBefore parameter is the "published" date of the last entry of page N.

This is an exclusive bound, i.e., updatedBefore=X means that all results will have published < X (not published <= X).

In roll-up mode (i.e., rollup=true), the caller must also provide the snapshot parameter when providing the updatedBefore parameter. When requesting page N+1, the caller must provide the snapshot value that was returned on page N (as the "snapshot" property of the "connections" object).

Note that updatedBefore is applied to threads (after roll-up), as opposed to dateFilter which is applied to individual events.

Also note that due to performance considerations, the pagination mechanism is limited to 10 pages. When requesting for the 11th page (i.e., the 10th consecutive page with the same snapshot), it could be that not all available results will be returned (but all returned results are guaranteed to satisfy the updatedBefore constraint).



Following topics ic45Create New Article

Input
Method URI Description
GET /connections/opensocial/{auth}/rest/activitystreams/{userId}/@all/@all Retrieve a stream of events for any given user, filtered by a number of specific criteria.
Name Type Optional Description
query
string Yes Query text
queryLanguage
string Yes The language to use for analyzing the query text. The format of this parameter is the standard Java locale format (e.g., "en", "en_US"). The default value is the locale specified on the http request.
filters
string Yes this parameter specifies a list of filters to be applied on top of the query. Multiple filters may be specified, and they are ANDed. The parameter is a JSON array. Each object in the array is of the form {'type':t,'values':[val1,val2,...]}, where t is the filter type and val1,val2,.. are possible values for the filter. These values are OR-ed.
Supported filter type:
actor - a person ID, as appears in the feed, e.g. urn:lsid:lconn.ibm.com:profiles.person:807c7ec0-b0b2-102e-8ca4-bf6747fb3789 (807c7ec0-b0b2-102e-8ca4-bf6747fb3789 is also accepted)
target_person - a person ID
involved - a person ID. This filter retrieves events where the specified people are either actor or target.
source
community - a community UUID. This filter retrieves events which are related to one of the specified communities.
object - a roll-up ID (the ID of some Connections object)
tag
topic - a followed topic. This filter retrieves events where at least one of the specified topics was detected.
hot_topic
Example: retrieve events where the actor ID is 72353640-8f4a-102b-8b12-99c200cfc5b7 and the tag 'android' or 'iphone' appears: filters=[{'type':'actor', 'values':['72353640-8f4a-102b-8b12-99c200cfc5b7']}, {'type':'tag','values':['android', 'iphone']}]
dateFilter
string Yes a range filter on the date of the requested events. The date filter, as all other filters, is applied at the event level, not at the thread level (that is, the filter is applied before rolling up the events into threads), which means that in roll-up mode the results will include the parts of the threads that satisfy the date filter. The parameter is in JSON format, and is of the form {'from':d1,'to':d2,'fromInclusive':b1,'toInclusive':b2}, where:
d1 and d2 are strings representing the start and end dates of the range, in the format specified in RFC 3339, e.g. 'from':'2012-04-05T15:12:06.163Z'.
'from' or 'to' may be omitted (in order to specify an open-ended range)
'fromInclusive' and 'toInclusive' are boolean values specifying whether the date values are inclusive or not, e.g. 'fromInclusive':false.
These properties are optional, default value is true.
facetRequests
string Yes his parameter specifies a list of facet requests, i.e., facets that need to be calculated on the search results and returned as part of the REST response. Multiple facet requests may be specified. The parameter is a JSON array. Each object in the array is of the form {facetType:count}, where count is the size of the "cloud" to be returned (number of facet values in the cloud).
Supported facet types:
people: This is a facet on the "actor" of events. Can be used for getting a list of people who generated the most events (within the events matching the query and filters)
communities: can be used for getting a list of communities that have the most events related to them
hot_topics: can be used for getting a list of topics that represent the result set well.
Each facet type may be specified at most once
Example: getting 3 top people, 5 top communities and 10 Hot Topics: facetRequests=[{'communities':5},{'people':3},{'hot_topics':10}]
preferSearchIndex
boolean Yes specifying preferSearchIndex=true means that the request will be served using the search index even if none of the parameters above were specified. This is needed in order to retrieve a personal stream that contains events delivered to that stream due to following a topic (as the DB-based implementation of the API does not take topic-following into account). The default value is false.
snapshot
string Yes used for pagination (see "Pagination" above)
Name Type Optional Description
Authorization
enumerated No The authentication mechanism selected by your application to access the API.
Basic is the Base64 encoding of the IBM Connections Cloud username and password: Base64(username:password). For example, Base64(twatson@us.ibm.com:password).
Bearer is the oauth 2.0 access token that is generated when the user grants your application access to IBM Connections Cloud services.
See the reference topic "OAuth 2.0 APIs for web server flow" for more information.
Authorized values:
  • bearer
  • basic
Output
Content Type: application/json
Code Description
401
Unauthorized. Returned when no authenticated user or no userid, email, or key parameter are provided on the request.
References
Examples
 
Search for "example" on all public events:
/@public/@all/@all?rollup=true&query=example

Search for public events with "example" in their text whose actor Id is either id1 or id2 and are related to the community c1:
/@public/@all/@all?rollup=true&query=example&filters=[{'type':'actor','values':['id1','id2']}, {'type':'community','values':['c1']}]

Retrieve events from my stream that were tagged with "iphone" or "android", and also get the top 5 people for these events:
/@me/@all/@all?rollup=true&filters=[{'type':'tag','values':['iphone','android']}]&facetRequests=[{'people':5}]
Retrieve events from my stream that were generated between July 18 2012 at 13:00 and July 19 2012 at 19:00 (UTC time).

For these events, get the top 5 people, 3 communities and 10 Hot Topics:
/@me/@all/@all?rollup=true&facetRequests=[{'communities':3},{'people':5},{'hot_topics':10}]&dateFilter={'from':'2012-07-18T13:00:00Z','to':'2012-07-19T19:00:00Z'}

Noam Gal commented on Nov 11, 2015

Re: Activity Stream Search

I've been trying to use the updatedBefore parameter, and I am seeing that it is *inclusive*

https://apps.collabservnext.com/connections/opensocial/basic/rest/activitystreams/@me/@all/@all?format=json&rollup=true&count=4&updatedBefore=2015-11-10T10:34:11.954Z&updatedSince=2015-08-11T07:09:09.631Z

returns 4 entries, the first of which is exactly on "2015-11-10T10:34:11.954Z"

I also looked for a "snapshot" parameter in the "connections" object, and found nothing there, nor anywhere else in the returned json.

I tried issuing the same request with roolup=false, but I'm still getting the first item included.