Group endpoints in the REST API

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

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 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",
 "parent_id": "string"
}
Example request body
{
 "description": "Group for Operators",
 "name": "Operators",
 "parent_id": "250794599774447"
}
Parameters

NameLocated inDescriptionMandatoryScheme
namebodyName of the group.yesstring
descriptionbody

Description of the group.

no

string
parent_idbody

ID of the parent group under which you want to add the group.

If you do not provide this ID, the group will be created as an independent group.

nostring

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 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
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters

NameLocated inDescriptionMandatoryScheme
filterParentsquery

Indication of whether the parent group details need to be retrieved.

Valid values:

  • true
  • (default) false
noboolean
pagequery

Page number of the Common Services > Group Management page displayed on the console from where you want to retrieve details.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

nointeger
orderByquery

Sort order of the details to be retrieved.

Valid value: (Default) created_date_time

nostring

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 group
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters

NameLocated inDescriptionMandatoryScheme
idpath

ID of the group that you want to delete.

Note: You cannot delete a group with child groups and associated users.

yesstring

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 group
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/groups/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters

NameLocated inDescriptionMandatoryScheme
idpathID of the group from which you want to retrieve details.
yesstring

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 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",
  "parent_id": "string"
}
Example request body
{
  "description": "This is a new group",
  "name": "Admins2",
  "parent_id": "424264533111147"
}
Parameters

NameLocated inDescriptionMandatoryScheme
idpathID of the group that you want to update.yesstring
namebodyUpdated name of the group.nostring
descriptionbody

Updated description of the group.

no

string
parent_idbody

ID of the parent group under which you want to add the group.

If you do not provide this ID, the parent group association remains unchanged.

nostring

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 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

NameLocated inDescriptionMandatoryScheme
idpathID of the group that you want to update.yesstring
idbodyID of the user that you want to add or remove.

yes

string
opbody

Type of operation that you want to perform.

Valid values:

  • add
  • remove
yesstring

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 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

NameLocated inDescriptionMandatoryScheme
idpathID of the group in which you want to replace users.yesstring
user_idbodyID 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
 Search 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
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

NameLocated inDescriptionMandatoryScheme
pagequery

Page number of the Common Services > Group Management page displayed on the console from where you want to retrieve details.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

nointeger
orderByquery

Sort order of the details to be retrieved.

Valid value: (Default) created_date_time

nostring
fieldbody

Field by which you want to search groups.

At one time, you can search either by the group name or by the description. If you want to perform a global search in both the fields, provide asterisk (*) as the value.

Valid values:

  • name
  • description
Yesstring
valuesbody

Value with which you want to search the group.

At a time, you can provide only one value corresponding to the specified field.

YesArray[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 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 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"
}


Was this page helpful? Yes No Submitting... Thank you

Comments