Search for Management Roles

POST /GetAllSearchAdvanced

Send a POST request to the GetAllSearchAdvanced() method on the ManagementRoleView object to return information about one or more Management Roles. The information included in the response depends on the range of properties and parameter values included in the request.

A valid OAuth 2.0 Bearer token is required.

URL

POST https://<FQDN_Of_Your_EmpowerID_Web_Server>/api/webui/v1/ManagementRoleView/GetAllSearchAdvanced

Header Key/Value Pairs

Key	Value
Authorization	Bearer <access_token>
X-EmpowerID-API-Key	The API key from the registered OAuth application
Content-Type	application/json

Request Body

The body of the request must include all parameters required by the method and the IncludedProperties object with at least one Management Role property.

Included Properties

Use IncludedProperties to return one or more role properties.

Body Parameters

The GetAllSearchAdvanced() method includes a number of parameters that must be included in the body of the request. Use parameters to filter the number of Management Roles returned by the endpoint.

View Parameters

Parameter	Type	Description
ManagementRoleDefinitionID	`int`	Return all roles with a matching the Management Role Definition (MRD) specified by the MRD ID Set to `null` to ignore Required
OrgZoneID	`int`	Return roles with a matching OrgZone ID Set to `null` to ignore Required
LinkedToApplicationID	`GUID`	Return roles linked to the application specified by the application ID
PersonID	`GUID`	Return roles where the person specified by the PersonID (GUID) is a member Set to `null` to ignore Required
NotAssignedToPersonID	`Boolean`	Return roles not assigned to the Person specified by the Person ID set for the `PersonID` parameter Set to `null` to ignore Required
ShowDirectPersonAssignmentsOnly	`Boolean`	Return roles that have been directly assigned to the person specified by the `PersonID` parameter Set to `null` to ignore Required
ManagementRoleGUIDInherited	`GUID`	Return roles inherited from the Management Role specified by the GUID Set to `null` to ignore Required
HighSecurity	`Boolean`	Return roles marked as high security Set to `null` to ignore Required
ShowTRBACRoles	`Boolean`	Return TRBAC roles Set to `null` to ignore Required
OwnerPersonGUID	`GUID`	Return roles where the person identified by the GUID is the owner Set to `null` to ignore Required
Requestable	`Boolean`	Return roles published in the IAM Shop Set to `null` to ignore Required
columnsToSearch	`string`	Specifies one or more search conditions. Formatted as follows: `"%[[][[]%<Conditions><Condition PropertyName=\"Name of the property to search\" SearchValue=\"Value of the property\" Operator=\"Equality\" QuerySuffix=\" Suffix Value \"StartGroupString=\"\" EndGroupString=\"\" /></Conditions>"` Required
pageLength	`int`	Specifies the number of roles to return in the list of roles Required
resourceTags	`string`	Return roles with a matching resource tag Set to `null` to ignore Required
start	`int`	Specifies the first role in the list of roles returned by the API; set to `0` to return the first role Required
textToSearch	`string`	Set to `"AdvancedSearch"` Required
totalCount	`int`	This is an output parameter that returns the number of roles matching the search conditions and parameter values Set to `null` to ignore Required

columnsToSearch

The columnsToSearch body parameter is used to return Management Roles meeting one or more conditions. Each condition specifies a property with a specific value to search. For example, to return a list of deprecated "All Access" Management Roles, the value for columnsToSearch would be set to that shown below.

"%[[][[]%<Conditions><Condition PropertyName=\"FriendlyName\" SearchValue=\"deprecated\" Operator=\"EqualTo\" QuerySuffix=\" AND \" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/><Condition PropertyName=\"Description\" SearchValue=\"All Access\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"1\" SearchType=\"Boolean\"/></Conditions>"

Remarks

In the above example, columnsToSearch contains two search conditions. The API returns roles matching both conditions. Each condition includes the PropertyName to search, the SearchValue to search for, an Equality Operator, a QuerySuffix and a SearchType for the relevant data type.

Search Examples

The below examples demonstrate how to use IncludedProperties, parameters, and conditions in columnsToSearch to query the API for a list of Management Roles matching the search conditions. Attributes returned for each record are set by the properties specified in IncludedProperties.

Get all High Security Management Roles that a specific person has been directly assigned to

Set the HighSecurity parameter to true, the PersonID parameter to the GUID of an EmpowerID Person and the ShowDirectPersonAssignmentsOnly parameter to true

{
    "IncludedProperties": [        
        "FriendlyName",
        "ManagementRoleTypeFriendlyName",
        "Description",
        "OwnerAssigneeFriendlyName",
        "IsHighSecurity",
        "RiskFactorTotal"   
    ],
    "Parameters": {
        "HighSecurity": true,
        "LinkedToApplicationID": null,
        "ManagementRoleDefinitionID": null,
        "ManagementRoleGUIDInherited": null,
        "NotAssignedToPersonID": null,
        "OrgZoneID": null,
        "OwnerPersonGUID": null,        
        "PersonID": null,
        "ShowDirectPersonAssignmentsOnly": 1,
        "ShowTRBACRoles": null,
        "textToSearch": "AdvancedSearch",
        "columnsToSearch": "%[[][[]%<Conditions/>",
        "pageLength": 10,
        "resourceTags": null,
        "start": 0,
        "totalCount": null
    }
}

Get all Management Roles owned by a specific person

Set the OwnerPersonGUID parameter to the GUID of an EmpowerID Person to return roles owned by that person.

