How to use the SOAP API for Cloud Management Console

Introduction

There are two types of web services in the Cloud: Management Service and Reporting Service. Both types of services are exposed via SOAP protocol.

Both types of services use SOAP 1.1 protocol.
If a SOAP method call is successful, the SOAP body contains an appropriate response.
If a method call failed, the SOAP body contains the SOAP Fault element and the response is omitted as shown in the example below.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:repsvc="urn:repserv-methods"> <soapenv:Body soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 
<soapenv:Fault> <faultcode>soapenv:Server</faultcode> 
<faultstring>Exception executing request</faultstring> 
<detail> 
<operationResult> 
<errorCode>101</errorCode> 
<errorMessage>Cannot locate storage path</errorMessage> 
</operationResult> 
</detail> 
</soapenv:Fault> 
</soapenv:Body> 
</soapenv:Envelope>

If a SOAP header does not carry any information, it must be omitted.

The Management Service provides management functions and total device statistics. Management Service is available at a single access point.

Reporting Services are used to obtain detailed information about backups for specific backup Devices. Reporting Services run on every storage node.

Use this link for the latest WSDL version with request schemas for the SOAP API services.

Management Service Protocol

Authorization

Any action or request to the Management Service has to be authorized. Non-authorized requests are rejected. A request is authorized if and only if it contains valid Visa. A Visa is a GUID-like string generated by Service. A Visa originates from an authentication request (see the Login method) and then is returned in response to any authorized request. A valid Visa obtained from a response of any authorized request should be provided in the next request (Visa chaining). If the time period between subsequent service calls is longer than the Visa expiration time, the Visa chain is interrupted and the Login method should be called again to start a new Visa chain. A SOAP header must contain an additional Visa element that is used for authorization (see below).

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:manserv-methods">
<soapenv:Header>
<visa>111-111-1-CCCC</visa>
</soapenv:Header>
<soapenv:Body>
<urn:EnumerateColumns>
<request>
<partnerId>309</partnerId>
</request>
</urn:EnumerateColumns>
</soapenv:Body>
</soapenv:Envelope>

The main concepts

Partner scope covers all objects of all entities that belong to this partner and/or Partners of its subtree.
Partner-only scope covers all objects of all entities that belong to this Partner only.
Partner-and-parents scope covers all objects of all entities that belong to this Partner and/or Partners of its subtree and/or its parent Partners.

The key entity in the protocol is the Partner. The Partner is a company that provides or uses backup services. Partners are hierarchically organized in a Partner tree. Any object of any entity (User, Device, Product etc.) is (directly or transitively) related to (in most cases owned by) a specific Partner. In relation to this several object scopes are defined.

Access restrictions

Any activity (human or automated) operating on the Cloud via Management Service is represented by the User. For authentication Partner name, User name and Password need to be provided. The Partner and User provided for authentication are called the effective Partner and effective User. To any action or request, there are two kinds of restrictions applied: Scope restriction and Role restriction.

Scope restriction rejects access to any objects out of the Partner scope of the effective Partner. Scope restriction is also known as “where” restriction.
Role restriction rejects actions on specific entities that are not granted by the effective User role. Role restriction is also known as “what” restriction.

Management service API reference

Methods are grouped by entities for convenience. In most cases, methods implement obvious CRUD operations. Non-trivial methods are commented in notes. Detailed information can be obtained from the WSDL specification.

Common methods

Login – Should be called first to get authorized as described above. SOAP header must be omitted.

Partner management methods

The following methods are used to manage Partners. The Partner name is unique in the system scope.

EnumeratePartners – Allows returning a Partner’s subtree into a plain format with a child-parent reference
AddPartner – Allows adding a new Partner
GetPartnerInfo – Allows obtaining information about a Partner
GetPartnerInfoById – Allows obtaining information about a Partner by the ID
ModifyPartner – Allows changing features of a Partner
RemovePartner – Allows deleting an already created Partner
ChangePartnerState – Allows changing of a Partner state in accordance with a Partner state machine described in the method EnumeratePartnerStateTransitions
EnumeratePartnerStateTransitions – A list of state transitions for a selected Partner

