Development Guides Home >> Guide to Transfer and Restore API Functions

Guide to Transfer and Restore API Functions - Monitor the Transfer Session

Introduction

When you monitor the transfer session, you check the status of the transfer session. Use the same process for both the root and transfer sessions.

In this example, the following statements are true:

remote.example.com and local.example.com represent the remote server and the local server.
You logged in to the local server with the cpsess########## security token.
The example account owns example.com , and you want to transfer it from the remote server to the local server.
The example.com domain contains 123,456,789 bytes.
You want to transfer the package1 package from the remote server to the local server.
luggage12345 represents the root password for the remote server.

Determine the state of the transfer session

To determine the state of a transfer session, use the WHM API 1 get_transfer_session_state function.

Select the method by which you wish to call the function:

JSON API

https://hostname.example.com:2087/cpsess##########/json-api/get_transfer_session_state?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP

include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG');
$_result = $xmlapi->xmlapi_query('get_transfer_session_state' , $settings);

print $_result;

The function will respond with one of the following states:

TRANSFER_PENDING
TRANSFER_INPROGRESS
RESTORE_PENDING
RESTORE_INPROGRESS
PENDING
COMPLETED
FAILED

In the following example, the transfer session is in progress:

{
  "data": {
    "state_name": "TRANSFER_INPROGRESS"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "get_transfer_session_state"
  }
}

Review the master log

Review the master log for the transfer session with the WHM API 1 fetch_transfer_session_log function.

Select the method by which you wish to call the function:

JSON API

https://hostname.example.com:2087/cpsess##########/json-api/fetch_transfer_session_log?api.version=1&transfer_session_id=vm5docscpanelcopya20140224163412sylG&logfile=master.log

PHP

include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array(
    'api.version'=>1,
    'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG' ,
    'logfile' => 'master.log'
);
$_result = $xmlapi->xmlapi_query('fetch_transfer_session_log' , $settings);

print $_result;

The following example shows the contents of a log file:

