Changing Role Settings

Use the set operation to change role settings.

Request Packet Structure

A request XML packet that changes role settings should include the set operation node:

<packet>
<role>
   <set>
   ...
   </set>
</role>
</packet>

Note: Built-in roles are not modifiable.

The set node is of type RoleSetInput (site.xsd). This node has the following graphics representation:

• filter, required

  It specifies a filtering rule to match roles. 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.

• values, required

  It specifies the settings to change. Data type: RoleValuesInput (role.xsd).

• permissions, optional

  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.

• new-name, optional

  It defines a new role name. Data type: string.

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

Response Packet Structure

The set 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: resultFilterType (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 if the operation fails. Data type: unsignedInt.

• errtext, optional

  Can be used to return an error message if the operation fails. Data type: string.

• filter-id, optional

  If supported, it is always present and used to return the filtering rule given in the request packet. If all roles are matched, this node contains the ID of a role. Data type: anySimple.

• id, optional

  It is missing if the request packet fails before the validation on the server side. If the node is present, it identifies the role whose settings are updated. Data type: integer.

Samples

The following packet changes settings of a role of the customer with GUID ff5e2685-6f44-490f-bdc8-9a46fb2f0308:

<packet version="1.6.3.0">
  <role>
    <set>
    <filter>
       <all/>
    </filter>
    <owner-guid>ff5e2685-6f44-490f-bdc8-9a46fb2f0308</owner-guid>
      <values>
      <permissions>
         <permission>
           <name>applicationsManagement</name>
           <value>true</value>
         </permission>
      </permissions>
     </values>
    </set>
  </role>
</packet>

A positive response from the server can look as follows:

<packet version="1.6.3.0">
  <role>
    <set>
      <result>
        <status>ok</status>
        <filter-id>34</filter-id>
        <id>34</id>
      </result>
    </set>
  </role>
</packet>