Helix Swarm Guide (2020.1)

Reviews: Swarm reviews

Get review information

Summary

Get review information and metadata.

GET /api/v10/reviews/{id}

Description

Retrieve all of the information and metadata for a review.

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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

transitions

To limit the results to a list of the state transitions that are allowed for the review, add the transitions parameter to the request.

query path No

Example usage

Fetch information for a review with an id of 12345

Fetching information for review number 12345.

curl -u "username:ticket" "https://myswarm-url/api/v10/reviews/12345"

Swarm responds with a review entity:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "reviews": [{
      "id": 12345,
      "type": "default",
      "changes": [1,3],
      "commits": [],
      "author": "normal-user",
      "approvals": null,
      "participants": ["normal-user"],
      "participantsData": {
        "normal-user": []
      },
      "hasReviewer": 0,
      "description": "Added a file\n",
      "created": 1576595749,
      "updated": 1576595754,
      "projects": [],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "transitions": {
        "needsRevision": "Needs Revision",
        "approved": "Approve",
        "approved:commit": "Approve and Commit",
        "rejected": "Reject",
        "archived": "Archive"
      },
      "testStatus": null,
      "testDetails": [],
      "deployStatus": null,
      "deployDetails": [],
      "pending": true,
      "commitStatus": [],
      "groups": [],
      "versions": [
        {
          "difference": 1,
          "stream": "//jam/main",
          "streamSpecDifference": 0,
          "change": 2,
          "user": "normal-user",
          "time": 1576595752,
          "pending": true,
          "addChangeMode": "replace",
          "archiveChange": 3,
          "testRuns": [}
        },
        {
          ...
          <other "versions" formatted as above>
          ...
        }
      ],
      "description-markdown": "<span class=\"first-line\">Added a file</span>"
    }]
  }
}

Fetch allowed state transitions for a review with an id of 12345

Fetching a list of the state transitions that are allowed for review 12345

curl -u "username:ticket" "https://myswarm-url/api/v10/reviews/12345/transitions"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "transitions": {
      "needsRevision": "Needs Revision",
      "approved": "Approve",
      "approved:commit": "Approve and Commit",
      "rejected": "Reject",
      "archived": "Archive"
    }
  }
}

If a request fails

<error code>:

    404 Review does not exist

HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Get list of files that changed in a review

Summary

Get a list of files that changed between specified versions of a review.

GET /api/v10/reviews/{id}/files?from={x}&to={y}

Description

Get a list of files that changed between specified versions of a review.

The GET request returns the following:

  • root: the common root depot path of the files that changed between the specified versions of the review.
  •  limited: Swarm limits the number of files presented for changelists based on the max_changelist_files setting for the Helix server connection. By default, a maximum of 1000 files are returned:
    • true: the number of files in the review is ≥ max_changelist_files. Some of the files changed in the specified review versions might not have been returned by this request.
    • false: the number of files in the review is < max_changelist_files. All of the files changed in the specified review versions have been returned by this request.
  • For each file:
    • depotFile: the filename and path of the file.
    • action: how the file changed, Add, Edit, or Delete.
    • type: the filetype of the file, text, binary, symlink, unicode, utf8, utf16, apple, or resource.
    • For more information on filetypes, see the Base filetypes section of the Helix Core P4 Command Reference.

    • rev: the file revision number.
    • fileSize: the file size in bytes.
    • digest: the file digest.
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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

from

Specify a value for from:

  • 0 specifies the base version of the review.
  • -1 specifies the current #head version of the review files in the Helix server.
  • If omitted, from defaults to 0 which is the base version of the review.
  • Must not be greater that the latest version of the review.

integer

query

No

to

Specify a value for to:

  • If omitted, to defaults to the latest version of the review.
  • Cannot be 0 or -1
  • Must not be greater that the latest version of the review.

integer

query

No

Example usage

Get a list of files changed between version 1 and 3 of review 12345

Get a list of files that changed between version 1 and 3 of review 12345.

