1. REST API for Oracle Enterprise Performance Management Cloud
  2. Migration REST APIs
  3. Clone an Environment

Clone an Environment

Use this REST API to clone the current environment and, optionally, identify domain artifacts (users and predefined roles), Data Management records, audit records, Job Console records, contents of the inbox and outbox, and stored snapshots.

This API is executed on the source environment after details are provided for the target environment to be cloned. It is an alternative to using the Clone Environment feature in a browser or the EPM Automate cloneEnvironment command.

Prerequisites: The password of the target EPM Cloud environment must have already been encrypted using EPM Automate. The encrypted password string must then be passed as one of the parameters for the Clone Environment REST API. See the encrypt command in Working with EPM Automate for Oracle Enterprise Performance Management Cloud.

For considerations with cloning an environment, see Cloning EPM Cloud Environments in Administering Migration for Oracle Enterprise Performance Management Cloud.

This REST API is version v1.

Required Roles

Service Administrator

Identity Domain Administrator role is required to clone users and predefined roles.

REST Resource

POST /interop/rest/v1/services/clone

Supported Media Types: application/json

Note:

Before using the REST resources, you must understand how to access the REST resources and other important concepts. See Implementation Best Practices for EPM Cloud REST APIs. Using this REST API requires prerequisites. See Prerequisites.

The following table summarizes the POST request parameters.

Table 9-97 Parameters

Name Description Type Required Default
api_version Specific API version, such as v1 Path Yes None
targetUsername The ID of a Service Administrator in the target environment. If you plan to clone user and role assignments in the target environment, this user must also have the Identity Domain Administrator role. Payload Yes None
targetEncryptPassword

The encrypted password of the user identified by targetUsername to be passed as a string.

For information on encrypting and generating the password.epw file with EPM Automate, see encrypt in Working with EPM Automate for Oracle Enterprise Performance Management Cloud.

Payload Yes None
targetURL The URL of the environment that will become the cloned environment Payload Yes None
snapshotName Optionally, the name of a snapshot that should be used for cloning. This snapshot must be present in the source environment. Payload No Last maintenance snapshot
migrateUsers Whether to clone users and their predefined and application role assignments, True or False.

For this option to work, the user identified by targetUsername must have the Identity Domain Administrator role in the target environment.

Payload No False
maintenanceStartTime Whether to reset the maintenance start time of the cloned environment to that of the source environment. To keep the current maintenance start time of the target environment, set this value to False. Payload No True
dataManagement Whether to clone the Data Management records of the source to the target environment for all environments other than Oracle Enterprise Data Management Cloud and Narrative Reporting, True or False. Payload No True
applicationAudit Whether to clone the application audit data in the source to the target environment for FreeForm, Planning, Planning Modules, Financial Consolidation and Close, and Tax Reporting environments, True or False. Including application audit data while cloning an environment makes the target environment keep the application audit history. Payload No True
jobConsole Whether to clone the job console data in the source to the target environment for FreeForm, Planning, Planning Modules, Financial Consolidation and Close, and Tax Reporting environments, True or False. Including job console data while cloning an environment makes the target environment keep the job console history. Payload No True
storedSnapshotsAndFiles Whether to clone the contents of the inbox, outbox, and stored snapshots in the source to the target environment for all environments, True or False. Including stored snapshots and files while cloning an environment makes sure that the stored snapshots and files are not lost. This is useful especially while cloning a Classic environment to an OCI (Gen 2) environment. Payload No False

Example URL and Payload

{
   "targetURL":" https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com ",   "targetUserName":"cloneUser@oracle.com", "targetEncryptPassword":"<targetUserEncryptedPasswordString>",
   "parameters":{"snapshotName":"Artifact Snapshot" "migrateUsers":"true","maintenanceStartTime":"true", "dataManagement":"true", "jobConsole":"true", "applicationAudit":"true", "storedSnapshotsAndFiles":"false"}
}

Response

Supported Media Types: application/json

Table 9-98 Parameters

Name Description
details In the case of errors, details are published with the error string
status See Migration Status Codes
links Detailed information about the link
href Links to API call or status API
action The HTTP call type
rel Possible values: self or Job Status. If the value is set to Job Status, you can use the href to get the status
intermittentStatus Status of each step performed; can be polled regularly from the job status URL

Example of Response Body

The following shows an example of the response body in JSON format.

{"intermittentStatus":null, "links":[{"rel":"Job Status","href":"https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com/interop/rest/v1/services/status","data":null,"action":"GET"}],"details":null,"status":-1"items":null)

Example 9-30 Java Sample – CloneEnvironment.java

Prerequisites: json.jar

Common functions: See Appendix A, Common Helper Functions for Java. 

//
	// BEGIN – Clone Environment 
	//
	public void cloneEnvironment() throws Exception {
		String targetUrl = "https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com" ;
		String targetUsername = "<Target User name>";
		String encryptedPwdString = fetchPwdFromFile("epw_file_Path") ; //"<Target system encrypted password>"; 
		String snapshotToClone = "Artifact Snapshot";
		JSONObject params = new JSONObject();
		JSONObject payload = new JSONObject();
		 //Optional parameters if not passed default values will be picked
         /*
         params.put("snapshotName", snapshotToClone);
         params.put("migrateUsers", Boolean.TRUE.toString());
         params.put("maintenanceStartTime", Boolean.TRUE.toString());
         params.put("dataManagement", Boolean.TRUE.toString());
         */
         //Mandatory parameters
         payload.put("targetURL", targetUrl);
         payload.put("targetUserName", targetUsername);
         payload.put("targetEncryptPassword", encryptedPwdString);
         payload.put("parameters", params);

	  String urlString = String.format("%s/interop/rest/v1/services/clone", serverUrl);
	  String response = executeRequest(urlString, "POST", payload.toString(), "application/json");

	  getMigrationJobStatus(fetchPingUrlFromResponse(response, "Job Status"),"GET");
	}
	
 private String fetchPwdFromFile(String filePath) {
		BufferedReader br = null;

		try {
			br = new BufferedReader(new FileReader(filePath));
			String line = null;
			String pwdString = null;
			while ((line = br.readLine()) != null) {
				pwdString = line;
			}
			return pwdString;
		} catch (Exception e) {
		} finally {
			if (null != br)
				try {
					br.close();
				} catch (IOException e) {
					// TODO Auto-generated catch block
					e.printStackTrace();
				}

		}

		return null;
}
//
// END – Clone Environment
//

