×
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')
 
 
  •  

   

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.

BMC Helix Portal 21.3 Performing role-based access control with REST API

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

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

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

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 an 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 an 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
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 list 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 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."
}






Was this page helpful? Yes No Submitting... Thank you
Last modified by Sulekha Gulati on Oct 22, 2021
development reference rest_api using_api authorization

Comments

Log in or register to comment.

User endpoints in the REST API
Role endpoints in the REST API
© Copyright 2020-2021 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2023 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.