User management methods

The following methods are used to manage Users of a specific Partner. The User name is unique in the Partner-only scope.

GetUserInfo – Allows obtaining information about a User
AddUser – Allows adding a new User
ModifyUser – Allows changing features of a User
RemoveUser – Allows deleting an already created User
EnumerateUsers – Users list for a selected Partner
EnumerateUserRoles – Allows listing all roles available in the system
EnumeratePermissions – Allows listing permissions of an effective User

Contact management methods

The following methods are used to manage contact persons of a specific Partner.

GetContactPersonInfoById – Allows obtaining information about a ContactPerson by the ID
AddContactPerson – Allows adding a new ContactPerson
ModifyContactPerson – Allows changing features of a ContactPerson
RemoveContactPerson – Allows deleting a ContactPerson
EnumerateContactPersons – Allows listing permissions of an effective ContactPerson

Device management methods

The following methods are used to manage backup Devices for a specific Partner. A backup device is used to identify a backup client. The device name is unique in the scope of the system.

AddAccount – Allows adding a new device
RemoveAccount – Allows deleting an already created device
ModifyAccount – Allows changing features of a device
ChangeAccountPassword – Allows changing a password of a device
GetAccountInfo – Allows obtaining information about a device
GetAccountFeatures – Allows obtaining features of a device
GetAccountCustomColumnValues – Allows obtaining values of a device
SetAccountFeatures– Allows setting features for a device
EnumerateAccountStatistics – Allows obtaining statistics in accordance of a device
EnumerateColumns – A list of columns for a selected Partner
GetRemoteConnectionConfig – Allows to get Config for the remote Connection GUI to Backup FP
UpdateAccountCustomColumnValues – Allows to update device custom column values
EnumerateAccountStatisticsReports – Allows listing permissions of an effective device

Product management methods

The following methods are used to manage Products of a specific Partner. The Product defines a set of features that are available for specific backup client. The Product name is unique in a Partner-and-Parent scope. Products are inherited from parent Partners.

AddProduct – Allows adding a Product
ModifyProduct – Allows changing features of a Product
RemoveProduct – Allows deleting a Product
EnumerateFeatures – Allows listing all features available in the system
EnumerateProducts – Allows listing Products from the parent-and-Partner scope of the effective Partner

Storage management methods

The following methods are used to manage storages and storage nodes of a specific partner.

AddStorage – Allows adding new storage
EnumerateStorages – Allows listing storages for a selected partner
AddStorageNode – Allows adding a new storage node
EnumerateStorageNodes – Allows listing storage nodes for a selected partner
UpdateStorageNode – Allows updating a storage node
UpdateStorageNodeState – Allows updating a storage node state
EnumerateStorageStatistics – Allows listing permissions of an effective user

Notification management methods

The following methods are used to configure the Notification subsystem.

AddNotificationTemplate – Allows adding a new notification template
ModifyNotificationTemplate – Allows changing features of a notification template
RemoveNotificationTemplate – Allows deleting a notification template
GetNotificationTemplate– Allows getting a notification template
EnumerateTemplates – Allows listing all templates available
AddNotificationRule – Allows adding a notification rule
RemoveNotificationRule – Allows deleting a notification rule
ModifyNotificationRule – Allows changing features of a notification rule
GetNotificationRule – Allows getting a notification rule
EnableNotificationRule – Allows enabling a notification rule
EnumerateNotificationRules – Allows listing all notification rules available
EnumerateActiveNotificationRules – Allows listing permissions of an effective user
AddNotificationTransport – Allows adding a notification transport
RemoveNotificationTransport – Allows deleting a notification transport
ModifyNotificationTransport – Allows changing features of a notification transport
GetNotificationTransport – Allows getting a notification transport
EnumerateNotificationTransports – Allows listing all notification transports available
LookupTransport – Allows looking up transport

Custom columns management methods