Example 9-31 cURL Sample – cloneEnvironment.sh

Prerequisites: jq (http://stedolan.github.io/jq/download/linux64/jq)

Common Functions: See Common Helper Functions for cURL

funcCloneEnvironment() {
    url="$SERVER_URL/interop/rest/v1/services/clone"
    local targetUrl="<TargetSystemURL>"
    local targetUserName="<TargetSystemUsername>"
    local targetEncryptedPassword= $(cat $EPWfilePath) #"<TargetSystemEncryptedPasswordString>"  

    #optionalParams="{\"snapshotName\":\"Artifact Snapshot\",\"migrateUsers\":\"true\",\"maintenanceStartTime\":\"true\",\"dataManagement\":\"true\"}"

    param="{\"targetURL\":\"$targetUrl\",\"targetUserName\":\"$targetUserName\",\"targetEncryptPassword\":\"$targetEncryptedPassword\"}" #,\"parameters\":\"$optionalParams\"}"
    funcExecuteRequest "POST" $url "$param" "application/json"

    output=$(cat response.txt)
    status=$(echo $output | jq '.status')
    if [ $status == -1 ]; then
        echo "CloneEnvironment is in progress.."
        funcGetStatus "GET"
    else
        error=$(echo $output | jq '.details')
        echo "Error occurred. " $error
    fi
}

Example 9-32 Groovy Sample – cloneEnvironment.groovy

Prerequisites: json.jar

Common Functions: See CSS Common Helper Functions for Groovy

def cloneEnvironment(targetURL,targetUsername,targetEncyptedPasswordFile){
    String scenario = "Clone Environment";
    def targetEncyptedPassword = fetchPwdFromFile(targetEncyptedPasswordFile);
    def json = new JsonBuilder()
    //Optional parameter to be set if needed
   //def optionalParams = [snapshotName: "Artifact Snapshot", migrateUsers: "true", maintenanceStartTime: "true" ,dataManagement:"true"]

    def payload = new JsonBuilder()
        payload targetURL: targetURL,
                targetUserName: targetUsername,
                targetEncryptPassword: targetEncyptedPassword //,
                //parameters: optionalParams

    params=payload.toString();
    def url = null;
	def response = null;
	try {
		url = new URL(serverUrl + "/interop/rest/v1/services/clone");
	} catch (MalformedURLException e) {
		println "Please enter a valid URL"
		System.exit(0);
	}
	response = executeRequest(url, "POST", params, "application/json");
	if (response != null) {
		getJobStatus(getUrlFromResponse(scenario, response, "Job Status"), "GET");
	}
}
def fetchPwdFromFile(filePath) {
		BufferedReader br = null;

		try {
			br = new BufferedReader(new FileReader(filePath));
			String line = null;
			String pwdString = null;
			while ((line = br.readLine()) != null) {
				pwdString = line;
			}
			return pwdString;
		} catch (Exception e) {
		} finally {
			if (null != br)
				try {
					br.close();
				} catch (IOException e) {
					// TODO Auto-generated catch block
					e.printStackTrace();
				}

		}

		return null;
}
Common Functions

Sample cURL Command Basic Auth

curl -X POST -s -u '<USERNAME>:<PASSWORD>' -H 
'Content-Type: application/json' -d '{"targetURL":
" https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com ","targetUserName":
"<TARGET-USERNAME>","targetEncryptPassword":"<TARGET-ENCRYPTED-PASSWORD>","parameters":
{"snapshotName":"<SNAPSHOT-NAME>","migrateUsers":"true","maintenanceStartTime":"<TRUE/FALSE>","dataManagement":
"<TRUE/FALSE>","jobConsole":"<TRUE/FALSE>","applicationAudit":"<TRUE/FALSE>","storedSnapshotsAndFiles":
"<TRUE/FALSE>"}}' 'https://<EPM-CLOUD-BASE-URL>/interop/rest/v1/services/clone'

Sample cURL Command OAuth 2.0

curl -X POST --header "Authorization: Bearer <OAUTH_ACCESS_TOKEN>" -H 
'Content-Type: application/json' -d '{"targetURL":
" https://<SERVICE_NAME>-<TENANT_NAME>.<SERVICE_TYPE>.<dcX>.oraclecloud.com ","targetUserName":
"<TARGET-USERNAME>","targetEncryptPassword":"<TARGET-ENCRYPTED-PASSWORD>","parameters":
{"snapshotName":"<SNAPSHOT-NAME>","migrateUsers":"true","maintenanceStartTime":
"<TRUE/FALSE>","dataManagement":"<TRUE/FALSE>","jobConsole":"<TRUE/FALSE>","applicationAudit":
"<TRUE/FALSE>","storedSnapshotsAndFiles":"<TRUE/FALSE>"}}' 
'https://<EPM-CLOUD-BASE-URL>/interop/rest/v1/services/clone'