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
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
Name | Located in | Description | Mandatory | Scheme |
---|---|---|---|---|
name | body | Name of the group. | yes | string |
description | body | Description of the group. | no | string |
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
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
Name | Located in | Description | Mandatory | Scheme |
---|---|---|---|---|
filterParents | query | Indication of whether the parent group details need to be retrieved. Valid values:
| no | boolean |
page | query | Page number from which you want to retrieve groups. Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter. | no | integer |
size | query | Total number of records that you want to retrieve from a page. Default: 1000 records | no | integer |
orderBy | query | Column on which you want to sort. Valid values:
| no | string |
sortOrder | query | Sort order of the details to be retrieved. Valid values:
| no | string |
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}
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Name | Located in | Description | Mandatory | Scheme |
---|---|---|---|---|
id | path | ID of the group that you want to delete. Note: You cannot delete a group with child groups and associated users. | yes | string |
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}
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Name | Located in | Description | Mandatory | Scheme |
---|---|---|---|---|
id | path | ID of the group from which you want to retrieve details. | yes | string |
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}
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
Name | Located in | Description | Mandatory | Scheme |
---|---|---|---|---|
id | path | ID of the group that you want to update. | yes | string |
name | body | Updated name of the group. | no | string |
description | body | Updated description of the group. | no | string |
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
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
Name | Located in | Description | Mandatory | Scheme |
---|---|---|---|---|
id | path | ID of the group that you want to update. | yes | string |
id | body | ID of the user that you want to add or remove. | yes | string |
op | body | Type of operation that you want to perform. Valid values:
| yes | string |
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
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
Name | Located in | Description | Mandatory | Scheme |
---|---|---|---|---|
id | path | ID of the group in which you want to replace users. | yes | string |
user_id | body | ID of the user that you want to assign to the group. | yes | string |
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
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
Name | Located in | Description | Mandatory | Scheme |
---|---|---|---|---|
page | query | Page number from which you want to retrieve groups. Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter. | no | integer |
size | query | Total number of records that you want to retrieve from a page. Default: 1000 records | no | integer |
orderBy | query | Column on which you want to sort. Valid values:
| no | string |
sortOrder | query | Sort order of the details to be retrieved. Valid values:
| no | string |
field | body | Field by which you want to search user groups. At one time, you can search by the user group name, description, or the user group ID. If you want to perform a global search in all the fields, provide an asterisk (*) as the value. Valid values:
| Yes | string |
values | body | Value with which you want to search the user group. You can pass a comma-separated list of multiple values for all the valid fields except when you use an asterisk (*) as the field. | Yes | Array[string] |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
op | body | Type of operation that you want to perform. Valid values:
Note: If you specify all the operations in the same request body, the API evaluates and runs these operations by using the following precedence order. Multiple expressions of the same operation are run together. For example, all the expressions for adding users are performed together.
| yes | string |
user_ids | body | Comma-separated list of user IDs to use for performing the operation. | yes | string |
group_id | body | ID of the group that you want to update. | yes | string |
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."
}
Comments
Log in or register to comment.