Acronis Webservices API User Manual

Webservices API Manual

WebService Interface Description

1. Introduction

This reference explains possibilities for integrating BackupAgent with other IT and/or

administrative services. It contains technical documentation describing the public WebService

interface for managing user accounts.

In this case BackupAgent uses the following specifications for their WebService:

 Version 4: Native SOAP/XML interface based on Microsoft WSE 2.0 sp3
 Version 5: Native SOAP/XML interface based on Microsoft WCF

The native interface is completely open and offers full BackupAgent Provider functionality.

This document only demonstrates functionality for:

 User account management
 Storage group management

This document will explain both SOAP/ XML integration. Technical references will be provided

on the following subjects:

 Interface access and function specifications
 Code samples
 Exception codes

2. SOAP/XML interface - Version 4

BackupAgent’s core technology is a WebService. For security and authentication control this

interface is protected using Microsoft WSE 2.0 sp3. All WebService functions are available for

integration.

1

2.1 Access

To access the interface, choose a programming language or software package that supports

client consumption of a WSDL which is protected by WSE 2.0. By default C# allows easy and

reliable access to BackupAgent WebServices. Following step-by-step instructions show how to

access BackupAgent WebServices.

1. Find the WSDL. In the normal case the WSDL is provided on an url like

‘https://yourdomain.com/CloudBackupService/BackupService.asmx?WSDL’

2. Create a proxy class to represent the WebService. In C# this proxy class is called a ‘web

reference’.

3. Derive the proxy class from the Microsoft.Web.Services2.WebServicesClientProtocol

4. Attach a UsernameToken to object references based on the client proxy class using the

RequestSoapContext.Security.Tokens collection. Add a MessageSignature based on the

UsernameToken to the RequestSoapContext.Security.Elements collection.

5. Login for user/administrator access calling the CheckUserLogin function.

Important: Use the URL where the license is installed on. Otherwise you will receive a license

error.

The UsernameToken must be based on an existing username/password combination in the

BackupAgent Server system. For full access to administrative functions an administrator

UsernameToken must be provided.

2.2 Code sample for connecting to a BackupAgent WebService

Deriving the proxy class from WSE 2.0 WebServiceClientProtocol in class definition:

public class BAWebService2 :

Microsoft.Web.Services2.WebServicesClientProtocol{ … }

Creating an object reference to attach a token:

StorageXS.BAWebService2 server = new StorageXS.BAWebService2();

UsernameToken token = new UsernameToken(username,password,PasswordOption.SendPlainText);

2

server.RequestSoapContext.Security.Tokens.Clear();

server.RequestSoapContext.Security.Tokens.Add(token);

server.RequestSoapContext.Security.Elements.Add(new MessageSignature(token))

return server;

Login the user:

StorageXS.LoginInfo login = server.CheckUserLogin(username.Trim(),

password.Trim(), "clientname");

if(login.LoginStatus > 0) return true;

else return false;

Note: StorageXS is the local reference name used in the above example.

Note: In case you use the WSE 3.0 libraries, you need to manually set the encryption to be 128

bits:

ISecurityTokenManager stm3 =

Microsoft.Web.Services3.Security.Tokens.UsernameTokenManager.GetSecurityTokenManagerByToken

Type(WSTrust.TokenTypes.UsernameToken);

stm3.DefaultKeyAlgorithm = "AES128";

After logging in, this client can have full access to BackupAgent Server functions. Depending on

common use cases, BackupAgent can support and develop custom interfaces or support client-

side development of custom functionality. The working of the WebService is proprietary.

Therefore documentation is limited to this document and the WSDL.

2. SOAP/XML interface - Version 5

In Version 5, the API interface is a WCF interface. By default C# allows easy and reliable access

to BackupAgent WebServices. Following step-by-step instructions show how to access

BackupAgent WebServices.

2.1 Access

3

To access the interface, choose a programming language or software package that supports

client consumption of a WSDL

1. Find the WSDL. In the normal case the WSDL is provided on an url like

‘https://yourdomain.com/CloudBackupService/BackupService.svc’

2. Add a Service Reference, which connects to the above Address.

3. Give the namespace a friendly name such as 'BackupService'

4. Add a valid administrator or group username and password to the Credentials.

5. Set the Authentication.CertificateValidationMode = X509CertificateValidationMode.None

6. Login for user/administrator access calling the CheckUserLogin function.

2.2 Code sample for connecting to a BackupAgent WebService using WCF

The following is a code sample which works using the .Net Framework v4:

Step 1 - include the ServiceModel libraries and the reference to the Service:

using System.ServiceModel;

using System.ServiceModel.Security;

using ConsoleApplicationWCF.BackupService;

Step 2 - add credentials

namespace ConsoleApplicationWCF

{

class Program

{

static void Main(string[] args)

{

EndpointAddress endpointAddress = new EndpointAddress(new

Uri("https://yourcompany/CloudBackupService/BackupService.svc"));

CloudBackupServiceClient client = new

CloudBackupServiceClient("BasicHttpBinding_ICloudBackupService", endpointAddress);

4

Function

Result

Required parameters

Explanation

GetUsersAdmin

An array of
strings
containing either
usernames or a
summary of user
statistics

bool Totalbool
Top10Recentstring
ParentUserstring Criteria

The function
returns either a
set of usernames
or a summary of
total users given
the criteria and
parameters

GetOwnerInfo1

An array of
OwnerInfo
objects
containing all
information on
storage groups

string Owner

The function
returns all storage
group info or info
for a single
storage group

GetAccountTypes

An array of
AccountType
objects

enum
TypesToRetreiveenum
DescriptionType

The function
returns all
account types
based on the

client.ClientCredentials.UserName.UserName = "username";

client.ClientCredentials.UserName.Password = "password";

client.ClientCredentials.ServiceCertificate.Authentication.CertificateValidationMode =

System.ServiceModel.Security.X509CertificateValidationMode.None;

}

}

}

