/
Search for Groups

Search for Groups

Post /GetAllSearchAdvanced

Send a POST request to the GetAllSearchAdvanced() method on the GroupView object to return information about one or more groups. The information included in the response depends on the range of group 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/GroupView/GetAllSearchAdvanced

Header Key/Value Pairs

Key

Value

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

Included Properties

Use IncludedProperties to return one or more group properties.

Body Parameters

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

AccountStoreID int Return all groups with a matching account store ID Set to null to ignore Required SecurityBoundaryID int Set to the ID of the Security Boundary to return groups with a matching Security Boundary ID Set to null to ignore Required

SecurityBoundaryTypeID

int

  • Set to the ID of the Security Boundary Type to return groups with a matching Security Boundary Type ID

  • Set to null to ignore

  • Required

GroupTypeID int Return all groups with a matching Group Type ID Set to null to ignore Required GroupUsageTypeID int Return groups with a matching Group Usage Type ID Set to null to ignore Required ResourceTypeID int Return groups with a matching Resource Type ID Set to null to ignore Required IsEmpty Boolean Return empty groups Set to null to ignore Required IsMailEnabled Boolean Return mail-enabled groups Set to null to ignore Required IsHighSecurityGroup Boolean Return groups marked as high security Set to null to ignore Required HideInEmpowerID Boolean Return groups hidden in EmpowerID Set to null to ingore Required OrgZoneID int Return groups with a matching OrgZone ID Set to null to ignore Required AccountStoreUsageTypeID int Return groups with a matching Account Store Usage Type ID Set to null to ignore Required ITEnvironmentTypeID Boolean Return groups with a matching IT Environment Type ID Set to null to ignore Required EligibilityAssigneeID GUID Return groups with a matching Eligibillity Assignee ID Set to null to ignore Required EligibilityTypeID int Return groups with a matching Eligibility Type ID Set to null to ignore Required RbacAssignedToAssigneeID GUID Return groups with a matching Rbac Assigned to Assignee ID Set to null to ignore Required TCode Set to null to ignore Required IsAssignable Boolean Return groups marked as assignable Set to null to ignore Required ReferencePersonID GUID Return groups where the person identified by the ReferencePersonID is a member Set to null to ignore Required OwnerPersonGUID GUID Return groups where the person identified by the GUID is the owner Set to null to ignore Required AzGlobalFunctions String Return groups with the referenced global functions Set to null to ignore Required ProtectedApplicationResourceID GUID Return groups with the referenced Protected Application Resource ID Set to null to ignore Required AccountMemberID GUID Return groups where the specified ID is a member Set to null to ignore Required IsAccountIDMember Boolean Return groups where the specified ID is a member 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 groups to return in the list of groups Required resourceTags String Return groups with a matching resource tag Required start int Specifies the first group in the list of groups returned by the API; set to 0 to return the first group Required textToSearch string Set to AdvancedSearch Required totalCount int This is an output parameters that returns the number of groups matching the search conditions and parameter values. Required

columnsToSearch

The columnsToSearch body parameter is used to return groups meeting one or more conditions. Each condition specifies a property with a specific value to search. For example, to return a list of groups where the FriendlyName field contains "NH30" and the Notes field contains "For Internal Audit Use", the value for columnsToSearch would be set to that shown below.

"%[[][[]%<Conditions><Condition PropertyName=\"FriendlyName\" SearchValue=\"NH30\" Operator=\"EqualTo\" QuerySuffix=\" AND \" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/><Condition PropertyName=\"Notes\" SearchValue=\"For Internal Audit Use\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"1\" SearchType=\"String\"/></Conditions>"

Remarks

In the above example, columnsToSearch contains two search conditions. The API returns accounts 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. Each of these must be set correctly or an error will occur.

Search Examples

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

Get all high security groups that a specific person belongs to

Set the ReferencePersonID parameter to the GUID of an EmpowerID Person and the IsHighSecurityGroup parameter to 1 to return a list of high security groups where the reference person has a linked user account.

