Public OBRM SDK


General

Infrascale Online Backup Recovery Manager (OBRM) includes SDK to provide reliable integration with external systems in scope of client PC.

It supports direct calls like start jobs, getting statistics etc.

Also client can subscribe callbacks to receive notifications   

OBRM SDK Components

  • OBRM 7.X.X.X and higher  - implements direct/callbacks operations as WCF service based .net pipes binding
  • SOS.SDK.dll - standalone library without external dependencies that defines contracts and DTOs, provides mail class InfrascaleClient to connect to OBRM Agent Service
  • SOS.SDK.Console - demo client to show how integration works

Client prerequisites

  • .NET 4.5 or higher
  • OBRM 7.X.X.X and higher 
  • SOS.SDK.dll should be used by client application as contracts definitions, 
  • Infrascale extends SDK contracts by keeping compatibility with old clients 
  • SDK does not support non Windows OS    

Contract: IInfrascaleSdk 

Service contract that supports direct calls. Supported operations:  

Operation: SingIn 

Creates session for specific backup account.

Returns  Identity that must be used for all further operations

Input fields: 

Parameter

Description

Type / Validation Rules

LoginBackup account user namestring
PasswordBackup account passwordstring

Output  fields: 

Output Value

Description

 
TokenDefines backup account session. Used as input for all operations in backup account scopestring

Faults: 

  • InvalidUsernameOrPassword
  • AccountNotActive
  • MethodCallFailed 

Operation: GetAccountInfo

Returns information about signed in account.

Input fields:


Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenobject
RefreshAsk Cloud for updated account information and update AccountInfo state in the service cachebool


Output fields:

Output Value

Description

 Type / Validation Rules
AccountSizeStorage quota for account, byteslong
CurrentBackupServerNameAddress of the Backup Serverstring
CurrentUploadServerNameAddress of the Upload Serverstring
EmailEmail addresses string, on which email report will be sent.

string

Splitted by ';' or ' ' or ','.

EntityIdID of the Partner/Distributor, i.e. the root of the hierarchy thee.int, >=0
HasConfiguredExchangeBackupsetUser has configured Exchange backupsetbool
HasConfiguredMsSqlBackupsetUser has configured MsSql backupsetbool
IsBackupBlockedDueToAccountOverQuotaBackup is not available for current account due to exceeding the limit of the stored databool
LoginAccount Loginstring
SendEmailReportSending of the reports is enabled for accountbool
SecurityType

The type of the security for current account:

  1. Regular,
  2. Safe,
  3. UltraSafe

enum

SecurityTypeContract

UsedSpaceUsed space utilization by contained accounts, byteslong

Faults: 

  • IsNotSignedIn
  • MethodCallFailed
Example
      [Test]
        public void GetAccountInfo_Ok()
        {
            _client = new InfrascaleClient();
            _client.Connect();
            var signInResponse = _client.SignIn(new SignInRequest { Credentials = new CredentialsContract { Login = _testAccount, Password = _testAccountPassword } });

            var accountInfo = _client.GetAccountInfo(new GetAccountInfoRequest { Identity = signInResponse.Identity});
            Tools.PrintAccountInfo(accountInfo.AccountInfo);

            _client.SignOut(new SignOutRequest { Identity = signInResponse.Identity });
            _client.Disconnect();
        }
Output
Login: sdk.test@sosonlinebackup.com
Account Size: 10737418240
UsedSpace: 0
Email: sdk.test@sosonlinebackup.com
Is blocked by overquota: False
SecurityType: Regular
Send backup report by email: False

Operation: SubscribeCallback

Allows to receive notification about events are occurred in scope of specific backup account   

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenobject

Output  fields: N/A

Faults: 

  • MethodCallFailed 

Operation: UnsubscribeCallback

 Stops receiving notification about events are occurred in scope of specific backup account   

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenobject

Output  fields: N/A

Faults: 

  • MethodCallFailed 

Operation: GetJobSession

Retrieves job's state by JobId  

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenobject
JobIdIdentifies running job.string

 Output  fields: 

Output Value

Description

 
SessionState identifies current state

enum:

Undefined,
Runnig ,
Completed,
Canceled,
Failed

StartedUtcWhen job started in UTCDatreTime
CompletedUtcWhen job completedDateTime, optional
ProgressPercentageExecution progressfloat
ProcessedFilessize and count of processed filesobject
RemainingFilessize and count of remaining filesobject
FailedFilessize and count of remaining filesobject
ErrorMessageerror detailsstring

 Faults:

  •  MethodCallFailed 

Operation: RunRefreshRecoveryInfoJob

Starts RefreshRecoveryInfo job that refreshes local db of metadata by syncing it with backup server. For huge backup sets - potentially long running task

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract

 Output  fields: 

