Public APIs
- Alexey Turchanikov (Unlicensed)
- Dmytro Tsaryk
- TK (Deactivated)
- 1 Account Management
- 2 Entity Management
- 3 Partner Management
- 4 Company Management
- 5 User Account Management
- 6 Policy management
- 6.1.1 Object: EntityPolicy
- 6.2 Policy object in response
- 6.2.1 Operation: CreateEntityPolicy / GetEntityPolicy
- 6.2.2 Operation: GetEntityPoliciesAll / GetEntityPolicies
- 6.2.3 Operation: UpdateEntityPolicy / DeleteEntityPolicy
- 6.2.4 Operation: AddAccountPolicy
- 6.2.5 Object: AccountPolicy
- 6.2.6 Operation: AddAccountPolicySimple
- 6.2.7 Operation: GetAccountPolicies
- 6.2.8 Operation: DeleteAccountPolicy / DeleteAccountPolicySilent
- 7 Policy management (Advanced)
- 7.1 Some terms & rules: BackupSet, Scanner & etc
- 7.2 Object: CustomPathes
- 7.3 Operation: GetScannerCustomPathes
- 7.4 Operation: SetScannerCustomPathes
- 7.5 Operation: GetBackupSetCustomPathes
- 7.6 Operation: SetBackupSetCustomPathes
- 7.7 Object: FileSizeLimit
- 7.8 Operation: GetScannerFileSizeLimits
- 7.9 Operation: SetScannerFilesizeLimits
- 8 Product Licenses Management
- 9 Entities Monitoring
- 10 Appliances Management
- 11 Folder Backup Management
- 12 Backup Devices Management
- 13 Cloud Application Backup Management
All production endpoints have their version on sandbox with changed domain names:
Application | Production (Live) | Sandbox |
|---|---|---|
Dashboard | ||
Account Management APIs |
NB: APIs might be a bit raw, but we’d like to give you a chance to try using them ASAP.
You have to pass API credentials to all methods via SOAP AuthHeader.
We have following services in our public Web API
Service Self-Documentation | WSDL |
|---|---|
NB. * means new or "coming soon" feature
Following is a archive with a straight forward usage example on C# (.Net Framework 2.0) with autogenerated by Visual Studio proxy
We don't recommend to use autogenerated by Visual Studio proxy classes. It's here only for sake of fast start and learning purposes.
All our web methods return standard Result object (lines 5-9).
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<CreateAdditionalAdminResponse xmlns="sosonlinebackup.com">
<CreateAdditionalAdminResult>
<Result>
<Result>52</Result>
<Code>AlreadyExists</Code>
<Message>Err-5e24e99f-071a-4463-84eb-b42fc24e1de3;</Message>
</Result>
</CreateAdditionalAdminResult>
</CreateAdditionalAdminResponse>
</soap:Body>
</soap:Envelope>
Following are the most common result codes.
Result.Result | Result.Code | Description (not returned in the response) |
|---|---|---|
0 | Success | Everything is OK. Web method has been executed without errors. |
3
| InvalidSoapCredentials
| Invalid auth header, i.e. invalid username or password |
Attempt to use inactive entity or entity not from your hierarchy | ||
One of the fields in request is invalid. Check Result.Message for more details. | ||
Unexpected error had appeared on our site. Try again later. If it's not gone contact support team. | ||
We encourage you to use native for your programming language libraries and frameworks those allow easily call soap web methods using wsdl file provided by us.
Below we show how requests to our API should look like. Usually this will be generated automaticaly by soap framework choosed by you.
Http headers will be generated similar to following
Account Management
=Plenty of old web methods=
Production: http://secure.sosonlinebackup.com/WebApi/AccountManagementService/AccountManagementService.asmx
Check links above. There are plenty of old web methods not covered by this page yet.
Operation: UncancelAccount (added on November 2019)
Activates cancelled backup account.
Important notes:
System cleanups data hold by cancelled account after some grace period. For instance, backed up files are automatically deleted in about 3 month, licences usually get deactivated in about 7 days and so on. Uncancel operation won't revert any of those, or similar, purge actions when they are already partially or fully completed by the date of uncancel. It only marks account as active and allows you to reuse it again.
Input request fields:
Parameter | Description | Validation |
|---|---|---|
Username | Username, aka AccountName. It's globally unique | String |
UncanelReason | Reason for uncancel backup account. | String, Optional |
SendEmailToCustomer | When set true backup account will get email notification on successful uncancel. BEFORE set it to true, go to Dashboard and check your email templates. Ensure you have one with the code 'UMSUNCANCEL'. If you don't have it try to load parents'/Infrascale ones using button 'Add missing email templates' | Bool |
Request example:
Request
Output result fields:
Returns only result code.
Important custom result codes.
Result.Result | Result.Code | Description (not returned in the response) |
|---|---|---|
Attempt to use account not from your hierarchy. OR Attempt to use account from unmanaged entity hierarchy OR Attempt to use account from cancelled entity | ||
Username format is not valid OR Attempt to use unknown Username | ||
Backup account is already NOT cancelled | ||
5020 | CannotSendEmail | Account has been uncancelled, but we could not send email to backup account. |
Response example:
Entity Management
Operation: GetEntityHierarchy
it will provide sufficient info to build an entity tree on the client side
Input request fields
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the Partner/Distributor, i.e. the root of the hierarchy thee. | Int, >=0. Use 0 for yourself. |
IncludeInactive | When true the output will include canceled, suspended and other types of not active entities | Bool |
ConnectwiseIntegratorEntityID | EntityID for which Connectwise is configured. If not set, then TargetEntityID used instead | Int, Optional |
Returns an array of the rows. Each output row has following format.
Output Value | Description | Validation |
|---|---|---|
EntityID | ID of the Entity | Int, >0. |
EntityName | Internal name of the entity | String |
ParentEntityID | Parent for the entity | Int, >0. |
DistributorEntityID | ID of the Distributor | Int, >0. |
PartnerEntityID | ID of the Partner | Int, >=0. 0 means direct Company of the Distributor or Distributor itself. |
CompanyEntityID | ID of the Company | Int, >=0. 0 means Partner of the Distributor. |
EntityType | Entity type | Infrascale, Distributor, Partner, Company, Unknown |
IsActive | True, when entity is active | Bool |
ConnectWiseTicketingCompanyId | Connectwise company identifier | String |
Example of the output when target entity is distributor.
EntityID | EntityName | ParentEntityID | DistributorEntityID | PartnerEntityID | CompanyEntityID | EntityType | IsActive |
|---|---|---|---|---|---|---|---|
888 | SomeDistributor | 1 | 888 | 0 | 0 | Distributor | true |
111 | SomeDistrCompany | 888 | 888 | 0 | 111 | Company | true |
112 | OtherDistrCompany | 888 | 888 | 0 | 112 | Company | false |
221 | SomePartner1 | 888 | 888 | 221 | 0 | Partner | true |
311 | Company1OfPartner1 | 221 | 888 | 221 | 311 | Company | true |
312 | Company2OfPartner1 | 221 | 888 | 221 | 312 | Company | true |
225 | SomePartner2 | 888 | 888 | 225 | 0 | Partner | false |
226 | SomePartner3 | 888 | 888 | 226 | 0 | Partner | true |
321 | Company1OfPartner3 | 226 | 888 | 226 | 321 | Company | false |
The distributor in the example has
ID = 888 and it's root node for the request (TargetEntityID =0 or TargetEntityID =888 ).
Two direct companies (111, 112)
Three partners (221, 225, 226)
Partner 221 with two companies (311, 312 )
Partner 225 with no companies
Partner 226 with one company (321 )
Example of the output when target entity is partner
EntityID | EntityName | ParentEntityID | DistributorEntityID | PartnerEntityID | CompanyEntityID | EntityType | IsActive |
|---|---|---|---|---|---|---|---|
221 | SomePartner1 | 888 | 888 | 221 | 0 | Partner | true |
311 | Company1OfPartner1 | 221 | 888 | 221 | 311 | Company | true |
312 | Company2OfPartner1 | 221 | 888 | 221 | 312 | Company | true |
The partner in the example has
ID = 221 and it's root node for the request.
Two companies (311, 312 )
Example of the output when target entity is company
EntityID | EntityName | ParentEntityID | DistributorEntityID | PartnerEntityID | CompanyEntityID | EntityType | IsActive |
|---|---|---|---|---|---|---|---|
312 | Company2OfPartner1 | 221 | 888 | 221 | 312 | Company | true |
Operation: GetEntityDirectAccounts
Provides a list of direct entity accounts
Input request fields
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the Partner/Distributor, i.e. the root of the hierarchy thee. | Int, >=0. Use 0 for yourself. |
IncludeInactive | When true the output will include canceled, suspended and other types of not active accounts | Bool |
PageSize | Number of rows per page. | int <= 5000 |
PageIndex | Identifies 1-based index of data frame. Data are sorted by Username. | Int, >=1. |
Returns following object
Output Value | Description | Validation |
|---|---|---|
TotalRecords | Total accounts in the entity | int, >=0 |
Accounts | Array of the rows with account info | AccountInfo[] |
Each output row in the Accounts field has following format.
Output Value | Description | Validation |
|---|---|---|
Username | Username, aka AccountName. It's globally unique | String |
IsActive | True, when user is active | Bool |
IsEntityAdmin | True, when user is entity admin of the target entity | Bool |
SignupDate | Account sign up date | DateTime |
Account email | String | |
IsMonitored | True, when user backup activity is monitored in our databases. | Bool |
IsEndGuardEnabled | True, when user has EndGuard™ enabled. | Bool |
Operation: GetEntityAccounts
Provides a list of all active accounts in the entity tree. For each account it counts number of active devices on each OS "protected"* with our software.
Device can be deactivated on the dashboard. It's re-activated automatically with each login (interactive or non-interactive) of user on the device.
Input request fields
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the Partner/Distributor, i.e. the root of the hierarchy thee. | Int, >=0. Use 0 for yourself. |
PageSize | Number of rows per page. | int <= 10000 |
PageIndex | Identifies 1-based index of data frame. Data are sorted by ParentEntityID, EntityID, Username. | Int, >=1. |
Returns following object
Output Value | Description | Validation |
|---|---|---|
TotalRecords | Total accounts in the entity | int, >=0 |
Accounts | Array of the rows with account info | AccountDevicesInfo[] |
Request
Each output row in the Accounts field has following format.
Output Value | Description | Validation |
|---|---|---|
ParentEntityID | ID of the Entity who owns entity that owns this account. | Int, >0. |
EntityID | ID of the Entity who owns this account. | Int, >0. |
Username | Username, aka AccountName. It's globally unique | String |
IsEntityAdmin | True, when user is entity admin of the entity indicated by EntityID | Bool |
SignupDate | Account's sign up date | DateTime |
Account's email | String | |
FullName | Account's full name | Bool |
WindowsDevicesTotal | Total number of "protected"* devices with Windows OS. | Int, >=0. |
AndroidDevicesTotal | Total number of "protected"* devices with Android OS. | Int, >=0 |
MacDevicesTotal | Total number of "protected"* devices with Mac OS. | Int, >=0 |
UsedSpaceKB | Space utilization by account | long, >=0 |
AccountSizeMB | Storage quota for account | long, >0 |
* "Protected" here only means that device had our software installed and successfully authorized on it at least once.
Response
Operation: GetAccountEntities
will provide info about account's place in the entity hierarchy, i.e his distributor, partner, company and direct parent
Input request fields
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the Partner/Distributor, i.e. the root of the hierarchy thee. | Int, >=0. Use 0 for yourself. |
Username | Backup account unique ID, aka Username (AccountName) | String, "^[^<>]{0,100}$" |
Returns following object
Output Value | Description | Validation |
|---|---|---|
DistributorEntityID | ID of the Distributor | Int, >0. |
PartnerEntityID | ID of the Partner | Int, >=0. 0 means direct Company of the Distributor or Distributor itself. |
CompanyEntityID | ID of the Company | Int, >=0. 0 means Partner of the Distributor or Distributor itself. |
ParentEntityType | Entity type | Infrascale, Distributor, Partner, Company, Unknown |
ParentEntityID | ID of the direct account Entity. It either DistributorEntityID, PartnerEntityID or CompanyEntityID. | Int, >0. |
IsAccountActive | True, when entity is active | Bool |
IsEntityAdmin | True, when user is entity admin of the parent entity | Bool |
DistributorName | Internal name of the Distributor | String. |
PartnerName | Internal name of the Partner | String. Empty string means direct Company of the Distributor or Distributor itself. |
CompanyName | Internal name of the Company | String. Empty string means Partner of the Distributor or Distributor itself. |
ParentName | Internal name of the Parent | String |
SignupDate | Account sign up date | DateTime |
Account email | String | |
IsMonitored | True, when user backup activity is monitored in our databases | Bool |
IsEndGuardEnabled | True, when user has EndGuard™ enabled. | Bool |
IsParentEntityActive | True, when account entity is active | Bool |
Operation: CancelEntity
Permanently removes entity (Partner, Company or Partner's Company) and all descendant accounts/companies in target entity hierarchy :
All active accounts will be cancelled permanently.
All active sub-companies will be cancelled permanently.
All Shadow Protect v5 licenses will be transferred to caller's entity.
Warning: Accidentally cancelled entity cannot be activated again by API call. are hard and tedious to reactivate again (see Uncancel operation for details).
Infrascale Customer Support team can do it, but it will take some time (days).
CancelEntity (unlike SuspendEntity) is NOT fully revertible operation because it DOES release resource (disk space, licenses & so on) held by entity.
Request:
Parameter | Description | Validation |
|---|---|---|
TargetEntityId | ID of the Partner/Company to cancel | Int > 0 , Caller cannot cancel itself. Parent only can cancel it's child entities |
Request example:
Response:
Output Value | Description | Type |
|---|---|---|
AlreadyCanceled | Re-enterability flag. It is set if attempt is taken to cancel already canceled entity | bool |
Response example:
Operation: UncancelEntity (added on November 2019)
Marks entity as active again. If entity is company and it has backup account administrator of this entity it'll un-cancelled automatically.
Important notes:
It's not full rollback operation to CancelEntity because it doesn't:
uncancel entities in hierarchy
uncancel direct backup accounts
uncancel backup accounts in hierarchy
return revoked licences
so on
Also take note that system cleanups data hold by cancelled accounts & entities after some grace period. For instance, backed up files are automatically deleted in about 3 month, used licences usually get deactivated in about 7 days, unused licences get transferred to parent entity immediately and so on. Uncancel operation won't revert any of those or similar purge actions those already partially or fully completed by the date of uncancel. It only marks entity as active and allows you to reuse it again.
Input request fields:
Parameter | Description | Validation |
|---|---|---|
TargetEntityId | ID of the Partner/Company to uncancel | Int > 0 , Caller cannot uncancel himself. |
Request example:
Request
Output response fields:
Returns only result code.
Important custom result codes.
Result.Result | Result.Code | Description (not returned in the response) |
|---|---|---|
Attempt to use entity not from your hierarchy. OR Attempt to use entity from unmanaged entity hierarchy OR Attempt to use not existing entity | ||
Entity is not Cancelled but Expired, i.e. trial period has ended. | ||
Backup account is already NOT cancelled |
Response example:
Operation: SuspendEntity
Suspends entity (Partner, Company or Partner's Company).
SuspendEntity (unlike CancelEntity) is fully revertible operation because it doesn't release any resource (disk space, licenses & so on) held by entity .
Suspended entities can be activated again by API call (see ActivateEntity).
Request:
Parameter | Description | Validation |
|---|---|---|
TargetEntityId | ID of the Partner/Company to cancel | Int > 0 , Caller cannot cancel itself. Parent only can cancel it's child entities |
Request example:
Response:
Output Value | Description | Type |
|---|---|---|
AlreadySuspended | Re-enterability flag. It is set if attempt is taken to suspend already suspended entity | bool |
Operation: ActivateEntity
Activates suspended entities (Partner, Company or Partner's Company)
Request:
Parameter | Description | Validation |
|---|---|---|
TargetEntityId | ID of the Partner/Company to cancel | Int > 0 , Caller cannot cancel itself. Parent only can cancel it's child entities |
Request example:
Response:
Output Value | Description | Type |
|---|---|---|
AlreadyActivated | Re-enterability flag. It is set if attempt is taken to activate already active entity | bool |
Request example:
Operation: AuthenticateDashboardUser (added on July 2019)
Authenticates Dashboard user from your hierarchy. Returns information about it and his temporary security token.
Request:
Parameter | Description | Validation |
|---|---|---|
UserName | Login name for dashboard user. | Required, "^(?!^\d+(WS|Ws|wS|ws|FL|Fl|fL|fl)$)(?!^(U|u)\d+$)[a-zA-Z0-9@\._-]{3,50}$" |
Password | Password of the dashboard user | Required, "^[a-zA-Z0-9!@#$%^&*()]{6,20}$" |
Request example:
Response:
Output Value | Description | Type |
|---|---|---|
EntityId | Entity ID of given dashboard user. It unique identifies dashboard company/partner/distributor | int, >0 when set |
ParentEntityId | Entity ID of the parent company for given dashboard user. It unique identifies dashboard company/partner/distributor | int, >0 when set |
LocaleId | Preferable language for UI for this user. Following is a list of supported languages as on now
| int, >0 when set |
IsManaged | Are you able to modify parameters and objects controlled by this entity. E.g. backup accounts, ICAB accounts, appliances and so on. When it's false you have read-only access. | bool |
AuthenticationToken | Internal temporarily security token. Might be useful for some new web methods. | string, null-able |
ValidTillUtcDate | Expiration date in UTC for AuthenticationToken. | datetime, null-able |
Following are important result codes (in addition to listed at the top of the page).
Result.Result | Result.Code | Description (not returned in the response) |
|---|---|---|
Provided dashboard username is not found or provided password is not valid. | ||
Either provided dashboard user is not active or his entity (aka dashboard company) is not active or his entity trial period is ended | ||
53 | ObjectEntityMismatch | This account is not from your hierarchy, i.e. it's not your partner. You won't be able to manage it using you Web API credential. You don't have even read access to his data. |
Response example:
Partner Management
Operation: CreatePartner
*Can break compatibility even in a case of unbreakable changes. Requires special notification*
Parameter | Description | Validation |
|---|---|---|
PartnerName | Non-unique identifier of partner. Max 50 characters according to the regular expression provided. | Required,"^[a-zA-Z0-9]([a-zA-Z0-9\.-_\s&]){0,48}([a-zA-Z0-9\.]){1}$" |
GeneralContactPerson | Name of contact person | Required, "^[a-zA-Z]([a-zA-Z\.-]|\s){1,49}$" |
GeneralContactEmail | Required, "^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,}){1,49}$" | |
DiskQuotaGB | Storage quota for partner | Integer >= 1 |
AllowUploadOverAccountSize | Bool | |
AutoUpgradeClientApp | Indicates if all accounts of new partner will use automatic update of client software | bool , Optional, false if missed |
SendResetPasswordEmail | If true, email with reset password link is sent to user. See details about reset password link in SendResetPasswordLink method description | bool , Optional, false if missed |
Return ID of created partner and dashboard user name.
Operation: SendResetPasswordLink
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the Partner/Company/Distributor where you want to reset password for admin | Int, >=0. Use 0 for yourself. |
Returns dashboard user which will get reset password link .
Email is sent to GeneralContactEmail provided on partner creation.
The look and content of reset password email you can configure in the dashboard
https://dashboard.managedoffsitebackup.net/EmailTemplate/Edit?code=EntityResetPwd&localeID=1
https://dashboard.managedoffsitebackup.net/EmailTemplate (template with code "EntityResetPwd")
By default, for security sake, dashboard user name is not sent in email.
It means user must already know his user name, or you should inform him using other channels (e.g. phone, skype and so on).
Also, if you wish, you can add user name into email using place-holder "#?UserName?#" (check image above)
Reset password link valid
until next one is generated
until it's is used
no longer then one day
Current password of user is valid and not changed until someone will follow the link and provide new password (there is a web form with button).
Operation: CreateAdditionalAdmin
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the Partner/Company/Distributor where new administrator is needed | Int, >=0. Use 0 for yourself. |
UserName | Login name for dashboard. Names like 2222WS, 2222FL and U2222 are forbidden here. | Required, "^(?!^\d+(WS|Ws|wS|ws|FL|Fl|fL|fl)$)(?!^(U|u)\d+$)[a-zA-Z0-9@\._-]{3,50}$" |
Password | Password, leave it empty if you want system to generate it | Optional, "^[a-zA-Z0-9!@#$%^&*()]{6,20}$" |
Returns generated password and standard Result object. Can return following custom result codes.
Result.Result | Result.Code | Description (not returned in the response) |
|---|---|---|
User with this name already exists in some entity. Try to pick up another user name. |
Operation: EditPartner
*Can break compatibility even in a case of unbreakable changes. Requires special notification*
Parameter | Description | Validation |
|---|---|---|
PartnerEntityId | Partner ID | Integer >= 1 |
GeneralContactPerson | Name of contact person | "^[a-zA-Z]([a-zA-Z\.-]|\s){1,49}$" |
GeneralContactEmail | "^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,}){1,49}$" | |
DiskQuotaGB | Storage quota for partner | Nullable Integer >= 1 |
AllowUploadOverAccountSize | Nullable Bool | |
AutoUpgradeClientApp | Indicates if all accounts of partner will use automatic update of client software | bool , Optional, no changes if missed |
SetAutoUpgradeClientAppForChildren | Indicates if AutoUpgradeClientApp is also set for partner companies | bool , Optional, false if missed |
Operation: GetCompaniesSummary
*Can break compatibility even in a case of unbreakable changes. Requires special notification*
Retrieves general information about partner's companies
Parameter | Description | Validation |
|---|---|---|
PartnerEntityId | Identifies Partner for which all companies info is extracted | Int It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
|
Returns result as array where each item contains following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
CompanyEntityId | Identifies company | int | |
CompanyName | Name of company | string | |
DiskQuotaGB | Disk space quota for company | long | GB |
UsedSpaceKB | Used space utilization by contained accounts | Long | Kilobytes |
AllocatedSpaceMB | Space allocation by contained accounts | Long | Megabytes |
NumberOfAccounts | Number of active accounts(AVG devices) | int | |
NumberOfLicensesShadowProtectV5 | Number of ShadowProtect Licenses assigned to company | int | |
DataCenterCountryCodeIsoA2 | ISO 3166-1 two-letter country code (alpha-2). Shows location of data center, where company backup accounts are created. | string | |
NumberOfMobileDevices | Number of mobile devices for active accounts | int | |
NumberOfDesktopDevices | Number of desktop devices for active accounts | int |
Operation: GetPartnerDetails
*Can break compatibility even in a case of unbreakable changes. Requires special notification*
Retrieves detailed information about specific partner
Parameter | Description | Validation |
|---|---|---|
PartnerEntityId | Identifies partner. | Int It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
if 0 , ApiCallerEntityId is used for Partner identification |
Returns result with following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
PartnerEntityId | EntityId of partner | Int | |
PartnerName | Name of partner | String | |
DiskQuotaGB | Quota(Backup plan of Partner) | Long | Gigabytes |
NumberOfLicensesShadowProtectV5 | Number of licenses assigned to partner | Int | |
AllowUploadOverAccountSize | Shows if accounts are able to exceed partner's quota | Boolean |
Operation: GetPartnerDetailsByApplicationUser
Retrieves detailed information about specific partner by Partner Dashboard Administrator credentials
Request example:
Returns result with following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
PartnerEntityId | EntityId of partner | Int | |
PartnerName | Name of partner | String | |
DiskQuotaGB | Quota(Backup plan of Partner) | Long | Gigabytes |
NumberOfLicensesShadowProtectV5 | Number of licenses assigned to partner | Int | |
AllowUploadOverAccountSize | Shows if accounts are able to exceed partner's quota | Boolean |
Response example:
Operation: CancelEmptyPartner
Completely removes entity from system. Partner's entity should be empty. It cannot contain companies, licenses.
Disk quota of canceled partner is excluded from allocated space of parent distributor.
If Partner is not empty, error EntityIsNotEmpty error code is returned.
Parameter | Description | Validation |
|---|---|---|
PartnerEntityId | Identifies partner to cancel. | Int > 0 It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following condition is validated:
|
Reason | Description of reason | String, optional, MaxLength = 500 |
Returns following output:
Output Value | Description | Type |
|---|---|---|
AlreadyCanceled | Re-enterability flag. It is set if attempt is taken to cancel already canceled partner | bool |
Operation: MoveCompany
*Can break compatibility even in a case of unbreakable changes. Requires special notification*
Distributor can move Company with all resources(accounts, licenses) from source Partner to destination Partner
All non-direct account backup policies (i.e. when entity backup policy belongs to the parent entity ) will be unassigned.
Parameter | Description | Validation |
|---|---|---|
CompanyEntityId | Identifies company to move. | Int > 0 It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following condition is validated:
|
FromPartnerEntityId | Identifies Partner's entity which is current owner for CompanyEntityId | Int > 0 It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following condition is validated:
|
ToPartnerEntityId | Identifies Partner's entity which is new owner for CompanyEntityId | Int > 0 It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following condition is validated:
|
IncreaseQoutaOfDestinationPartner | If flag is set, quota of entity identified by ToPartnerEntityId should be increased by quota of moving Company | Boolean. If false(default), quota size of ToPartnerEntityId is validated: ToPartnerEntityId.FreeSpace >= CompanyEntityId.DiskQuotaSize |
Company Management
Operation: CreateCompany
*Can break compatibility even in a case of unbreakable changes. Requires special notification*
Parameter | Description | Validation |
|---|---|---|
TargetEntityId | ID of the parent Partner | Required, integer |
CompanyName | Required,"^[a-zA-Z0-9]([a-zA-Z0-9\.-_\s&]){0,48}([a-zA-Z0-9\.]){1}$" | |
GeneralContactPerson | Name of contact person | Required, "^[a-zA-Z]([a-zA-Z\.-]|\s){1,49}$" |
GeneralContactEmail | Required, "^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,}){1,49}$" | |
DiskQuotaGB | Storage quota for company | Integer >= 1 |
AllowUploadOverAccountSize | Bool | |
DataCenterCountryCodeIsoA2 | ISO 3166-1 two-letter country code (alpha-2) | Optional, string, can be empty. Now available data centers in following countries: US - UNITED STATES GB -UNITED KINGDOM AU -AUSTRALIA CA -CANADA ZA -SOUTH AFRICA DE -GERMAN If not set or empty, when backup account is created for company, backup server will be selected automatically. If parameter is correct country code, all backup accounts of this entity will persist data in scope of data centers restricted by region of specific country. If parameter is correct country code, but there are no data centers in that country, error is fired ( err-code: CannotFindDataCenterForCountry) If parameter is not correct ISO 3166-1 two-letter country code,error is fired( err-code: InvalidInputParameters) Availability of non US backup servers should be discussed during sales by dedicated request to Account Manager |
AutoUpgradeClientApp | Indicates if all accounts of new company will use automatic update of client software | bool , Optional, false if missed |
Allow to disable sending all emails notifications | bool , Optional, false if missed |
Returns ID of created company.
Returns CannotFindDataCenterForCountry error code if there are no data centers in country specified by parameter "DataCenterCountryCodeIsoA2"
Operation: CreateCompanyWithBackupAccount
Parameter | Description | Validation |
|---|---|---|
CompanyName | Required,"^[a-zA-Z0-9]([a-zA-Z0-9\.-_\s&]){0,48}([a-zA-Z0-9\.]){1}$" | |
TargetEntityId | ID of the parent Partner | Required, integer |
DiskQuotaGB | Storage quota for company | Integer >= 1 |
Required, "^[a-zA-Z]([a-zA-Z\.-]|\s){1,30}$" | ||
Required, "^[^<>]{0,100}$" | ||
Required, "^[a-zA-Z0-9!@#$%^&*()]{6,20}$" | ||
Standard or Ultrasafe security | Bool | |
Required, "^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,}){1,49}$" | ||
Bool | ||
DataCenterCountryCodeIsoA2 | ISO 3166-1 two-letter country code (alpha-2) | Optional, string, can be empty. Now available data centers in following countries: US - UNITED STATES GB -UNITED KINGDOM AU -AUSTRALIA CA -CANADA ZA -SOUTH AFRICA If not set or empty, when backup account is created for company, backup server will be selected automatically. If parameter is correct country code, all backup accounts of this entity will persist data in scope of data centers restricted by region of specific country. If parameter is correct country code, but there are no data centers in that country, error is fired ( err-code: CannotFindDataCenterForCountry) If parameter is not correct ISO 3166-1 two-letter country code,error is fired( err-code: InvalidInputParameters) Availability of non US backup servers should be discussed during sales by dedicated request to Account Manager |
AutoUpgradeClientApp | Indicates if all accounts of new company will use automatic update of client software | bool , Optional, false if missed |
Allow to disable sending all emails notifications | bool , Optional, false if missed |
Returns ID of created company.
Returns CannotFindDataCenterForCountry error code if there are no data centers in country specified by parameter "DataCenterCountryCodeIsoA2"
Operation: CreateAdditionalAdmin
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the Partner/Company/Distributor where new administrator is needed | Int, >=0. Use 0 for yourself. |
UserName | Login name for dashboard. Names like 2222WS, 2222FL and U2222 are forbidden here. | Required, "^(?!^\d+(WS|Ws|wS|ws|FL|Fl|fL|fl)$)(?!^(U|u)\d+$)[a-zA-Z0-9@\._-]{3,50}$" |
Password | Password, leave it empty if you want system to generate it | Optional, "^[a-zA-Z0-9!@#$%^&*()]{6,20}$" |
Returns generated password and standard Result object. Can return following custom result codes.
Result.Result | Result.Code | Description (not returned in the response) |
|---|---|---|
User with this name already exists in some entity. Try to pick up another user name. |
Operation: EditCompany
*Can break compatibility even in a case of unbreakable changes. Requires special notification*
Parameter | Description | Validation |
|---|---|---|
CompanyEntityId | Company ID | Required, Integer, > 0 |
GeneralContactPerson | Name of contact person | optional, string, "^[a-zA-Z]([a-zA-Z\.-]|\s){1,49}$" If missed, current value is not changed. |
GeneralContactEmail | optional, string, "^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,}){1,49}$" If missed, current value is not changed. | |
DiskQuotaGB | Storage quota for partner | Optional, Integer, > 0 If missed, current value is not changed. |
AllowUploadOverAccountSize | optional, Bool If missed, current value is not changed. | |
DataCenterCountryCodeIsoA2 | ISO 3166-1 two-letter country code (alpha-2) | Optional, string, can be empty. Now available data centers in following countries: US - UNITED STATES GB -UNITED KINGDOM AU -AUSTRALIA CA -CANADA ZA -SOUTH AFRICA If missed, current value is not changed. If empty, backup server for new backup accounts will be selected automatically . If parameter is correct country code, all new backup accounts of this entity will persist data in scope of data centers restricted by region of specific country.Existing backup accounts will continue use back servers assigned when account was created. If parameter is correct country code, but there are no data centers in that country, error is fired ( err-code: CannotFindDataCenterForCountry) If parameter is not correct ISO 3166-1 two-letter country code,error is fired( err-code: InvalidInputParameters) Availability of non US backup servers should be discussed during sales by dedicated request to Account Manager |
AutoUpgradeClientApp | Indicates if all accounts of company will use automatic update of client software | bool , Optional, no changes if missed |
Returns CannotFindDataCenterForCountry error code if there are no data centers in country specified by parameter "DataCenterCountryCodeIsoA2"
Operation: GetUsedSpaceForAllAccounts
Retrieves information about disk space already used by accounts
Parameter | Description | Validation |
|---|---|---|
EntityId | Identifies entity. Used space info is retrieved for all accounts in scope of this entity | Int It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
|
ChildAccountsOnly | If true, restricts scope of entity by child accounts, If false, all descendant accounts are used | Bool |
Returns result as array where each item contains following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
Username | Identifies account | String | |
UsedSpaceKB | Space utilization by account | Long | Kilobytes |
Operation: GetCompanyDetails
Retrieves detailed information about specific company
Parameter | Description | Validation |
|---|---|---|
CompanyEntityId | Identifies company. | Int It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
if 0 , ApiCallerEntityId is used for Company identification |
Returns result with following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
CompanyEntityId | EntityId of company | Int | |
CompanyName | Name of company | String | |
DiskQuotaGB | Quota(Backup plan of Company) | Long | Gigabytes |
UsedSpaceKB | Used space utilization by contained accounts | Long | Kilobytes |
AllocatedSpaceMB | Space allocation by contained accounts | Long | Megabytes |
NumberOfAccounts | Number of contained accounts | Int | |
NumberOfLicensesShadowProtectV5 | Number of licenses assigned to company | Int | |
AllowUploadOverAccountSize | Shows if accounts are able to exceed company's quota | Boolean | |
DataCenterCountryCodeIsoA2 | ISO 3166-1 two-letter country code (alpha-2). Shows location of data center, where company backup accounts are created. | String |
User Account Management
Operation: CreateAccountBySize
Parameter | Description | Validation | Change |
|---|---|---|---|
TargetEntityId | ID of the parent Company/Partner | Integer | |
Username | Username | Required, "^[^<>]{0,100}$" | |
Password | Password for user account | "^[a-zA-Z0-9!@#$%^&*()]{6,20}$" | |
AccountSizeMB | Storage quota for account | Integer >= 1, only from a list of allowed values (right now: 1024 * 1GB, 2GB, 3, 4, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 150, 200, 250, 300, 400) | |
FullName | Full Name for user | "^[a-zA-Z]([a-zA-Z\.-]|\s){1,30}$" | |
"^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,}){1,49}$" | |||
IsUltrasafe | Standard or Ultrasafe security | Bool | |
SecretQuestion | Secret question for password reset (works only for non-Ultrasafe accounts) | String | |
SecretAnswer | Answer for secret question (works only for non-Ultrasafe accounts) | "^[a-zA-Z0-9!@#$%^&*()\s]{3,20}$" | |
Allow to disable sending all emails notifications | bool, Optional, no changes if missed |
Operation: ChangeBackupAccountEmail
Parameter | Description | Validation | Change |
|---|---|---|---|
Username | Username | Required, "^[^<>]{0,100}$" | |
New Email | "^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,}){1,49}$" | ||
SendEmailToCustomer | send email notification to user |
Operation: ChangeBackupAccountPassword
Works only for Regular backup accounts.
Parameter | Description | Validation | Change |
|---|---|---|---|
Username | Username | Required, "^[^<>]{0,100}$" | |
NewPassword | New password | "^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9_-]+)*\.([a-zA-Z]{2,}){1,49}$" | |
SendEmailToCustomer | send email notification to user |
Operation: ChangeAccountSize
Parameter | Description | Validation | Change |
|---|---|---|---|
Username | Username | Required, "^[^<>]{0,100}$" | |
AccountSizeMB | New size value in MB | Integer >= 1, only from a list of allowed values (right now: 1024 * 1GB, 2GB, 3, 4, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 150, 200, 250, 300, 400) | |
SendEmailToCustomer | send email notification to user |
Operation: Suspend/UnsuspendAccount
Parameter | Description | Validation | Change |
|---|---|---|---|
Username | Username | string It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
If account is canceled , AccountIsNotActive error is fired | |
Reason | Details about reason of status change | string, optional |
Returns following output:
Output Value | Description | Type |
|---|---|---|
AlreadyDone | Re-entrability flag. It is set if attempt is taken to suspend already suspended account OR unsuspend already unsuspended | bool |
Request
Response
Operation: GetAccountUsedSpace
Parameter | Description | Validation | Change |
|---|---|---|---|
Username | Username | Required, "^[^<>]{0,100}$" |
Returns following output:
Output Value | Description | Type |
|---|---|---|
long |
Operation: GetAccountUsedSpaceBySystem
Parameter | Description | Validation | Change |
|---|---|---|---|
Username | Username | Required, "^[^<>]{0,100}$" |
Returns following output:
Output Value | Description | Type |
|---|---|---|
Type AccountSpace
Output Value | Description | Type |
|---|---|---|
string | ||
long | ||
string | ||
DeviceType | "Desktop" or "Mobile" | string |
Operation: GetAuthenticationToken
Parameter | Description | Validation | Change |
|---|---|---|---|
Username | Username |
| |
Password | Password | Required |
Returns output:
Output Value | Description | Type |
|---|---|---|
Token | Value can be used for further call client operations | string |
Operation: GetAuthorizationTokenByEntity
Parameter | Description | Validation | Change |
|---|---|---|---|
Username | Username |
| |
IsAppUser | If value is 'true' then 'Username' is Application User | 1. Not required, System.Nullable<System.Boolean> |
Returns output:
Output Value | Description | Type |
|---|---|---|
AuthToken | Value can be used for autologin to Partner Dashboard according to pattern https://dashboard.managedoffsitebackup.net/Account/Login?uid={username}&token={tokenstring}, see example below The access token has a “time-to-live” (ttl) - 30 minutes. | string |
Example:
Request
Response
Correct url to dashboard autologin is https://dashboard.managedoffsitebackup.net/Account/Login?uid=sdk.test@sosonlinebackup.com&token=KFZ2sLv3gJiauSaXKeBuPuCWvWHw4G
Policy management
Production: https://secure.sosonlinebackup.com/WebApi/AccountManagementService/BackupPolicyManagementService.asmx
Object: EntityPolicy
Operates with two kinds of objects, i.e. Entity Policy and Account Policy.
Entity policy incapsulates all PC Client settings those we can change by policy.
Entity policy object has following structure
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | The unique ID of entity policy. Used to identify entity policy. | Int. Populated by SOS. On create entity policy just send 1. |
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
PolicyName | Unique name of policy | String, required, "^[\x20-\x3B\x3D\x3F-\x7F]*$";//ASCII without <> |
DateCreated | Date when entity policy was created. | DateTime. Populated by SOS. On create entity policy just send any valid value. |
BackupSet | Settings for the Smart Scanner | Object, Not mandatory |
BackupSet.ScannerMode | Scope of scanning for file, i.e. where to scan. | Enum (ScanAll or ScanPersonal or DontScan) |
BackupSet.BackupDocuments | Include document files to backup set. | Bool |
BackupSet.BackupImages | Include image files to backup set. | Bool |
BackupSet.BackupMusic | Include music files to backup set. | Bool |
BackupSet.BackupVideo | Include video files to backup set. | Bool |
BackupSet.BackupCustom | Include files with specified in BackupSet.CustomFileTypes extensions | Bool |
BackupSet.CustomFileTypes | Delimited list of custom file types to backup. Used when BackupSet.BackupCustom = true. | String, Not mandatory. E.g.: “xls, midi, txt” Invalid characters are ASCII/Unicode characters 1 through 31, as well as quote ("), less than (<), greater than (>), pipe (|), backspace (\b), null (\0) and tab (\t). Comma (,), dot (.), space ( ) and semicolon (;) are treated as separators. Empty extensions are ignored. |
BackupSet.ExcludeFileTypes | Delimited list of file types to ignore. It's applied to all types of the documents. | String, Not mandatory. E.g.: “tmp, log, temp” Invalid characters are ASCII/Unicode characters 1 through 31, as well as quote ("), less than (<), greater than (>), pipe (|), backspace (\b), null (\0) and tab (\t). Comma (,), dot (.), space ( ) and semicolon (;) are treated as separators. Empty extensions are ignored. |
Schedule | Settings for the scheduler. | Object, Not mandatory |
Schedule.ScheduleType | How often backup should run | Enum (Monthly or Weekly or Daily or Hourly) |
Schedule.ScheduledTime | When to run backup. Only time part is used. | DateTime. |
Schedule.ScheduledEndTime* | When to terminate running backup. Only time part is used. Cannot be combined with Hourly ScheduleType. | DateTime. |
Schedule.UseEndTime* | Activates ScheduledEndTime option. | Bool |
Schedule.ScheduledDayOfTheMonth | Day of month to run. Used when ScheduleType = Montly. | 1-31 |
Schedule.ScheduledDayOfTheWeek | Day of week to run. Used when ScheduleType = Weekly. | Sunday or Monday or Tuesday or Wednesday or Thursday or Friday or Saturday |
Schedule.ScheduledHoursBetweenRuns | Interval between backup runs. Used when ScheduleType = Hourly. | 1-12 |
RunAs | Credentials to run PC Client with. Required if you want to backup when user is not logged in. | Object, Not mandatory |
RunAs.RunAsDomainAndLogin | Windows domain name and login. | Optional, String,
|
RunAs.RunAsPassword | Password for user above. it'll be kept encrypted in SOS databases. PC client don't keep it locally. | Optional, String |
Options | Some options and triggers. | Object, Not mandatory |
Options.RunScheduledBackup | Turns on/off scheduller. | Bool, use “true” |
Options.RunWhenNotLoggedOn | Activates RunAs section. If it's false backup will run by scheduler only if user is currently logged in. | Bool, use “false” |
Options.SendEmailReportAfterBackup | Whether to send backup email report | Bool |
Options.EmailAddressToSendReportsTo | Coma separated list of emails to send report to | String, Required if previous SendEmailReportAfterBackup is true. |
Options.ExcludeFilesOlderThanDate | Exclude files that are older than inputed Date | DateTime, Optional |
Options.ExcludeFilesLargerThanMb | Exclude files that are larger than inputed value in Mb | Integer, > 0, Optional |
Options.ExcludeFilesSmallerThanKb | Exclude files that are smaller than inputed value in Kb | Integer, > 0, Optional |
Options.RemoveFilesAfterDays | Time limited retention policy parameter. If file's modification date is less than Current Date - Options.RemoveFilesAfterDays, files will be removed from cloud | Integer, > 0, Optional, If value passed, EmailAddressToSendReportsTo must be true |
Options.RemoveDeletedFilesAfterDays | Time limited retention policy parameter. If file have been deleted from Client PC, it will be also removed from cloud in RemoveDeletedFilesAfterDays days | Integer, > 0, Optional, If value passed, EmailAddressToSendReportsTo must be true |
When set to true OBRM 7.3+ uses SYSTEM account to run backup | Bool, use “false” | |
ScannerFileFilters** | Filter to apply to all files found by scanner. | Object, Not mandatory |
ScannerFileFilters.Mode** | How filter will should work:
| None |
ScannerFileFilters.IncludeFiles** | Semicolon separated values of file name (including extension) templates. | Optional, String, '"^(?!(.*[\x22\x3C\x3E\x7C\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F\x3A\x5C\x2F]+.*))[^;]+(;*[^;]+)+$"
|
ScannerFileFilters.IncludeFolders** | Semicolon separated values of folder path templates. | Optional, String, "^(?!(.*[\x22\x3C\x3E\x7C\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F]+.*))[^;]+(;*([^;]*[*?]+[^;]*)+)+$"
|
ScannerFileFilters.ExcludeFiles** | Semicolon separated values of file name (including extension) templates. | Optional, String,'"^(?!(.*[\x22\x3C\x3E\x7C\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F\x3A\x5C\x2F]+.*))[^;]+(;*[^;]+)+$"
|
ScannerFileFilters.ExcludeFolders** | Semicolon separated values of folder path templates. | Optional, String,"^(?!(.*[\x22\x3C\x3E\x7C\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F]+.*))[^;]+(;*([^;]*[*?]+[^;]*)+)+$"
|
LiveProtectWholeBackupSet** | When set to true OBRM 7.6+ automatically turns on LiveProtect technology for each file found accordingly to Explicit Pathes ( aka GetBackupSetCustomPathes method data). LiveProtect technology ensures that file uploaded to the cloud shortly after it has been modified. | Bool, optional. Default and when not specified is false |
* Dashboard UI doesn't support these fields yet.
** Added at December 2019 & January 2020. OBRM v7.6.0 & higher recognises and uses them.
Example:
Policy object in response
Operation: CreateEntityPolicy / GetEntityPolicy
Start with creating policy:
Returns contents of created Policy including populated by SOS EntityBackupPolicyID and DateCreated.
Then you can get just created policy. It returns entity policy.
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | The unique ID of entity policy. Used to identify policy. | Integer, > 0 |
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
Operation: GetEntityPoliciesAll / GetEntityPolicies
When you've created several entity policies you migth want to get a list of them. It's method without parameters. It returns list of entity policies.
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
There is also paged verion of the method.
Parameter | Description | Validation |
|---|---|---|
pageIndex | The page number | Integer, >= 1 |
pageSize | The page size | Integer, >= 1 |
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
Operation: UpdateEntityPolicy / DeleteEntityPolicy
Also you can modify entity policy. Changes will affect all assigned to entity policy accounts and machines:
When you've created many entity policies you might want to delete few entity policies. In that case you should use following method.
Please note that only not assigned to any account policy may be deleted.
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | The unique ID of entity policy. Used to identify policy. | Integer, > 0 |
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
Operation: AddAccountPolicy
At that moment you are ready to apply entity policy to some backup account on particular PC/device.
To achieve it assign policy to an account on machine, i.e create account policy:
Object: AccountPolicy
Account policy object has following structure.
Parameter | Description | Validation |
|---|---|---|
AccountBackupPolicyID | The unique ID of account policy. Used to identify account policy. | Int. Populated by SOS. On create account policy just send 1. |
AccountName | Username | |
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
EntityBackupPolicyID | ID of Entity Policy to assign | Integer, >0 |
SystemName | Name of machine | String, Optional,
If SystemName is not specified, policy applies to all devices where user with specified AccountName logs in. |
PolicyName | Name of Entity Policy | Optional, Ignored. On create account policy just leave empty. |
DateCreated | Date when account policy was created. | DateTime. Populated by SOS. On create account policy just send any valid value. |
RunAs | Credentials to run PC Client with. When defined they override Entity Policy Credentials. | Object, Not mandatory |
RunAs.RunAsDomainAndLogin | Windows domain name and login. | Optional, String,
|
RunAs.RunAsPassword | Password for user above. it'll be kept encrypted in SOS databases. PC client don't keep it locally. | Optional, String |
Operation: AddAccountPolicySimple
Also we have simplified version of this method which does the same.
Parameter | Description | Validation |
|---|---|---|
AccountName | Username | |
EntityBackupPolicyID | ID of Entity Policy to assign | Integer, >0 |
SystemName | Name of machine | String, Optional @"^([^~!@#$\^&\*\(\)=\+\[\]\{\}\\\|;:'"",<>/\?\s]{1,25})$"
If SystemName is not specified, policy applies to all devices where user with specified AccountName logs in. |
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
Operation: GetAccountPolicies
When you've created several account policies you might want to get a list of all account policies.
Parameter | Description | Validation |
|---|---|---|
AccountName | Username | |
SystemName | Name of machine | String, Optional. When it's not null result set is filtered by provided system name. @"^([^~!@#$\^&\*\(\)=\+\[\]\{\}\\\|;:'"",<>/\?\s]{1,25})$"
|
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
Operation: DeleteAccountPolicy / DeleteAccountPolicySilent
There are two methods to delete account policy ( N.B. Entity policy is not affected on delete account policy).
The first way is by Account name and System name.
It deletes account policy (unassigns entity policy) for backup account on the particular system. Returns deleted account policy. Returns corresponding error codes when something is not found or not accessable.
Parameter | Description | Validation |
|---|---|---|
AccountName | Username | |
SystemName | Name of machine | String, Required @"^([^~!@#$\^&\*\(\)=\+\[\]\{\}\\\|;:'"",<>/\?\s]{1,25})$"
|
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
Also there is more silent version. It returns success even when requested record is not found or not accessable.
Parameter | Description | Validation |
|---|---|---|
AccountBackupPolicyID | The unique ID of account policy. Used to identify account policy. | Integer, >0 |
TargetEntityID | ID of the parent Company/Partner. | Int, >=0. Use 0 for yourself. |
Policy management (Advanced)
Production: https://secure.sosonlinebackup.com/WebApi/AccountManagementService/BackupPolicyManagementService.asmx
Dashboard has UI only for editing BackupSetCustomPathes. PC client supports all advanced settings from 5.9.
All methods work with existing Entity Backup Policy.
Some terms & rules: BackupSet, Scanner & etc
There are two backup sets. They don't affect each other in any way.
First Backup Set is formed by Scanner before each backup. What gets included is determined by scanner settings.
Second Backup Set is formed based on Explicit Pathes or user manual selection in the "tree" after scan but before backup itself .
There are rules
Remote policy ALWAYS override local settings provided by user.
First we apply includes and then we apply excludes.
Before backup those Backup Sets get merged.
Terms:
Scanner (aka Smart Scanner) is a piece of PC Client (aka Online Backup an Recovery Manager ) business logic which determines what files and folder should be watched and backup-ed, Scanner is run before each backup to update BackupSet.
BackupSet is actualized list of the files and folders those exist in the file system and should be backup-ed.
Formed by Scanner BackupSet (aka First Backup Set ) is shown on the 2nd screen of the Setup Backup flow of the PC Client. It looks like Files&Folders tree with selected items.Scanner Pathes are root locations where Scanner looks for files and folders to backup. It's set automatically depending from BackupPolicy.BackupSet.ScannerMode (ScanAll or ScanPersonal or DontScan) .
File Size Limits are restrictions for size of the files included into BackupSet by Scanner. They are not applied to Explicit Items.
Explicit Pathes (aka Explicit Items ) are files and folders manually included (don't confuse it with the scanner settings!) by user into formed BackupSet. They form Second Backup Set.
Also take into account Mutual Scanner Settings Rules . PC Client always apply those rule regardless user settings.
Object: CustomPathes
Parameter | Description | Validation |
|---|---|---|
IncludeFolders | Folders those should always be included into backup set. Null elements are not allowed. Path string restrictions are provided below the table. | string[] |
IncludeFiles | Files those should always be included into backup set. Null elements are not allowed. Path string restrictions are provided below the table. | string[] |
ExcludeFolders | Folders those should always be excluded from backup set. Null elements are not allowed. Path string restrictions are provided below the table. | string[] |
ExcludeFiles | Files those should always be excluded from backup set. Null elements are not allowed. Path string restrictions are provided below the table. | string[] |
Path string restrictions ( http://msdn.microsoft.com/en-us/library/aa365247.aspx ).
"^((([C-Zc-z][:])|(%[Uu][Ss][Ee][Rr][Pp][Rr][Oo][Ff][Ii][Ll][Ee]%))([\\](?!((PRN|AUX|CLOCK\$|NUL|CON|COM\d|LPT\d|([.]+)))([\\]|$))([^\x00-\x1f\\\<\>?*:\""|/]+))*)$"
Full list of the restrictions see by link above
Maximum path length 260 chars
Placeholder %UserProfile% is allowed. When UseSystemAccountForScanningUserPersonalFolders field in the policy is set to true it's resolved into actual path (e.g. C:\Users\Peter).
Path regex deep dive:
Windows kernel forbids the use of characters in range 1-31 (i.e., 0x01-0x1F) and characters " * : < > ? \ |. Although NTFS allows each path component (directory or filename) to be 255 characters long and paths up to about 32767 characters long, the Windows kernel only supports paths up to 259 characters long. Additionally, Windows forbids the use of the MS-DOS device names AUX, CLOCK$, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, CON, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, NUL and PRN, as well as these names with any extension (for example, AUX.txt), except when using Long UNC paths (ex. \.\C:\nul.txt or \?\D:\aux\con). (In fact, CLOCK$ may be used if an extension is provided.) These restrictions only apply to Windows - Linux, for example, allows use of " * : < > ? \ | even in NTFS.
Properly formed path is something like C:\Documents and Settings\السعودية\Русские буквы\请收藏.我们的网址\.السعودية \file.d 藏.我 d.hd.ext
Operation: GetScannerCustomPathes
Call it to view custom Scanner Pathes .
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | ID of Entity Policy to apply for | Integer, >0 |
TargetEntityID | ID of the Company/Partner owner of the policy. | Int, >=0. Use 0 for yourself. |
Operation: SetScannerCustomPathes
Call it to set new custom Scanner Pathes . Standard Scanner Pathes are not shown and cannot be modified,
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | ID of Entity Policy to apply for | Integer, >0 |
TargetEntityID | ID of the Company/Partner owner of the policy. | Int, >=0. Use 0 for yourself. |
CustomPathes | Object |
Operation: GetBackupSetCustomPathes
Call it to view Explicit Pathes .
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | ID of Entity Policy to apply for | Integer, >0 |
TargetEntityID | ID of the Company/Partner owner of the policy. | Int, >=0. Use 0 for yourself. |
Operation: SetBackupSetCustomPathes
Call it to set new custom Explicit Pathes .
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | ID of Entity Policy to apply for | Integer, >0 |
TargetEntityID | ID of the Company/Partner owner of the policy. | Int, >=0. Use 0 for yourself. |
CustomPathes | Object |
Object: FileSizeLimit
Parameter | Description | Validation |
|---|---|---|
FileType | Type of the file/document to apply size restricton to | Enum (Documents, Video, Music, Image, Custom) |
MinSizeUnit | MinSize unit. | Enum (B, KB, MB, GB, TB) |
MinSize | Minumum file size | Int, >=0 |
MaxSizeUnit | MaxSize unit. | Enum (B, KB, MB, GB, TB) |
MaxSize | Maximum file size | Int, >=0 |
Operation: GetScannerFileSizeLimits
Call it to view File Size Limits .
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | ID of Entity Policy to apply for | Integer, >0 |
TargetEntityID | ID of the Company/Partner owner of the policy. | Int, >=0. Use 0 for yourself. |
Operation: SetScannerFilesizeLimits
Call it to set new File Size Limits .
Parameter | Description | Validation |
|---|---|---|
EntityBackupPolicyID | ID of Entity Policy to apply for | Integer, >0 |
TargetEntityID | ID of the Company/Partner owner of the policy. | Int, >=0. Use 0 for yourself. |
FileSizeLimits | Array of the objects. Should contain row for each document/file type (Documents, Video, Music, Image, Custom) . Missing element for FileType means "use default values". Current default values are 0KB ... 5GB. Null elements are not allowed. | FileSizeLimit[] |
Product Licenses Management
Operation: GetAssignedLicensesSummary
Retrieves summary about all assigned licenses
Parameter | Description | Validation |
|---|---|---|
EntityId | Identifies partner or company for which assignment info is retrieved | int |
ChildAccountsOnly | If true, only child accounts of EntityId are taken, otherwise all descendant accounts | Bool |
Returns collection of items with following fields:
Output Value | Description | Type |
|---|---|---|
Username | Identifies account where license is assigned | string |
LicenseType | Specifies type of assigned license : KrollExchangeRecovery, SkraftDiskImageV5, SqlBackup,ExchangeBackup | enum |
Operation: GetAssignedLicenseDetails
Retrieves detailed info about specified license
Parameter | Description | Validation |
|---|---|---|
Username | Identifies account where license is assigned | Required, "^[^<>]{0,100}$" |
LicenseType | Specifies type of assigned license KrollExchangeRecovery, SkraftDiskImageV5, SqlBackup,ExchangeBackup | enum |
Returns result with following fields:
Output Value | Description | Type |
|---|---|---|
ProductKey | License key is required for activation SkraftDiskImageV5. Empty for SqlBackup, ExchangeBackup. | string |
LicenseData | License data is required for activation KrollExchangeRecovery. Empty for SqlBackup, ExchangeBackup. | byte[] |
If license does not exist, returns error code NoLicensesFound.
Operation: RemoveLicense
Completely deactivates v5 license using shadow protect API. Removes all license assignments.
Now supported for ShadowProtect v5.
Parameter | Description | Validation |
|---|---|---|
Username | Identifies account where license is assigned | Required, "^[^<>]{0,100}$". It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following constraints are validated: Username should belong to ApiCallerEntityId or it's descendant entity. |
LicenseType | SkraftDiskImageV5 is only supported | enum |
If license does not exist, returns error code NoLicensesAreAvailable.
If there is ShadowProtect API error, returns error code ShadowProtectApiError. In case of any ShadowProtect API error, license assignment is not changed
Operation: AssignLicenseToAccount
Operation: UnassignAccountLicense
Assigns/Unassigns license of specific type to account (not available)
Sandbox:
Production:
Parameter | Description | Validation |
|---|---|---|
Username | Identifies account for assignment/unassignment | Required, "^[^<>]{0,100}$" |
LicenseType | Specifies type of license to (un)assign. Should be in range of supported license types: KrollExchangeRecovery, SkraftDiskImageV5, SqlBackup,ExchangeBackup | array: enum [] |
LicenseProviderEntityId | For assignment operation identifies source Entity where licenses are taken from. For unassignment operation identifies destination Entity where licenses are returned. In unassignment, licenses should be returned only to entity where they were taken from in assignment process | It is supposed that client of this service belongs to entity identified by ApiCallerEntityId, then following constraints are validated:
if LicenseProviderEntityId is not set, ApiCallerEntityId will be used as licenses source for assignment and destination for unassignment |
Entities Monitoring
Allows to extract Online Backup Events in scope of Entities
Field: Version, i.e. Monitoring API Version
It's an integer value that identifies version of service your integration understands. Method behaviour changes depending on provided value.
We'll be adding some new EventBackupTypes & HistoryEventTypes in future. It ensures that those changes won't affect your integration
It's strongly recommended to use maximum allowed at the moment version for new integrations.
Values | |
|---|---|
No value, 0, <1, >3 | Default, compatible with really old stuff |
1 |
For compatibility, in lower versions, these new values get replaced
|
2 |
For compatibility, in lower versions, rows with these new types get removed |
3 |
For compatibility, in lower versions, rows with these new types get removed |
...
Operation: GetHistoryEvents
Extracts logged online backup events for Entity, restricts output by filters:
Parameter | Description | Validation |
|---|---|---|
EntityId | Identifies parent entity (Company, Partner) of account for which this event is fired. | Int It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
|
FromDateFilterDefined | If this flag is set, FromDateFilterValue is taken into account when output is extracted. | Bool |
FromDateFilterValue | "AND" filter: restricts output only by events happened after this date. | DateTime |
ToDateFilterDefined | If this flag is set, ToDateFilterValue is taken into account when output is extracted. | Bool |
ToDateFilterValue | "AND" filter: restricts output by events happened before this date. | DateTime |
AccountNameFilterDefined | If this flag is set, AccountNameFilterValue is taken into account when output is extracted. | Bool |
AccountNameFilterValue | "AND" filter: restricts output by events happened only for this account. | String |
AccountTypeFilterIsNotDefined* | If this flag is set, AccountTypeFilterValue is NOT taken into account. | Bool |
AccountTypeFilterValue* | "AND" filter: restricts output by events happened for particular account types. BackupAccount - events related to backup accounts | Enum |
EventTypeFilterDefined | If this flag is set, EventTypeFilterValue is taken into account when output is extracted. | Bool |
EventTypeFilterValue | "AND" filter: restricts output by events of specific type. One of following values BackupStarted, BackupCompleted, BackupProgress, BackupCancelled, BackupConfigured NoProgressEvent1 NoProgressEvent2 NoBackupEvent1 NoBackupEvent2 | Enum |
StatusFilterDefined | Does not participate in this operation. May have any valid value (e.g. false). | Bool |
StatusFilterValue | Does not participate in this operation. May have any valid value (e.g. Canceled) | Enum |
PageSize | Number of entries to extract. | int <= 5000 |
PageIndex | Identifies 1-based index of data frame if volume of data to extract exceeds PageSize. | >=1. If 0 , 1 is taken into account |
Version | Identifies version of service consumer. Use maximum allowed for new integrations. | Int, 0, 1, 2, 3 |
Returns result as array of events, where each item contains following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
AccountName | Identifies account. | String | |
AccountType* | Type of the account BackupAccount - event is related to backup accounts | Enum | |
EntityId | Identifies entity (Company, Partner) for which account this event is fired. | Int | |
ClientDate | Identifies when event was fired on client side (in client time-zone). | DateTime, optional | |
TotalFilesCount | Total number of files in backup set. | Long, optional | |
TotalFilesSize | Total size of backup set. | Long, optional | Bytes |
ErrorFilesCount | Number of files were handled with errors when event was fired. | Long, optional | |
ErrorFilesSize | Size of files were handled with errors when event was fired. | Long, optional | Bytes |
UploadedFilesCount | Number of files were uploaded when event was fired. | Long, optional | |
UploadedFilesSize | Size of files were uploaded when event was fired. | Long, optional | Bytes |
UnchangedFilesCount | Number of files were unchanged since previous backup. | Long, optional | |
UnchangedFilesSize | Size of files were unchanged since previous backup. | Long, optional | Bytes |
BackupDuration | Duration of backup at moment when event was fired | Long | Seconds |
EventBackupType | Identifies type of backup. Filled by one of following values: Online, ShadowProtectBackup ApplianceHyperVBackup IcabMsOffice IcabSharepoint | Enum | |
IsScheduled | Identifies that backup( for which current event was fired) was scheduled | Bool | |
Indicator | Filled by one of following values: Ok, Warning, Error | Enum | |
EventType | Filled by one of following values: BackupStarted, BackupCompleted, BackupProgress, BackupCancelled, BackupConfigured NoProgressEvent1 NoProgressEvent2 NoBackupEvent1 NoBackupEvent2 | Enum | |
BackupSummary | Not localized text message describing additional details related to event : Could not find [sosuploadagent] for [NOVALISTECH\Jim] Job status: 9 (Completed), Volumes: C:\, D:\, G:\, ImageNames: H:\C_VOL-b005-i4471.spi, H:\D_VOL-b005-i4471.spi, H:\G_VOL-b001-i4471.spi You have exceeded your account storage space (100.00 GB). Total data processed 123.58 GB. Cannot process next 815.08 MB. Job status: 9 (Completed), Volumes: C:\, E:\, ImageNames: \\FILE\Net Admin\SP Repository\exchange\C_VOL-b001-i046.spi, \\FILE\Net Admin\SP Repository\exchange\E_VOL-b001-i034.spi Could not find [sosuploadagent] for [Linda-PC\Linda] Job status: 9 (Completed), Volumes: P:\, C:\, ImageNames: D:\Backup Image\P_VOL-b001-i244.spi, D:\Backup Image\C_VOL-b001-i244.spi Path is a zero-length string or contains only white space. Parameter name: path You have exceeded your account storage space (15.00 GB). Total data processed 16.52 GB. Cannot process next 2.54 MB. Writer is in faulty state. Please restart Microsoft Exchange Writer service or reboot the computer. You have exceeded your account storage space (100.00 GB). Total data processed 135.81 GB. Cannot process next 369.87 MB. Could not find [sosuploadagent] for [RPPA\ptadmin] Illegal characters: [] in path. Parameter name: _M_1346.CR2 | String, optional | |
TotalRecords | Total count of entries what fit to filters | int |
Request to get top 5 history events for specific backup account and device
Response
Operation: GetMonitoringEvents
Extracts active online backup events for Entity, restricts output by AND-filters:
Parameter | Description | Validation |
|---|---|---|
EntityId | Identifies parent entity (Company, Partner) of account for which this event is fired. | Int It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
|
AccountNameFilterDefined | If this flag is set, AccountNameFilterValue is taken into account when output is extracted. | Bool |
AccountNameFilterValue | "AND" filter: restricts output by events happened only for this account. | String |
AccountTypeFilterIsNotDefined* | If this flag is set, AccountTypeFilterValue is NOT taken into account. | Bool |
AccountTypeFilterValue* | "AND" filter: restricts output by events happened for particular account types. BackupAccount - events related to backup accounts | Enum |
StatusFilterDefined | If this flag is set, StatusFilterValue is taken into account when output is extracted. | Bool |
StatusFilterValue | "AND" filter: restricts output by events with specific status. One of following values: Uploading | Enum |
PageSize | Number of entries to extract. | int <= 5000 |
PageIndex | Identifies 1-based index of data frame if volume of data to extract exceeds PageSize. | >=1. If 0 , 1 is taken into account |
Version | Identifies version of service consumer. Use maximum allowed for new integrations. | Int, 0,1,2,3 |
Returns result as array of events, where each item contains following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
AccountName | Identifies account. | String | |
AccountType* | Type of the account BackupAccount - event is related to backup accounts | Enum | |
EntityId | Identifies entity (Company, Partner) for which account this event is fired. | Int | |
ClientDate | Identifies when active event was fired on client side (in client time-zone). | DateTime, optional | |
TotalFilesCount | Total number of files in backup set. | Long, optional | |
TotalFilesSize | Total size of backup set. | Long, optional | Bytes |
ErrorFilesCount | Number of files were handled with errors when event was fired. | Long, optional | |
ErrorFilesSize | Size of files were handled with errors when event was fired. | Long, optional | Bytes |
UploadedFilesCount | Number of files were uploaded when event was fired. | Long, optional | |
UploadedFilesSize | Size of files were uploaded when event was fired. | Long, optional | Bytes |
UnchangedFilesCount | Number of files were unchanged since previous backup. | Long, optional | |
UnchangedFilesSize | Size of files were unchanged since previous backup. | Long, optional | Bytes |
BackupDuration | Duration of backup at moment when event was fired | Long | Seconds |
EventBackupType | Identifies type of backup. Filled by one of following values: Online, ShadowProtectBackup
IcabMsOffice | Enum | |
IsScheduled | Identifies that backup( for which current event was fired) was scheduled | Bool | |
Indicator | Filled by one of following values: Ok, Warning, Error | Enum | |
Status | Filled by one of following values: Uploading | Enum | |
Description | Not localized text message describing this event | String, optional | |
TotalRecords | Total count of entries what fit to filters | int |
Request to get monitoring event for specific backup account and system name
Response
Operation: GetHistoryTotalsPerDay
Extracts logged online backup events for Entity as per-day aggregated summaries
Parameter | Description | Validation |
|---|---|---|
EntityId | Identifies parent entity (Company, Partner) of account for which events were logged. | Int It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
|
DaysInterval | Last N days interval. Events summaries are aggregated per day in this interval | 0< int <= 60 |
Returns result as array of summaries where each item is per day aggregated info with following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
UploadedFilesCount | Number of files were uploaded in specific day. | Long | |
UploadedFilesSize | Number of files were uploaded in specific day. | Long | |
PeriodDate | Identifies day. UploadedFilesCount and UploadedFilesSize are aggregated as sum for that day. If there are no events for specific day, results for that day are not included in output | DateTime |
Operation: GetHiSTORYRecoveryEvents
Extracts logged online backup events for Entity, restricts output by filters:
Parameter | Description | Validation |
|---|---|---|
EntityId | Identifies parent entity (Company, Partner) of account for which this event is fired. | Int It is supposed that client of this service belongs to entity identified by ApiCallerEntityId then following is validated:
|
FromDateFilterDefined | If this flag is set, FromDateFilterValue is taken into account when output is extracted. | Bool |
FromDateFilterValue | "AND" filter: restricts output only by events happened after this date. | DateTime |
ToDateFilterDefined | If this flag is set, ToDateFilterValue is taken into account when output is extracted. | Bool |
ToDateFilterValue | "AND" filter: restricts output by events happened before this date. | DateTime |
AccountNameFilterDefined | If this flag is set, AccountNameFilterValue is taken into account when output is extracted. | Bool |
AccountNameFilterValue | "AND" filter: restricts output by events happened only for this account. | String |
SystemNameFilterDefined | If this flag is set, SystemNameFilterValue is taken into account when output is extracted. | Bool |
SystemNameFilterValue | "AND" filter: restricts output by events happened for particular system. | String |
PageSize | Number of entries to extract. | Int <= 5000 |
PageIndex | Identifies 1-based index of data frame if volume of data to extract exceeds PageSize. | >=1. If 0 , 1 is taken into account |
Returns result as array of events, where each item contains following fields:
Output Value | Description | Type | Units |
|---|---|---|---|
AccountName | Identifies account. | String | |
SystemName | Identifies system. | String | |
EntityId | Identifies entity (Company, Partner) for which account this event is fired. | Int | |
ClientDate | Identifies when event was fired on client side. | DateTime, UTC | |
HistoryRecoveryEventType | Possible values: RecoveryCompleted RecoveryFailed | String | |
RecoveryId | Identifies recovery | String | |
RecoveryDuration | Duration of recovery at moment when event was fired | Long | Seconds |
ClientVersion | Version of backup software | String, formatted as: major.minor.build.revision | |
Summary | N/A | String |
Appliances Management
There are operations for retrieving appliances related data in scope of entities
Endpoints:
Production: https://secure.sosonlinebackup.com/WebApi/AccountManagementService/AppliancesManagementService.asmx
Operation: GetEntityAppliances
Extracts data appliances details using filter:
Request:
Parameter | Description | Validation |
|---|---|---|
EntityId | Identifies appliance owner entity (Company, Partner). | Int, optional It is supposed that client of this service belongs to entity identified by ApiCallerEntityId If client passes value, EntityId should identify entity which is descendant for ApiCallerEntityId If client omits value or value is 0, ApiCallerEntityId is used as EntityId |
Field for filtering appliances by type. Possible values: Unknown PremisePhysical PremiseVirtualPremise VmWare PremiseActiveActive Cloud | Enum, optional |
Request example:
Response:
Returns result as array of appliance details, where each item contains following fields:
Field | Description | Type |
|---|---|---|
Primary | Detailed info about primary appliance | Object: ApplianceInfo |
Secondary | Detailed info a bout secondary appliance | Object: ApplianceInfo |
ReplicationInfo | Detailed info about replication | Object:ReplicationInfo |
Object: ApplianceInfo
Field | Description | Type |
|---|---|---|
Uuid | Appliance identifier | string |
ApplianceType | Type of appliance : Unknown, | string |
Name | Appliance name | string |
DeviceSpaceUsed | Used space, bytes | long |
DeviceSpaceTotal | Total space, bytes | long |
Protected | Total protected, bytes | long |
ProtectedReplicable | Protected replicable, bytes | long |
VmwareHostCount | count of WmWare hosts | int |
HasRemoteAccess | If true, it is possible to get browse url using GetEntityApplianceBrowseInfo | bool |
StatusInfo | Details about current state | object:ApplianceStatusInfo |
Object: ApplianceStatusInfo
Field | Description | Type |
|---|---|---|
Status | Describes status, following values are possible CannotParse,
| string |
Name | Status name | string |
SeverityLevel | Describes severity, following values are possible: Unknown, | string |
StatusMessage | Set of related messages | object:StatusMessage |
Object: StatusMessage
Field | Description | Type |
|---|---|---|
Message |
| string |
SeverityLevel | Describes severity, following values are possible: Unknown, | string |
Object:ReplicationInfo
Field | Description | Type |
|---|---|---|
SpeedBytesPerSecond | value of progress | long |
BytesRemaining | value of progress | long |
SecondsRemaining | value of progress | long |
QueueStatus | Details about current state | object:QueueStatusInfo |
Object:QueueStatusInfo
Field | Description | Type |
|---|---|---|
Status | Describes status, following values are possible Unknown,
| string |
Name | Status name | string |
SeverityLevel | Describes severity, following values are possible: Unknown, | string |
StatusMessage | Set of related messages | object:StatusMessage |
Response example:
Operation: GetEntityApplianceBrowseInfo
Gives url to remote access to specific appliance:
Request:
Parameter | Description | Validation |
|---|---|---|
Uuid | Identifier of appliance | Appliance must have HasRemoteAccess = true |
Request example:
Response:
Field | Description | Type |
|---|---|---|
Url | url to remote access page | string |
Response example:
Folder Backup Management
Endpoints:
Object: ImageStreamSettings
Parameter | Description | Validation |
|---|---|---|
ImageStreamSettingsId | Image stream settings identifier | Int, required |
ImageStreamFolders | Collection of object:ImageStreamFolder | |
SendEmailReport | Check if need to send report on SendEmailReportTo email address | bool |
SendEmailReportTo | Email address, on which email report will be sent | string, email address |
RunAsEnabled | Set to true if you need to run as user | bool |
RunAsUsername | Username if you are running under specific user | string required if RunAsEnabled is set to true |
RunAsPassword | Password if you are running under specific user | string required if RunAsEnabled is set to true |
Object: ImageStreamFolder
Parameter | Description | Validation |
|---|---|---|
ImageStreamFolderId | Image stream folder identifier | int, required |
BackupSchedule | Object:BackupSchedule | |
FolderFriendlyName | Folder name | string, required |
FolderPath | Folder path | string, required |
FolderPathDomainUser | User for specified folder | string, optional |
FolderPathPassword | Password for specified folder | string, optional |
RetentionPolicyTypeId | Unknown = 0, | int, required |
TimeLimitedBackupDays | Limited backup days | int, required |
SkipFilesModifiedDays | Skip files that were not modified X last days Could be specified if RetentionPolicyTypeId = 2-5 | int, optional |
CloudDeleteOlderThanDays | Delete files that are older then X days | int, optional Required if RetentionPolicyTypeId = 5 |
CloudForWholeHierarchy | Include subfolders | bool |
DateCreated | Date created | datetime |
Object: BackupSchedule
Parameter | Description | Validation |
|---|---|---|
ScheduleTypeId | Frequency Unknown = 0, | int, required |
HourlyPeriod | Hourly period | int, optional Required if ScheduleTypeId is set to 1 |
WeeklyDayOfWeek | Sunday, | string, optional Required if ScheduleTypeId is set to 3 |
MonthlyDayNumber | Day of Month | int, 1-31, optional Required if ScheduleTypeId is set to 4 |
StartTimeUTC | Start time Could be specified if ScheduleTypeId = 2-4 | datetime, required |
EndTimeUTC | End time Could be specified if ScheduleTypeId = 2-4 | datetima, optional Required if EndTimeEnabled is set to true |
EndTimeEnabled | Flag shows if EndTimeUTC should be entered | bool, required |
Operation: GetAdvancedFolderSettings
Get folder settings:
Request:
Parameter | Description | Validation |
|---|---|---|
UserName | Identifies account | Required, "^[^<>]{0,100}$" |
SystemName | Computer system name | Required |
Request example:
Response:
Field | Description | Type |
|---|---|---|
ImageStreamSettings | object:ImageStreamSettings |
Response example:
Operation: SetAdvancedFolderSettings
Set folder settings:
Request:
Parameter | Description | Validation |
|---|---|---|
UserName | Identifies account | Required, "^[^<>]{0,100}$" |
SystemName | Computer system name | Required |
ImageStreamSettings | object:ImageStreamSettings | Required |
Request example:
Response:
Field | Description | Type |
|---|---|---|
ImageStreamSettings | object:ImageStreamSettings |
Response example:
Backup Devices Management
Endpoints:
Production: https://secure.sosonlinebackup.com/WebApi/BackupDevicesManagementService/AppliancesManagementService.asmx
Operation: GetBackupDevices
Extracts devices details using filter:
Request:
Parameter | Description | Validation |
|---|---|---|
UserName | Filters devices by backup account | string, required It is supposed that client of this service belongs to entity identified by ApiCallerEntityId User name must belong to ApiCallerEntityId hierarchy |
Filters devices by device name | string, optional |
Request example:
Response:
Returns result as array where each item describes device details:
Field | Description | Type |
|---|---|---|
UserName | Backup account that uses device | string |
SystemName | Device name | string |
ProductVersion | Version of backup software | string, formatted as: major.minor.build.revision |
RegistrationDateUtc | Describes when device successfully logged in first time | DateTime, UTC |
OsName | Name of installed operating system | string |
ClrVersion | Version of .NET (if installed ) | string |
Response example:
Operation: GetDeviceAccounts (added on Mar 2018)
Gets all backup accounts registered on device:
Request:
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | ID of the Partner/Distributor, i.e. the root of the hierarchy thee. | required, int, >=0. Use 0 for yourself. |
InstallationId | Designed as unique, OBRM installation ID. Generated and stored on divice during installation. Doesn't get changed after upgrade. | required, guid string Examples: |
Windows system/computer/device name | string, optional | |
IsActiveUser | Allows to get only active (true), inactive (false) or all (when not set) accounts | boolean, optional |
IsActiveRegistration | Allows to get only curent (true), obsolete (false) or all (when not set) device registrations | boolean, optional |
Request example:
Response:
Returns result as array where each item describes device details:
Field | Description | Type |
|---|---|---|
UserName | Backup account that uses device | string |
SystemName | Windows system/computer/device name | string |
Ip | Ip adress of device | string, e.g "8.8.4.4" |
EntityID | Entity that owns UserName | int |
BackupDeviceID | Globally uinique device id | int |
IsActiveUser | Is backup account active | boolean |
IsActiveRegistration | Is it this device registration active | boolean |
ProductVersion | Version of backup software | string, formatted as: major.minor.build.revision |
UsedSpaceKb | Backed up data size, Kb | long |
RegistrationDateUtc | Describes when device successfully logged in first time | DateTime, UTC |
LastBackupDate | Last backup date | DateTime |
LastConnectedDateUtc | Version of .NET (if installed ) | DateTime, UTC |
Response example:
Cloud Application Backup Management
Endpoints:
Operation: EnableBackup (added on May 2018)
Request:
Parameter | Description | Validation |
|---|---|---|
ForEntityId | Entity owner of ICAB account | int |
Login of ICAB account | string, can be null. When null GeneralContactEmail of entity is used. | |
Region | Location of data center | string, can be null. When null 'US_EST' is used. Valid values are (without quotes): 'US_EST' , 'CANADA', 'EU' and 'ASIA_SIDNEY' |
Request example:
Response:
returns the standard Result object
Operation: DisableBackup (added on July 2018)
An opposite to EnableBackup method. Disables Infrascale Cloud Applications Backup for given entity by un-subscribing its account from ICAB Services.
Request:
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | EntityID of the Partner/Company/Distributor which ICAB account you want to disable, i.e unsubscribe from ICAB Services. | Int, >=0. Use 0 for yourself. |
Request example:
Response:
returns the standard Result object
Operation: GetCloudUsage (added on July 2018)
Parameter | Description | Validation |
|---|---|---|
TargetEntityID | EntityID of the Partner/Company/Distributor for which you want to get cloud backup usage | int, >=0. Use 0 for yourself. |
PageNumber | The page number | int >= 1 |
PageSize | The number of companies to display per page | int > 0, Default value: 1000 |
Request example:
Response:
Returns result as array where each item describes cloud backup usage for an used cloud service:
Field | Description | Type |
|---|---|---|
LastBackupDate | Last backup date | DateTime, can be null |
Accounts | For the user based pricing the number of activated accounts | long, can be null |
StorageBytes | For the storage based pricing the number of used storage (in bytes) | long, can be null |
Source | Service internal type | string |
Service | Service name | string |
ICABAccountName | Name of the ICAB account | string |
AccountDateCreated | Date of creating of ICAB account | DateTime |
CompanyID | EntityID of the Partner/Company/Distributor which uses cloud backup | int |
CompanyName | name of Partner/Company/Distributor which uses cloud backup | string |
ConfiguredDate | date when was configured the backup for the service | DateTime, can be null |
PageNumber | number of a current page | int |
NumberOfPages | Total number of pages | int |
TotalCount | Total number of companies for the request | int |
Response example: