Activity : Swarm Activity List
List Activity Entries
Summary
List Activity Entries
GET /api/v9/activity
Description
Retrieve the Activity List.
Parameters
Parameter | Description | Type | Parameter Type | Required | Default Value |
---|---|---|---|---|---|
|
Optionally filter activity entries by associated Changelist ID. This only includes records for which there is an activity entry in Swarm. |
integer |
form |
No |
|
|
Optional activity stream to query for entries. This can include user-initiated actions ( |
string |
form |
No |
|
|
Type of activity, for example, |
string |
form |
No |
|
|
An activity ID to seek to. Activity entries up to and including the specified ID are excluded from the results and do not count towards |
integer |
query |
No |
|
|
Maximum number of activity entries to return. This does not guarantee that |
integer |
query |
No |
100 |
|
An optional comma-separated list (or array) of fields to show. Omitting this parameter or passing an empty value shows all fields. |
string |
query |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"activity": [
{
"id": 123,
"action": "committed",
"behalfOf": null,
"behalfOfExists": false,
"change": 1,
"date": "2016-01-15T12:12:12-08:00",
"depotFile": null,
"description": "test\n",
"details": [],
"followers": [],
"link": ["change", {"change": 1}],
"preposition": "into",
"projectList": {"restricted": ["main"]},
"projects": {"restricted": ["main"]},
"streams": ["review-2", "user-foo", "personal-foo", "project-restricted"],
"target": "change 1",
"time": 1404776681,
"topic": "changes/1",
"type": "change",
"url": "/changes/1",
"user": "bruno",
"userExists": true
}
],
"lastSeen": 1
}
Examples of usage
Fetching review history
To get the latest activity entries on a review:
curl -u "username:password" "https://myswarm.url/api/v9/activity?stream=review-1234\
&fields=id,date,description,type\
&max=2"
You can tweak max
and fields
to fetch the data that works best for you.
Swarm responds with an array of activity entities, and a lastSeen
value that can be used for pagination:
{
"activity": [
{
"id": 10,
"date": "2016-04-15T16:10:32-07:00",
"description": "This is a test comment.",
"type": "comment"
},
{
"id": 9,
"date": "2016-03-31T13:48:15-07:00",
"description": "Updating RELNOTE review",
"type": "review"
}
],
"lastSeen": 9
}
Activity pagination
To get the second page of activity entries for a review (based on the previous example):
curl -u "username:password" "https://myswarm.url/api/v9/activity?stream=review-1234\
&fields=id,date,description,type\
&max=2\
&lastSeen=9"
Swarm again responds with a list of activity entities and a lastSeen
value:
{
"activity": [
{
"id": 8,
"date": "2016-03-30T12:12:12-07:00",
"description": "This is the first test comment.",
"type": "comment"
},
{
"id": 7,
"date": "2016-03-29T12:13:14-07:00",
"description": "Updating RELNOTE review",
"type": "review"
}
],
"lastSeen": 7
}
Create Activity Entry
Summary
Create Activity Entry
POST /api/v9/activity
Description
Creates an entry in the Activity List. Note: The authenticated user must match the user provided unless the authenticated user has minimum admin-level privileges in which case any user may be specified.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
Type of activity, used for filtering activity streams (values can include |
string |
form |
Yes |
|
User who performed the action. |
string |
form |
Yes |
|
Action that was performed - past-tense, for example, |
string |
form |
Yes |
|
Target that the action was performed on, for example, |
string |
form |
Yes |
|
Optional topic for the activity entry. Topics are essentially comment thread IDs. Examples: |
string |
form |
No |
|
Optional description of object or activity to provide context. |
string |
form |
No |
|
Optional changelist ID this activity is related to. Used to filter activity related to restricted changes. |
integer |
form |
No |
|
Optional array of streams to display on. This can include user-initiated actions ( |
array (of strings) |
form |
No |
|
Optional URL for |
string |
form |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"activity": {
"id": 123,
"action": "ate",
"behalfOf": null,
"change": null,
"depotFile": null,
"details": [],
"description": "",
"followers": [],
"link": "",
"preposition": "for",
"projects": [],
"streams": [],
"target": "the manual",
"time": 1404776681,
"topic": "",
"type": "comment",
"user": "A dingo"
}
}
Examples of usage
Creating an activity entry
To create a plain activity entry:
curl -u "username:password" -d "type=job" -d "user=jira" -d "action=punted" -d "target=review 123" \
"https://myswarm.url/api/v9/activity"
JSON Response:
{
"activity": {
"id": 1375,
"action": "punted",
"behalfOf": null,
"change": null,
"depotFile": null,
"description": "",
"details": [],
"followers": [],
"link": "",
"preposition": "for",
"projects": [],
"streams": [],
"target": "review 123",
"time": 1461607739,
"topic": "",
"type": "job",
"user": "jira"
}
}
Linking an activity entry to a review
Linking activity entries to reviews is useful. This involves providing link
, stream
, and topic
fields in
the activity data. The link
field is used to make the review 123
string in the activity entry clickable.
The stream
field is needed so that the activity entry can be attached to the review in the Swarm interface.
The topic
field is used to link the activity entry to the comment thread for that topic, in the event that a
user wants to comment on the activity.
To create a fully linked activity entry:
curl -u "username:password" -d "type=job" -d "user=jira" -d "action=punted" -d "target=review 123" \
-d "streams[]=review-123" \
-d "link=reviews/123" \
-d "topic=reviews/123" \
"https://myswarm.url/api/v9/activity"
Swarm responds with an activity entity:
{
"activity": {
"id": 1375,
"action": "punted",
"behalfOf": null,
"change": null,
"depotFile": null,
"description": "",
"details": [],
"followers": [],
"link": "reviews/123",
"preposition": "for",
"projects": [],
"streams": ["review-123"],
"target": "review 123",
"time": 1461607739,
"topic": "reviews/123",
"type": "job",
"user": "jira"
}
}
Your search for returned result(s).