{
  "data": {
    "log":

"\“pid\“:\“14358\“,\“contents\“:{\“action\“:\“start\“,\“child_number\“:0},\“type\“:\“control\“}\n{\“pid\“:\“14358\“,\“contents\“:{\“msg\“:\“copyacct\“,\“action\“:\“initiator\“,\“child_number\“:0},\“type\“:\“control\“}\n{\“pid\“:\“14358\“,\“contents\“:{\“msg\“:\“1.6\“,\“action\“:\“version\“,\“child_number\“:0},\“type\“:\“control\“}\n{\“pid\“:\“14358\“,\“contents\“:{\“msg\“:\“3\“,\“action\“:\“queue_count\“,\“queue\“:\“TRANSFER\“,\“child_number\“:0},\“type\“:\“control\“}\n{\“pid\“:\“14358\“,\“contents\“:{\“msg\“:\“3\“,\“action\“:\“queue_count\“,\“queue\“:\“RESTORE\“,\“child_number\“:0},\“type\“:\“control\“}\n{\“pid\“:\“14358\“,\“contents\“:{\“msg\“:\“vm5.docs.cpanel.net\“,\“action\“:\“remotehost\“,\“child_number\“:0},\“type\“:\“control\“}\n{\“pid\“:\“14360\“,\“contents\“:{\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“fredfred\“,\“action\“:\“start\“,\“queue\“:\“TRANSFER\“,\“item_name\“:\“Account\“,\“child_number\“:1},\“type\“:\“control\“}\n{\“pid\“:\“14360\“,\“contents\“:{\“msg\“:\“item-TRANSFER_AccountRemoteRoot_fredfred\“,\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“fredfred\“,\“item_name\“:\“Account\“,\“action\“:\“process-item\“,\“queue\“:\“TRANSFER\“,\“child_number\“:1,\“logfile\“:\“item-TRANSFER_AccountRemoteRoot_fredfred\“},\“type\“:\“control\“}\n{\“pid\“:\“14361\“,\“contents\“:{\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“colin\“,\“action\“:\“start\“,\“queue\“:\“TRANSFER\“,\“item_name\“:\“Account\“,\“child_number\“:2},\“type\“:\“control\“}\n{\“pid\“:\“14361\“,\“contents\“:{\“msg\“:\“item-TRANSFER_AccountRemoteRoot_colin\“,\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“colin\“,\“item_name\“:\“Account\“,\“action\“:\“process-item\“,\“queue\“:\“TRANSFER\“,\“child_number\“:2,\“logfile\“:\“item-TRANSFER_AccountRemoteRoot_colin\“},\“type\“:\“control\“}\n{\“pid\“:\“14362\“,\“contents\“:{\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“stacy\“,\“action\“:\“start\“,\“queue\“:\“TRANSFER\“,\“item_name\“:\“Account\“,\“child_number\“:3},\“type\“:\“control\“}\n{\“pid\“:\“14362\“,\“contents\“:{\“msg\“:\“item-TRANSFER_AccountRemoteRoot_stacy\“,\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“stacy\“,\“item_name\“:\“Account\“,\“action\“:\“process-item\“,\“queue\“:\“TRANSFER\“,\“child_number\“:3,\“logfile\“:\“item-TRANSFER_AccountRemoteRoot_stacy\“},\“type\“:\“control\“}\n{\“pid\“:\“14362\“,\“contents\“:{\“msg\“:{\“warnings\“:0,\“dangerous_items\“:0,\“contents\“:{\“dangerous_items\“:null,\“altered_items\“:null},\“skipped_items\“:0,\“altered_items\“:0,\“message\“:null},\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“stacy\“,\“item_name\“:\“Account\“,\“action\“:\“success-item\“,\“queue\“:\“TRANSFER\“,\“child_number\“:3,\“logfile\“:\“item-TRANSFER_AccountRemoteRoot_stacy\“},\“type\“:\“control\“}\n{\“pid\“:\“14361\“,\“contents\“:{\“msg\“:{\“warnings\“:0,\“dangerous_items\“:0,\“contents\“:{\“dangerous_items\“:null,\“altered_items\“:null},\“skipped_items\“:0,\“altered_items\“:0,\“message\“:null},\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“colin\“,\“item_name\“:\“Account\“,\“action\“:\“success-item\“,\“queue\“:\“TRANSFER\“,\“child_number\“:2,\“logfile\“:\“item-TRANSFER_AccountRemoteRoot_colin\“},\“type\“:\“control\“}\n{\“pid\“:\“14363\“,\“contents\“:{\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“stacy\“,\“action\“:\“start\“,\“queue\“:\“RESTORE\“,\“item_name\“:\“Account\“,\“child_number\“:1},\“type\“:\“control\“}\n{\“pid\“:\“14363\“,\“contents\“:{\“msg\“:\“item-RESTORE_AccountRemoteRoot_stacy\“,\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“stacy\“,\“item_name\“:\“Account\“,\“action\“:\“process-item\“,\“queue\“:\“RESTORE\“,\“child_number\“:1,\“logfile\“:\“item-RESTORE_AccountRemoteRoot_stacy\“},\“type\“:\“control\“}\n{\“pid\“:\“14365\“,\“contents\“:{\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“colin\“,\“action\“:\“start\“,\“queue\“:\“RESTORE\“,\“item_name\“:\“Account\“,\“child_number\“:2},\“type\“:\“control\“}\n{\“pid\“:\“14365\“,\“contents\“:{\“msg\“:\“item-RESTORE_AccountRemoteRoot_colin\“,\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“colin\“,\“item_name\“:\“Account\“,\“action\“:\“process-item\“,\“queue\“:\“RESTORE\“,\“child_number\“:2,\“logfile\“:\“item-RESTORE_AccountRemoteRoot_colin\“},\“type\“:\“control\“}\n{\“pid\“:\“14360\“,\“contents\“:{\“msg\“:{\“warnings\“:0,\“dangerous_items\“:0,\“contents\“:{\“dangerous_items\“:null,\“altered_items\“:null},\“skipped_items\“:0,\“altered_items\“:0,\“message\“:null},\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“fredfred\“,\“item_name\“:\“Account\“,\“action\“:\“success-item\“,\“queue\“:\“TRANSFER\“,\“child_number\“:1,\“logfile\“:\“item-TRANSFER_AccountRemoteRoot_fredfred\“},\“type\“:\“control\“}\n{\“pid\“:\“14360\“,\“contents\“:{\“action\“:\“complete\“,\“queue\“:\“TRANSFER\“,\“child_number\“:1},\“type\“:\“control\“}\n{\“pid\“:\“14362\“,\“contents\“:{\“action\“:\“complete\“,\“queue\“:\“TRANSFER\“,\“child_number\“:3},\“type\“:\“control\“}\n{\“pid\“:\“14361\“,\“contents\“:{\“action\“:\“complete\“,\“queue\“:\“TRANSFER\“,\“child_number\“:2},\“type\“:\“control\“}\n{\“pid\“:\“14363\“,\“contents\“:{\“msg\“:{\“warnings\“:2,\“dangerous_items\“:0,\“contents\“:{\“dangerous_items\“:[],\“altered_items\“:[]},\“skipped_items\“:10,\“altered_items\“:0,\“message\“:null},\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“stacy\“,\“item_name\“:\“Account\“,\“action\“:\“success-item\“,\“queue\“:\“RESTORE\“,\“child_number\“:1,\“logfile\“:\“item-RESTORE_AccountRemoteRoot_stacy\“},\“type\“:\“control\“}\n{\“pid\“:\“14363\“,\“contents\“:{\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“fredfred\“,\“action\“:\“start\“,\“queue\“:\“RESTORE\“,\“item_name\“:\“Account\“,\“child_number\“:1},\“type\“:\“control\“}\n{\“pid\“:\“14363\“,\“contents\“:{\“msg\“:\“item-RESTORE_AccountRemoteRoot_fredfred\“,\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“fredfred\“,\“item_name\“:\“Account\“,\“action\“:\“process-item\“,\“queue\“:\“RESTORE\“,\“child_number\“:1,\“logfile\“:\“item-RESTORE_AccountRemoteRoot_fredfred\“},\“type\“:\“control\“}\n{\“pid\“:\“14365\“,\“contents\“:{\“msg\“:{\“warnings\“:4,\“dangerous_items\“:1,\“contents\“:{\“dangerous_items\“:[[[\“Mysql\“,\“_restore_mysql\“,104],\“MySQL:
 Skipping grants for these MySQL databases: colin_%. These databases
don't exist in the
archive.\“,null]],\“altered_items\“:[[[\“Mysql\“,\“_update_dbname\“,437],\“mySQL
 database \u201ccolin_testdatabase\u201d restored as
\u201ctestdatabase\u201d\“,[\“Rename\“,\“\/scripts5\/rename_mysql_db\“,{\“new\“:\“testdatabase\“,\“orig\“:\“colin_testdatabase\“}]],[[\“Mysql\“,\“_update_dbuser_name\“,348],\“mySQL
 user \u201ccolin\u201d restored as
\u201ccolin\u201d\“,[\“Rename\“,\“\/scripts5\/rename_mysql_user\“,{\“new\“:\“colin\“,\“orig\“:\“colin\“}]]]},\“skipped_items\“:10,\“altered_items\“:1,\“message\“:null},\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“colin\“,\“item_name\“:\“Account\“,\“action\“:\“success-item\“,\“queue\“:\“RESTORE\“,\“child_number\“:2,\“logfile\“:\“item-RESTORE_AccountRemoteRoot_colin\“},\“type\“:\“control\“}\n{\“pid\“:\“14363\“,\“contents\“:{\“msg\“:{\“warnings\“:2,\“dangerous_items\“:0,\“contents\“:{\“dangerous_items\“:[],\“altered_items\“:[]},\“skipped_items\“:11,\“altered_items\“:0,\“message\“:null},\“item_type\“:\“AccountRemoteRoot\“,\“item\“:\“fredfred\“,\“item_name\“:\“Account\“,\“action\“:\“success-item\“,\“queue\“:\“RESTORE\“,\“child_number\“:1,\“logfile\“:\“item-RESTORE_AccountRemoteRoot_fredfred\“},\“type\“:\“control\“}\n{\“pid\“:\“14363\“,\“contents\“:{\“action\“:\“complete\“,\“queue\“:\“RESTORE\“,\“child_number\“:1},\“type\“:\“control\“}\n{\“pid\“:\“14365\“,\“contents\“:{\“action\“:\“complete\“,\“queue\“:\“RESTORE\“,\“child_number\“:2},\“type\“:\“control\“}\n{\“pid\“:\“14358\“,\“contents\“:{\“action\“:\“complete\“,\“child_number\“:0},\“type\“:\“control\“}\n“
 },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "fetch_transfer_session_log"
  }
}