{ "IncludedProperties": [ "LogonName", "NetBiosName", "FriendlyName", "AllowJoinRequests", "IsHighSecurityGroup", "RiskFactorTotal", "DistinguishedName", "ResourceID", "GroupID", "ResourceGUID", "ValidUntil", ], "Parameters": { "AccountStoreID": null, "SecurityBoundaryID": null, "SecurityBoundaryTypeID": null, "GroupTypeID": null, "GroupUsageTypeID": null, "ResourceTypeID": null, "IsEmpty": null, "IsMailEnabled": null, "IsHighSecurityGroup": 1, "HideInEmpowerID": null, "OrgZoneID": null, "AccountStoreUsageTypeID": null, "ITEnvironmentTypeID": null, "EligibilityAssigneeID": null, "EligibilityTypeID": null, "RbacAssignedToAssigneeID": null, "TCode": null, "IsAssignable": null, "ReferencePersonID": "4e98a3bd-ac98-401a-ac73-042332d73bd9", "OwnerPersonGUID": null, "AzGlobalFunctions": null, "ProtectedApplicationResourceID": null, "AccountMemberID": null, "IsAccountIDMember": null, "textToSearch": null, "columnsToSearch": "%[[][[]%<Conditions/>", "pageLength": 10, "resourceTags": null, "start": 0, "totalCount": null } }

 

Get all groups belonging to a specified account store

Set the AccountStoreID parameter to the ID of an account store to return groups belonging to that account store.

{ "IncludedProperties": [ "LogonName", "NetBiosName", "FriendlyName", "AllowJoinRequests", "IsHighSecurityGroup", "RiskFactorTotal", "DistinguishedName", "ResourceID", "GroupID", "ResourceGUID", "ValidUntil", ], "Parameters": { "AccountStoreID": 2096, "SecurityBoundaryID": null, "SecurityBoundaryTypeID": null, "GroupTypeID": null, "GroupUsageTypeID": null, "ResourceTypeID": null, "IsEmpty": null, "IsMailEnabled": null, "IsHighSecurityGroup": null, "HideInEmpowerID": null, "OrgZoneID": null, "AccountStoreUsageTypeID": null, "ITEnvironmentTypeID": null, "EligibilityAssigneeID": null, "EligibilityTypeID": null, "RbacAssignedToAssigneeID": null, "TCode": null, "IsAssignable": null, "ReferencePersonID": null, "OwnerPersonGUID": null, "AzGlobalFunctions": null, "ProtectedApplicationResourceID": null, "AccountMemberID": null, "IsAccountIDMember": null, "textToSearch": "AdvancedSearch", "columnsToSearch": "%[[][[]%<Conditions />", "pageLength": 25, "resourceTags": null, "start": 0, "totalCount": null } }

 

Get all mail-enabled groups

Use columnsToSearch to return mail-enabled groups. Note the PropertyName for the search condition is set to IsMailEnabled, SearchValue is set to True, the Operator is set to EqualTo and the SearchType is Boolean.

{ "IncludedProperties": [ "LogonName", "NetBiosName", "FriendlyName", "AccountOrganizationStatusFriendlyName", "AccountUsageTypeFriendlyName", "ResourceID", "AccountID", "Name", "Description", "CreatedDate", "ExpiresOn", "AccountStoreFriendlyName", ],     "Parameters": {         "AccountStoreID": null, "SecurityBoundaryID": null, "SecurityBoundaryTypeID": null,          "AccountTypeID": null, "ShowSystemAccountsOnly": null, "ShowSystemBuiltInAccountsOnly": null, "AccountUsageTypeID": null, "IsOrphan": null, "Disabled": null, "LockedOut": null, "NeverLoggedInOnly": null, "HideInEmpowerID": null, "OrgZoneID": null, "PersonID": null, "ManagerPersonID": null, "MemberOfGroupID": null, "textToSearch":"AdvancedSearch", "pageLength": 50, "resourceTags": null, "start": 0, "totalCount": null,         "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName="IsMailEnabled" SearchValue="true" Operator="EqualTo" QuerySuffix="" StartGroupString="" EndGroupString="" Index="0" SearchType="Boolean"/></Conditions>"     } }

 

Get all group memberships for a specific user account

Set the AccountMemberID parameter to the GUID of a specific user account and the IsAccountIDMember parameter to true to return groups where that account is a member.