EnumerateCustomColumns – Allows listing permissions of an effective user
AddCustomColumn – Allows adding a custom column
GetCustomColumnById – Allows getting a custom column by ID
ModifyCustomColumn – Allows changing features of a custom column
RemoveCustomColumn – Allows deleting a custom column

Location management methods

AddLocation – Allows adding a new location
EnumerateLocations – Allows listing locations

Reporting service protocol

A full version of the Reporting Service protocol is available in any storage node at the following path: https://<home_node_address>/repserv?wsdl.

Authorization

Reporting Services use basic HTTP authentication. Reporting Services does not use Visa-authorization, so the SOAP header must be omitted.

Since Reporting Service provides device-level functionality, all methods of Reporting Services require a device’s token to identify the device that the requested method operates on.

Getting device-level information

Here is short description of typical steps that are necessary to get detailed device-level information provided by Reporting Services (it is assumed that the requester is already authorized in Management Service):

Call GetAccountInfo method of Management Service with a device name specified. Response will contain the device’s token and Device Home Node information. The Device Home Node information contains the address and credentials of Device Home Node where correspondent Reporting Service is running.
Perform necessary Reporting Service method call using information obtained at step 1.

Reporting service API reference

EnumerateAccountSessions – Returns list of backup/restore sessions
EnumerateAccountSessionErrors – Returns errors occurred in specific session
EnumerateAccountBackupFiles – Returns files backed up during specific session
EnumerateAccountRemovedBackupFiles – Returns files removed during specific session
EnumerateAccountAudit – Returns list of user actions
SendAccountCommand – Sends specific command to the backup client

Sample usage

Let’s say you want to get the amount of used storage for a partner. The task involves three steps: log in to the system, get partner ID, and then get statistics for all devices belonging to the partner. This makes three SOAP calls – Login, GetPartnerInfo and EnumerateAccountStatistics.

Step 1: log in

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:iaso-com:cloud:mansvc:14.0.0">
<soapenv:Header/>
<soapenv:Body>
<urn:Login>
<request>
<partnerName>PARTNER</partnerName>
<userName>USER</userName>
<password>PASSWORD</password>
</request>
</urn:Login>
</soapenv:Body>
</soapenv:Envelope>

Response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:common="urn:iaso-com:cloud:common" xmlns:storsvc="http://tempuri.org/storsvc.xsd" xmlns:mansvc="urn:iaso-com:cloud:mansvc" xmlns:mansvc-13-2-0="urn:iaso-com:cloud:mansvc:13.2.0" xmlns:mansvc-13-2-1="urn:iaso-com:cloud:mansvc:13.2.1" xmlns:mansvc-13-2-2="urn:iaso-com:cloud:mansvc:13.2.2" xmlns:mansvc-13-5-0="urn:iaso-com:cloud:mansvc:13.5.0" xmlns:mansvc-13-5-1="urn:iaso-com:cloud:mansvc:13.5.1" xmlns:mansvc-13-5-2="urn:iaso-com:cloud:mansvc:13.5.2" xmlns:mansvc-14-0-0="urn:iaso-com:cloud:mansvc:14.0.0" xmlns:mansvc-14-1-0="urn:iaso-com:cloud:mansvc:14.1.0">
<SOAP-ENV:Header>
<common:visa>111-111-1-CCCC</common:visa>
</SOAP-ENV:Header>
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<mansvc:EmptyResponse/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Step 2: get partner info

Request:

<soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:iaso-com:cloud:common" xmlns:urn1="urn:iaso-com:cloud:mansvc:14.0.0"> 
<soapenv:header>
<urn:visa>111-111-1-CCCC<urn:visa>
</soapenv:Header> 
<soapenv:Body> 
<urn1:GetPartnerInfo> 
<request> 
<name>IT Services Nederland B.V.<name>
</request> 
</urn1:GetPartnerInfo> 
</soapenv:body> 
</soapenv:envelope>

Response:

