Composing XML Commands

A reader of this guide must be familiar with XML (Extensible Markup Language) and XML Schema. More information on XML and Schema specification can be found at the World Wide Web Consortium site.

A usual way for any Plesk Expand operator to receive input parameters is to get an XML package on its standard input. The operator's result is also formatted as an XML packet which can be obtained on its standard output. These XML packets are rigidly structured and this structure is described in XML Schema files (*.xsd). You can find the Schema specification in the project documentation. The Schema usage rules are outlined in Chapter 4. Reference Materials in section Obtaining Operator Usage Info.

Hereinafter we will use standard XML idioms such as nodes, child nodes, parent nodes, sibling nodes (those which have the same parent). We will think of XML as a tree document structure. Its root is the root node of an XML packet. Descending a tree means getting child nodes, ascending means returning back to parents.

Plesk Expand uses a simplified subset of XML. The following restrictions are imposed on all Plesk Expand XML packets:

Node attributes cannot be used (except for the root node, where a single attribute 'version' is mandatory).
A node can contain only one text child node, in this case no other child nodes can be present in that node. Such nodes are called here 'terminal'.
Every packet has one root node called 'packet'. Though the 'packet' node itself doesn't limit the number of its children.

Now, let's try and open the Schema for 'exp_plesk_domain' input specification located in the /usr/local/expand/share/expand/protocol/plesk/domain_input.xsd file of Plesk Expand installation (to learn how to find the right .xsd file, see Obtaining Operator Usage Info.

If we wish to delete a domain, we need to expand the 'packet' node, and all the children for the 'del' node (as you can notice, the 'del' node annotation manifests the purpose of the command, i.e. to delete something). Below you can find the description of element <del> in the XSD:

<xs:element name="del">

<xs:annotation>

<xs:documentation>Delete domain(s) from a database and a related Plesk server</xs:documentation>

</xs:annotation>

<xs:complexType>

<xs:sequence>

<xs:element name="filter" type="filterType">

<xs:annotation>

<xs:documentation>Filter client accounts to be deleted</xs:documentation>

</xs:annotation>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

As you can see, the 'del' node can contain the only one node named 'filter'. Below you can see the XSD description of element <filter>:

<xs:complexType name="filterRefrType">

<xs:annotation>

<xs:documentation>Filter the list of domains to be refreshed</xs:documentation>

</xs:annotation>

<xs:choice>

<xs:element name="server_id" type="id_type" minOccurs="0" maxOccurs="unbounded">

<xs:annotation>

<xs:documentation>Plesk server ID</xs:documentation>

</xs:annotation>

</xs:element>

<xs:element name="client_id" minOccurs="0" maxOccurs="unbounded">

<xs:annotation>

<xs:documentation>The ID of the client the domain owner belongs to</xs:documentation>

</xs:annotation>

</xs:element>

<xs:element name="id" type="id_type" minOccurs="0" maxOccurs="unbounded">

<xs:annotation>

<xs:documentation>Domain ID</xs:documentation>

</xs:annotation>

</xs:element>

<xs:element name="plesk_domain" minOccurs="0" maxOccurs="unbounded">

<xs:annotation>

<xs:documentation>Plesk domain</xs:documentation>

<xs:documentation>Plesk domain ID</xs:documentation>

</xs:annotation>

<xs:complexType>

<xs:sequence>

<xs:element name="server_id" type="id_type">

<xs:annotation>

<xs:documentation>Server ID</xs:documentation>

</xs:annotation>

</xs:element>

<xs:element name="domain_name" type="string">

<xs:annotation>

<xs:documentation>Plesk domain name</xs:documentation>

</xs:annotation>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:choice>

</xs:complexType>

However, the 'filter' node can have 3 types of children grouped by the 'choice' type – this means that only children of the same type can be under the 'filter' node at the same time: either 'id', or 'client_id', or 'server_id' Thus, we need a separate packet for each child mentioned. In this case, the number of the 'filter' node children is unlimited (from zero to infinity). So, in accordance to the XML Schema we can write a packet:

<del>

</filter>

</del>

</packet>

This packet commands the domain operator to delete the domains with IDs 1, 3 and 7. The next packet is valid according to the XML Schema too:

<del>

</del>

</packet>

This packet means we want to delete ALL of the domains Plesk Expand knows. This is a bad practice to use such packets, usually you need to specify which kind of domains you need to delete.

In addition, the schema allows deleting groups of domains:

<del>

<client_id>1</client_id>

</filter>

</del>

</packet>

Using this packet you can delete all domains owned by a client with ID 1 in Plesk Expand.

Plesk Expand operator output is specified by an XML schema too. An operator will list all the operated objects in the output packet with separate result for each object. The result at last contains the status of an object, both the error message and the code on error occurred, and also a separate ID, in case an object is unique, or a group ID.

Below are several examples of the XML output:

1. Domain was created successfully:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>

<packet version="2.0.1.2">

<del>

<result>

<status>ok</status>

<id>2</id>

<client_id>0</client_id>

<server_id>1</server_id>

</result>

</del>

</packet><?xml version="1.0" encoding="UTF-8" standalone="no" ?>

<del>

<status>error</status>

<errtext>Specified domain ID not found in database</errtext>

</result>

</del>

</packet>

2. Domain creation failed:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>

<del>

<status>error</status>

<errtext>Specified domain ID not found in database</errtext>

</result>

</del>

</packet>

Error: wrong domain ID.