{ "IncludedProperties": [ "LogonName", "NetBiosName", "FriendlyName", "AccountOrganizationStatusFriendlyName", "AccountUsageTypeFriendlyName", "ResourceID", "AccountID", "Name", "Description", "CreatedDate", "ExpiresOn", "AccountStoreFriendlyName", ],      "Parameters": { "AccountStoreID": null, "SecurityBoundaryID": null, "SecurityBoundaryTypeID": null, "GroupTypeID": null, "GroupUsageTypeID": null, "ResourceTypeID": null, "IsEmpty": null, "IsMailEnabled": null, "IsHighSecurityGroup": null, "HideInEmpowerID": null, "OrgZoneID": null, "AccountStoreUsageTypeID": null, "ITEnvironmentTypeID": null, "EligibilityAssigneeID": null, "EligibilityTypeID": null, "RbacAssignedToAssigneeID": null, "TCode": null, "IsAssignable": null, "ReferencePersonID": null, "OwnerPersonGUID": null, "AzGlobalFunctions": null, "ProtectedApplicationResourceID": null, "AccountMemberID": "0EC3DE4D-DDD7-4B2E-A104-52C1ECE422F8", "IsAccountIDMember": true, "textToSearch": "AdvancedSearch", "columnsToSearch": "%[[][[]%<Conditions />", "pageLength": 25, "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 used to return all objects matching those values. For groups, SearchTerms encompass the Name, FriendlyName, Email, EmpowerIDName, EmpowerIDFriendlyName, LogonName, NetBiosName, FQN, DistinguishedName, and Description properties. When used, the API returns all groups 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 groups

  • Any group with a match in the name

  • Any group with a match in the friendly name

  • Any group with a match in the email address

  • Any group with a match in the EmpowerID name

  • Any group with a match in the EmpowerID friendly name

  • Any group with a match in the logon name

  • Any group with a match in the Net BIOS name

  • Any group with a match in the FQN

  • Any group with a match in the Distinguished Name

  • Any group with a match in the description

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

Get all groups with a SearchTerm of “SAP”

{         "IncludedProperties": [         "LogonName", "NetBiosName", "FriendlyName", "Description", "GroupTypeName", "DistinguishedName", "GroupID"           ],      "Parameters": {         "AccountStoreID": null, "SecurityBoundaryID": null, "SecurityBoundaryTypeID": null, "GroupTypeID": null, "GroupUsageTypeID": null, "ResourceTypeID": null, "IsEmpty": null, "IsMailEnabled": null, "IsHighSecurityGroup": null, "HideInEmpowerID": null, "OrgZoneID": null, "AccountStoreUsageTypeID": null, "ITEnvironmentTypeID": null, "EligibilityAssigneeID": null, "EligibilityTypeID": null, "RbacAssignedToAssigneeID": null, "TCode": null, "IsAssignable": null, "ReferencePersonID": null, "OwnerPersonGUID": null, "AzGlobalFunctions": null, "ProtectedApplicationResourceID": null, "AccountMemberID": null, "IsAccountIDMember": null, "textToSearch": "AdvancedSearch",         "columnsToSearch":"%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"SAP\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/></Conditions>"     } }

 

Get all groups where the SearchValue of the SearchTerm is an email address containing "onmicrosoft"

{     "IncludedProperties": [         "LogonName", "NetBiosName", "FriendlyName", "Description", "Email", "GroupTypeName", "DistinguishedName", "GroupID"           ], "Parameters": {         "AccountStoreID": null, "SecurityBoundaryID": null, "SecurityBoundaryTypeID": null, "GroupTypeID": null, "GroupUsageTypeID": null, "ResourceTypeID": null, "IsEmpty": null, "IsMailEnabled": null, "IsHighSecurityGroup": null, "HideInEmpowerID": null, "OrgZoneID": null, "AccountStoreUsageTypeID": null, "ITEnvironmentTypeID": null, "EligibilityAssigneeID": null, "EligibilityTypeID": null, "RbacAssignedToAssigneeID": null, "TCode": null, "IsAssignable": null, "ReferencePersonID": null, "OwnerPersonGUID": null, "AzGlobalFunctions": null, "ProtectedApplicationResourceID": null, "AccountMemberID": null, "IsAccountIDMember": null, "textToSearch": "AdvancedSearch", "columnsToSearch": "%[[][[]%<Conditions><Condition PropertyName=\"SearchTerms\" SearchValue=\"Email_*microsoft\" Operator=\"EqualTo\" QuerySuffix=\"\" StartGroupString=\"\" EndGroupString=\"\" Index=\"0\" SearchType=\"String\"/></Conditions>" } }

Sample Responses