curl -u "username:ticket" "https://myswarm-url/api/v10/reviews/12345/files?from=1&to=3"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "root": "//jam/main/src",
    "limited": false,
    "files": [{
        "depotFile": "//jam/main/src/execvms.c",
        "action": "edit",
        "type": "text",
        "rev": "3",
        "fileSize": "3343",
        "digest": "82D5161601D12DB46F184D3F0778A16D"
      },
      {
        "depotFile": "//jam/main/src/jam.h",
        "action": "add",
        "type": "text",
        "rev": "2",
        "fileSize": "7364",
        "digest": "2E94B379F201AD02CF7E8EE33FB7DA99"
      }
    ]
  }
} 

If a request fails

<error code>:

  • 400 invalid review version number requested
  • 403 Insufficient permissions to access the review
  • 404 Review does not exist
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Set vote for the authenticated user

Summary

Set the vote for the authenticated user to be up, down, or cleared

POST /api/v10/reviews/{id}/vote

Description

Set the vote for the authenticated user to be up, down, or cleared.

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 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.

Parameters

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

vote

Specify the vote value you want to set on the review. Valid vote values are up, down, and clear. If the requested vote value already exists on the latest version of the review, the vote is not changed.

string body Yes

version

Votes can only be set on the latest version of a review. The version parameter is used to check that you are voting on the latest version of the review.

If the specified version is not the latest version of the review, the vote is not applied to the review and a 400 error is returned. If the version parameter is not included, the vote is applied to the latest version of the review.

integer

body

No

Example usage

Voting up version 1 of review id 12345

Vote up version 1 of review 12345.

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/vote"

The "mybodyfilename.txt" file contains the authenticated user's vote and the version of the review they are voting on:

{
  "vote": "up"
  "version": "1"
}

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "vote": {
      "value": 1,
      "version": 1,
      "isStale": false
    }
  }
} 

If a request fails

<error code>:

  • 400 Version specified is not the latest version of the review
  • 401 User must be authenticated
  • 403 Insufficient permissions to access the review
  • 404 Review does not exist
  • 409 Invalid vote specified, the response error message lists valid votes.
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Change review state

Summary

Change the state of a review.

POST /api/v10/reviews/{id}/transition

Description

Change the state of a review. The state that a review can be changed to depends on a number of factors including its current state. You can check that the state change you want to make is allowed for the review by making a Get review information request first. For more information on review states and restrictions on changing them, see States

Review state transitions:

  • needsRevision
  • needsReview
  • approved only available if the voting requirements for the review are satisfied
  • committed only available for Pre-commit model reviews that have been approved
  • approved:commit only available for unapproved Pre-commit model reviews when the voting requirements for the review are satisfied
  • rejected
  • archived
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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

Example usage

Change state of a review with an id of 12345

Change the state of review 12345 to approved:

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/transition"

The "mybodyfilename.txt" file contains the state you want to change the review to:

{
  "transition": "approved"
}

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "state": "approved",
    "stateLabel": "Approved"
  }
}

If a request fails

<error code>:

  • 400 Specified review state does not exist
  • 401 Insufficient permissions to change review state
  • 403 Insufficient permissions to access the review
  • 404 Review does not exist
  • 409 Specified state is not a valid transition for this review. API response message lists all valid transition states for the review
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Change review author

Summary

Change review author.

PUT /api/v10/reviews/{id}/author

Description

Change the review author.

Important

By default you cannot change the author of a review, this option must be enabled by your Swarm administrator. See Allow author change for details.

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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

Example usage

Change author for review 12345

Change the author for review 12345.

curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/author"

The "mybodyfilename.txt" file contains the new author username:

{
  "author": "asmith"
} 

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "author": "asmith"
  }
}

If a request fails

<error code>:

  • 400 Author change not allowed, set allow_author_change to true
  • 401 Insufficient permissions to change author
  • 403 Insufficient permissions to access the review
  • 404 Review does not exist
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Replace review description

Summary

Replace review description.

PUT /api/v10/reviews/{id}/description

Description

Replace the review description with a new description.

Optional: also replace pending changelist description

Only available if you are editing the description of a pre-commit review and you are the original author of the changelist that created the review.

To also apply your review description changes to the original changelist description, specify 'updateOriginalChangelist' : true.

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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

Example usage

Replace description for review 12345

Replace the description for review 12345.

curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/description"

The "mybodyfilename.txt" file contains the new description:

{
  "description": "This is my replacement description text and it is better than the original description."
} 

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "description": "This is my replacement description text and it is better than the original description.",
    "description-markdown": "<span class=\"first-line\">This is my replacement description text and it is better than the original description.</span>"
  }
}

