1. Cloud Control Database Lifecycle Management Administrator's Guide
  2. Database Provisioning
  3. Provisioning Oracle Standby Databases

12 Provisioning Oracle Standby Databases

This chapter contains the following sections:

Overview of Creating a Standby Database

Creating a standby database is the first thing you must do before you can manage and monitor the databases. Enterprise Manager Cloud Control provides the Add Standby Database wizard to create a broker configuration that includes a primary database and one or more standby databases.

You can create a physical or a logical standby database. Physical standby databases are physically identical to the primary database, mounted or open read-only when in recovery mode, and support all datatypes and DDL. Logical standby databases are physically different from the primary database, open read-write only when in recovery mode, can be used for data protection and reporting, and support only some databases and DDL.

The standby database creation process performs the following steps:

  • Performs an online backup (or optionally uses an existing backup) of the primary database control file, datafiles, and archived redo log files

  • Transfers the backup pieces from the primary host to the standby host

  • Creates other needed files (e.g., initialization, password) on the standby host

  • Restores the control file, datafiles, and archived redo log files to the specified locations on the standby host

  • Adds online redo log files and other files to the standby database as needed

  • Configures the recovered database as a physical or logical standby database

Creating a New Physical Standby Database (single-instance only)

To create a new physical standby database (single-instance only), follow these steps:

Note:

New physical databases will be created as single-instance databases. The Enterprise Manager Convert to Cluster Database function can be used to convert the standby database to a cluster database after it is created.

  1. From the Targets menu, select Databases.
  2. On the Databases page, you see a list of databases. Select the primary database for which you want to create a new physical standby database.
  3. On the primary database home page, click Availability and then select Add Standby Database.
  4. On the Database Login page, enter your credentials. Click Login.

    Note:

    You need to connect to the primary database using SYSDBA credentials, if you are not yet connected.

    If you log in as a user with SYSDBA privileges, you will have access to all Data Guard functionality, including all monitoring and management features. If you log in as a non-SYSDBA user, you will have access to monitoring functions only; features such as standby creation, switchover, and failover will not be available.

  5. On the Add Standby Database page, select Create a new physical standby database. Click Continue.

    Note:

    If you choose to create a new physical or logical standby database, Data Guard checks the following when you click Continue:

    • Server parameter file (SPFILE) -- Data Guard requires that all databases in a configuration use a server parameter file (SPFILE). If the wizard encounters a primary database that does not use an SPFILE, the wizard stops and returns a message asking you to create one. You can create one with a non-default name. Data Guard only requires that the primary database uses an SPFILE.

    • NOARCHIVELOG mode -- Regardless of what method you choose to add the standby database, the primary database must be in ARCHIVELOG mode. If the primary database is in NOARCHIVELOG mode, you will be asked to exit the wizard and put the primary database into ARCHIVELOG mode.

  6. The Add Standby Database wizard opens. It takes you through the following steps:

    • Determine the backup type.

    • Set up the backup options.

    • Select the Oracle home in which to create the standby database.

    • Set up the location for standby database files.

    • Provide standby database configuration parameters.

    • Review the information before clicking Finish.

Step 1: Determine the backup type

Enterprise Manager uses Oracle Recovery Manager (RMAN) to create a single-instance standby database from a new or existing backup of the primary database. You can select one of two backup operations to use for the standby database creation:

  • Perform a live backup of the primary database using RMAN to copy database files, or by copying the database files via staging areas.

  • Use an existing RMAN backup or an existing backup from a previous standby database creation.

Click Next.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

Step 2: Set up the backup options

For an online backup using RMAN, enter the Degree of Parallelism (the number of parallel channels used by RMAN to copy the database files). The default number is 2.

For an online backup by copying the database files via staging areas, provide the staging area location. You can also choose if you want to retain the directory or delete it after the standby database has been created.

For an offline backup using RMAN, provide the RMAN backup location and the staging area location.

Enter the primary host credentials. You can use existing credentials or create new credentials. If you create new credentials you can save the credentials to use for another database standby creation later. To do this, check the Set As Preferred Credentials box.

Click Next.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

Step 3: Select the Oracle home in which to create the standby database

The standby database can be created in any Oracle home that was discovered by Oracle Enterprise Manager. Only Oracle homes on hosts that match the operating system of the primary host are shown. You must select a discovered Oracle home and provide a unique instance name for the standby database. Standby host credentials are required to continue.

Step 4: Set up the location for standby database files

Since the primary and standby databases are the same host, the standby database files are placed into an Oracle Optimal Flexible Architecture (OFA) directory structure. Click Customize to modify individual file names.

In the Listener Configuration section, specify the name and port of the listener that will be used for the standby database. If a new name and port are specified that are not in use by an existing listener, a new listener using the specified port will be created.

Click Next.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

Step 5: Provide standby database configuration parameters

Standby database configuration parameters must be set. These parameters include the database name, database unique name, target name, and standby archive location. The standby archive location can be a regular directory or a flash recovery area. The default values are based on corresponding primary database settings.

After you verify that the parameters are correct, click Next.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

Step 6: Review the information before clicking Finish

The Add Standby Database wizard allows one last review of the data you input for the configuration and standby database. Click Finish when you are certain all of the information is correct.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

By clicking Standby Database Storage, you can see additional information about all the standby database file locations.

Once you click Finish, the standby database creation process runs as an Oracle Enterprise Manager job. You can cancel the standby creation at any point before the job submission.

After the job is submitted, you will be returned to the Data Guard Overview page. In the Status column of the Standby Databases table, you will see Creation in progress listed. If you click that link, you can monitor the progress of the standby database creation.

Note:

To add additional standby databases after the initial creation of the configuration, click Add Standby Database to run the Add Standby Database wizard again.

Creating a New Logical Standby Database (single-instance only)

To create a new physical standby database (single-instance only), follow these steps:

Note:

New logical standby databases will be created as single-instance databases. The Enterprise Manager Convert to Cluster Database function can be used to convert the standby database to a cluster database after it is created.

  1. From the Targets menu, select Databases.

  2. On the Databases page, you see a list of databases. Select the primary database for which you want to create a new physical standby database.

  3. On the primary database home page, click Availability and then select Add Standby Database.

  4. On the Database Login page, enter your credentials. Click Login.

    Note:

    You need to connect to the primary database using SYSDBA credentials, if you are not yet connected.

    If you log in as a user with SYSDBA privileges, you will have access to all Data Guard functionality, including all monitoring and management features. If you log in as a non-SYSDBA user, you will have access to monitoring functions only; features such as standby creation, switchover, and failover will not be available.

  5. On the Add Standby Database page, select Create a new physical standby database. Click Continue.

    Note:

    If you choose to create a new physical or logical standby database, Data Guard checks the following when you click Continue:

    • Server parameter file (SPFILE) -- Data Guard requires that all databases in a configuration use a server parameter file (SPFILE). If the wizard encounters a primary database that does not use an SPFILE, the wizard stops and returns a message asking you to create one. You can create one with a non-default name. Data Guard only requires that the primary database uses an SPFILE.

    • NOARCHIVELOG mode -- Regardless of what method you choose to add the standby database, the primary database must be in ARCHIVELOG mode. If the primary database is in NOARCHIVELOG mode, you will be asked to exit the wizard and put the primary database into ARCHIVELOG mode.

  6. On the database page, in the Standby Databases section, click Add Standby Database.

  7. The following steps assume a broker configuration already exists with one primary database and one physical standby database, and creates a new logical standby database. It shows how the wizard takes you through additional steps to select the Oracle home for the database and to copy datafiles to the standby database.

    The Add Standby Database wizard takes you through the following steps:

    1. Determine the backup type.

    2. Set up the backup options.

    3. Select the Oracle home in which to create the standby database.

    4. Set up the location for standby database files.

    5. Provide standby database configuration parameters.

    6. Review the information before clicking Finish.

