AddPredefinedDestination

This API can be used to add (create) a predefined destination on the backup server.

The settings can be found on the AhsayCBS web console at:

• System Settings > Basic > Predefined Destinations

URL

https://CBS.EXAMPLE.COM/obs/api/json/AddPredefinedDestination.do

Available Since Version: 9.7

Parameters

Key	Type	Description
SysUser	String	Username of an AhsayCBS System User with Admin, API or Read-Only API role.
SysPwd	String	Password matching SysUser.
Type	String	The type of the predefined destination, please use one of the available type within the set provided in the table "Destination Type".
DestinationName	String	The name of the predefined destination, if not provided, the name will be auto-generated by the server.
DestinationSettings	JSON Object	The settings for the predefined destination, the underlying parameters are specific to each destination type. Please refer to the tables labeled with “DestinationSettings (DESTINATION_TYPE)” for the correct format of each destination type.
Owner	String	The owner administrator name of the newly added predefined destination, defaults to ADMIN.

Return Values

Key	Type	Description
Status	String	"OK" or "Error"
Message	String	Error message, it only appears if status displays "Error".
DestinationID	String	The ID for the newly added predefined destination, available only for successful addition.
ExptType	String	The type of exception (Java-class name), available only in error response body.

JSON Objects

Additional Fields (to merge with return values on error)

Key	Type	Description
InstructionID	String	The instruction id of this error, please refer to the table “Instruction ID” for the value set.
AvailableOptions	JSON Object	The available options for certain missing parameters, this field will be set when InstructionID equals MISSING_PARAMETER.
OAuthUrl	String	The authorization url for retrieving the authorization token, this field will be set when InstructionID equals OAUTH_OPEN_URL.
Message	String	The detailed message of this error.

Destination Type

Type	Description
FTP	An FTP-based destination.
SFTP	An SFTP-based destination.
Local	A local destination (local to the client).
OBS	A destination ("User Home") provided by the AhsayCBS server.
Pooled	A destination pool.
RPS	Used for replication.
Aliyun	Alibaba Aliyun
AWSCompatible	AWS Compatible
Azure	Microsoft Azure.
Backblaze	Backblaze
CTYun	China Telecom CTYun
Dropbox	Dropbox
GCS	Google Cloud Service
GDrive	Google Drive
OneDrive	Microsoft OneDrive
OneDrive4Biz	Microsoft OneDrive for Business
OpenStack	OpenStack
Rackspace	Rackspace
S3	Amazon S3
Wasabi	Wasabi

Instruction ID

Value	Description
MISSING_PARAMETER	Returned from a failed addition of a predefined destination, due to a missing parameter with predefined value set. If this ID is encountered, please refer to the RESPONSE_BODY. Message for instructions and RESPONSE_BODY_AvailableOptions for the value set.
OAUTH_OPEN_URL	Returned from a failed addition of predefined destination, due to undefined or empty authorization token in the request body. If encountered, please refer to RESPONSE_BODY. Message for instructions and RESPONSE_BODY.OAuthUrl for the url to kick start the authorization procedure.

Destination Settings - OBS

Key	Type	Description
Immutable	Boolean	Whether stored data cannot be changed, modified, or deleted after being created; defaults to false.
TempDelete	Boolean	Whether temporary delete is enabled for AhsayCBS destination; defaults to false.
TempDeleteDate	String	Temporary delete date in yyyy-mm-dd format; defaults to tomorrow’s date.
Hour	Integer	The end hour of temporary delete. "0", "1"..."23" can be set; defaults to 0.
Minute	Integer	The end minute of temporary delete. "0", "1"..."59" can be set; defaults to 0.

Destination Settings - FTP

Key	Type	Description
Host	String	The hostname of the FTP server.
Port	String	The port of the FTP server.
Username	String	The username of the FTP account.
Password	String	The password of the FTP account.
Ssl	Boolean	Whether the FTP connection will be in SSL mode.

Destination Settings - SFTP

Key	Type	Description
Host	String	The hostname of the SFTP server.
Port	String	The port of the SFTP server.
Username	String	The username of the SFTP account.
Password	String	The password of the SFTP account.

Destination Settings - Local