If a request fails

<error code>:

  • 401 Insufficient permissions to change description
  • 404 Review does not exist
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Replace review participants

Summary

Replace review participants.

PUT /api/v10/reviews/{id}/participants

Description

Replace the review participants with a new set of participants.

Note
  • The text file used for your request must contain a complete list of all of the participants you want on the review (users and groups). The existing review participants are completely replaced by the participants in the text file. For example, if you already have some group participants on the review and you do not specify any group roles in the text file, all of the participant groups will be removed from the review.
  • Default reviewers can be removed from a review but retained default reviewers cannot be removed from a review, see Default reviewers and Retain default reviewers.

    If your request tries to remove a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been removed.

  • You cannot reduce the voting requirement of a retained default reviewer but you can increase it, see Retain default reviewers.
  • If your request tries to reduce the voting requirement of a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been changed.

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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

Example usage

Replace participants for review 12345

Replace participants for review 12345.

curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/participants"

The "mybodyfilename.txt" file contains the new review participants and their voting requirements:

{
  "participants": {
    "users": {
      "asmith": {
        "required": "yes"
      },
      "jbloggs": {
        "required": "no"
      },
      "molsen": {
        "required": "no"
      }
    },
    "groups": {
      "docs": {
        "required": "none"
      },
      "qa": {
        "required": "all"
      },
      "dev": {
        "required": "one"
      },
      "testers": {
        "required": "one"
      }
    }
  }
}

Swarm responds with a list of all of the participants and their voting requirements:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": {
    "combinedReviewers": [
      "'molsen' must be a reviewer with a minimum requirement of 'required'",
      "'testers' must be a reviewer with a minimum requirement of 'require all'"
    ]
  },
  "data": {
    "participants": {
      "users": {
        "asmith": {
          "required": "yes"
        },
        "jbloggs": {
          "required": "no"
        },
        "molsen": {
          "required": "yes",
          "minimumRequired": "yes"
        }
      },
      "groups": {
        "dev": {
          "required": "one"
        },
        "docs": {
          "required": "none"
        },
        "qa": {
          "required": "all"
        },
        "testers": {
          "required": "all",
          "minimumRequired": "all"
        }
      }
    }
  }
}

If a request fails

<error code>:

  • 400 Invalid participant data, for example: unknown participant id or voting requirement
  • 401 Insufficient permissions to replace participants
  • 403 Insufficient permissions to edit reviewers
  • 404 Review does not exist
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Append review participants

Summary

Append review participants.

POST /api/v10/reviews/{id}/participants

Description

Append more participants to the existing review participants.

Note

Only the users and groups specified in the request are appended to the review. For example, if you don't want to append any group participants to the review there is no need to include the groups role in the text file.

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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

Example usage

Append participants to review 12345

Append participants to review 12345.

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/participants"

The "mybodyfilename.txt" file contains the new review participants and their voting requirements. In this example, bjones is an optional participant:

{
  "participants": {
    "users": {
      "bjones": []
    }
  }
}

Swarm responds with a list of all of the participants and their voting requirements:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "participants": {
      "users": {
        "asmith": {
          "required": "yes"
        },
        "jbloggs": {
          "required": "no"
        },
        "molsen": {
          "required": "yes",
          "minimumRequired": "yes"
        },
        "bjones": []
      },
      "groups": {
        "dev": {
          "required": "one"
        },
        "docs": {
          "required": "none"
        },
        "qa": {
          "required": "all"
        },
        "testers": {
          "required": "all",
          "minimumRequired": "all"
        }
      }
    }
  }
}

If a request fails

<error code>:

  • 400 Invalid participant data, for example: unknown participant id or voting requirement
  • 401 Insufficient permissions to append participants
  • 403 Insufficient permissions to edit reviewers
  • 404 Review does not exist
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Delete review participants

Summary

Delete review participants.

DELETE /api/v10/reviews/{id}/participants

Description

Delete review participants from a review.

Note
  • Only the users and groups specified in the request are deleted from the review. For example, if you don't want to delete any group participants from the review there is no need to include the groups role in the text file.

  • Default reviewers can be removed from a review but retained default reviewers cannot be removed from a review, see Default reviewers and Retain default reviewers.

    If your request tries to remove a retained default reviewer, your request will succeed but with a message in the response indicating that the retained default reviewer has not been removed.

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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