Step 1: Determine the backup type

Enterprise Manager uses Oracle Recovery Manager (RMAN) to create a single-instance standby database from a new or existing backup of the primary database. You can select one of two backup operations to use for the standby database creation:

  • Perform a live backup of the primary database

  • Use an existing backup of the primary database

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

Step 2: Set up the backup options

A working directory is needed to store the primary database backup files. It can optionally be retained and used to create additional standby databases in the future. Specify a location on the primary host in which the working directory can be created.

Primary host credentials are required for this step. Enter the credentials of the owner of the primary database Oracle server installation. These credentials can be saved by checking the box marked Save as Preferred Credential.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

Step 3: Select the Oracle home in which to create the standby database

The standby database can be created in any Oracle home that was discovered by Oracle Enterprise Manager. Only Oracle homes on hosts that match the operating system of the primary host are shown. You must select a discovered Oracle home and provide a unique instance name for the standby database. Standby host credentials are required to continue.

Step 4: Set up the location for standby database files

Part of the create broker configuration process involves making the datafiles for the primary database available to the standby host. You have the option of customizing the location for the standby database files. Standby host credentials are required to continue. The following list describes your options:

  • Specify the backup file access method

    Choose the method by which you want to make the primary database backup files accessible to the standby host. The two options are:

    • Transfer files from the primary host working directory to a standby host working directory

    • Directly access the primary host working directory location from the standby host using a network path name

  • Specify the standby database file location

    Choose the locations for the standby database files. You have two options:

    • Convert to Oracle OFA (Optimal Flexible Architecture)

    • Keep file names and locations the same as the primary database

  • Specify the network configuration file location

    Data Guard will add configuration information for the standby database to the network configuration files (listener.ora and tnsnames.ora) in the specified directory on the standby host.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

Step 5: Provide standby database configuration parameters

Standby database configuration parameters must be set. These parameters include the database name, database unique name, target name, and standby archive location. The standby archive location can be a regular directory or a flash recovery area. The default values are based on corresponding primary database settings.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

Step 6: Review the information before clicking Finish

The Add Standby Database wizard allows one last review of the data you input for the configuration and standby database. Click Finish when you are certain all of the information is correct.

You can click Cancel to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

By clicking Standby Database Storage, you can see additional information about all the standby database file locations.

Once you click Finish, the standby database creation process runs as an Oracle Enterprise Manager job. You can cancel the standby creation at any point before the job submission.

After the job is submitted, you will be returned to the Data Guard Overview page. In the Status column of the Standby Databases table, you will see Creation in progress listed. If you click that link, you can monitor the progress of the standby database creation.

Note:

To add additional standby databases after the initial creation of the configuration, click Add Standby Database to run the Add Standby Database wizard again.

Managing an Existing Standby Database with Data Guard Broker

To add an existing standby database, follow these steps:

  1. From the Targets menu, select Databases.
  2. On the Databases page, you see a list of databases. Select the database you want to manage an existing standby database.
  3. On the primary database home page, click Availability and then select Add Standby Database.
  4. On the Database Login page, enter your credentials. Click Login.

    Note:

    You need to connect to the primary database using SYSDBA credentials, if you are not yet connected.

    If you log in as a user with SYSDBA privileges, you will have access to all Data Guard functionality, including all monitoring and management features. If you log in as a non-SYSDBA user, you will have access to monitoring functions only; features such as standby creation, switchover, and failover will not be available.

  5. In the Add Standby Database page, select Manage an Existing Standby Database with Data Guard Broker.
  6. Select an existing standby database that you want to be managed by the Data Guard broker. The database you choose must have been created from the primary database and must be configured to function as a standby database.

    All discovered databases in your environment (both RAC and non-RAC databases) will be shown in the list.

    Click Next.

    Note:

    You can click Cancel at any time to terminate the current process and begin again at the introductory page of the Add Standby Database wizard.

  7. Enter the log in details for the database. You can select Named or New credentials. For new credentials, create a unique credential. You can set it to Preferred Credential if you want to use it again.

    Click Next.

  8. (optional) Change the Standby Archive Location setting of the existing standby cluster database. Click Next.
  9. Review the data for the configuration and standby database. Click Finish

Creating a Primary Database Backup Only

An additional option is to only create a primary database backup without creating a standby database. This backup can be used for future standby database creations by re-running the Add Standby Database wizard and choosing to create a standby database from an existing backup. The existing backup can be used from either the primary or standby host. Consider this option if you are not able to use the file transfer mechanism provided by Enterprise Manager to transfer the backup files from the primary to the standby hosts, and instead wish to transfer and stage the backup files on the standby host using your own mechanism.

To create a primary database backup only, follow these steps:

  1. From the Targets menu, select Databases.
  2. On the Databases page, you see a list of databases. Select the database you want to manage an existing standby database.
  3. On the primary database home page, click Availability and then select Add Standby Database.
  4. On the Database Login page, enter your credentials. Click Login.

    Note:

    You need to connect to the primary database using SYSDBA credentials, if you are not yet connected.

    If you log in as a user with SYSDBA privileges, you will have access to all Data Guard functionality, including all monitoring and management features. If you log in as a non-SYSDBA user, you will have access to monitoring functions only; features such as standby creation, switchover, and failover will not be available.

  5. In the Add Standby Database page, select Create a Primary Backup Only.

    Click Continue.

  6. On the Backup Options page, specify a location on the primary host where a directory can be created to store the primary database backup files. Click Next.
  7. On the Schedule page, specify a name, description, and start time for the backup job.

    You can choose to start the backup immediately or at a later time. If you want to start at a later time, set the time and date for when the backup should start.

    Click Next.

  8. Review the data for the configuration and standby database. Click Finish

Database High Availability REST API

This chapter provides details of the REST APIs for Database High Availability supported in Enterprise Manager. Enable Data Guard to improve production database performance by offloading resource-intensive backup and reporting operations to standby systems.

Data Guard

Data Guard Switchover REST API

Table 12-1 Data Guard Switchover

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/switchover

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "primaryTargetName" : "<primary target name>",
    "primaryTargetType" : "oracle_database|rac_database",
    "standbyTargetName" : "<standby target name>",
    "standbyTargetType" : "oracle_database|rac_database",
    ["primaryDbCredsName" : "<primary database credential name>",]
    ["primaryHostCredsName" : "<primary database host credential name>",]
    ["standbyDbCredsName" : "<standby database credential name>",]
    ["standbyHostCredsName" : "<standby database host credential name>",]
    ["swapJobs" : "false|true",]
    ["swapThresholds" : "false|true",]
    ["tdeWalletCredsName" : "<transparent data encryption wallet credentials of the primary database>"]
    ["tdeWalletPassword"  :  "<transparent data encryption wallet password of the primary database>"]
}

Request method

POST

Sample Body

 
{
    "primaryTargetName" : "dbname", 
    "primaryTargetType" : "oracle_database", 
    "standbyTargetName" : "sdbname", 
    "standbyTargetType" : "oracle_database", 
    "primaryDbCredsName" : "SYS", 
    "primaryHostCredsName" : "AIMEDB_N", 
    "standbyDbCredsName" : "SYS", 
    "standbyHostCredsName" : "AIMEDB_N", 
    "swapJobs" : "true", 
    "swapThresholds" : "true", 
    "tdeWalletCredsName" : "WC1"
}

