Use the get operation to get information about a role.

Request Packet Structure

A request XML packet getting information about specified roles includes the get operation node:

<packet>
<role>
   <get>
   ...
   </get>
</role>
</packet>

The get node is nested within the RoleGetInput type (role.xsd). This node has the following graphics representation:

• filter, required

  It specifies the filtering rule to match roles the information on which will be provided. Data type: RoleSelectionFilter (role.xsd). To see the structure of this node, proceed to section Available Filters.

• owner-guid, optional

  It specifies the GUID of a role owner (a customer or the Administrator). If you do not specify this node, the role owner will be the request packet sender. Data type: string. For details on how to get a customer GUID, see the Getting Information About Client Accounts section.

Response Packet Structure

The get node of the response packet is structured as follows:

• result, optional

  It wraps the result of the requested operation. It can be missing if some error occurs before the validation starts. Data type: resultType (common.xsd).

• status, required

  It returns the execution status of the operation. Data type: string. Allowed values: ok | error.

• errcode, optional

  It is used to return the error code when the operation fails. Data type: unsignedInt.

• errtext, optional

  It contains the error message if the operation fails. Data type: string.

• filter-id, optional

  If supported, it is always present and contains the filtering rule parameter specified in a request packet. Data type: anySimple.

• id, optional

  The node is missing if the request packet fails before the validation on the server side. If present, it returns the ID of the retrieved role. Data type: integer.

• data, optional

  It contains a collection of requested role settings if the operation succeeds. Data type: RoleGetOutputData (role.xsd).

The data node of the response get packet is structured as follows:

• name, required

  It defines a role name. Data type: string.

• owner-guid, required

  It specifies the GUID of a role owner (a customer or the Administrator). Data type: string.

• is-built-in, required

  If a role is the Admin or Accountant, the node value is true. Otherwise, it is false. Data type: boolean.

• permissions, required

  It specifies a collection of permissions granted to a role. Data type: RolePermissions (role.xsd) . See the structure of this node in the Permissions Granted to Roles section.

Samples

A request packet to get the information about the role with ID 1 looks as follows:

<packet version="1.6.3.0">
<role>
   <get>
      <filter>
        <id>1</id>
      </filter>
   </get>
</role>
</packet>

A response packet that includes the information about the role with ID 57 (reduced) can look as follows:

<packet version="1.6.3.0">
  <role>
    <get>
      <result>
        <status>ok</status>
        <filter-id>1</filter-id>
        <id>1</id>
        <data>
          <name>Admin</name>
          <owner-guid>58bb9092-4c8b-4110-ba3d-c40bdad3b178</owner-guid>
          <is-build-in>true</is-build-in>
          <permissions>
            <permission>
              <name>userManagement</name>
              <value>true</value>
            </permission>
...
          </permissions>
        </data>
      </result>
    </get>
  </role>
</packet>