{
    "IncludedProperties": [        
        "FriendlyName",
        "ManagementRoleTypeFriendlyName",
        "Description",
        "OwnerAssigneeFriendlyName",
        "IsHighSecurity",
        "RiskFactorTotal"   
    ],
    "Parameters": {
        "HighSecurity": null,
        "LinkedToApplicationID": null,
        "ManagementRoleDefinitionID": null,
        "ManagementRoleGUIDInherited": null,
        "NotAssignedToPersonID": null,
        "OrgZoneID": null,
        "OwnerPersonGUID": "d399765d-fcd7-45c9-913f-2b0c9e65f8b7",        
        "PersonID": null,
        "ShowDirectPersonAssignmentsOnly": 1,
        "ShowTRBACRoles": null,
        "textToSearch": "AdvancedSearch",
        "columnsToSearch": "%[[][[]%<Conditions/>",
        "pageLength": 10,
        "resourceTags": null,
        "start": 0,
        "totalCount": null
    }
}

Get all Management Roles by type

Use columnsToSearch to return "Feature Set (UI)" Management Roles. Note the PropertyName for the search condition is set to ManagementRoleTypeID, SearchValue is set to 7, the Operator is set to EqualTo and the SearchType is Int.

{
    "IncludedProperties": [        
        "FriendlyName",
        "ManagementRoleTypeFriendlyName",
        "Description",
        "OwnerAssigneeFriendlyName",
        "IsHighSecurity",
        "RiskFactorTotal"   
    ],
    "Parameters": {
        "HighSecurity": true,
        "LinkedToApplicationID": null,
        "ManagementRoleDefinitionID": null,
        "ManagementRoleGUIDInherited": null,
        "NotAssignedToPersonID": null,
        "OrgZoneID": null,
        "OwnerPersonGUID": null,        
        "PersonID": null,
        "ShowDirectPersonAssignmentsOnly": null,
        "ShowTRBACRoles": null,
        "textToSearch": null,
        "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"ManagementRoleTypeID\" SearchValue=\"7\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"Int\"/></Conditions>",
        "pageLength": 10,
        "resourceTags": null,
        "start": 0,
        "totalCount": null
    }
}

SearchTerms

Each identity object in the EmpowerID Identity Warehouse has a SearchTerms property with a specific set of search values that can be used to return all objects matching those values. For Management Roles, SearchTerms include the Name, FriendlyName, Email, DistinguishedName, and Description properties. When used, the API returns all roles where the specified search value finds a match in any of those properties. For example, if the search value is set to "Doc", the API would return all the following roles:

Any Management Role with a match in the name
Any Management Role with a match in the friendly name
Any Management Role with a match in the email address
Any Management Role with a match in the Distinguished Name
Any Management Role with a match in the description

The following examples illustrate how to use SearchTerms to return a subset of roles:

Get all Management Roles where the search value for SearchTerms is set to "help"

Use SearchTerms to return the Friendly Name, Management Role Type Friendly Name, Description and Risk Factor Total for Management Roles where the search value is set to "Help"

{    
    "IncludedProperties": [
        "FriendlyName",
        "ManagementRoleTypeFriendlyName",
        "Description",
        "RiskFactorTotal"      
    ],
    "Parameters": {
        "HighSecurity": true,
        "LinkedToApplicationID": null,
        "ManagementRoleDefinitionID": null,
        "ManagementRoleGUIDInherited": null,
        "NotAssignedToPersonID": null,
        "OrgZoneID": null,
        "OwnerPersonGUID": null,        
        "PersonID": null,
        "ShowDirectPersonAssignmentsOnly": null,
        "ShowTRBACRoles": null,
        "textToSearch": "AdvancedSearch",
        "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"Help\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/></Conditions>",
        "pageLength": 10,
        "resourceTags": null,
        "start": 0,
        "totalCount": null
    }
}

Get all Management Roles where the SearchValue of SearchTerms matches Description containing "Azure"

info

When using SearchTerms, results can be filtered to specific text within supported properties. For SearchTerms, the syntax for SearchValue is Property_TextToSearch. Include wildcards to broaden results. The example below returns roles where Description contains Azure.

{    
    "IncludedProperties": [
        "FriendlyName",
        "ManagementRoleTypeFriendlyName",
        "Description",
        "RiskFactorTotal"      
    ],
    "Parameters": {
        "HighSecurity": true,
        "LinkedToApplicationID": null,
        "ManagementRoleDefinitionID": null,
        "ManagementRoleGUIDInherited": null,
        "NotAssignedToPersonID": null,
        "OrgZoneID": null,
        "OwnerPersonGUID": null,        
        "PersonID": null,
        "ShowDirectPersonAssignmentsOnly": null,
        "ShowTRBACRoles": null,
        "textToSearch": "AdvancedSearch",
        "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"Description_*Azure\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/></Conditions>",
        "pageLength": 10,
        "resourceTags": null,
        "start": 0,
        "totalCount": null
    }
}

Sample Responses

200 OK
Error

{
    "Tags": [],
    "Data": [
        {
            "FriendlyName": "All Access - Sales",
            "ManagementRoleTypeFriendlyName": "Feature Set (UI)",
            "Description": "Provides full access to the Sales application UI",
            "OwnerAssigneeFriendlyName": "ROLE_Owners_Sales",
            "IsHighSecurity": false,
            "RiskFactorTotal": 12.5
        }
    ]
}

{
    "Success": false,
    "Error": {
        "Code": 400,
        "Message": "Invalid request: columnsToSearch is required"
    }
}

POST /GetAllSearchAdvanced​

URL​

Header Key/Value Pairs​

Request Body​

Included Properties​

Body Parameters​

columnsToSearch​

Remarks​

Search Examples​

Get all High Security Management Roles that a specific person has been directly assigned to​

Get all Management Roles owned by a specific person​

Get all Management Roles by type​

SearchTerms​

Get all Management Roles where the search value for SearchTerms is set to "help"​

Get all Management Roles where the SearchValue of SearchTerms matches Description containing "Azure"​

Sample Responses​