Key	Type	Descriptions
TopDir	String	The path to the target directory can be network locations.
Username	String	The username of the account.
Password	String	The password of the account.

Destination Settings - Pooled

Key	Type	Description
DestinationIDList	JSON Array	An array of predefined destination ids, all of the ids should reference any existing predefined destination within the AhsayCBS server.

Destination Settings - RPS

Key	Type	Description
Host	String	The hostname of the target replication AhsayCBS server.
Port	String	The port of the target replication AhsayCBS server.
Username	String	The username of the replication account created within the replication AhsayCBS server.
Password	String	The password of the replication account created within the replication AhsayCBS server.
Ssl	Boolean	Whether the connection uses SSL, defaults to "false".

Destination Settings - Aliyun

Key	Type	Description
AccessKey	String	The access key.
SecretKey	String	The secret key.
Location	String	The location of this destination, please refer to Aliyun Locations for the value set.
BucketName	String	The bucket name, optional.

Destination Settings - Aliyun Locations

Location	Value
China (Hangzhou)	oss-cn-hangzhou
China (Shanghai)	oss-cn-shanghai
China (Qingdao)	oss-cn-qingdao
China (Beijing)	oss-cn-beijing
China (Zhangjiakou)	oss-cn-zhangjiakou
China (Hohhot)	oss-cn-huhehaote
China (Ulanqab)	oss-cn-wulanchabu
China (Shenzhen)	oss-cn-shenzhen
China (Heyuan)	oss-cn-heyuan
China (Guangzhou)	oss-cn-guangzhou
China (Chengdu)	oss-cn-chengdu
China (Hong Kong)	oss-cn-hongkong
Singapore	oss-ap-southeast-1
Australia (Sydney)	oss-ap-southeast-2
Malaysia (Kuala Lumpur)	oss-ap-southeast-3
Indonesia	oss-ap-southeast-5
Japan (Tokyo)	oss-ap-northeast-1
India (Mumbai)	oss-ap-south-1
Germany (Frankfurt)	oss-eu-central-1
UK (London)	oss-eu-west-1
US (Silicon Valley)	oss-us-west-1
US (Virginia)	oss-us-east-1
UAE (Dubai)	oss-me-east-1

Destination Settings - AWSCompatible

Key	Type	Description
Host	String	The hostname of the AWS Compatible service.
Port	String	The port of the AWS Compatible service.
Immutable	Boolean	Whether stored data cannot be changed, modified, or deleted after being created; defaults to false.
AccessKey	String	The access key.
SecretKey	String	The secret key.
BucketName	String	The bucket name.

Destination Settings - Azure

Key	Type	Description
StorageAccountName	String	The storage account name.
AccessKey	String	The access key of the storage account.
Region	String	The region of the destination, please refer to Azure Regions section for the value set.
Immutable	Boolean	Whether stored data cannot be changed, modified, or deleted after being created; defaults to false.

Destination Settings - Azure Regions

Region	Value
Global	GLOBAL
China	CHINA
Germany	GERMANY
USGOV	USGOV

Destination Settings - Backblaze

Key	Type	Description
KeyId	String	The key ID.
ApplicationKey	String	The application key.
Immutable	Boolean	Whether stored data cannot be changed, modified, or deleted after being created; defaults to false.
BucketName	String	The bucket name, optional.

Destination Settings - CTYun

Key	Type	Description
AccessKey	String	The access key.
AccessSecretKey	String	The access secret key.

Destination Settings - Dropbox

Key	Type	Description
AccessToken	String	The authorization token retrieved from the Dropbox site, when this field is undefined or empty, the request will fail, with RESPONSE_BODY. InstructionID set to OAUTH_OPEN_URL and RESPONSE_BODY. OAuthUrl set to the url for kick-starting the authorization procedure.

Destination Settings - Google Cloud Storage

Key	Type	Description
AccessKey	String	The access key.
Secret	String	The access secret key.
Immutable	Boolean	Whether stored data cannot be changed, modified, or deleted after being created; defaults to false.
LocationType	String	The location type of this destination, please refer to GCS Location Types section for the value sets.
Location	String	The location of this destination, please refer to GCS Locations for the value set.
StorageClass	String	The storage class name of this destination, please visit this page for the latest documentation.
BucketName	String	The bucket name, optional.