Sample Response

 
{
    "status": "Succeeded",
    "submissionName": "dbname_DataguardSwitchover_091418163542",
    "executionGUID": "75D3A124B36D1A4DE0536A8A7B0A80E0",
    "databaseName": "dbname",
    "message": "Deployment procedure for switchover to dbname:oracle_database successfully submitted."
}

Supported Since Release

EM DB 13.3.2.0.0

Note:

Parameters listed within a square bracket are optional.

Table 12-2 Data Guard Switchover Parameters

Parameter Description
primaryTargetName

Primary database Enterprise Manager target name. Can be either a single-instance database or a cluster database.
primaryTargetType

Primary database target type. Allowed values are either single-instance database (oracle_database) or cluster database (rac_database).
standbyTargetName

Standby database Enterprise Manager target name. Can be either a single-instance database or a cluster database.
standbyTargetType

Standby database target type. Allowed values Allowed values are either single-instance database (oracle_database) or cluster database (rac_database).
primaryDbCredsName

Primary database named credential for a user with SYSDBA or SYSDG role. If this argument is not specified, preferred credential will be used.
primaryHostCredsName

Primary database host named credential for an operating system user who can access the primary database Oracle home. If this argument is not specified, preferred credential will be used.
standbyDbCredsName

Standby database named credential for a user with SYSDBA or SYSDG role. If this argument is not specified, preferred credential will be used.
standbyHostCredsName

Standby database host named credential for an operating system user who can access the standby database Oracle home.
swapJobs

Specifies that scheduled jobs on either the primary or standby database that are of a transferable type (Backup, RMAN Script, and SQL Script) will be moved to the other database after the switchover is complete. Only jobs that use global named or preferred credentials can be transferred. Default Value: Not enabled.
swapThresholds

Specifies that monitoring settings will be swapped between the primary and standby databases after the switchover is complete.

Default Value: Not enabled
tdeWalletCredsName

Transparent Data Encryption wallet credentials for the primary database. Use create_named_credential verb to create these credentials as shown below:

emcli create_named_credential -cred_name=WC1 -cred_type=GenericPassword -auth_target_type='<system>' -attributes="GENERIC_PASSWORD:<Primary Database TDE Wallet Password>"
tdeWalletPassword

Transparent Data Encryption wallet password for the primary database.

Convert Standby Database REST API

Table 12-3 Convert Standby Database

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/convertStandby

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "dbTargetName" : "<standby target name>",
    "dbTargetType" : "oracle_database|rac_database",
    ["dbHostCredName" : "<standby database host credential name>",] 
    ["dbCredName" : "<standby database credential name>",]
    ["convertToDbRole" : "PHYSICAL STANDBY|SNAPSHOT STANDBY" ]
}

