User Group Report

Generates a User Group Report of users in the system and writes the report to the filename provided. This report lists the direct or indirect membership of users assigned to the group. It can be downloaded using the download command. The report indicates whether the user assignment to group is direct (as member of a group) or indirect (as member of a group that is a child of a nested group). The report identifies the user's login name, first name, last name, email address, assigned group, and type of assignment in the following format. It is identical to the CSV version of the report created from the User Group Report tab in Access Control.

For example, assume that user jdoe is a member of group Test1, which is a child of nested group Test2. In this scenario, the report will display the following information for jdoe:

User, First Name, Last Name, Email, Direct, Group

jdoe, John, Doe, jdoe@example.com, Yes, test1

jdoe, John, Doe, jdoe@example.com, No, test2

This is an asynchronous job and returns the Job ID.

This API is version v1.

Before using the REST resources, you must understand how to access the REST resources and other important concepts. See About the REST APIs. Using this REST API requires prerequisites. See Prerequisites.

Table 8-32 Tasks for User Group Report

Task Request REST Resource
User Group Report POST
/interop/rest/security/<api_version>/usergroupreport
User Group Report Status GET
/interop/rest/security/<api_version>/jobs/<jobId>

REST Resource

POST /interop/rest/security/<api_version>/usergroupreport

Request

Supported Media Types: application/x-www-form-urlencoded

The following table summarizes the request parameters.

Table 8-33 Parameters

Name Description Type Required Default
api_version The specific API version, v1 Path Yes None
fileName The name of the file where the report is to be populated, such as userGroupReport.csv. Form Yes None

Response

Supported Media Types: application/json

Table 8-34 Parameters

Parameters Description
details In case of errors, details are published with the error string
status See Migration Status Codes
links Detailed information about the link
href Links to API call
action The HTTP call type
rel Can be self and/or Job Status. If set to Job Status, you can use the href to get the status of the import operation
data Parameters as key value pairs passed in the request

Example of Response Body

The following shows an example of the response body in JSON format.

Response 1 example when job is in progress:

{
    "details": null,
    "links": [
        {
            "href": "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/security/<api_version>/usergroupreport",
            "rel": "self",
            "data": {
                "jobType": "GENERATE_USER_GROUP_REPORT",
                "filename": "<filename>"
            },
            "action": "POST"
        },
        {
            "href": "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/security/<api_version>/jobs/<jobId>",
            "rel": "Job Status",
            "data": null,
            "action": "GET"
        }
    ],
    "status": -1,
    "items": null
}

Response example 2 when the job completes with errors:

{
    "details": "Failed to generate User Group Report. File <filename> already exists. Please provide different file name. ",
    "links": [
        {
            "href": "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/security/<api_version>/jobs/<jobId>",
            "rel": "self",
            "data": null,
            "action": "GET"
        }
    ],
    "status": 1,
    "items": null
}

Response example 3 when the job completes without errors

{
    "details": null,
    "links": [
        {
            "href": "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/security/<api_version>/jobs/<jobid>",
            "rel": "self",
            "data": null,
            "action": "GET"
        }
    ],
    "status": 0,
    "items": null
}

Sample Code

Example 8-22 Example Java Sample Code

Prerequisites: json.jar

Common Functions: See Common Helper Functions for Java

//
// BEGIN 
//
public void generateUserGroupReport(String fileName) {
		try {
			String url = this.serverUrl + "/interop/rest/security/" + apiVersion + "/usergroupreport";
			Map<String, String> reqHeaders = new HashMap<String, String>();
			reqHeaders.put("Authorization", "Basic " + DatatypeConverter
					.printBase64Binary((this.userName + ":" + this.password).getBytes(Charset.defaultCharset())));

			Map<String, String> reqParams = new HashMap<String, String>();
			reqParams.put("filename", fileName);
		
			Map<String, String> restResult = CSSRESTHelper.callRestApi(new HashMap(), url, reqHeaders, reqParams,
					"POST");
			String jobStatus = CSSRESTHelper.getCSSRESTJobCompletionStatus(restResult, reqHeaders);
			System.out.println(jobStatus);
		} catch (Exception e) {
			e.printStackTrace();
		}
	}
// END 
//

Example 8-23 Example Shell Script Sample Code

Prerequisites: jq (http://stedolan.github.io/jq/download/linux64/jq)

Common Functions: See Common Helper Functions for cURL

funcGenerateUserGroupReport() {
        url="$SERVER_URL/interop/rest/security/$API_VERSION/usergroupreport"
        params="filename=$1"
        header="Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
        cssRESTAPI="generateUserGroupReport"
        statusMessage=$(funcCSSRESTHelper "POST" "$url" "$header" "$USERNAME" "$PASSWORD" "$params" "$cssRESTAPI")
        echo $statusMessage
}

Example 8-24 Example Groovy Sample Code

Prerequisites: json.jar

Common Functions: See CSS Common Helper Functions for Groovy


def generateUserGroupReport(fileName) {
	String scenario = "Generating User Group Report in " + fileName;
	String params = "jobtype=GENERATE_USER_GROUP_REPORT&filename="+ fileName;
	def url = null;
	def response = null;
	try {
		url = new URL(serverUrl + "/interop/rest/security/" + apiVersion + "/usergroupreport");
	} catch (MalformedURLException e) {
		println "Please enter a valid URL"
		System.exit(0);
	}
	response = executeRequest(url, "POST", params, "application/x-www-form-urlencoded");
	if (response != null) {
		getJobStatus(getUrlFromResponse(scenario, response, "Job Status"), "GET");
	}
}

Additional Sample Code