Output Value

Description

 
JobSession

 created job session with: 

  • JobId
  • AccountLogin
  • State
  • CreatedUtc
  • StartedUtc
  • CompletedUtc
  • ProgressPercentage
  • ErrorMessage

RefreshRecoveryInfoJobSessionContract

  Faults:
  •   MethodCallFailed  

Operation: GetRecoveryItems

Retrieves the list of folders and files available for recovery at specified Path. If Path is not specified returns a list of systems

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract
Filter

filter object with includes:

  • DateFrom - date, optional
  • DateTo - date, optional
  • FileSizeInKbFrom - int, optional
  • FileSizeInKbTo - int, optional
  • FileName - string, optional
  • PathFilter - string, optional

RecoveryFilterContract

PathPath of directory to load children fromstring

 Output  fields: 

Output Value

Description

 
Items

 array of recovery items which include Path and can be one of two types:

  • RecoveryDirectoryContract: additionally contains:
    • array of Children
    • Files - CountAndSizeContract of files inside (recursively) 
  • RecoveryFileContract: additionaly contains FileVersion which contains:
    • FileId
    • DeltaId
    • CreatedAt
    • SizeBytes

array of RecoveryItemContract

Faults:
  MethodCallFailed  
Example
        [Test]
        public void ExtarctAllRecoveryTree_Ok()
        {
            //Init SDK
            _client = new InfrascaleClient();
            _client.Connect();
            
            var signInResponse = _client.SignIn(new SignInRequest { Credentials = new CredentialsContract { Login = _testAccount, Password = _testAccountPassword } });

            RefreshRecoveryInfo(signInResponse.Identity);

            //Extract metadata items
            var request = new GetRecoveryItemsRequest
            {
                Identity = signInResponse.Identity,
                Path = Environment.MachineName
            };
            var output = _client.GetRecoveryItems(request);
            
            //Handle files tree
            PrintTree(output);

            //Detach client 
            _client.SignOut(new SignOutRequest { Identity = signInResponse.Identity });
            _client.Disconnect();
        }

        public static void PrintTree(GetRecoveryItemsResponse response)
        {
            Action<RecoveryItemContract, int> handleLevel = null;
            handleLevel = (treeItem, level) =>
            {
                var padding = Enumerable.Range(0, level).Aggregate(new StringBuilder(), (sb, i) => sb.Append(" "));
                var dir = treeItem as RecoveryDirectoryContract;
                if (dir != null)
                {
                    foreach (var dirItem in dir.Children)
                    {
                        if (dirItem is RecoveryDirectoryContract)
                            Console.WriteLine(padding + dirItem.Path);
                        else
                            Console.WriteLine(padding + Path.GetFileName(dirItem.Path));
                        handleLevel(dirItem, level + 1);
                    }
                }
            };

            foreach (var item in response.Items)
            {
                Console.WriteLine(item.Path);
                handleLevel(item, 0);
            }
        }

         public static void RefreshRecoveryInfo(IdentityContract identity)
        {
            _client.SubscribeCallback(new SubscribeCallbackRequest
            {
                Identity = identity
            });

            bool isCompleted = false;

            Action<JobSessionContract> isCompletedFunc = contract =>
                isCompleted = contract.JobType == JobTypeContract.RefreshRecoveryInfo;

            _client.JobCompleted += isCompletedFunc;

            _client.RunRefreshRecoveryInfoJob(new RunRefreshRecoveryInfoJobRequest { Identity = identity });

            while (!isCompleted)
            {
                Thread.Sleep(100);
            }

            _client.JobCompleted -= isCompletedFunc;
        }

Output
ALEXK\C:
ALEXK\D:
Sample filter to get items  for the last 7 days where filename contains "123", size between 1 byte and 1 megabyte and located on disc C:


var filter = new RecoveryFilterContract
                {
                    DateFrom = DateTime.Today.AddDays(-7),
                    DateTo = DateTime.Today,
                    FileName = "123",
                    FileSizeInKbFrom = 1,
                    FileSizeInKbTo = 1024,
                    PathFilter = "C:\\"
                }

Operation: RunRecoveryJob

Starts recovery job

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract
Job

job object with includes:

  • Items - array of RecoveryItemContract to be recovered 
  • RestoreDestination - folder where to put recovered files
  • ConflictResolution - sets how the file conflicts should be handled
  • IncludePath - where to include original file path
  • PassPhrase - for Ultrasafe Max accounts - for data decryption

RecoveryJobContract

 Output  fields: 

Output Value

Description

 
JobSession

 job details including RecoveryProgress 

RecoveryJobSessionContract

Faults:
  MethodCallFailed 

Event: JobStarted

Occurs when new job starts executing

Fields: 

Value

Description

Type

