Starting from 1.5.0.0, XML API supports descriptors - containers that store information about properties of Plesk business logic objects. The basic goal of descriptors is to make object properties independent of a protocol version.

An Example of Using Descriptors

For example, you need to add the DNS zone management permission to a subscription with ID 11. This setting is accomplished by the following packet:

<packet>
<webspace>
<set>
   <filter>
      <id>11</id>
   </filter>
   <values>
        <permissions>
           <permission>
                  <name>manage_dns</name>
               <value>true</value>
           </permission>
        </permissions>
   </values>
</set>
</customer>
</packet>

To know that you should provide exactly manage_dns, it is mandatory first to get the permissions descriptor of the webspace operator by the following packet:

<packet>
<webspace>
   <get-permission-descriptor>
   <filter/>
   </get-permission-descriptor>
</webspace>
</packet>

Among other permissions in the response packet, you will see:

<property>
  <name>manage_dns</name>
  <type>boolean</type>
  <default-value>false</default-value>
  <writable-by>admin</writable-by>
  <writable-by>reseller</writable-by>
  <label>cl_perm__manage_dns</label>
  <extension>
    <level>reseller</level>
    <level>domain</level>
  </extension>
</property>

The data you received is the description of the permission we need.

This example shows that even if the type of a certain permission changes or the permission becomes unavailable throughout time, you can always retrieve the actual list of permissions and find all the information you need to change the permission you want by using appropriate descriptors.

Hint: If you are not sure that a particular property is the one you need, find its label in messages_en-US.php, the file which stores user interface messages. In case of the DNS zone management permission, we will see:

'cl_perm__manage_dns' => "DNS zone management",

The messages file path is as follows:

• On Linux: /usr/local/psa/admin/plib/locales/en-US/messages_en-US.php
• On Windows: %plesk_dir%admin\plib\locales\en-us\

Descriptor Types

There are two types of descriptors: object descriptors and property descriptors. Property descriptor is comprised of parameters that specify an object property. There can be only one property descriptor for each property. Every object descriptor is composed of a set of property descriptors and correlation between properties of the object.

All descriptors can be divided into the following groups:

• Server-level descriptors
• Plan-level descriptors
• Subscription-level descriptors (including reseller accounts descriptors)

On the server level one can retrieve general information on the availability and possible limitations of specified services. They are not linked to any specific object.

The plan-level descriptors contain data of a particular plan. The subscription-level descriptors contain information about specific subscriptions belonging to a specified customer account. That is why descriptors are changed if Plesk objects are changed. For instance, if Perl support is not installed, it will be unavailable in hosting settings. But if administrator installs and configures it, the hosting settings descriptor will be changed, and Perl in hosting settings will be editable.

For more information on descriptors representation in the protocol, refer to Representation of Object Descriptors.