Sample Body

 
{
    "dbTargetName": "s11gfss",
    "dbTargetType":"oracle_database",
    "dbHostCredName": "GIMAN_N",
    "dbCredName": "SYSDBA_CREDS", 
    "convertToDbRole": "snapshot"
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"dbname_DGConvertStandby_092318020955",
    "executionGUID":"76815E6ABC9465F5E053C365F20A61AF",
    "databaseName":"dbname",
    "message":"Deployment procedure to convert the standby database successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.3.2.0.0

Table 12-4 Convert Standby Database Parameters

Parameter Description
dbTargetName

Standby database Enterprise Manager target name. Can be either a single-instance database or a cluster database.
dbTargetType

Standby database target type. Allowed values Allowed values are either single-instance database (oracle_database) or cluster database (rac_database).
dbHostCredName

Standby database host named credential for an operating system user who can access the standby database Oracle home. If this argument is not specified, preferred credential will be used.
dbCredName

Standby database named credential for a user with SYSDBA or SYSDG role. If this argument is not specified, preferred credential will be used.
convertToDbRole

Standby database role to be converted to given role. Possible values are Physical Standby and Snapshot Standby.

Backup and Recovery

Configure Backup REST API

Table 12-5 Configure Database to Send Backup

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/backup/configure

Request header

Authorization: basic

Content-Type: application/json

Body1

Configure database to be protected by a Recovery Appliance, with the ability to send backups to the Recovery Appliance.

{
    "dbTargetName":"<database target name>",
    "dbTargetType":"oracle_database|rac_database",
    "configureRABackup":"true"
    "raTargetName":"<Recovery Appliance target name>"
    "raUser":"<Recovery Appliance database user name>"
    ["dbCredName":"<database named credential>"],
    ["dbHostCredName":"<database host named credential>"],
    ["enableRedoShip":"true"]
    ["forceBackupModuleInstall":"true"]
}

Sample Body

 
{
    "configureRABackup":"true",
    "dbTargetType":"oracle_database",
    "dbTargetName":"zd2", 
    "raTargetName":"ra",
    "raUser":"orsadmin",
    "dbCredName": "RMAN",
    "dbHostCredName":"AIMEDB_N"
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"BACKUP_CONFIG_011419155235",
    "executionGUID":"7F69505339B4413FE053EB987B0A226E",
    "databaseName":"zd2",
    "message":"Deployment procedure to configure high availability settings to database successfully submitted."
}

Body2

Configure database to send backups to Oracle Database Backup Cloud Service.

{
    "dbTargetName":"<database target name>",
    "dbTargetType":"oracle_database|rac_database",
    "configureCloudBackup":"true",
    ["dbCredName":"<database named credential>"],
    ["dbHostCredName":"<database host named credential>"],
    ["forceBackupModuleInstall":"true"]
    ["cloudAccount":"<Hybrid Cloud Console cloud service account name>"]
}

Sample Body

 
{
    "configureCloudBackup":"true",
    "dbTargetType":"oracle_database", 
    "dbTargetName":"dgprim", 
    "dbHostCredName":"GIMAN_N", 
    "dbCredName": "SYS",
    "cloudAccount":"endpoint:https://storage.example.com/v1/Storage-emdev2;identityDomain:emdev2;username:xxxx;password:xxxx;container:db19_cntr"
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"OPC_BACKUP_CONFIG_010919120757",
    "executionGUID":"7F000E71E0DE624BE053EB987B0ADF02",
    "databaseName":"dgprim",
    "message":"Deployment procedure to configure high availability settings to database successfully submitted."
}

Body3

Install an RMAN Backup Module in the Oracle Home of the specified database or install the Recovery Appliance file system backup agent on the host of the database.

{
    "dbTargetName":"<database target name>",
    "dbTargetType":"oracle_database|rac_database",
    "installSoftware":"true",
    "moduleType":"ra|cloud",
    "installBackupModule":"true",
    ["dbHostCredName":"<database host named credential>"],
    ["forceBackupModuleInstall":"true"]
}

Sample Body

 
{
    "installSoftware":"true",
    "dbTargetType":"oracle_database", 
    "dbTargetName":"dgprim", 
    "moduleType":"cloud",
    "installBackupModule":"true",
    "dbHostCredName":"GIMAN_N"
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"INSTALL_BKP_MODULE_011019111214",
    "executionGUID":"7F1502D6C5CB5E53E053EB987B0AA38E",
    "databaseName":"dgprim",
    "message":"Deployment procedure to configure high availability settings to database successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.3.2.0.0

Table 12-6 Configure Backup Parameters

Parameter Description
Body1
dbTargetName

A single-instance or cluster database target name for the database that will be configured to send backups to the Recovery Appliance.
dbTargetType

The type of the target specified by "dbTargetName", either a single-instance database (oracle_database) or a cluster database (rac_database).
configureRABackup

Configure database to be protected by a Recovery Appliance, with the ability to send backups to the Recovery Appliance. Any one option configureRABackup, configureCloudBackup or installSoftware must be provided. The possible value is "true".

dbCredName

The name of an existing Enterprise Manager database named credential that can be used to connect to the specified target database. If this argument is not specified, preferred credential will be used.
dbHostCredName

The name of an existing Enterprise Manager database host named credential that can be used to run operating system commands on the specified target database hosts. The credential should be for a user that has write permission for Oracle Home. If this argument is not specified, preferred credential will be used.
raTargetName

The target name of the Recovery Appliance that the specified database will be configured to send backups to.
raUser

The name of the Recovery Appliance database user that will be used by the specified database to send backups to and ship redo to the Recovery Appliance. This must be a virtual private catalog user, not the Recovery Appliance administrator user.
enableRedoShip

Enable realtime redo transport to the Recovery Appliance from the specified target database.

Default value: True

forceBackupModuleInstall

Force installation of the version of the Recovery Appliance Backup Module stored in the Enterprise Manager software library into the Oracle Home of the specified target database, regardless of whether there is an existing Backup Module installed in the Oracle Home. This will overwrite any existing Backup Module, so this option should be selected only if it is known that the Backup Module version in the software library is at the same or later version than the version installed on the specified target database. If this option is not specified, the Backup Module will be installed only if there is no existing Backup Module installed in the Oracle Home.

Default value: True

Body2
dbTargetName

A single-instance or cluster database target name for the database that will be configured to send backups
dbTargetType

The type of the target specified by "dbTargetName", either a single-instance database (oracle_database) or a cluster database (rac_database).

configureCloudBackup

Configure database to send backups to Oracle Database Backup Cloud Service. Any one option configureRABackup, configureCloudBackup or installSoftware must be provided. The possible value is "true".

dbCredName

The name of an existing Enterprise Manager database named credential that can be used to connect to the specified target database. If this argument is not specified, preferred credential will be used.

dbHostCredName

The name of an existing Enterprise Manager database host named credential that can be used to run operating system commands on the specified target database hosts. The credential should be for a user that has write permission for Oracle Home. If this argument is not specified, preferred credential will be used.
forceBackupModuleInstall

Force installation of the version of the Oracle Database Cloud Backup Module stored in the Enterprise Manager software library into the Oracle Home of the specified target database, regardless of whether there is an existing Backup Module installed in the Oracle Home. This will overwrite any existing Backup Module, so this option should be selected only if it is known that the Backup Module version in the software library is at the same or later version than the version installed on the specified target database. If this option is not specified, the Backup Module will be installed only if there is no existing Backup Module installed in the Oracle Home.

cloudAccount

The name of a cloud account configured under the Enterprise Manager Hybrid Cloud Setup console. All information needed to connect to the Backup Service will be obtained from the account and its associated Backup Service settings, including the service name, identity domain, username, password, and container (optional). If this argument is not specified, the global cloud account settings configured in the Database Backup Cloud Service Settings page will be used. (This argument is applicable only if the Hybrid Cloud Setup console has been used to configure accounts and Backup Service settings.). This is field should be provided with "configureCloudBackup" option.

Example- "cloudAccount":"endpoint:https://storage.oracle.com/ Storageemdev2;identityDomain:xxx;username:xxxx;password:xxxx;contai ner:xxxx"

Body3
dbTargetName

Same as -configureRABackup usage above.
dbTargetType

Same as -configureRABackup usage above.
installSoftware

Install an RMAN Backup Module in the Oracle Homes of one or more databases or install the Recovery Appliance file system backup agent on the host of one database. Any one option configureRABackup, configureCloudBackup or installSoftware have be provided. The possible value is "true".

dbHostCredName

Same as -configureRABackup usage above.
installBackupModule

Install the version of the Backup Module (of the type specified by the moduleType option) stored in the Enterprise Manager software library in the Oracle Home of the specified target database. By default, the module will be installed only if there is not an existing module in the database Oracle Home, unless the force_backup_module_install flag is specified.
moduleType

The type of RMAN backup module to be installed. Possible values:

  • ra: Recovery Appliance Backup Module
  • cloud: Oracle Database Cloud Backup Module
forceBackupModuleInstall

Used in combination with installBackupModule option. Same as -configureRABackup usage above.

Backup REST API

This section provides the details of the Backup REST API.

Table 12-7 Backup

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/backup

Request header

Authorization: basic

Content-Type: application/json

Body

Configure database to be protected by a Recovery Appliance, with the ability to send backups to the Recovery Appliance.

{
    "dbTargetName":"<database target name>",
    "dbTargetType":"oracle_database|rac_database|oracle_cloud_dbcs",
    ["dbCredName":"<database named credential>"],
    ["dbHostCredName":"<database host named credential>"],
    ["scope":"wholeDB|tablespace|datafile|archivedLog|,recoveryFilesOnDisk|cdbRoot|pluggableDbs"],
    ["scopeValue":"<comma-separated list of values>"],
    ["backupType":"full|incr0|incr1" ["incrType:"diff|cumulative"]],
    ["destinationMedia":"disk|tape|ra|cloud"],
    ["skipBackupArchivedLogs":"true|false"],
    ["deleteArchivedLogsAfterBackup":"true|false"],
    ["deleteObsolateBackups":"true|false"],
    ["maxFilesPerSet":"<numeric value>"],
    ["maxCorruptions":"<numeric value>"],
    ["sectionSize":"<numeric value>"],
    [["backupEncryptionMode":"wallet|password|both"],
    ["rmanEncryptionCredName":"<RMAN encryption named credential>"],
    ["encryptionAlogrithm":"AES128|AES192|AES256"]],
    ["cloudAccount":"<cloud storage container url with endpoint, identityDomain, username,passoword and container name>"]
}

Request method

POST

Supported Since Release

EM DB 13.3.2.0.0

Sample Body

 
{
    "dbTargetType":"oracle_database", 
    "dbTargetName":"dgprim", 
    "dbHostCredName":"GIMAN_N", 
    "dbCredName": "SYS", 
    "scope":"wholeDB", 
    "backupType":"full", 
    "backupEncryptionMode":"password",
    "encryptionAlogrithm":"AES128",
    "rmanEncryptionCredName":"WC1",
    "cloudAccount":"endpoint:https://storage.example.com/v1/Storage-emdev2;identityDomain:emdev2;username:xxxx;password:xxx;container:db19_cntr", 
    "destinationMedia":"cloud", 
    "maxFilesPerSet":2
}

Sample Response

 
{
    "status":"Succeeded",
    "submissionName":"Backup_DB_from_OMC_010919152109",
    "executionGUID":"7F044AF2D1F60905E053EB987B0A569B",
    "databaseName":"dgprim",
    "message":"Backup to Oracle Cloud deployment procedure successfully submitted."
}

Table 12-8 Backup Parameters

Parameter Description
Body1
dbTargetName

A single-instance, cluster database, or database cloud service target name for the database that will be backed up.
dbTargetType

The type of the target specified by "dbTargetName", either a single-instance database (oracle_database), a cluster database (rac_database), or a database cloud service (oracle_cloud_dbcs).
dbCredName

The name of an existing Enterprise Manager database named credential that can be used to connect the specified target database. If the operating system user specified by the "dbHostCredName" argument is a member of the operating system DBA group, the database credential can specify a Normal role user. Otherwise, the database credential must specify a SYSDBA role user. If this argument is not specified, then preferred credential will be used.
dbHostCredName

The name of an existing Enterprise Manager database host named credential that can be used to run the RMAN command on the specified target database host. If this argument is not specified, then preferred credential will be used.
scope

The scope of the backup. If this argument is not specified, the default value is wholeDB. Possible values are:

  • wholeDB: All data files in the database.
  • tablespace: One or more data files associated with the tablespace name.
  • datafile: One or more data files.
  • archivedLog: Exactly one copy of each distinct log sequence number.
  • recoveryFilesOnDisk: All recovery files on disk, whether they stored in the fast recovery area or other locations on disk.
  • cdbRoot: The data files in the whole container root.
  • pluggableDbs: The data files in one or more pluggable databases.
scopeValue

A comma-separated list of values to back up. It is required when the -scope value is tablespace|datafile|pluggableDbs.

backupType

The type of backup. If this argument is not specified, the default value is full. Possible values:

  • full: Back up all data blocks in data files being backed up.
  • incr0: Incremental level 0. Similar to a full backup, but can be used as the base of an incremental backup strategy.
  • incr1: Incremental level 1. Back up only changed blocks.
incrType

The type of incremental backup. Used in combination with -"backupType":"incr". If this argument is not specified, the default value is diff. Possible values:

  • diff: Back up blocks updated since the most recent level 0 or level 1 incremental backup.
  • cumulative: Back up all blocks changed since the most recent level 0 backup.
destinationMedia

The destination media for this backup. If this argument is not specified, the default value is disk. Possible values:

  • disk: Backup to disk (not allowed when - scope="recoveryFilesOnDisk").
  • tape: Backup to a SBT (system backup to tape) device.
  • ra: Backup to a Recovery Appliance.
  • cloud: Backup to Database Backup Cloud Service.
backupEncryptionMode

Specify to encrypt the backup using the Oracle Encryption Wallet, a user-supplied password, or both. Possible values:

  • wallet: Oracle Encryption Wallet
  • password: user-supplied password
  • both: Oracle Encryption Wallet and user-supplied password

This option can be specified when -scope="wholeDB| tablespace|datafile|archivedLog|recoveryFilesOnDisk|cdbRoot| pluggableDbs".
rmanEncryptionCredName

The name of an existing Enterprise Manager generic named credential that contains the encryption password. Required when "backupEncryptionMode":"password" is specified.
encryptionAlogrithm

The name of the encryption algorithm to use when encrypting backups. Used in combination with "backupEncryptionMode". Possible values are AES128, AES192, and AES256. If this argument is not specified, the default value is AES256.
skipBackupArchivedLogs

Do not back up all archived logs on disk that have not been backed up. The default behavior if this argument is not specified is to back up all archived logs that have not been backed up.Possible values are true|false. This option can be specified when -scope="wholeDb|tablespace|datafile| cdbRoot|pluggableDbs".
delete_Archived_Logs_After_Backup

Delete all archived logs from disk after they are successfully backed up. Ignored if "-skip_Backup_Archived_Logs" is specified. Possible values are true|false.

This option can be specified when -scope="wholeDB| tablespace|datafile|cdbRoot|pluggableDbs".

deleteObsolateBackups

Delete backups that are no longer required to satisfy the retention policy. Possible values are true|false.This option can be specified when -scope="wholeDB|tablespace| datafile|cdbRoot|pluggableDbs".
maxFilesPerSet

The maximum number of files to include in each backup set. This option can be specified when -scope="wholeDB| tablespace|datafile|archivedLog|cdbRoot|pluggableDbs".
maxCorruptions

The maximum number of physical corruptions allowed in data files. This option can be specified when -scope="datafile".
sectionSize

The size in MB of each backup section produced during a data file backup, resulting in a multi-section backup where each backup piece contains one file section. This option cannot be used if the Maximum Backup Piece Size is set in the RMAN configuration.This option can be specified when - scope="wholeDB|tablespace|datafile|archivedLog|cdbRoot| pluggableDbs".

cloudAccount

The name of a cloud account configured under the Enterprise Manager Hybrid Cloud Setup console. All information needed to connect to the Backup Service will be obtained from the account and its associated Backup Service settings, including the service name, identity domain, username, password, and container (optional). If this argument is not specified, the global cloud account settings configured in the Database Backup Cloud Service Settings page will be used. (This argument is applicable only if the Hybrid Cloud Setup console has been used to configure accounts and Backup Service settings.).

Example - "cloudAccount":"endpoint:https://storage.example.com/ Storageemdev2;identityDomain:xxx;username:xxxx;password:xxxx;contai ner:xxxx"

Fast-Start Failover REST API

This chapter provides details of the REST APIs for Fast-Start Failover and Observers supported in Enterprise Manager. When Fast-Start Failover is enabled, the Data Guard broker automatically fails over to a synchronized standby site in the event of a disaster at the primary site, requiring no intervention by the DBA. In addition, applications are automatically notified of the role transition.

Fast-Start Failover Management REST API

Fast-Start Failover is a feature that allows the Oracle Data Guard broker to failover a failed primary database automatically to a predetermined standby database. This feature increases the availability of the database by eliminating the need for user involvement as part of the failover process.

Fast-Start Failover Management REST API

Table 12-9 Fast-Start Failover

Feature Description
URL https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/configure/fsfo
Request header

Authorization: Basic

Content-Type: application/json
Body 
{
    "action" : "<edit | enable | disable| change_mode>",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>",
        "dbGIHostCredName" : "<grid infrastructure credential name>"

        "dbObserverConnectIdentifier" : "<ObserverConnectIdentifier value of the primary database>",
        "dbFastRecoveryArea" : "<Fast recovery area location of the database - default V$RECOVERY_FILE_DEST>",
        "dbFastRecoveryAreaSize" : "<Fast recovery area size(MB) of the database - default 2x database size>",
        "dbFlashbackRetentionTime" : "<Flashback retention time hours - default 24h>"
    },
    "candidateFSFOTargets" : 
        {
            "dbTargetName" : "<standby database target name>",
            "dbTargetType" : "<oracle_database | rac_database>",
            "dbCredName" : "<standby database credential name>",
            "dbHostCredName" : "<standby database host credential name>",
            "dbGIHostCredName" : "<grid infrastructure credential name>"

            "dbObserverConnectIdentifier" : "<ObserverConnectIdentifier value of the primary database>",
            "dbFastRecoveryArea" : "<Fast recovery area location of the database - default V$RECOVERY_FILE_DEST>",
            "dbFastRecoveryAreaSize" : "<Fast recovery area size(MB) of the database - default 2x database size>",
            "dbFlashbackRetentionTime" : "<Flashback retention time hours - default 24h>"
        },
    "observer" : {
            "name": "<observer name - default is the hostname>",
            "hostName" : "<observer host name>",
            "oracleHome" : "<observer oracle home>",
            "hostCredName" : "<observer host credential name>"
    },
    "alternateObserver" : {
            "hostName" : "<alternate observer host name>",
            "oracleHome" : "<alternate observer oracle home>",
            "hostCredName" : "<alternate observer host credential name>"
    },
    "failoverThreshold" : "<failover threshold>",
    "lagLimit" : "<lag limit>",
    "failoverConditions" : "<failover conditions>",

    "calloutScripts" : {
            "hostName" : "<host name>", 
            "hostCredentials" : "<host credential>"
            "preCallout" : "<path of pre role change callout script>",
            "postCallout" : "<path of post role change callout script>",
            "sucFileName" : "<Name of the suc file that>",
            "errorFileName" : "<Name of the .err file>",
            "fsfoPreCalloutTimeout" : "<Value in seconds>",
            "fsfoActionOnPreCalloutFailure" : "<STOP | CONTINUE>"

        },
    "enableFlashBackDatabase" : "<Yes | No>",
    "autoReinstatePrimary" : "<Yes | No>",
    "autoShutdownPrimary" : "<Yes | No>"
    "observeOnly" : "<Yes | No  - Default Value: No>"
    "includeOraError240" : "<Yes | No  -Default Value: Yes>",
}
Body for Disable 
{
        "action" : "disable",
        ["stopAllObservers" : "<Yes | No - Default value: Yes, applicable only for 'disable' action>"]
        "primary" :  { 
                "dbTargetName" : "<Primary database Enterprise Manager target name>", 
                "dbTargetType" : "oracle_database | rac_database", 
                ["dbCredName" : "<Primary database named credential for a user with SYSDBA or SYSDG role. Default Value: Preferred credential will be used>",] 
                ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credential will be used>",] 
                ["dbGIHostCredName" : "<Grid Infrastructure named credentials for an operating system user who can access the grid infrastructure Oracle home of the Primary Database. Default Value: Preferred credential will be used>"] 
         } 
}
Body for Change Mode 
{
        "action" : "change_mode",
        "primary" :  { 
                "dbTargetName" : "<Primary database Enterprise Manager target name>", 
                "dbTargetType" : "oracle_database | rac_database", 
                ["dbCredName" : "<Primary database named credential for a user with SYSDBA or SYSDG role. Default Value: Preferred credential will be used>",] 
                ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credential will be used>",] 
                ["dbGIHostCredName" : "<Grid Infrastructure named credentials for an operating system user who can access the grid infrastructure Oracle home of the Primary Database. Default Value: Preferred credential will be used>"] 
         } 
}
Notes Observers and alternate observers are optional.
Request method POST
Sample Response 
{
    "status" : "Succeeded",
    "submissionName" : "DG_FAST_START_FAIL_OVER_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment Procedure for configuring fast-start failover of the Data Guard configuration determined from the primary database <primary database name> is successfully submitted."
}
Supported Since Release EM DB 13.4

Table 12-10 Fast-Start Failover

Feature Description
URL https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/configure/fsfo
Request header

Authorization: Basic

Content-Type: application/json
Body 
{
    "action" : "<edit | enable | disable| change_mode>",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>",
        "dbGIHostCredName" : "<grid infrastructure credential name>"

        "dbObserverConnectIdentifier" : "<ObserverConnectIdentifier value of the primary database>",
        "dbFastRecoveryArea" : "<Fast recovery area location of the database - default V$RECOVERY_FILE_DEST>",
        "dbFastRecoveryAreaSize" : "<Fast recovery area size(MB) of the database - default 2x database size>",
        "dbFlashbackRetentionTime" : "<Flashback retention time hours - default 24h>"
    },
    "candidateFSFOTargets" : 
        {
            "dbTargetName" : "<standby database target name>",
            "dbTargetType" : "<oracle_database | rac_database>",
            "dbCredName" : "<standby database credential name>",
            "dbHostCredName" : "<standby database host credential name>",
            "dbGIHostCredName" : "<grid infrastructure credential name>"

            "dbObserverConnectIdentifier" : "<ObserverConnectIdentifier value of the primary database>",
            "dbFastRecoveryArea" : "<Fast recovery area location of the database - default V$RECOVERY_FILE_DEST>",
            "dbFastRecoveryAreaSize" : "<Fast recovery area size(MB) of the database - default 2x database size>",
            "dbFlashbackRetentionTime" : "<Flashback retention time hours - default 24h>"
        },
    "observer" : {
            "name": "<observer name - default is the hostname>",
            "hostName" : "<observer host name>",
            "oracleHome" : "<observer oracle home>",
            "hostCredName" : "<observer host credential name>"
    },
    "alternateObserver" : {
            "hostName" : "<alternate observer host name>",
            "oracleHome" : "<alternate observer oracle home>",
            "hostCredName" : "<alternate observer host credential name>"
    },
    "failoverThreshold" : "<failover threshold>",
    "lagLimit" : "<lag limit>",
    "failoverConditions" : "<failover conditions>",

    "calloutScripts" : {
            "hostName" : "<host name>", 
            "hostCredentials" : "<host credential>"
            "preCallout" : "<path of pre role change callout script>",
            "postCallout" : "<path of post role change callout script>",
            "sucFileName" : "<Name of the suc file that>",
            "errorFileName" : "<Name of the .err file>",
            "fsfoPreCalloutTimeout" : "<Value in seconds>",
            "fsfoActionOnPreCalloutFailure" : "<STOP | CONTINUE>"

        },
    "enableFlashBackDatabase" : "<Yes | No>",
    "autoReinstatePrimary" : "<Yes | No>",
    "autoShutdownPrimary" : "<Yes | No>"
    "observeOnly" : "<Yes | No  - Default Value: No>"
    "includeOraError240" : "<Yes | No  -Default Value: Yes>",
}
Notes Observers and alternate observers are optional.
Request method POST
Sample Response 
{
    "status" : "Succeeded",
    "submissionName" : "DG_FAST_START_FAIL_OVER_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment Procedure for configuring fast-start failover of the Data Guard configuration determined from the primary database <primary database name> is successfully submitted."
}
Supported Since Release EM DB 13.4

Fast-Start Failover Parameters

Parameter Description Required Value | Default Value
action Operation to be performed on the fast-start failover configuration.
  • enable : Enable fast-start failover.
  • disable : Disable fast-start failover and stop the observer.
  • edit : Change the fast-start failover target database and thresholds, and start or restart the observer process.
Required edit | enable | disable
dbTargetName Primary or standby database Enterprise Manager target names. Required N/A
dbTargetType Primary or standby database target types. Required oracle_database | rac_database
dbCredName Primary or standby database named credential for a user with SYSDBA or SYSDG role. Optional Preferred credential will be used.
dbHostCredName Primary or standby database host named credential for an operating system user who can access the database Oracle home. Optional Preferred credential will be used.
dbGIHostCredName Grid Infrastructure named credential for an operating system user who can access the grid infrastructure Oracle home of the database. Optional N/A
hostName Discovered host where Enterprise Manager will start the observer or alternate observer. Required N/A
oracleHome Oracle home on the observer or alternate host (as specified by "hostName") from which Enterprise Manager will start the observer or alternate observer.. Required N/A
observer A DGMGRL (Data Guard command line interface) client that continuously monitors the primary and target standby databases, evaluates whether failover is necessary, and initiates a fast-start failover when selected conditions occur. Required N/A
alternateObserver Enterprise Manager supports the automatic restart of an alternate observer on a different host if it detects that the observer process had failed in the earlier host. Required N/A
hostCredName Observer or alternate observer host named credential for an operating system user who can access the observer Oracle home. Required N/A
failoverThreshold Amount of time in seconds the primary database must be out of contact with the observer and the standby database before a fast-start failover is initiated. Optional 30 Seconds.
lagLimit Amount of time in seconds the standby database is allowed to fall behind the primary database, beyond which a fast-start failover will not be allowed. Optional 30 Seconds.
failoverConditions A comma separated list of failover conditions which should cause a fast-start failover if detected on the primary database.
  • 1 - Corrupted Controlfile
  • 2 - Corrupted Dictionary
  • 3 - Inaccessible Logfile
  • 4 - Stuck Archiver
  • 5 - Datafile Offline
 Optional 1, 2, 5
autoReinstatePrimary Causes the former primary database to be automatically reinstated if a fast-start failover was initiated because the primary database was either isolated or had crashed. Optional Yes | No Default: Yes
autoShutdownPrimary Causes the primary database to automatically shut down if fast-start failover is enabled. Optional Yes | No
dbObserverConnectIdentifier Primary database ObserverConnectIdentifier configurable property value Optional N/A
dbFastRecoveryArea Fast recovery area location of the database Optional V$RECOVERY_FILE_DEST
dbFastRecoveryAreaSize Fast recovery area size of the database in MB Optional Twice the database size
dbFlashbackRetentionTime Flashback retention time in hours Optional 24 hours
name Name of the observer Optional hostname
hostName host name of host containing the pre and post role change callout scripts Optional N/A
hostCredentials host credential name of host containing pre and post role change callout scripts Optional N/A
preCallout Full path of pre role change callout script Optional N/A
postCallout Full path of post role change callout script Optional N/A
sucFileName Name of the success (.suc) file that the precallout script creates Optional precallout.suc
errorFileName Name of the error (.err) file that the precallout script creates Optional precallout.err
fsfoPreCalloutTimeout Callout timeout, numeric value expressed in seconds Optional 600 seconds
fsfoActionOnPreCalloutFailure Precallout action in case of failure. STOP or CONTINUE Optional STOP | CONTINUE

Default: Top
enableFlashBackDatabase Enables flash back of database. Optional YES|NODefault: NO
observeOnly Observe only failover Optional YES|NODefault: NO

Observer Management REST API

Note:

This REST API is applicable to Oracle Database version 12.2 and higher.

Configure Multiple Observers for a Data Guard Configuration

Table 12-11 Start Observers

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/configure/observers

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "action" : "<start | stop | setMaster | show | delete_alternate_observer | stopall | editCallout | removeCallout>",
    "primary" : {
        "dbTargetName" : "<Primary database Enterprise Manager target name>",
        "dbTargetType" : "oracle_database | rac_database",
        ["dbCredName" : "<Primary database named credential for a user with SYSDBA role. Default Value: Preferred credentials will be used>",]
        ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credentials will be used.>"]
    },
    "observers" : [
        {
            "name" : "<Observer name>",
            "hostName" : "<Host name where observer will be started>",
            "oracleHome" : "<Oracle home location on the host where observer will be started>",
            "hostCredName" : "<Host named credential for user who can access the observer Oracle home>",
            "hostWalletCredName" : "<Named credential of the Oracle wallet configured in the observer Oracle home>",
            ["isMaster" : "<Y|N>",]
            ["runTimeDataFile" : "<Runtime data file path and name for the observer. If not specified, the file fsfo.dat will be created under the oracle base>",]
            ["logFile" : "<The full path of the observer log file>"]
        },
        {
            ...
        },
        {
            ...
        }
    ]

    ["calloutScripts" : {
            "hostName" : "<Name of the host containing the pre and post role change callout scripts>", 
            "hostCredentials" : "<Credential name of the host containing pre and post role change callout scripts>"
            "preCallout" : "<Absolute path of pre role change callout script on the hostName>",
            "postCallout" : "<Absolute path of post role change callout script on the hostName>",
            "sucFileName" : "<Name of the suc file that the precallout script would create on the observer host | Default - precallout.suc>",
            "errorFileName" : "<Name of the err file that the precallout script would create on the observer host | Default - precallout.err>",
            "fsfoPreCalloutTimeout" : "<Numeric value in seconds of the time for whic the observer will wait for the suc/err file to be generated, default value - 600>",
            "fsfoActionOnPreCalloutFailure" : "<Action that indicates what the observer will do if the suc file does not exist even if after FastStartFailoverPreCalloutTimeout seconds, or the error file is detected before FastStartFailoverPreCalloutTimeout seconds passed. Initiate the failover - CONTINUE, or not do failover - STOP. Values - STOP | CONTINUE, default value - STOP>"

        },
    ]

}
Body for Start 
{
    "action" : "start",
    "primary" : {
        "dbTargetName" : "<Primary database Enterprise Manager target name>",
        "dbTargetType" : "oracle_database | rac_database",
        ["dbCredName" : "<Primary database named credential for a user with SYSDBA or SYSDG role. Default Value: Preferred credentials will be used>",]
        ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credentials will be used.>"]
    },
    "observers" : [
        {
            "name" : "<Observer name>",
            "hostName" : "<Host name where observer will be started>",
            "oracleHome" : "<Oracle home location on the host where observer will be started>",
            "hostCredName" : "<Host named credential for user who can access the observer Oracle home>",
            "hostWalletCredName" : "<Named credential of the Oracle wallet configured in the observer Oracle home>",
            ["isMaster" : "<Y|N>",]
            ["runTimeDataFile" : "<Runtime data file path and name for the observer. If not specified, the file fsfo.dat will be created under the oracle base>",]
            ["logFile" : "<The full path of the observer log file>"]
        },
        {
            ...
        },
        {
            ...
        }
    ]
    ["calloutScripts" : {
            "hostName" : "<Name of the host containing the pre and post role change callout scripts>", 
            "hostCredentials" : "<Credential name of the host containing pre and post role change callout scripts>"
            "preCallout" : "<Absolute path of pre role change callout script on the hostName>",
            "postCallout" : "<Absolute path of post role change callout script on the hostName>",
            "sucFileName" : "<Name of the suc file that the precallout script would create on the observer host | Default - precallout.suc>",
            "errorFileName" : "<Name of the err file that the precallout script would create on the observer host | Default - precallout.err>",
            "fsfoPreCalloutTimeout" : "<Numeric value in seconds of the time for whic the observer will wait for the suc/err file to be generated, default value - 600>",
            "fsfoActionOnPreCalloutFailure" : "<Action that indicates what the observer will do if the suc file does not exist even if after FastStartFailoverPreCalloutTimeout seconds, or the error file is detected before FastStartFailoverPreCalloutTimeout seconds passed. Initiate the failover - CONTINUE, or not do failover - STOP. Values - STOP | CONTINUE, default value - STOP>"
 
        },
    ]
}
Body for Stop 
{
    "action" : "stop",
    "primary" : {
        "dbTargetName" : "<Primary database Enterprise Manager target name>",
        "dbTargetType" : "oracle_database | rac_database",
        ["dbCredName" : "<Primary database named credential for a user with SYSDBA or SYSDG role. Default Value: Preferred credentials will be used>",]
        ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credentials will be used.>"]
    }
    "observers" : [
        {"name" : "<observer 1 name>"},
        {"name" : "<observer 2 name>"},
        {"name" : "<observer 3 name>"}
    ]
}
Body for Set Master 
{
    "action" : "setMaster",
    "primary" : {
        "dbTargetName" : "<Primary database Enterprise Manager target name>",
        "dbTargetType" : "oracle_database | rac_database",
        ["dbCredName" : "<Primary database named credential for a user with SYSDBA or SYSDG role. Default Value: Preferred credentials will be used>",]
        ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credentials will be used.>"]
    }
    "masterObserver" : "<master observer name>"
}
Body for Show and Stop All 
{
    "action" : "show | stopall",
    "primary" : {
        "dbTargetName" : "<Primary database Enterprise Manager target name>",
        "dbTargetType" : "oracle_database | rac_database",
        ["dbCredName" : "<Primary database named credential for a user with SYSDBA or SYSDG role. Default Value: Preferred credentials will be used>",]
        ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credentials will be used.>"]
    }
}
Body for Edit Callout 
{
    "action" : "editCallout",
    "primary" : {
        "dbTargetName" : "<Primary database Enterprise Manager target name>",
        "dbTargetType" : "oracle_database | rac_database",
        ["dbCredName" : "<Primary database named credential for a user with SYSDBA or SYSDG role. Default Value: Preferred credentials will be used>",]
        ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credentials will be used.>"]
    }    
    ["calloutScripts" : {
            "hostName" : "<Name of the host containing the pre and post role change callout scripts>", 
            "hostCredentials" : "<Credential name of the host containing pre and post role change callout scripts>"
            "preCallout" : "<Absolute path of pre role change callout script on the hostName>",
            "postCallout" : "<Absolute path of post role change callout script on the hostName>",
            "sucFileName" : "<Name of the suc file that the precallout script would create on the observer host | Default - precallout.suc>",
            "errorFileName" : "<Name of the err file that the precallout script would create on the observer host | Default - precallout.err>",
            "fsfoPreCalloutTimeout" : "<Numeric value in seconds of the time for whic the observer will wait for the suc/err file to be generated, default value - 600>",
            "fsfoActionOnPreCalloutFailure" : "<Action that indicates what the observer will do if the suc file does not exist even if after FastStartFailoverPreCalloutTimeout seconds, or the error file is detected before FastStartFailoverPreCalloutTimeout seconds passed. Initiate the failover - CONTINUE, or not do failover - STOP. Values - STOP | CONTINUE, default value - STOP>"
 
        },
    ]
}
Body for Remove Callout 
{
    "action" : "removeCallout",
    "primary" : {
        "dbTargetName" : "<Primary database Enterprise Manager target name>",
        "dbTargetType" : "oracle_database | rac_database",
        ["dbCredName" : "<Primary database named credential for a user with SYSDBA or SYSDG role. Default Value: Preferred credentials will be used>",]
        ["dbHostCredName" : "<Primary database host named credential for an operating system user who can access the primary database Oracle home. Default Value: Preferred credentials will be used.>"]
    },
     "observers" : [
        {
            "name" : "<Observer name>",
            "hostName" : "<Host name where observer will be started>",
            "oracleHome" : "<Oracle home location on the host where observer will be started>",
            "hostCredName" : "<Host named credential for user who can access the observer Oracle home>"
        },
        {
            ...
        },
        {
            ...
        }
    ] 
}
Notes A maximum of 3 observers can be assigned.

Sample Response

 
{
    "status" : "Succeeded",
    "submissionName": "ConfigureObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to start the observer(s) for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
                 
}

Request method

POST

Supported Since Release

EM DB 13.4

Table 12-12 Delete, Show, or Stop All Observers

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/configure/observers

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "action" : "<delete_alternate_observer | show | stopall>",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>"
    }
}