JobSessionContractjob detailsJobSessionContract

Event: JobProgress

Occurs when job progress is updated

 Fields: 

Value

Description

Type

JobSessionContractjob detailsJobSessionContract

Event: JobCompleted

Occurs when job is completed 

 Fields: 

Value

Description

Type

JobSessionContractjob detailsJobSessionContract

Event: JobEvents

Occurs when something is happened during backup 

 Fields: 

Value

Description

Type

JobSessionContractArray of JobEventBackupJobEventContract


Example
        [Test]
        public void ListenBackupEvents_Ok()
        {
            _client = new InfrascaleClient();
            _client.Connect();
            var signInResponse = _client.SignIn(new SignInRequest { Credentials = new CredentialsContract { Login = _testAccount, Password = _testAccountPassword } });

            _client.JobStarted += s => Tools.PrintBackupSession("Backup Started", s as BackupJobSessionContract);
            _client.JobProgress += s => Tools.PrintBackupSession("Backup Progress", s as BackupJobSessionContract);
            _client.JobCompleted += s => Tools.PrintBackupSession("Backup Completed", s as BackupJobSessionContract);

            _client.SubscribeCallback(new SubscribeCallbackRequest { Identity = signInResponse.Identity});

            _backupProcess = Tools.EmulateBackup(_testStorageDb, _storageDbBackupPath, _storageDbPath, _testAccount, _testAccountPassword, _obrmFolder);
            _backupProcess.WaitForExit(300000);

            _client.SignOut(new SignOutRequest { Identity = signInResponse.Identity });
            _client.Disconnect();
        }
Output
Event: Backup Started
JobType: Backup
ProgressPercentage: 0
CreatedUtc: 01.01.0001 0:00:00
StartedUtc: 
CompletedUtc: 
AccountLogin: 
State: Undefined
ErrorMessage: 


Event: Backup Completed
JobType: Backup
ProgressPercentage: 0
CreatedUtc: 01.01.0001 0:00:00
StartedUtc: 
CompletedUtc: 
AccountLogin: 
State: Undefined
ErrorMessage: 
Processed Files Count: 0
Processed Files Size: 0
Remaining Files Count: 0
Remaining Files Size: 0
Uploaded Files Count: 0
Uploaded Files Size: 0
Unchanged Files Count: 120
Unchanged Files Size: 3972
Failed Files Size: 0
Failed Files Size: 0

Data Contracts

JobSessionContract

Represents the job state

Fields: 

Value

Description

Type

JobIdIdentifies jobstring

SessionState

Identifies current state

enum SessionStateContract:

Undefined,
Runnig ,
Completed,
Canceled,
Failed

AccountLoginLogin of account who's running the jobstring
CreatedUtcWhen job was created in UTCDateTime
StartedUtcWhen job started in UTCDatreTime
CompletedUtcWhen job completedDateTime, optional
ProgressPercentageExecution progressfloat
ErrorMessageError detailsstring
JobType

enum JobTypeContract: 

None,
Backup,
Recovery,
RefreshRecoveryInfo,

CountAndSizeContract

Represents couint and size of files

Fields: 

Value

Description

Type

CountNumber of fileslong

SizeBytes

Size of files in bytes

long

Operation: SetOnlineBackupSettings

Save Online Backup settings to the settings storage

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract
Settings

Online backup settings with includes:

  • ProtectFileset - FilesetContract with items to be protected 
  • NetShares - NetShareContract array with description of network shares, included to filesets
  • other fields, are not implemented yet

OnlineBackupSettingsContract


Output fields (SetOnlineBackupSettingsResponse): 

Parameter

Description

Type / Validation Rules

IsWarning

If cleanup of existing settings was not succeed

New settings do not apply to the database in this case

bool
WarningDetailsDescription of warnings during cleanup procedurestring

Faults:
  MethodCallFailed 

Data Contracts

FileSetContract

Parameter

Description

Type / Validation Rules

IncludedDirs

Array of FilesetDirContract

List of directories to include to backupset

FilesetDirContract
IncludedFiles

Array of FilesetFileContract

List of files to include to backupset

FilesetFileContract

Excludes

Array of FilesetExcludeItemContract

List of filesystem items (files or folders) to exclude from backupset

FilesetExcludeItemContract

FilesetDirContract

Parameter

Description

Type / Validation Rules

Path

Path to backupset directory.

If directory located on the mapped drive, use full network path.
Example: D:\ is a network drive, mapped to network path \\server\share.
Use \\server\share\directory instead of D:\directory

string

FilesetFileContract

Parameter

Description

Type / Validation Rules

Path

Path to backupset file.

If file located on the mapped drive, use full network path.
Example: D:\ is a network drive, mapped to network path \\server\share.
Use \\server\share\1.txt instead of D:\1.txt

