Activity : Swarm Activity List

Important

From Swarm 2022.2, Swarm no longer supports APIs older than v9.

List Activity Entries

Summary

List Activity Entries

GET /api/v9/activity

Description

Retrieve the Activity List.

Tip

Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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:

To get the latest activity entry on a review:

curl -u "username:password" http://myswarm.url/api/v9/activity?stream=review-290&max=1

Swarm responds with an array of activity entities, and a lastSeen value that can be used for pagination:

HTTP/1.1 200 OK

{
  "activity": [
    {
      "id": 619,
      "action": "updated files in",
      "behalfOf": null,
      "behalfOfExists": false,
      "behalfOfFullName": "",
      "change": 290,
      "comments": [
        0,
        0
      ],
      "date": "2019-01-23T02:46:59-08:00",
      "depotFile": null,
      "description": "Start of Project Blue Book.",
      "details": [

      ],
      "followers": [

      ],
      "link": [
        "review", 
        {
          "review": "290",
          "version": 2
        }
      ],
      "preposition": "for",
      "projectList": {
        "blue-book": [
          "main"
        ]
      },
      "projects": {
        "blue-book": [
          "main"
        ]
      },
      "streams": {
        "0": "review-290",
        "1": "user-allison.clayborne",
        "2": "personal-allison.clayborne",
        "3": "project-blue-book",
        "7": "group-triage",
        "8": "personal-alex.randolph",
        "9": "personal-jack.boone"
      },
      "target": "review 290 (revision 2)",
      "time": 1548240419,
      "topic": "reviews/290",
      "type": "review",
      "url": "/main/reviews/290/v2/",
      "user": "allison.clayborne",
      "userExists": true,
      "userFullName": "Allison Clayborne"
    }
  ],
  "lastSeen": 618
}

Examples of usage

Fetching review activity

To get the latest activity entries on a review:

Tip

In this example, the review has more than 2 activities but the request has been made to limit the response to a max of 2 activities. This will return the most recent activities unless lastseen is included in the request. This allows for pagination of your results, see Activity pagination.

curl -u "username:password" http://myswarm.url/api/v9/activity?stream=review-1234&fields=id,action,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:

HTTP/1.1 200 OK

{
  "activity": [
    {
      "id": 619,
      "action": "updated files in",
      "date": "2019-01-23T02:46:59-08:00",
      "description": "Start of Project Blue Book.",
      "type": "review"
    },
    {
      "id": 618,
      "action": "commented on",
      "date": "2019-01-23T02:46:19-08:00",
      "description": "This is a short comment.",
      "type": "comment"
    }
  ],
  "lastSeen": 618
}

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=618"

Swarm again responds with a list of activity entities and a lastSeen value:

HTTP/1.1 200 OK

{
  "activity": [
    {
      "id": 617,
      "action": "commented on",
      "date": "2018-12-30T12:12:12-07:00",
      "description": "This is the first test comment.",
      "type": "comment"
    },
    {
      "id": 616,
      "action": "commented on",
      "date": "2018-12-27T12:13:14-07:00",
      "description": "Start of Project Blue Book.",
      "type": "review"
    }
  ],
  "lastSeen": 616
}

Create Activity Entry

Summary

Create Activity Entry

POST /api/v9/activity

Description

Creates an entry in the Activity List.

Important

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.

Tip

Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

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

Examples of usage

Creating an activity entry

To create a plain activity entry:

curl -u "username:password"
     -X POST 
     -d "type=job" 
     -d "user=jira" 
     -d "action=punted" 
     -d "target=review 123" \
     "https://myswarm.url/api/v9/activity"

JSON Response:

HTTP/1.1 200 OK

{  
  "activity":{  
    "id":620,
    "action":"punted",
    "behalfOf":null,
    "change":null,
    "depotFile":null,
    "description":null,
    "details":[  

    ],
    "followers":[  

    ],
    "link":null,
    "preposition":"for",
    "projects":[  

    ],
    "streams":[  

    ],
    "target":"review 123",
    "time":1560783425,
    "topic":null,
    "type":"job",
    "user":"jira"
  }
}

Linking an activity entry to a review

Linking activity entries to reviews is useful. This involves providing link, streams, 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"
     -X POST
     -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:

HTTP/1.1 200 OK

{
  "activity": {
    "id": 1375,
    "action": "punted",
    "behalfOf": null,
    "change": null,
    "depotFile": null,
    "description": null,
    "details": [

    ],
    "followers": [

    ],
    "link": "reviews/123",
    "preposition": "for",
    "projects": [


    ],
    "streams": [
      "review-123"
    ],
    "target": "review 123",
    "time": 1461607739,
    "topic": "reviews/123",
    "type": "job",
    "user": "jira"
  }
}