User group endpoints in the REST API

The following section provides a list of supported endpoints for user groups and details about running these endpoints. For more information about how user groups can be useful, see User-groups

For information about the supported user endpoints, see User-endpoints-in-the-REST-API. 

Before you run an endpoint, you must authenticate yourself. For more information, see Access-and-authentication-for-the-REST-API.

POST /ims/api/v1/groups
Create a user group
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
"description": "string",
"name": "string"
}
Example request body
{
"description": "Group for Operators",
"name": "Operators"
}
Parameters
Successful response
{
"group_id": "555568022225499"
}
Unsuccessful response
{
"timestamp": "2020-10-05T07:29:49.150974Z",
"code": 400,
"message": "BAD_REQUEST",
"error": "name Operator already exists."
}
GET /ims/api/v1/groups
Get all user groups under a tenant
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups
Request URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/groups?filterParents={true/false}&page={pagenumber}&size={records}&orderBy=created_date_time&sortOrder=asc
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
 "records": [
   {
     "name": "Administrators",
     "description": "Group of users with tenant administrator permissions.",
     "system_object": true,
     "group_id": "172058502313325"
   },
   {
     "name": "Admins",
     "description": "Admins group",
     "system_object": true,
     "group_id": "209102834577001"
   },
   {
     "name": "Viewers",
     "description": "Viewers group",
     "system_object": true,
     "group_id": "832875755873939"
   },
   {
     "name": "Monitoring Administrators",
     "description": "Monitoring Administrators group",
     "system_object": true,
     "group_id": "646537009286276"
   },
   {
     "name": "Monitoring CS Administrators",
     "description": "Monitoring CS Administrators group",
     "system_object": true,
     "group_id": "802668222332039"
   },
   {
     "name": "ITSM Insight Administrators",
     "description": "ITSM Insight Administrators",
     "system_object": true,
     "external_id": "10f1bb27-2e1e-402d-bcc4-ec999564a194",
     "group_id": "861163279423440"
   },
   {
     "name": "Problem Identification User",
     "description": "Problem Identification User",
     "system_object": true,
     "external_id": "11f1bb27-2e1e-402d-bcc4-ec999564a194",
     "group_id": "701228884763254"
   },
   {
     "name": "ITSM Identification User",
     "description": "ITSM Identification User",
     "system_object": true,
     "external_id": "15f1bb27-2e1e-402d-bcc4-ec999564a194",
     "group_id": "172421019472008"
   },
   {
     "name": " Viewers",
     "description": " Viewers",
     "system_object": true,
     "external_id": "19f1bb27-2e1e-402d-bcc4-ec999564a194",
     "group_id": "548755735505614"
   },
   {
     "name": "RBAC Admins",
     "system_object": false,
     "group_id": "513653507292122"
   },
   {
     "name": "Viewers",
     "system_object": false,
     "group_id": "815123392720773"
   },
   {
     "name": "ADE ITSM Insight Administrator",
     "description": "ADE ITSM Insight Administrator",
     "system_object": true,
     "external_id": "AGGADG09FCNVHAQKYT0UQKYT0U8AO9",
     "group_id": "557119297948906"
   },
   {
     "name": "ADE Predictive Insights",
     "description": "ADE Predictive Insights",
     "system_object": true,
     "external_id": "AGGADG09FCNVHAQKYTORQKYTOR8CIW",
     "group_id": "149088488406951"
   },
   {
     "name": "ADE Incident Correlation User",
     "description": "ADE Incident Correlation User",
     "system_object": true,
     "external_id": "AGGADG09FCNVHAQKYTMLQKYTML8CAQ",
     "group_id": "931246876045909"
   }
  ],
 "_metadata": {
   "page": 0,
   "records_per_page": 1000,
   "page_count": 1,
   "total_count": 66
 }
}
DELETE /ims/api/v1/groups/{id}
Delete a user group
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T07:13:02.895052Z",
 "code": 1200,
 "message": "Group not found.",
 "error": "Group with id: 154927585141310 not found."
}
GET /ims/api/v1/groups/{id}
Get details of a specific user group
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
 "name": "Administrators",
 "description": "Group of users with tenant administrator permissions.",
 "system_object": true,
 "users": [
   {
     "user_id": "786532229118438"
   },
   {
     "user_id": "246274386859172"
   },
   {
     "user_id": "939428113782553"
   }
  ],
 "group_id": "172058502313325"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T07:14:39.912345Z",
 "code": 1200,
 "message": "Group not found.",
 "error": "Group with id: 154927585141310 not found."
}
PATCH /ims/api/v1/groups/{id}
Update general details of a user group
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "description": "string",
 "name": "string"
}
Example request body
{
 "description": "This is a new group",
 "name": "Admins2"
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T07:33:31.352710Z",
 "code": 1200,
 "message": "Group not found.",
 "error": "Group with id: 154927585141310 not found."
}
PATCH /ims/api/v1/groups/{id}/users
Update users associated with a user group
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}/users
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "users": [
   {
     "id": "string",
     "op": "string"
   },
   {
     "id": "string",
     "op": "string"
   }
  ]
}
Example request body