string

FilesetExcludeItemContract

Parameter

Description

Type / Validation Rules

Path

Path to filesystem item, which will been skipped during backup.

No difference betwen excluded file or excluded directory.

string

NetShareContract

Parameter

Description

Type / Validation Rules

RemoteName

Remote name of the network share (remote path)

string
Credentials

Credentials for access to the Network share

CredentialsContract

Operation: GetOnlineBackupSettings

Get Online Backup settings from the settings storage

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract

 Output fields (GetOnlineBackupSettingsResponse): 

Parameter

Description

Type / Validation Rules

Settings

Online backup settings with includes:

  • ProtectFileset - FilesetContract with items to be protected 
  • NetShares - NetShareContract array with description of network shares, included to filesets
  • other fields, are not implemented yet
OnlineBackupSettingsContract

Faults:
  MethodCallFailed 

Operation: RemoveOnlineBackupSettings

Remove existing Online Backup settings from the settings storage

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract

 Output fields (RemoveOnlineBackupSettingsResponse): 

Parameter

Description

Type / Validation Rules

IsWarning

Only if ResetExistingSettings is set

true, if cleanup of existing settings was not succeed

New settings do not apply to the database in this case

bool
WarningDetailsDescription of warnings during cleanup procedurestring

Faults:
  MethodCallFailed 

Operation: RunOnlineBackupJobRequest

Add new Online Backup job request using existing settings

 Input fields: 

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract
ConfigurationConfiguration of the new backup jobOnlineBackupJobContract

 Output fields: RunOnlineBackupJobResponse (Nested from JobSessionContract)

Faults:
  MethodCallFailed 

Data Contracts

OnlineBackupJobContract

Parameter

Description

Type / Validation Rules

WindowsUser

Name of the current windows user.

Is required to impersonate from user of the backup service to get access to all user files

string
CallingProcessName

Name of the process, which running under requested windows user rights.

Is required to impersonate from user of the backup service.

As usual, this is the CurrentProcess.Name of the assembly, which calling SDK

string

EndTime

Time, when backup service should cancel current backup.

When is reached, backup service completing current part of backup and safely cancel backup.

If not set - no time limit for completion of backup.

DateTime
Other fileldsIs not implemented yet

BackupJobEventContract

Backup engine reports about some operations, such as new backup request, starting of the calculation of the files hashes, skipping excluded files, issues etc.

This events is collected in the engine and after that SDK reports. Due to report threshold SDK can report about several events in the one callback.

Parameter

Description

Type / Validation Rules

EventTime

Time of event

DateTime
MessageType

Type of the message

  • Info
  • Notify
  • Warning
  • Error

MessageTypeContract

Message

Event message

String

BackupJobProgressContract

This event is sent in the BackupStarted and BackupProgress callbacks.

In the BackupCompleted callback this event include whole backup summary report.

Parameter

Description

Type / Validation Rules

FailedFiles

Quantity and size of files, which was failed

CountAndSizeContract
UploadedFilesQuantity and size of files, which was uploaded to serverCountAndSizeContract
UnchangedFilesQuantity and size of files, which have not changed since last backupCountAndSizeContract
TotalFilesTotal quantity and size of all processed and failed filesCountAndSizeContract
BackupSetFilesTotal quantity and size of files, included to current backup procedureCountAndSizeContract
ModifiedFilesQuantity and size of files, which was modified since last backupCountAndSizeContract
FileStates

Array of the FileStateContract. This files is in progress right now.

Array, because backup can process several files simultaneously.

Existing just for show 'small' progress, shows only files, processed right now, without collecting of whole history.

Some files can be excluded from this array, if they was completed between collection ticks.

FileStateContract

FileStateContract

Parameter

Description

Type / Validation Rules

Name

Name of file

string
Status

Description of the file status (localized)

string

TotalSizeBytes

Total size of file, bytes

long
CompletedSizeBytesCompleted size, byteslong

Operation: PauseOnlineBackupJobRequest

Pause the current backup session.

Pausing the current backup session, regardless of who launched it.

If there are other requests for backup in the queue, they will be paused too.

In the absence of active sessions, the Pause does nothing.

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract

Operation: ResumeOnlineBackupJobRequest

Resume the current backup session (if paused).

Resume the current backup session after pausing, regardless of who launched/paused it.

In the absence of active sessions, the Resume does nothing.

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract

Operation: CancelOnlineBackupJobRequest

Cancel the current backup session.

Cancels the current backup session, regardless of who launched it.

If there are other requests for backup in the queue, they will be executed immediately after the current session is canceled.

In the absence of active sessions, the Cancel does nothing.

Parameter

Description

Type / Validation Rules

Identityidentity object with valid tokenIdentityContract