Users: Swarm users

Get a list of users

Summary

Get a list of users.

GET /api/v11/users

Description

Returns a list of users in Swarm.

Parameters

Parameter Description Type Parameter Type Required

ids

An optional single string or an array of users to display. Omitting this parameter or passing an empty value shows all users.

string

query

No

ignoreExcludeList

Determines if the list of users has the user_exclude_list filter applied or not. Add the parameter to ignore the user_exclude_list filter.

boolean

query

No

Example usage

Get a list of users

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

Swarm responds with all users in Swarm:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "users": [
      {
        "id": "bruno",
        "type": "standard",
        "email": "bruno@perforce.com",
        "update": "2013/10/11 21:05:15",
        "access": "2021/01/21 16:55:38",
        "fullName": "Bruno First",
        "jobView": null,
        "password": null,
        "authMethod": "perforce",
        "reviews": []
      },
        ...
        <other users formatted as above>
        ...
      }
    ]
  }
} 		

Fetch a specific user

To fetch details for bruno:

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

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "users": [
      {
        "id": "bruno",
        "type": "standard",
        "email": "bruno@perforce.com",
        "update": "2013/10/11 21:05:15",
        "access": "2021/01/21 16:55:38",
        "fullName": "Bruno First",
        "jobView": null,
        "password": null,
        "authMethod": "perforce",
        "reviews": []
      }
    ]
  }
} 		

Fetch a number of specific users

To fetch details for bruno and alice:

curl -u "username:ticket" "https://myswarm-url/api/v11/users?ids[]=bruno&ids[]=alice"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "users": [
      {
        "id": "bruno",
        "type": "standard",
        "email": "bruno@perforce.com",
        "update": "2013/10/11 21:05:15",
        "access": "2021/01/21 16:55:38",
        "fullName": "Bruno First",
        "jobView": null,
        "password": null,
        "authMethod": "perforce",
        "reviews": []
      },
      {
        "user": "alice",
        "type": "standard",
        "email": "asmith@perforce.com",
        "update": "2018/09/11 18:17:14",
        "access": "2020/12/24 16:55:38",
        "fullName": "Alice Smith",
        "jobView": null,
        "password": null,
        "authMethod": "perforce",
        "reviews": []
      }
    ]
  }
} 		

If a request fails

<error code>:

    401 Incorrect or missing credentials

HTTP/1.1 <response error code>		

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

Get information for a specific user

Summary

Get information for a specific user.

GET /api/v11/users/{id}

Description

Returns information for a specific user in Swarm.

Parameters

Parameter Description Type Parameter Type Required

id

User ID

string

path

Yes

Example usage

Get information for a specific user

To fetch information for bruno:

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

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": [],
  "data": {
    "users": [
      {
        "id": "bruno",
        "type": "standard",
        "email": "bruno@perforce.com",
        "update": "2013/10/11 21:05:15",
        "access": "2021/01/21 16:55:38",
        "fullName": "Bruno First",
        "jobView": null,
        "password": null,
        "authMethod": "perforce",
        "reviews": []
      }
    ]
  }
} 		

If a request fails

<error code>:

  • 401 Incorrect or missing credentials
  • 404 User does not exist
HTTP/1.1 <response error code>		

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

Check for user deletion or add user for deletion in Swarm

Summary

Check if a user has been successfully deleted from the user profile, test definitions, workflows, projects, or groups.

POST /api/v11/users/{id}/cleanup

Description

When a user is deleted from the Helix Core Server, Swarm automatically removes the deleted user from the user configuration, test definitions, workflows, projects, or groups. An admin user can use this API endpoint to determine if a user is successfully deleted from Swarm or if a user is not deleted, Swarm adds the cleanup action for that user in the queue . For more information about how Swarm handles deleted users, see How Swarm handles deleted users .

Parameters

Parameter Description Type Parameter Type Required

id

User ID

string

path

Yes

Example usage

Check if a user has been successfully deleted across all entities in Swarm

To check if user bruno is successfully deleted from Swarm:

curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null,
  "messages": {
      "code": 200,
      "text": {
          "testdefinition": "The requested user bruno does not exist in any testdefinition",
          "workflow": "The requested user bruno does not exist in any workflow",
          "project": "Your request to clean up project for the deleted user bruno has been queued",
          "group": "Your request to clean up group for the deleted user bruno has been queued",
          "followers": "Your request to clean up followers for the deleted user bruno has been queued"
      }
  },
  "data": []
}		 				

Check if a user has been successfully deleted from all test definitions in Swarm

To check if user bruno is successfully deleted from all test definitions in Swarm:

curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/testdefinition"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null, 
  "messages": {
      "code": 200,
      "text": "The requested user bruno does not exist in any test definition"
  },
  "data":[]
}			 				

Check if a user has been successfully deleted from all workflows in Swarm

To check if user bruno is successfully deleted from all workflows in Swarm:

curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/workflow"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null, 
  "messages": {
      "code": 200,
      "text": "Your request to clean up workflow for the deleted user bruno has been queued"
  },
  "data":[]
}			 				

Check if a user has been successfully deleted from all projects in Swarm

To check if user bruno is successfully deleted from all projects in Swarm:

curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/projects"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null, 
  "messages": {
      "code": 200,
      "text": "The requested user bruno does not exist in any project"
  },
  "data":[]
}			 				

Check if a user has been successfully deleted from all groups in Swarm

To check if user bruno is successfully deleted from all groups in Swarm:

curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/groups"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null, 
  "messages": {
      "code": 200,
      "text": "Your request to clean up group for the deleted user bruno has been queued"
  },
  "data":[]
}			 				

Check if a user has been successfully deleted from the user configuration in Swarm

To check if user bruno is successfully deleted from the user configuration in Swarm:

curl -u "username:ticket" -X POST "https://myswarm-url/api/v11/users/bruno/cleanup/config"

Swarm responds with:

HTTP/1.1 200 OK
 
{
  "error": null, 
  "messages": {
      "code": 200,
      "text": "The requested user bruno does not exist in any config"
  },
  "data":[]
}			 				

If a request fails

<error code>:

  • 400 User is active and not yet deleted
HTTP/1.1 <response error code>		

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