Sample Response

Show

{
    "status": "Succeeded",
    "submissionName" : "ShowObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to list the observer(s) for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Delete Alternate Observer

{
    "status" : "Succeeded",
    "submissionName" : "DeleteAlternateObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to delete the alternate observer for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Stop All

{
    "status" : "Succeeded",
    "submissionName" : "StopObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to stop the observer(s) for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.4

Table 12-13 Stop Observers

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/configure/observers

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "action" : "stop",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>"
    }
    "observers" : [
        {"name" : "<observer 1 name>"},
        {"name" : "<observer 2 name>"},
        {"name" : "<observer 3 name>"}
    ]
}

Sample Response

 
{
    "status" : "Succeeded",
    "submissionName": "StopObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to stop the observer(s) for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.4

Table 12-14 Set Master Observer

Feature Description

URL

https://<OMS_HOST>:<OMS_CONSOLE_PORT>/em/websvcs/restful/db/dataguard/configure/observers

Request header

Authorization: basic

Content-Type: application/json

Body

 
{
    "action" : "setMaster",
    "primary" : {
        "dbTargetName" : "<primary database target name>",
        "dbTargetType" : "oracle_database | rac_database",
        "dbCredName" : "<primary database credential name>",
        "dbHostCredName" : "<primary database host credential name>"
    }
    "masterObserver" : "<master observer name>"
}

Sample Response

 
{
    "status" : "Succeeded",
    "submissionName": "SetMasterObserver_*",
    "executionGUID" : "<execution guid>",
    "databaseName" : "<primary database name>",
    "message" : "Deployment procedure to set the master observer for the Data Guard Configuration associated with the primary database <primary database name> is successfully submitted."
}

Request method

POST

Supported Since Release

EM DB 13.4

Table 12-15 Observer Parameters

Parameter Description Required Value | Default Value
action
The action the API will execute. All the operations are mutually exclusive. They can't be combined and must be executed separately.
  • start : Starts one or more fast-start failover observers on the specified hosts and Oracle homes for the Data Guard configuration associated with the specified primary database.
  • delete_alternate_observer : Deletes the Enterprise Manager alternate observer and its associated corrective action job. The Enterprise Manager alternate observer feature is not supported for Oracle Database version 12.2 and higher.
  • show : Displays the list of observers configured for a Data Guard configuration associated with the specified primary database.
  • stop : Stops the respective observer(s) for a Data Guard configuration associated with the specified primary database.
  • stopall : Stops all the observers.
  • setMaster : Configures the master observer for a Data Guard configuration associated with the specified primary database.
Required start | delete_alternate_observer | show | stop | stopall | setMaster
dbTargetName Primary database Enterprise Manager target name. Required N/A
dbTargetType

Primary database target type.

 Required oracle_database | rac_database
dbCredName

Primary database named credential for a user with SYSDBA or SYSDG role.

 [OPTIONAL] Preferred credentials will be used.
dbHostCredName

Primary database host named credential for an operating system user who can access the primary database Oracle home.

[OPTIONAL] Preferred credentials will be used.
name Observer name. Required N/A
hostName Host name where observer will be started. Required N/A
oracleHome Oracle home location on the host where the observer will be started. Required N/A
hostCredName Host named credential for user who can access the observer Oracle home. Required N/A
hostWalletCredName Named credential of the Oracle wallet configured in the observer Oracle home. Required N/A
isMaster

Defines if the observer is master.

 [OPTIONAL] Y | N
masterObserver

Required for Set Master Observer

Defines the master observer.

 [OPTIONAL] N/A
runTimeDataFile

Runtime data file path and name for the observer. If not specified, the file fsfo.dat will be created under the Oracle base.

 [OPTIONAL] N/A
logFile

The full path of the observer log file.

 [OPTIONAL] N/A
hostName host name of host containing the pre and post role change callout scripts Optional N/A
hostCredentials host credential name of host containing pre and post role change callout scripts Optional N/A
preCallout Full path of pre role change callout script Optional N/A
postCallout Full path of post role change callout script Optional N/A
sucFileName Name of the success (.suc) file that the precallout script creates Optional precallout.suc
errorFileName Name of the error (.err) file that the precallout script creates Optional precallout.err
fsfoPreCalloutTimeout Callout timeout, numeric value expressed in seconds Optional 600 seconds
fsfoActionOnPreCalloutFailure Precallout action in case of failure. STOP or CONTINUE Optional STOP | CONTINUE

Default: Top