Destination Settings - GCS Location Types

Type	Value
Region	REGION
Multi-Region	MULTI_REGION
Dual-Region	Dual-Region_REGION

Destination Settings - GCS Locations

Region	Value
Montreal	NORTHAMERICA-NORTHEAST1L
Iowa	US-CENTRAL1
South Carolina	US-EAST1
Northern Virginia	US-EAST4
Oregon	US-WEST1
Los Angeles	US-WEST2
Salt Lake City	US-WEST3
Las Vegas	US-WEST4
Sao Paulo	SOUTHAMERICA-EAST1
Warsaw	EUROPE-NORTH1
Belgium	EUROPE-WEST1
London	EUROPE-WEST2
Frankfurt	EUROPE-WEST3
Netherlands	EUROPE-WEST4
Zurich	EUROPE-WEST6
Taiwan	ASIA-EAST1
Hong Kong	ASIA-EAST2
Tokyo	ASIA-NORTHEAST1
Osaka	ASIA-NORTHEAST2
Seoul	ASIA-NORTHEAST3
Mumbai	ASIA-SOUTH1
Singapore	ASIA-SOUTHEAST1
Jakarta	ASIA-SOUTHEAST2
Sydney	AUSTRALIA-SOUTHEAST1

Destination Settings - Google Drive

Key	Type	Description
Token	String	The authorization token retrieved from Google Drive site, when this field is undefined or empty, the request will fail, with RESPONSE_BODY. InstructionID set to OAUTH_OPEN_URL and RESPONSE_BODY. OAuthUrl set to the url for kick-starting the authorization procedure.

Destination Settings - Microsoft OneDrive

Key	Type	Description
Token	String	The token for the destination, if the provided value is undefined or empty, the request will fail, with RESPONSE_BODY. InstructionID set to OAUTH_OPEN_URL and RESPONSE_BODY. OAuthUrl set to the url for kick-starting the authorization procedure.

Destination Settings - Microsoft OneDrive4Biz

Key	Type	Description
Token	String	The token for the destination, if the provided value is undefined or empty, the request will fail, with RESPONSE_BODY. InstructionID set to OAUTH_OPEN_URL and RESPONSE_BODY. OAuthUrl set to the url for kick-starting the authorization procedure.
Region	String	The region of the destination, please refer to the section OneDrive4Biz Regions for the value set.

Destination Settings - Microsoft OneDrive4Biz Regions

Region	Value
Global	GLOBAL
China	CHINA
Germany	GERMANY

Destination Settings - OpenStack

Key	Type	Descriptions
Host	String	The hostname of the OpenStack service.
Port	String	The port of the OpenStack service.
Username	String	The username of the service account.
Password	String	The password of the service account.
Project	String	The project name for this destination. If the provided value is undefined, RESPONSE_BODY. InstructionID set to MISSING_PARAMETERS, please follow the instruction provided in RESPONSE_BODY. Message to select the project for this destination.

Destination Settings - Rackspace

Key	Type	Description
Username	String	The username of the Rackspace account.
ApiKey	String	The API key for accessing Rackspace APIs.
Region	String	The region name of the Rackspace service, please refer to Rackspace Regions section for the value set.
ContainerName	String	The container name of the destination.

Destination Settings - Rackspace Regions

Region	Value
Chicago	ORD
Dallas Ft. Worth	DFW
Hong Kong	HKG
London	LON
Northern Virginia	IAD
Sydney	SYD

Destination Settings - Amazon S3

Key	Type	Description
AccessKey	String	The access key.
SecretKey	String	The secret key.
Immutable	Boolean	Whether stored data cannot be changed, modified, or deleted after being created; defaults to false.
Location	String	The location of the destination, please refer to Amazon S3 Locations for the value sets.
StorageClass	String	The storage class of the destination, please refer to Amazon S3 Storage Classes for the value sets.
BucketName	String	The bucket name, optional.

Destination Settings - Amazon S3 Locations

