Creating User Migration XMLs Outside H-Sphere

This document explains how to format user data for migration from third party hosting systems into H-Sphere. Use it to:
- migrate direct end users, resellers, and resellers' end users;
- migrate only direct end users if you don't have resellers.

• Files
• User Data Format
• XML Validation

Files

Create the following three files:
- resellers.dtd - data type definitions for resellers (example | explanation)
- users.dtd - data type definitions for end users (example | explanation)
- migrate_resellers.xml - XML file containing both reseller and end user data (example)

You may have data for hundreds and thousands of users in the xml file.

Alternatively, You may define DTD definitions directly within the XML file:

	<?xml version="1.0" encoding="utf-8"?>
	<!DOCTYPE users [ 
	    // DTD rules as in users.dtd
	    . . .
	]>
	<users>
	. . .

We recommend defining DTD externally, using our latest DTD:
<DOCTYPE users SYSTEM "users.dtd">

Warning: If you make a mistake in DTD definitions, migration may fail.

User Data Format

Data formatting must comply with the following requirements:

• Resellers: End users that are hosted by resellers must be enclosed in corresponding 'reseller' tags. Users that are hosted by master admin must be enclosed in the 'resellers' tag.
  If you don't have any resellers at all, omit the lines containing information about resellers starting from <reseller login="..." and up to </zone>. As a result, your xml file will have simpler structure:
  

          <?xml version="1.0" encoding="utf-8"?>
          <!DOCTYPE resellers SYSTEM "resellers.dtd">
            <resellers>
              <users>
                ......
              </users>
            </resellers>
  

• Direct End Users: To create a user under a particular reseller, put reseller's login name in the reseller attribute:
  <user login="newuser" password="passw" reseller="somereseller">
  This is the login to reseller's account in the master admin CP.
  If a user belongs directly to master admin, there is no need for the reseller attribute in the user tag:
  <user login="mynewuser" password="passw">
  
• Account: All attributes of the 'account' tag contain billing-related info, including:
  
  • balance defines account opening balance
  • startdate defies account creation date in the format MM/DD/YYYY.
    Important: Don't set startdate later than the migration date, as it will cause unpredictable billing malfunctions.
  • bpid defines transferred account billing period number, in a sequence set in the Payment Intervals list in Plan Settings.
    The first payment interval in the list (usually, 1 month) has bpid=0, the second one (for example, 3 months) has bpid=1, etc.
  • suspended set suspended to 1 if you want to have migrated accounts immediately suspended. Added in H-Sphere 2.5.

  Example:

  A user has registered an account on October 5, 2002;
  - on May 2, 2003 you migrate this user to H-Sphere;
  - the account is transferred on a three month billing period (bpid=2);
  - the total cost of resources available under the plan for three months makes $90;
  - the user has already pre-paid for the services until July 30, 2003.
  

  Setting the above account attributes to:

  <account balance="$115.00" startdate="10/5/2002" bpid="2">

  • You will transfer that account to H-Sphere as created on October 5, 2002, with the first invoice of April 5, 2003 - July 5, 2003.
  • H-Sphere will leave out all 'closed' billing periods by the time of the transfer (i.e. October 5, 2002 - January 5, 2003 and January 5, 2003 - April 5, 2003).
  • It will accrue the account $90 plan's recurrent fee for the current billing period of April 5, 2003 - July 5, 2003 and immediately credit $115 as Initial balance adjustment.
  • This amount covers the current billing period expenses ($90) and prorated expenses for 25 days of the next billing period the user already pre-paid for ($25).
• Contact And Billing Info: Most tags are required. If you don't have all required info, use dummy data and have users update their profiles after the migration. You can skip billing info for No Billing accounts. Read more in the Signup Customization guide.

• Supported Credit Card Types: these values can be taken from the H-Sphere database:
  select name_sh, name from cc_brands;

  The cc_type attribute in the account's billing info may take one of the values of the cc_brands.name_sh field.

• Limits: Defines disk quota in MB and traffic limit it GB.
• Domain: Domain tag takes the following attributes:
  
  • ip required only for domains with dedicated IP. Skip it for shared IP domains.
  • name domain name must not contain the www prefix.
  • type can be transfer, 3ldomain, etc.
• Web Service: to be added...
• MySQL: to be added...
• Mail Service: Each domain tag can contain a mailservice tag. It contains different types of mail objects. Each mail object has the "name" or "email" attributes. The value of the "name" attribute is appended to "@domain_name", where the domain_name is the name of the enclosing domain tag. In other words, do not assign attribute names such values as "smth@domain_name". However, when the attribute is called "email", provide a full e-mail address as the value.

XML Validation

Once you have created the XML, please do the following:

1. Validate the user data xml files with any xml validation software.
2. Make sure the xml file does not contain user with the login "admin".
3. Make sure that mail sections of each user don't contain mail loops.
4. Ensure that the billing period starting date has the MM/DD/YY format.
5. Make sure that in the user tag the value of the login attribute is unique and doesn't begin with a number (this value will be used as the H-Sphere control panel login name).

Now you are ready to create the accounts.