List Groups

The List Groups REST API generates a list of available groups in the environment.

The API identifies the group name, description, type, and identity. Additionally, it can provide information about the groups/user members belonging to the groups and the granular roles assigned to the groups.

The API is synchronous and returns the outcome of the operation in the response. Any non-zero status indicates failure in listing groups.

Required Roles

Service Administrator
Any predefined role and the Access Control - Manage granular role
Any predefined role and the Access Control - View granular role

REST Resource

POST /interop/rest/security/v1/groups/list

Table 13-63 Tasks for List Groups

Task	Request	REST Resource
List Groups	POST	`/interop/rest/security/v1/groups/list`

Request

Supported Media Types: application/json

Table 13-64 Request Parameters

Name	Description	Type	Required	Default
`groupname`	Get the groups matching the specified `groupname`.	Payload	No	Return all groups
`type`	Get the groups matching the specified `type`. This is a comma-separated list containing "EPM", "IDCS", or "PREDEFINED"	Payload	No	Return all groups
`members`	true: Returns the list of user and group members belonging to the groups, if any. false: Does not return the list of user and group members belonging to the groups, if any.	Payload	No	False
`roles`	true: Returns the list of granular roles assigned to the groups, if any. false: Does not return the list of granular roles assigned to the groups, if any.	Payload	No	False

Example URL and Payload

https://<BASE-URL>/interop/rest/security/v1/groups/list

{
  "groupname": "Analyst",
  "type": ["EPM","IDCS","PREDEFINED"], 
  "members": true,
  "roles": true
}

Response

Supported Media Types: application/json

Table 13-65 Response Parameters

Name	Description
`links`	Detailed information about the link and HTTP call type
`status`	Status of the operation 0: Operation succeeded 1: Operation failed
`error`	Detailed information about the error
`details`	Group details

Examples of Response Body

Example 1: REST API Issued without any Payload Completes without Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/groups/list",
    "action": "POST"
  },
  "status": 0,
  "error": null,
  "details": [
    {
      "groupname": "Analyst",
      "description": "Used for access assignments for Users",
      "type": "EPM",
      "identity": "native://nvid=7afc645a6c46bb19:39236dfe:17f68cb24d0:-7fbe?GROUP"
    },
    {
      "groupname": "Interactive User",
      "description": "Used for access assignments for Power Users",
      "type": "EPM",
      "identity": "native://nvid=7afc645a6c46bb19:39236dfe:17f68cb24d0:-7fc0?GROUP"
    },
    {
      "groupname": "IDCS_Group",
      "description": "Sample IDCS Group",
      "type": "IDCS",
      "identity": "rest://groupName=IDCS_Group?GROUP"
    },
    {
      "groupname": "Finance",
      "description": "Finance Group",
      "type": "IDCS",
      "identity": "rest://groupName=Finance?GROUP"
    }
  ]
}

Example 2: REST API Issued with Group Name and Type "EPM" in Payload Completes without Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/groups/list",
    "action": "POST"
  },
  "status": 0,
  "error": null,
  "details": [
    {
      "groupname": "Analyst",
      "description": "Used for access assignments for Users",
      "type": "EPM",
      "identity": "native://nvid=7afc645a6c46bb19:39236dfe:17f68cb24d0:-7fbe?GROUP"
    }
  ]
}

Example 3: REST API Issued with Group Name, Members, and Roles in Payload Completes with Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/groups/list",
    "action": "POST"
  },
  "status": 0,
  "error": null,
  "details": [
    {
      "groupname": "Analyst",
      "description": "Used for access assignments for Users",
      "type": "EPM",
      "identity": "native://nvid=7afc645a6c46bb19:39236dfe:17f68cb24d0:-7fbe?GROUP",
      "members": {
        "users": [
          {
            "userlogin": "jdoe",
            "firstname": "Jane",
            "lastname": "Doe",
            "email": "jane.doe@example.com"
          },
          {
            "userlogin": "chris",
            "firstname": "Chris",
            "lastname": "West",
            "email": "chris.west@example.com"
          }
        ],
        "groups": [
          {
            "groupname": "User",
            "description": "UserRole",
            "type": "PREDEFINED"
          },
          {
            "groupname": "InteractiveUser",
            "description": "Used for access assignments for Power Users",
            "type": "EPM"
          }
        ]
      },
      "roles": [
        {
          "rolename": "Ad Hoc - Read Only User",
          "id": "HP: 0017"
        },
        {
          "rolename": "Ad Hoc - User",
          "id": "HP: 0015"
        }
      ] 
    }

Example 4: REST API Issued Only with Type "EPM, IDCS, PREDEFINED" in Payload Completes without Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/groups/list",
    "action": "POST"
  },
  "status": 0,
  "error": null,
  "details": [
    {
      "groupname": "Analyst",
      "description": "Used for access assignments for Users",
      "type": "EPM",
      "identity": "native://nvid=7afc645a6c46bb19:39236dfe:17f68cb24d0:-7fbe?GROUP"
    },
    {
      "groupname": "Interactive User",
      "description": "Used for access assignments for Power Users",
      "type": "EPM",
      "identity": "native://nvid=7afc645a6c46bb19:39236dfe:17f68cb24d0:-7fc0?GROUP"
    },
    {
      "groupname": "IDCS_Group",
      "description": "Sample IDCS Group",
      "type": "IDCS",
      "identity": "rest://groupName=IDCS_Group?GROUP"
    },
    {
      "groupname": "Finance",
      "description": "Finance Group",
      "type": "IDCS",
      "identity": "rest://groupName=Finance?GROUP"
    },
    {
      "groupname": "Service Administrator",
      "description": "Service Administrator Role",
      "type": "PREDEFINED",
      "identity": "rest://displayName=Service_Administrator?GROUP"
    },
    {
      "groupname": "User",
      "description": "User Role",
      "type": "PREDEFINED",
      "identity": "rest://displayName=User?GROUP"
    }
  ]
}

Example 5: REST API Completes with Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/groups/list",
    "action": "POST"
  },
  "status": 1,
  "error": {
    "errorcode": "EPMCSS-21263",
    "errormessage": "Failed to get Groups. Authorization failed. Please provide valid authorized  ser."
  },
  "details": null
}

Sample cURL Command Basic Auth

curl -X POST -s -u '<USERNAME>:<PASSWORD>' -H 'Content-Type: application/json' 'https://<BASE-URL>/interop/rest/security/v1/groups/list

curl -X POST -s -u '<USERNAME>:<PASSWORD>' -H 'Content-Type: application/json' -d '{"groupname":"Analyst","members":true,"roles":true}' 'https://<BASE-URL>/interop/rest/security/v1/groups/list'

Sample cURL Command OAuth 2.0

curl -X POST -H 'Content-Type: application/json' 'https://<BASE-URL>/interop/rest/security/v1/groups/list' --header "Authorization: Bearer <OAUTH_ACCESS_TOKEN>"

curl -X POST --header "Authorization: Bearer <OAUTH_ACCESS_TOKEN>" -H 'Content-Type: application/json' -d '{"groupname":"Analyst","members":true,"roles":true}' 'https://<BASE-URL>/interop/rest/security/v1/groups/list'