Example usage

Delete participants from review 12345

Delete participants from a review 12345.

curl -X DELETE -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v10/reviews/12345/participants"

The "mybodyfilename.txt" file contains the participants you want to delete from the review:

{
  "participants": {
    "users": {
      "jbloggs": [],
      "molsen": []
    },
    "groups": {
      "docs": []
    }
  }
}

Swarm responds with a list of all of the participants and their voting requirements:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": {
    "combinedReviewers": [
      "'molsen' must be a reviewer with a minimum requirement of 'required'"
    ]
  },
  "data": {
    "participants": {
      "users": {
        "asmith": {
          "required": "yes"
        },
        "molsen": {
          "required": "yes",
          "minimumRequired": "yes"
        },
        "bjones": []
      },
      "groups": {
        "dev": {
          "required": "one"
        },
        "qa": {
          "required": "all"
        },
        "testers": {
          "required": "all",
          "minimumRequired": "all"
        }
      }
    }
  }
}

If a request fails

<error code>:

  • 400 Unknown participant id
  • 401 Insufficient permissions to delete participants
  • 403 Insufficient permissions to edit reviewers
  • 404 Review does not exist
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Obliterate a review

Summary

Obliterate a review.

DELETE /api/v10/reviews/{id}

Description

Important

Obliterate must be used with care, the review and all of its associated metadata are permanently deleted. An obliterated review cannot be reinstated, not even by Perforce Support.

Note
  • By default, you must be a user with admin or super user rights to obliterate a review.
  • Optional: Swarm can be configured to allow users to obliterate reviews that they have authored. Configured by your Swarm administrator, see Allow author obliterate review.

Obliterate is used to permanently delete reviews that have been created by mistake. For instance, if a review is associated with the wrong changelist, or a review contains sensitive information that should not be openly available.

For information on what happens to a review when it is obliterated, see When you obliterate a review.

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 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.

Parameter Description Type Parameter Type Required

id

Review ID

integer

path

Yes

Example usage

Obliterating a review with an id of 12345

Obliterating review number 12345.

curl -X DELETE -u "username:ticket" "https://myswarm-url/api/v10/reviews/12345"

Swarm responds with a message informing you that it has successfully Obliterated the review:

HTTP/1.1 200 OK

{
  "error": null,
  "messages": [{
    "code": "review-obliterated",
    "text": "The review with id [12345] has been obliterated."
  }],
  "data": {
    "reviews": [{
      "id": 12345,
      "type": "default",
      "changes": [1, 3],
      "commits": [],
      "author": "normal-user",
      "approvals": null,
      "participants": ["normal-user"],
      "participantsData": {
        "normal-user": []
      },
      "hasReviewer": 0,
      "description": "Hello\n",
      "created": 1576579928,
      "updated": 1576579932,
      "projects": [],
      "state": "needsReview",
      "stateLabel": "Needs Review",
      "testStatus": null,
      "testDetails": [],
      "deployStatus": null,
      "deployDetails": [],
      "pending": true,
      "commitStatus": [],
      "groups": []
      "versions": [
        {
          "difference": 1,
          "stream": "//jam/main",
          "streamSpecDifference": 0
          "change": 2,
          "user": "normal-user",
          "time": 1576595752,
          "pending": true,
          "addChangeMode": "replace",
          "archiveChange": 3
          "testRuns": []
        },
        {
          ...
          <other "versions" formatted as above>
          ...
        }
      }
    }
  }
}

Obliterating a review if you have insufficient permissions

Obliterating review number 56789.

curl -X DELETE -u "username:ticket" "https://myswarm-url/api/v10/reviews/56789"

Swarm responds with a message informing you that you do not have permission to obliterate the review:

HTTP/1.1 200 OK

{
  "error":403,
  "messages":[{
    "code": "forbidden-exception",
    "text": "Failed to Obliterate the review, you need to have admin privileges or be the review author with 'allow_author_obliterate' set to true."
  }]
  "data": null
}

If a request fails

<error code>":

  • 403 Insufficient permissions to obliterate review
  • 404 Review does not exist
HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
}