Exporting Data into XML Files

Below we describe command line tools for exporting the billing data from the Parallels Business Automation - Standard database into XML file. Traffic classes and traffic statistics can be imported only.

Note: Parallels Business Automation - Standard provides web-based tools for XML data import/export (Import-Export Manager in Provider Control Center). If you would like to, you can use this tool (please refer to the Parallels Business Automation - Standard Provider's guide fo more information or go to Provider Control Center and click Help link for detailed HTML help).

How Export Script Works

For the Export script to fetch the data, the indication of data type is necessary, so in the command line you must use the relevant key (described below) and either explicitly indicate the type of data to be exported or indicate the name of a special file called filter that includes information about the type of data to export and, as its name says, allows filtering a particular type of data (accounts, documents, etc.) down to a type, ID or ID range, and other parameters, depending on a type of data you are going to export.

If you do not specify the type of data to export, the Export script will not collect the data due to the input parameters incompleteness and just print you the help page.

The structure of a filter file is described later in this topic. However , if you are not sure, which tags to use, you can train using web-based tools.

When you export data using the web-based interface, filters are created automatically, while you pass a simple wizard that requires selecting the type of data and allows further filtering. In this case, the XML filter is created in accordance with your settings and the corresponding XML structure is added to the beginning of the resulting XML file. You can pass the wizard several times and take a look, what XML filters are produced by your selection. Later you can copy the filter block from an XML file, save it in a separate file, and this will be the filter you can use with the Export script in command line.

To train with filter files using the web interface, log in to the Provider Control Center, go to the Migration Director - Import-Export Manager and select Export Data from the Import-Export Manager submenu. You will be offered to select the type of data to export (in our example, Documents):

Exporting Data - Select Data Type

After you click the Next button you will be offered to filter the selected data type:

Exporting Data - Filter Selected Data Type

For example, you have filtered documents by types (Online Payments and Offline Payments) and then set the additional filter to Export documents within ID range from 1 to 30.

After this, you can finish the wizard and save the resulting XML to your local computer. When you open this XML, you will see that the first block of the XML file inside the <data> tag is <filters>:

<objects_name>documents</objects_name>

<property_name>type</property_name>

<where>

</where>

</filter>

<property_name>id</property_name>

<where>

</where>

</filter>

</filters>

Copy this block into a separate file, add the string

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

to the beginning and save the file. You have a ready to use filter with the functionality you are clearly understand:

The <objects_name> tag holds the information about the type of objects you have selected on the first screen of the export wizard (Documents, in our example), the <filter> tags hold the information about the further filtering you have set on the second screen of the wizard.
The first <filter> tag holds the information about the type of documents to export (in our example, online payments - PO and offline payments - PF). This selection is required, without this basic filter the filter file will be not valid.
The second filter tag is optional and have appeared because in our example, the option button in the Filter part of the form was set not to Export all documents, but to the documents ID range, which have resulted in creation of the additional <filter> block containing, in its turn, the property_name (id) and the IDs range specified using the <where> tag. Note that if the additional filter is set to All, i.e., you want to export all objects of the selected type, the second <filter> is omitted.

The Export script reads a filters file, exports data, converts it in XML format, saves and compresses (GZip) an XML file.

After the Parallels Business Automation - Standard installation, the export script location on your Management Node is

/usr/sbin/hspc-export.pl.

By default, the script places an XML file in the current directory. Errors, if any, are put in STDERR.

Command Line Syntax For Export Script

/usr/sbin/hspc-export.pl -f filters.xml

where filters.xml must be replaced with the actual name of a filter file, and -f is a key.

/usr/sbin/hspc-export.pl -all accounts

where -all is the key and accounts is the data type specified explicitly.

Export Script Keys

-h see help page

-f file with filters

-all export all (parameters can be one of accounts, or documents, or subscriptions, or hosting plans)

If the filters.xml file is not defined, filters are got from STDIN.

Filter File Structure

When composing a filter, please carefully follow the filter file structure diagram:

Export Script Filter File Diagram

Thus, the filter file structure is always looks like follows:

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

<objects_name> OBJECT </objects_name>

<property_name> PROPERTY </property_name>

<where>

</where>

</filter>

...

</filters>

Tag	Description
<filters>	The single tag that opens and closes the filter.
<objects_name>	The tag containing the information about the kind of objects to export: accounts,documents, subscriptions, or hosting plans. There can be only one kind of object specified in one filter file The kind of object inside the objects_name tag must be specified exactly as follows: `account` to filter accounts `document` to filter documents `subscription` to filter subscriptions `hp` to filter hosting plans.
<filter>	At least one filter tag must be in the filter file. This tag holds the information about the type of objects to export. Without the information about objects type the filter file is not valid. In general a filter file can contain two filter tags: The filter containing information about type of objects to export (type of documents, accounts, subscriptions, or hosting plans). The additional and optional filter that narrows the set of objects to be exported down to an ID range or creation date, or other property, depending on the type of objects.
<property_name>	The tag nested into any <filter> tag. The <property_name> tag specifies the filter itself: For the first and required <filter> tag, the <property_name> tag always contains the `type` word, which means that below in the <where> tag the type(s) of objects to be exported must be specified. For the second and optional <filter> tag, the <property_name> tag contains the type of additional filter: `id` to export objects within the pre-defined ID range or to export the selected objects by their IDs; `date` to export objects created between particular dates; `start_date` - for subscriptions only, to export subscriptions with particular subscription period start date; `end_date` - for subscriptions only, to export subscriptions with particular subscription period end date.
<where>	The tag that must be nested into any <filter> tag , below the <property_name> tag. The <where> tag contains a particular filter settings specified either in the <in> tag (if objects are filtered by IDs) or using the <start> <end> tags (if objects are filtered by creation date or ID range) nested into the <where> tag.
<in>	The tag nested into the <where> tag and containing the filter settings. The <in> tag is used in all cases except for filtering subscriptions by subscription period start or end date. In the latter case, the <date> For the first and required <filter> tag, the <in> tag contains the information about type(s) of object(s) to be exported. The object types must be specified in the form of special abbreviations, exactly as this written below, several object types must be specified in one string, divided by comma: For documents: `IN` - for invoices, `PO` for online payments, `PF` for offline payments, `CA` for credit adjustments, `DA` for debit adjustments, `CI` for credit invoices. For accounts: `customer` - for customer accounts, `reseller` - for reseller accounts, `res_customers` - for accounts of your resellers' customers. For hosting plans: `VE` - for Virtuozzo Container, `HN` - for Dedicated server, `HNVZ` - for Dedicated Parallels Virtuozzo Containers server, `MISC` - for Miscellaneous plans, `DM` - for Domain Registration, `PLSRV` - for Dedicated Plesk server, `PLCLT` - for Plesk Client, `PLDM` - for Plesk domain, `VEPLHN` - for Plesk Server in Virtuozzo Container plans. For subscriptions' types abbreviations are the same as for corresponding hosting plans. For the second and optional <filter> tag, the <in> tag contains particular filtering data: Object ID or IDs (in a string, divided by comma, for example, if filtering is by hosting plans or subscriptions selection).
<start> <end>	These tags are used instead of the <in> tag if filtering is by object ID range (first ID in the range is specified in the <start> tag, last ID in the range is specified in the <end> tag) or a subscription period start or end date (the time frame of subscription periods start or end date is specified similarly, using the <start> and <end> tags). In the latter case, the date format is year-month-day time, like YYYY-MM-DD hh:mm:ss (YYYY - year, MM - month, DD - date, hh - hour, mm - minute, ss - second)

Please send us your feedback on this help page