Each log file contains the following information in a line-delimited JSON format:

Key	Type	Description	Possible Values	Example
`pid`	integer	The process ID under which the command in the log entry ran.	An integer value.	`14538`
`indent`	integer	The level of indentation to display.	A valid positive integer.	`1`
`type`	string	The type of log file entry.	`out` `warn` `success` `failure` `control`	`control`
`partial`	Boolean	We do not currently use this key.	`0` is the only possible value.	`0`
`contents`	hash	A hash of transfer or restore session information.	This hash contains the action, `child_number`, `dangerous_items`, `item`, `item_name`, `item_type`, `local_item`, `logfile`, `message`, `msg`, `queue`, `skipped_items`, and `warnings` keys.
`action`	string	The action for the system to execute. The log file contains this key in the `content` hash.	A valid string.	`start-item`
`child_number`	integer	The number of child processes in the transfer or restore process. The log file contains this key in the `content` hash.	A positive integer.	`1`
`dangerous_items`	integer	The number of items in the transferred or restored account that the system flagged as potentially dangerous. The log file contains this key in the `content` hash.	A positive integer.	`1`
`item`	string	The name of the account to restore or transfer. The log file contains this key in the `content` hash.	A valid string.	`cptech`
`item_name`	string	The name of the item to transfer or restore. The log file contains this key in the `content hash`.	A valid string.	`Account`
`item_type`	string	The specific item to transfer or restore. The log file contains this key in the `content hash`.	A valid string.	`cptech`
`local_item`	string	The item to restore locally. The log file contains this key in the `content` hash.	A valid string.	`AccountLocal`
`logfile`	string	The absolute filepath for the log file. The log file contains this key in the `content` hash.	A valid string.	item-`RESTORE_AccountLocal_cptech`
`message`	string	A message about the transfer or restore process. The log file contains this key in the `content` hash.	A valid string.	`null`
`msg`	string	Additional information about the transfer or restore process. The log file contains this key in the `content hash`.	A valid string.	`null`
`queue`	string	The process that the system performed on the account. The log file contains this key in the `content` hash.	`TRANSFER` `RESTORE`	`RESTORE`
`skipped_items`	integer	The items in the account that the transfer or restore process skipped. The log file contains this key in the `content hash`.	A positive integer.	`1`
`warnings`	integer	The number of warnings that the system returned during the transfer or restore process. The log file contains this key in the `content` hash.	A positive integer.	`2`

Create a script to parse this log file to determine the progress of the transfer or restore operation.