GetGroups

Description

This services returns one or more existing groups.

Arguments

Argument	Type	Description
auth (optional)	Auth	The Auth type supplies credentials and optionally, a host name for licensing. The userId and password can be specified with HTTP BASIC or WS-SECURITY instead.
searchByName	string	Used to specify the name of the group as a search parameter.
group (required)	GroupIdentifier	The group or groups that you wish to return.
options	MultipleOptions	Holds name value pairing for future elements and enumeration to determine if the service should stop on failure and send an error message or continue processing.

Response

GroupHolder is returned. The GroupHolder response contains the GroupIdentifier and additional information about the group. For more specific information, see GroupHolder.

Usage

The GetGroups call is useful when you need data about a group. The GetGroups call retrieves data for a group as it exists in the TS_GROUPS table of the database. To retrieve information for a given user account, use GetUsers.

Use the following arguments to determine which groups are returned in the response:

searchByName – Enables you to enter a single string to return groups. For example, if you enter Engineer as the searchByName value, groups with following display names are returned: Engineers, Engineering, EngineerExperts. You can not enter multiple strings.
Note: To return all user records in the database, do not provide a value for searchByName, and do not enter specific GroupIdentifiers in the group argument. If you have a large number of groups in your database, consider limiting the return data using one or more arguments.
group – Enables you to specify one or more specific groups to be returned. If you want to return multiple groups, you must specify each desired group by providing the GroupIdentifier in a list of multiple group arguments. The group argument takes precedence over the searchByName argument.

Faults

Invalid database pointer.
The group ID is not valid.
The user lacks sufficient permission.

XML

The following XML is a snippet of the payload this is sent with GetGroups.

<urn:GetGroups>
   <urn:auth>
      <urn:userId>admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:searchByName></urn:searchByName>
   <urn:group>
      <urn:displayName>CR Submitters</urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
   </urn:group>
   <urn:group>
      <urn:displayName>IDM Team</urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
   </urn:group>
   <urn:options>
      <urn:multiOption></urn:multiOption>
   </urn:options>
</urn:GetGroups>

In this example, only group names that contain the string "IDM" will be returned:

<urn:GetGroups>
   <urn:auth>
      <urn:userId>admin</urn:userId>
      <urn:password></urn:password>
      <urn:hostname></urn:hostname>
      <urn:loginAsUserId></urn:loginAsUserId>
   </urn:auth>
   <urn:searchByName>IDM</urn:searchByName>
   <urn:group>
      <urn:displayName></urn:displayName>
      <urn:id></urn:id>
      <urn:uuid></urn:uuid>
   </urn:group>
   <urn:options>
      <urn:multiOption></urn:multiOption>
   </urn:options>
</urn:GetGroups>