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

This API is version v1.

Required Roles

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

REST Resource

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

Note:

Before using the REST resources, you must understand how to access the REST resources and other important concepts. See Implementation Best Practices for Cloud EPM REST APIs. Using this REST API requires prerequisites. See Prerequisites.

Table 12-56 Tasks for List Groups

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

Request

Supported Media Types: application/json

Table 12-57 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 application roles assigned to the groups, if any. false: Does not return the list of application 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 12-58 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

The following examples show the contents of the response body in JSON format:

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'