Region	Value
Africa (Cape Town)	af-south-1
Asia Pacific (Hong Kong)	ap-east-1
Asia Pacific (Mumbai)	ap-south-1
Asia Pacific (Osaka-Local)	ap-northeast-3
Asia Pacific (Seoul)	ap-northeast-2
Asia Pacific (Singapore)	ap-southeast-1
Asia Pacific (Singapore)	ap-southeast-1
Asia Pacific (Sydney)	ap-southeast-2
Asia Pacific (Tokyo)	ap-northeast-1
Canada (Central)	ca-central-1
China (Beijing)	cn-north-1
China (Ningxia)	cn-northwest-1
Europe (Ireland)	eu-west-1
Europe (Frankfurt)	eu-central-1
Europe (London)	eu-west-2
Europe (Milan)	eu-south-1
Europe (Stockholm)	eu-north-1
AWS GovCloud (US-East)	us-gov-east-1
AWS GovCloud (US)	us-gov-west-1
Middle East (Bahrain)	me-south-1
South America (Sao Paulo)	sa-east-1
US East (Ohio)	us-east-2
US West (Northern California)	us-west-2

Destination Settings - Amazon S3 Storage Classes

Type	Value	Description
Standard	STANDARD	Ideal for performance sensitive use cases and frequently accessed data. This is the default storage class.
Standard - Infrequent Access Storage	STANDARD_IA	(IA, for infrequent access) is optimized for long-lived and less frequently accessed data, for example backups and older data where access has diminished, but the use case still demands high performance.
Intelligent - Tiering Storage	INTELLIGENT_TIERING	Long-lived data with changing or unknown access patterns.
One Zone - Infrequent Access Storage	ONEZONE_IA	Long-lived, infrequently accessed, non-critical data.
Reduced Redundancy Storage (RRS)	REDUCED_REDUNDANCY	(RSS) Storage class is designed for non-critical, reproducible data stored at lower levels of redundancy than the STANDARD storage class, which reduces storage costs.

Destination Settings - Wasabi

Key	Type	Description
AccessKey	String	The access key.
SecretKey	String	The secret key.
Immutable	Boolean	Whether stored data cannot be changed, modified, or deleted after being created; defaults to false.
BucketName	String	The bucket name, optional.
Location	String	The location of the Wasabi service, please refer to Wasabi Locations section for the value sets.

Destination Settings - Wasabi Locations

Region	Value
Toronto	ca-central-1
Oregon	us-west-1
Plano, Texas	us-central
Northern Virginia	us-east-1
Southern Virginia	us-east-2
Amsterdam	eu-central-1
Frankfurt	eu-central-2
London	eu-west-1
Paris	eu-west-2
Tokyo	ap-northeast-1
Osaka	ap-northeast-2
Singapore	ap-southeast-1
Sydney	ap-southeast-2

Examples

Example 1: Creating a Google Drive Predefined Destination

INPUT

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"Type":"GDrive",
	"SkipVerify":false,
	"DestinationSettings":{
		"Token":"9/abc0e-g5bc2XX2jepVtYRSiA6J4Q03rgVPfssYVu3xhyl9PiHqkiabmwM3i"
	}
}

OUTPUT

{
	"Status":"OK",
	"DestinationID":"-1620712268943"
}

Example 2: Invalid Token for Google Drive Predefined Destination

INPUT

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"Type":"GDrive",
	"DestinationSettings":{
		"Token":"FAKE"
	}
}

OUTPUT

{
	"Status":"Error",
	"Message":"[GDriveManager$GDriveAuthorization.getOAuth2TokensByTempKey] Failed to get Oauth2Tokens after retrieved from GDrive",
	"ExptType":"java.lang.Exception"
}

Example 3: Creating AhsayCBS (OBS) Destination with no 2FA Setup

INPUT

{
	"SysUser":"api_user",
	"SysPwd":"qWeRtY123456!@#$%",
	"Type":"OBS",
	"DestinationSettings":{
		"Immutable":true,
		"TempDelete":true,
		"TempDeleteDate":"2024-08-25",
		"Hour":6,
		"Minute":13
	}
}

OUTPUT

{
	"Status":"Error",
	"Message":"Please setup 2FA devices to proceed with adding immutable destination.",
	"ExptType":"com.ahsay.obs.core.dbs.DbsException"
}