Getting Information About a Role

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.

Important: When creating request packets, put nodes and elements in the order they follow in the packet structure.

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>