Changes: Swarm changes

Get a list of changes

Summary

Get a list of changes.

GET /api/v11/changes

Description

Get a list of changes the user is able to view.

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

pending

Determines if all changelists, only pending changelists, or only submitted changelists are returned by the request.

  • Not set: All changelists (submitted and pending) are returned.

  • true: Only pending changelists are returned.

  • false: Only submitted changelists are returned.

boolean

query

No

user

The user parameter enables you to return just the changelists created by a specific user.

string

query

No

rootPath

The rootPath parameter enables you to return all the changelists in a specific root path. The rootPath parameter is encoded to URL safe Base64.

Various tools are available online to encode the id to URL safe Base64, for example: https://www.base64encode.org

string

query

No

Example usage

Get a list of changes

curl -u "username:ticket" "https://myswarm-url/api/v11/changes"

Swarm responds with the changes starting with the newest change:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "changes": [
      {
        "id": 12853,
        "date": "2022/04/14 08:59:59",
        "client": "swarm-test",
        "user": "bruno",
        "status": "submitted",
        "type": "public",
        "importedBy": null,
        "identity": null,
        "description": "Fix display bug. ",
        "jobStatus": null,
        "jobs": [],
        "stream": null,
        "files": [
          "//depot/main/myfile.txt#6"
        ]
      },
      {
      ...
      <other change ids formatted as above>
      ...
      }
    ]
  }
}

Get a list of the pending changes

curl -u "username:ticket" "https://myswarm-url/api/v11/changes?pending=true"

Swarm responds with a list of pending changes starting with the newest pending change:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "changes": [
      {
        "id": 12382,
        "date": "2022/04/10 12:59:59",
        "client": "swarm-test",
        "user": "paula.boyle",
        "status": "pending",
        "type": "public",
        "importedBy": null,
        "identity": null,
        "description": "Update license details. ",
        "jobStatus": null,
        "jobs": [],
        "stream": null,
        "files": [
          "//depot/main/license.txt#2"
        ]
      },
      {
      ...
      <other change ids formatted as above>
      ...
      }
    ]
  }
}

Get a list of changes created by Bruno

curl -u "username:ticket" "https://myswarm-url/api/v11/changes?user=bruno"

Swarm responds with the changes created by Bruno starting with the newest change: 

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "changes": [
      {
        "id": 12853,
        "date": "2022/04/14 08:59:59",
        "client": "swarm-test",
        "user": "bruno",
        "status": "submitted",
        "type": "public",
        "importedBy": null,
        "identity": null,
        "description": "Fix display bug. ",
        "jobStatus": null,
        "jobs": [],
        "stream": null,
        "files": [
          "//depot/main/myfile.txt#6"
        ]
      },
      {
      ...
      <other change ids formatted as above>
      ...
      }
    ]
  }
}

Get a list of changes in //depot/Jam/MAIN/...

//depot/Jam/MAIN/... encoded to URL safe Base64 is Ly9kZXBvdC9KYW0vTUFJTi8uLi4=.

curl -u "username:ticket" "https://myswarm-url/api/v11/changes?rootPath=Ly9kZXBvdC9KYW0vTUFJTi8uLi4="

Swarm responds with changelists in //depot/Jam/MAIN/... starting with the newest change:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "changes": [
      {
        "id": 12853,
        "date": "2022/04/14 08:59:59",
        "client": "swarm-test",
        "user": "paula.boyle",
        "status": "pending",
        "type": "public",
        "importedBy": null,
        "identity": null,
        "description": "Update the XML and Word files. ",
        "jobStatus": null,
        "jobs": [],
        "stream": null,
        "files": [
          "//depot/Jam/MAIN/src/anotherfile.xml#3",
          "//depot/Jam/MAIN/src/myfile.xml#15",
          "//depot/Jam/MAIN/src/yetanotherfile.docx#4"
        ]
      },
      {
      ...
      <other change ids formatted as above>
      ...
      }
    ]
  }
}

If a request fails

<error code>:

    403 Insufficient permissions to access the changes

HTTP/1.1 <response error code>		

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

Get a list of files on a change

Summary

Get a list of files on a change.

GET /api/v11/changes/{id}/files

Description

Get a list of files on a change. You must be authenticated to view the files on the change.

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

id

Change ID

integer

path

Yes

Example usage

Get a list of files on change 12106:

curl -u "username:ticket" "https://myswarm-url/api/v11/changes/12106/files"

