Helix Swarm Guide (2019.1)

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

change

Optionally filter activity entries by associated Changelist ID. This only includes records for which there is an activity entry in Swarm.

integer

form

No

 

stream

Optional activity stream to query for entries. This can include user-initiated actions (user-alice), activity relating to a user’s followed projects/users (personal-alice), review streams (review-1234), and project streams (project-exampleproject).

string

form

No

 

type

Type of activity, for example, change, comment, job, or review.

string

form

No

 

after

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 max. Useful for pagination. Commonly set to the lastSeen property from a previous query.

integer

query

No

 

max

Maximum number of activity entries to return. This does not guarantee that max entries are returned. It does guarantee that the number of entries returned won’t exceed max. Server-side filtering may exclude some activity entries for permissions reasons.

integer

query

No

100

fields

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

Type of activity, used for filtering activity streams (values can include change, comment, job, review).

string

form

Yes

user

User who performed the action.

string

form

Yes

action

Action that was performed - past-tense, for example, created or commented on.

string

form

Yes

target

Target that the action was performed on, for example, issue 1234.

string

form

Yes

topic

Optional topic for the activity entry. Topics are essentially comment thread IDs. Examples: reviews/1234 or jobs/job001234.

string

form

No

description

Optional description of object or activity to provide context.

string

form

No

change

Optional changelist ID this activity is related to. Used to filter activity related to restricted changes.

integer

form

No

streams[]

Optional array of streams to display on. This can include user-initiated actions (user-alice), activity relating to a user’s followed projects/users (personal-alice), review streams (review-1234), and project streams (project-exampleproject).

array (of strings)

form

No

link

Optional URL for target.

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"
  }
}