This documentation supports releases of BMC Helix Portal up to December 31, 2021. To view the latest version, select the version from the Product version menu.

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*