Step 3 - call the CheckUserLogin function:

LoginInfo login = client.CheckUserLogin_Ex("robbert.demo", "testtest");

3. Available functions

The following functions are available for integration purposes and will be described here in

further detail. Some functions will require public structures (objects or enumerations) as

parameters. The following table shows functions for retrieving server information:

5

enum
parametersq
GetUserInfoAdmin

An UserInfo
object

string Username

Returns all user
information of a
user

GetAccountInfoAdmin

An AccountInfo
object

string Username

Returns all
account
information of a
user

GetChildAccountInfo

An array of
UserAccountInfo
objects

string ParentUser (group
user)enum
AccountDescriptionTypeboo
l getAllAccountsenum
RequestType

Returns a
collection of user
and account
information
objects of
multiple users

GetUserBackupResults

An array of
BackupReportInf
o objects

string Usernamestring
Language

Returns a
collection of
backup report
objects

GetFullBackupReportInf
o

A more detailed
BackupReportInf
o object

Int BackupReportID (DBID)

Returns a more
detailed
BackupReportInf
o object including
logs

GetResellers2

An array of
strings containing
all group names

bool TotalResellerCount
(false)

Returns all
groups in the
systems

GetResellerInfo

A ResellerInfo
object

string ResellerName

Returns all
detailed
information of a
group

GetResellersUsageInfo

Array of
ResellerUsageInf
o objects

Returns usage
info of all groups

1

A storage group is represented in the API as an ‘owner’

2

BackupAgent groups are represented as ‘resellers’ in the API

Next to functions to retrieve information the following functions allow an administrator to

integrate account management (create, change accounts):

6

Function

Result

Parameters

Explanation

CreateAccount

Creates a new
user with an
account in the
BackupAgent
Server and
returns an
integer

string
ParentUserUserInfo
userInfoAccountInfo
accInfostring
Usernamestring
Passwordstring
[Obsolete]string
[Obsolete]bool
SendEmail

The function creates
an account. Return
codes:

1: User Ok

-1: Unexpected error

-2: User exists

-5: Wrong Owner

ChangeUserInfoAdmin

Changes
UserInfo for a
user and
returns an
integer

string
ChangedUserUserInfo
newInfo

The function
overwrites UserInfo
based on the new
UserInfo object.
Returns 1 if Ok, else
returns a negative
integer

ChangeAccountInfoAdmin

Changes
AccountInfo
for a user and
returns an
integer

string
ChangedUserAccountInfo
newInfo

The function
overwrites
AccountInfo based
on the new
AccountInfo object.
Returns 1 if Ok, else
returns a negative
integer

ActivateAccount

Activates a
new or
deactivated
account and
returns an
integer

string Usernamestring
Passwordbool Encrypted

The function
activates an account.
As administrator the
account can be
activated without
Password

DeactivateAccount

Deactivates
one or more
accounts and
returns an
integer

string[] Usernames

The function
deactivates all
accounts in the string
array

DeleteAccount

Deletes one or
more accounts
and returns an
integer

string[] Usernames
bool isReseller

The function deletes
all accounts and
removes all data in
the accounts.
Set 'isReseller' to
true to indicate that
the deleted users are
resellers/groups

ResetPassword

Resets
password and

string Username

The function resets
the password for a
user to ‘Backup01’

7

returns an
integer

ChangePassword

Allows a user
to change a
password and
returns an
integer

string OldPasswordstring
NewPassword

If the token of
request is a normal
user, this user can
change his/her own
password

CreateOwner

Creates a new
storage group
and returns an
integer

OwnerInfo NewInfobool
SetAsDefault

The function creates
a new storage group
Returns 1 if Ok, else
returns a negative
integer

ChangeOwner

Changes a
storage group
and returns an
integer

OwnerInfo NewInfo

The function
changes a storage
group based on an
existing OwnerID in
the OwnerInfo
object.

ChangeDefaultOwner

Sets a storage
group as
default group

string ResellerNamestring
Ownername

The function sets a
default group for an
administrator/reseller

CreateReseller

Creates a
group

UserInfo
newInfoResellerInfo
newInfostring
ResellerNamestring
Password

The function creates
a (whitelabel) group
in the BackupAgent
system

ChangeResellerInfo_Ex

Changes
settings of a
group

String
ResellerNameUserInfo
newInfoResellerInfo
newInfo

The function can
change certain
settings of
a(whitelabel) group

Note: The used credentials for authentication and access (see 3.1.) will also determine

ownership and hierarchy of a group or user. You can overrule this for CreateAccount by setting

the ParentUser property and for CreateReseller by setting the ParentReseller property of the

UserInfo object.

4. Supportive structures

Some functions require objects that are based on public structures (classes or enumerations)

which are part of the WebService public interface.

8

4.1 Enumerations

AccountTypesToRetrieve:

 All_AccountTypes
 Only_Active
 Only_NonActive

ChildAccountRequestType:

 Normal
 Active
 New

AccountDescriptionTypes:

 Normal_Account
 Trial_Account
 Free_Account
 Normal_And_Trial_Account

UserProfileTypes:

 Professional = 1 (“Professional” is called in the user interface “Server”)
 Home = 2 (“Home” is called in the user interface “Workstation”)

LanguageType:

 LanguageType_NL (Dutch)
 LanguageType_EN (English)
 LanguageType_FR (French)
 LanguageType_ES (Spanish)
 LanguageType_DE (German)
 LanguageType_IT (Italian)
 LanguageType_DK (Danish)

9