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
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.
Request
Supported Media Types: application/json
The following table summarizes the POST request parameters.
Table 9-102 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
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
|
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://<BASE URL>,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-103 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://<<BASE URL>/interop/rest/v1/services/status","data":null,"action":"GET"}],"details":null,"status":-1"items":null)
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://<BASE URL>";
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
//
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
}
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;
}
Sample cURL Command Basic Auth
curl -X POST -s -u '<USERNAME>:<PASSWORD>' -H 'Content-Type: application/json' -d '{"targetURL":
" https://<BASE URL>","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://<BASE URL>","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'