<urn:visa>111-111-1-CCCC<urn:visa>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:common="urn:iaso-com:cloud:common" xmlns:storsvc="http://tempuri.org/storsvc.xsd" xmlns:mansvc="urn:iaso-com:cloud:mansvc" xmlns:mansvc-13-2-0="urn:iaso-com:cloud:mansvc:13.2.0" xmlns:mansvc-13-2-1="urn:iaso-com:cloud:mansvc:13.2.1" xmlns:mansvc-13-2-2="urn:iaso-com:cloud:mansvc:13.2.2" xmlns:mansvc-13-5-0="urn:iaso-com:cloud:mansvc:13.5.0" xmlns:mansvc-13-5-1="urn:iaso-com:cloud:mansvc:13.5.1" xmlns:mansvc-13-5-2="urn:iaso-com:cloud:mansvc:13.5.2" xmlns:mansvc-14-0-0="urn:iaso-com:cloud:mansvc:14.0.0" xmlns:mansvc-14-1-0="urn:iaso-com:cloud:mansvc:14.1.0">
<SOAP-ENV:Header>
<common:visa>111-111-1-CCCC</common:visa>
</SOAP-ENV:Header>
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<mansvc-13-5-0:GetPartnerInfoResponse>
<partnerInfo>
<id>309</id>
<parentId>116</parentId>
<name>IT Services Nederland B.V.</name>
.....
</partnerInfo>
</mansvc-13-5-0:GetPartnerInfoResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parse the ID and use it for the next call.

Step 3: get used storage statistics

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:iaso-com:cloud:common" xmlns:urn1="urn:iaso-com:cloud:mansvc:14.0.0">
<soapenv:Header>
<urn:visa>111-111-111-AAA</urn:visa>
</soapenv:Header>
<soapenv:Body>
<urn1:EnumerateAccountStatistics>
<request>
<query>
<partnerId>309</partnerId>
<startRecordNumber>0</startRecordNumber>
<recordsCount>200</recordsCount>
<columns>
<string>US</string></columns>
<totals>
<string>SUM(US)</string></totals>
</query>
</request>
</urn1:EnumerateAccountStatistics>
</soapenv:Body>
</soapenv:Envelope>

startRecordNumber – get statistic from number of accounts
recordsCount – end statistic from number of accounts
columns – US (used storage)
totals – SUM(IS) – sum all used storages of accounts under specified partner.

Response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:common="urn:iaso-com:cloud:common" xmlns:storsvc="http://tempuri.org/storsvc.xsd" xmlns:mansvc="urn:iaso-com:cloud:mansvc" xmlns:mansvc-13-2-0="urn:iaso-com:cloud:mansvc:13.2.0" xmlns:mansvc-13-2-1="urn:iaso-com:cloud:mansvc:13.2.1" xmlns:mansvc-13-2-2="urn:iaso-com:cloud:mansvc:13.2.2" xmlns:mansvc-13-5-0="urn:iaso-com:cloud:mansvc:13.5.0" xmlns:mansvc-13-5-1="urn:iaso-com:cloud:mansvc:13.5.1" xmlns:mansvc-13-5-2="urn:iaso-com:cloud:mansvc:13.5.2" xmlns:mansvc-14-0-0="urn:iaso-com:cloud:mansvc:14.0.0" xmlns:mansvc-14-1-0="urn:iaso-com:cloud:mansvc:14.1.0">
<SOAP-ENV:Header>
<common:visa>111-111-111-AAA</common:visa>
</SOAP-ENV:Header>
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<mansvc-13-5-1:EnumerateAccountStatisticsResponse>
<accountStatistics>
<accountStatisticsInfo>
<accountId>1970</accountId>
<partnerId>309</partnerId>
<flags>
<string>Managed</string>
</flags>
<accountStatisticsInfoItem>
<pair>
<first>US</first>
<second>619166302208</second>
</pair>
</accountStatisticsInfoItem>
</accountStatisticsInfo>
............
<totalStatistics>
<totalStatisticsInfoItem>
<pair>
<first>SUM(US)</first>
<second>10301821943808</second>
</pair>
</totalStatisticsInfoItem>
</totalStatistics>
</mansvc-13-5-1:EnumerateAccountStatisticsResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Here you should parse totalStatistics to get the total amount. Note that the amount of storage is represented in bytes.