Swarm responds with a list of files on change 12106: 

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "root": "//depot/triggers",
    "files": [
      {
        "depotFile": "//depot/triggers/swarm-trigger.conf", 
        "action": "add",
        "type": "text",
        "rev": "1",
        "fileSize": "129",
        "digest": "635CC5C20C0C2F3534D94207C7F7FB25"
      },
      {
        "depotFile": "//depot/triggers/swarm-trigger.pl",
        "action": "add",
        "type": "text+x",
        "rev": "1",
        "fileSize": "51239",
        "digest": "0C0E14975CD4E6195E95805DEC98DA03"
      }
    ],
    "limited": false
  }
}

If a request fails

<error code>:

  • 403 Insufficient permissions to access the change

  • 404 Change does not exist

HTTP/1.1 <response error code>		

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

Get job information for jobs associated with a change

Summary

Get job information for jobs associated with a change

GET /api/v11/changes/{id}/jobs

Description

Get job information for jobs associated with a change. You must be authenticated to view the jobs associated with the change.

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

id

Change ID

integer

path

Yes

Example usage

Get job information for change 12344

curl -u "username:<ticket>" "https://myswarm-url/api/v11/changes/12344/jobs"

Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "jobs": [
      {
        "job": "job000020",
        "link": "/jobs/job000020",
        "fixStatus": "open",
        "description": "Fix final bugs for beta release.\n",
        "description-markdown": "<span class=\"first-line\">Fix final bugs for beta release.</span>"
      }
    ]
  }
}

If a request fails

<error code>:

  • 403 Insufficient permissions to access the change
  • 404 Change does not exist
HTTP/1.1 <response error code>		

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

Add a job to a change

Summary

Add a job to a change.

PUT /api/v11/changes/{id}/jobs/{job_id}

Description

Add a job to a change. You must be authenticated to add a job to a change.

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

id

Change ID

integer

path

Yes

job_id

Job ID

integer

path

Yes

Example usage

Add a job to a change

Add job000020 to change12344

curl -u "username:<ticket>" PUT "https://myswarm-url/api/v11/changes/12344/jobs/job000020"

Swarm responds with all of the jobs associated with the change:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "jobs": [
      {
        "job": "job000020",
        "link": "/jobs/job000020",
        "fixStatus": "open",
        "description": "Fix final bugs for beta release.\n",
        "description-markdown": "<span class=\"first-line\">Fix final bugs for beta release.</span>"
      }
    ]
  }
}

Add a job to a change that is already associated with another job

Add job001001 to change12344

curl -u "username:<ticket>" PUT "https://myswarm-url/api/v11/changes/12344/jobs/job001001"

Swarm responds with all of the jobs associated with the change:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "jobs": [
      {
        "job": "job000020",
        "link": "/jobs/job000020",
        "fixStatus": "open",
        "description": "Fix final bugs for beta release.\n",
        "description-markdown": "<span class=\"first-line\">Fix final bugs for beta release.</span>"
      },		
      {
        "job": "job001001",
        "link": "/jobs/job001001",
        "fixStatus": "fixed",
        "description": "Bug fixes by Terry\n",
        "descriptionMarkdown": "<span class=\"first-line\">Bug fixes by Terry</span>"
      }
    ]
  }
}

If a request fails

<error code>:

  • 403 Insufficient permissions to access the change
  • 404 Change does not exist
  • 500 Job does not exist
HTTP/1.1 <response error code>		

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

Remove a job from a change

Summary

Remove a job from a change.

DELETE /api/v11/changes/{id}/jobs/{job_id}

Description

Remove a job from a change. You must be authenticated to remove a job from a change.

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

id

Change ID

integer

path

Yes

job_id

Job ID

integer

path

Yes

Example usage

Remove a job from a change

Remove job000020 from change12344:

curl -u "username:<ticket>" PUT "https://myswarm-url/api/v11/changes/12344/jobs/job000020"

Swarm responds with all of the jobs associated with the change:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "jobs": []
  }
}

Remove a job from a change that is associated with more than one job

Remove job000020 from change12344:

curl -u "username:<ticket>" PUT "https://myswarm-url/api/v11/changes/12344/jobs/job000020"

Swarm responds with all of the jobs associated with the change:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "jobs": [
      {
        "job": "job001001",
        "link": "/jobs/job001001",
        "fixStatus": "fixed",
        "description": "Bug fixes by Terry\n",
        "description-markdown": "<span class=\"first-line\">Bug fixes by Terry</span>"
      }
    ]
  }
}

If a request fails

<error code>:

  • 403 Insufficient permissions to access the change
  • 404 Change does not exist
  • 500 Job does not exist
HTTP/1.1 <response error code>		

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