{
 "users": [
   {
     "id": "238076465729611",
     "op": "add"
   },
   {
     "id": "444476211329226",
     "op": "remove"
   }
  ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T09:34:32.618926Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "user_id 1087289297545 does not exist."
}
PUT /ims/api/v1/groups/{id}/users
Replace users associated with a user group
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}/users
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "users": [
   {
     "user_id": "string"
   },
   {
     "user_id": "string"
   }
  ]
}
Example request body
{
 "users": [
   {
     "user_id": "444476211329226"
   },
   {
     "user_id": "238076465729611"
   }
  ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T09:34:32.618926Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "user_id 1087289297545 does not exist."
}
POST /ims/api/v1/groups/search
Search user groups
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/search
Request URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/groups/search?page={pageNumber}&size={records}&orderBy=created_date_time&sortOrder=asc
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "filters": [
   {
     "field": "string",
     "values": [
       "string"
      ]
   }
  ]
}
Example request body
{
 "filters": [
   {
     "field": "*",
     "values": [
       "Parent Group"
      ]
   }
  ]
}
Parameters
Successful response
{
  "records": [   {
     "name": "Parent Group",
     "description": "Trainee Group",
     "system_object": false,
     "group_id": "731497821358320"
  }],
  "_metadata":    {
     "page": 0,
     "records_per_page": 1000,
     "page_count": 1,
     "total_count": 1
  }
}
Unsuccessful response

Scenario 1: The user group name does not exist.

{
  "records": [],
  "_metadata":    {
     "page": 0,
     "records_per_page": 1000,
     "page_count": 0,
     "total_count": 0
  }
}

Scenario 2: You search by both the user group name and the description.

{
  "timestamp": "2020-12-31T19:43:11.060242Z",
  "code": 2300,
  "message": "BAD_REQUEST",
  "error": "Only one value for search is supported."
}

Scenario 3: You search with any value other than the valid values for the field parameter.

{
  "timestamp": "2020-12-31T19:43:07.367968Z",
  "code": 2300,
  "message": "BAD_REQUEST",
  "error": "Unsupported search field: group_desc"
}
POST /ims/api/v1/groups/user_mappings
Update users associated with groups
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/groups/user_mappings
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "mappings": [
   {
     "actions": [
       {
         "op": "string",
         "user_ids": [
           "string"
          ]
       }
      ],
     "group_id": "string"
   }
  ]
}
Example request body
{
 "mappings": [
   {
     "actions": [
       {
         "op": "add",
         "user_ids": [
           "628553027974274"
          ]
       }
      ],
     "group_id": "721343778993755"
   }
  ]
}
Parameters


Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response

Scenario 1: You specify a group that does not exist.

{
  "timestamp": "2021-06-14T08:57:27.547266Z",
  "code": 2300,
  "message": "BAD_REQUEST",
  "error": "Some groupIds are missing, please send correct groupIds."
}

Scenario 2: You specify one or more users that do not exist.

{
 "timestamp": "2021-06-14T13:23:44.126419Z",
 "code": 2300,
 "message": "BAD_REQUEST",
 "error": "Some userIds are missing, please send correct userIds."
}

Scenario 3: You do not specify a mandatory field.

{
 "timestamp": "2021-06-14T13:25:38.848751Z",
 "code": 2300,
 "message": "BAD_REQUEST",
 "error": "At least one action with valid payload should be present. Please check the documentation for correct request body."
}






 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*