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

NameLocated inDescriptionMandatoryScheme
namebodyName of the group.yesstring
descriptionbody

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

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 User access > User groups 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

Column on which you want to sort.

Valid values: 

  • name
  • description
  • external_id
  • group_source_type
  • system_object
  • group_id
  • sync_date_time
  • (Default) created_date_time
nostring
sortOrderquery

Sort order of the details to be retrieved.

Valid values:

  • (Default) asc
  • desc
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 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

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

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

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

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

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

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

NameLocated inDescriptionMandatoryScheme
pagequery

Page number of the User access > User groups 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

Column on which you want to sort.

Valid values: 

  • name
  • description
  • external_id
  • group_source_type
  • system_object
  • group_id
  • sync_date_time
  • (Default) created_date_time
nostring
sortOrderquery

Sort order of the details to be retrieved.

Valid values:

  • (Default) asc
  • desc
nostring
fieldbody

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 asterisk (*) as the value.

Valid values:

  • name
  • description
  • group_id
Yesstring
valuesbody

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 asterisk (*) as the 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 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


NameLocated inDescriptionMandatorySchema
opbody

Type of operation that you want to perform.

Valid values:

  • add: Assigns the specified users to the group.
  • remove: Removes the specified users from the group.
  • replace: Replaces the existing users with the specified users.

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.

  1. Add operation is performed.
  2. Remove operation is performed.
  3. Replace operation is performed.
yesstring
user_ids
bodyComma-separated of user IDs to use for performing the operation.yesstring
group_idbodyID of the group that you want to update.yesstring

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 or 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, for example op.

{
  "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."
}






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

Comments