Getting Groovy with the EPM Cloud Migration REST API – Part 2
This post is late. It’s embarrassingly late. But it’s finally finished, and I hope you find it useful.
In the previous post, we discussed Oracle’s Migration API for EPM Cloud, and walked through some basic Groovy examples on:
- Retrieving the API Version
- Listing Files in the Inbox/Outbox
- Uploading Files to the Inbox/Outbox
- Downloading Files from the Inbox/Outbox
The features above are useful for tasks like loading data and metadata into an application because we often have to place files into the Inbox/Outbox before we can reference them with Data Management or as part of a job.
In Part 2 of this post, we will focus on the migration capabilities of the API. I generally don’t automate full migrations, as they often involve a lot of communication with developers and coordination regarding the specific artifacts being moved. However I almost always automate application backups. Your needs may be different, so we’ll cover it all, including:
- Listing Application Snapshots
- Downloading Application Snapshots
- Uploading Application Snapshots
- Initiating an LCM Export
- Initiating an LCM Import
- Running the User Provisioning Report
- Running the User Audit Report
Snapshots vs LCM Exports
Part of setting up PBCS involves defining a Maintenance Time. During this one-hour window, the application is backed up (nightly) and an Application Snapshot is created. The application snapshot contains everything necessary to restore the application, including data, metadata, forms, security, reports, business rules, mappings . . . you name it. Only one Application Snapshot is maintained in the Inbox/Outbox. It gets overwritten every night, so if you want to keep a rolling set of backups, you will likely want to automate and schedule the export of these files.
When we talk about an LCM Export, we are generally talking about a more focused artifact export, initiated by an admin. For example, when a developer wants to migrate a specific set of artifacts from the TEST instance to PROD. But technically speaking, an Application Snapshot is an LCM export . . . it’s just the automated nightly export that includes all artifacts and data.
Listing the Application Snapshots
We previously stated that the Inbox/Outbox only maintains the most recent Application Snapshot, so why would we bother listing these files? There’s only one of them at any given point in time, right? Well it turns out that when you use the Migration API to list Application Snapshots, you’re really just listing all files in the Inbox/Outbox. In fact, you may have noticed that the listFiles() function in the Groovy Common Helper Functions uses the URL for “/application snapshots”.
It’s interesting to note that the files in the Inbox/Outbox are classified as either “LCM” or “External”. LCM files include Application Snapshots and anything exported using LCM. But curiously, this property also applies to internal Inbox/Outbox directories. “External” files make up the remaining contents of the Inbox/Outbox. These are usually files uploaded for data and metadata.
We can see this LCM vs External designation by adding the code circled in red below to the listFiles() function.
If we then run the listFiles() function, we should see the current Artifact Snapshot (among any other files in the Inbox/Outbox:
Downloading Application Snapshots
Downloading Application Snapshots is one of the more useful aspects of the Migration API, as most clients want to keep a rolling set of files over a given time period. Because the Application Snapshot in the Inbox/Outbox gets overwritten every night, it’s important to download this file in an automated and scheduled manner.
Downloading an application snapshot is just like downloading any other file, however there are a couple of “gotchas”. While all of the Migration API documentation refers to the “Application Snapshot”, the actual file that gets produced nightly in the Inbox/Outbox is called the “Artifact Snapshot”.
Another unusual fact about this file is that it has no file extension, even though it is a .zip file. If you want to easily browse the contents of this file, you’ll need to add the .zip file extension once downloaded.
Other than those two items, the Application/Artifact Snapshot can be downloaded using the downloadFile() function in the Groovy Common Helper Functions. Please see the previous post here with some useful updates to this function.
Uploading Application Snapshots
Uploading an application snapshot is similar to uploading any other file to the Inbox/Outbox. With that said, I have not been successful in uploading a previously downloaded Artifact Snapshot without first updating the file name. This is because the nightly “Artifact Snapshot” file has a space in the file name, and has no file extension. Remove the space and add a “.zip” file extension and everything works as expected. But I have to ask, why would Oracle produce a download file that cannot be uploaded in its original state? It may have something to do with the fact that Oracle can’t be sure which operating system exists on the target file system, and different operating systems use different file compression programs.
Note the different file name below:
Regardless of the filename, the Migration API will recognize that the file being uploaded is an Artifact Snapshot (as opposed to any other file being uploaded to the Inbox/Outbox), however the file must have a “.zip” file extension.
Initiating an LCM Export
LCM Exports initiated via the Migration API aren’t especially intuitive, however once you know how they work, they’re pretty flexible. I’ll explain . . . in order to execute an LCM export using the Migration REST API, users must first execute a successful export via the PBCS interface. Once that has been done, developers can re-execute that same export using the API.
My initial reaction to this approach was concern. What if I setup a process in the PBCS user interface that archives all of my forms? Will that export contain a hard-coded list of forms, missing any future artifacts I might add to the application? The answer is no (and yes, depending on how you specify your artifacts). If I tell LCM to export all of my forms (without selecting any individual forms), then any new forms added at a later date will get picked up in future exports initiated using the API. If I specify specific forms in the initial selection using the PBCS user interface, then only those specific forms will get exported in the future when using the API.
Let’s look at an example, but before we get started, you will need to add the function exportSnapshot() from the Groovy Common Helper Functions to your script. Next we will log into PBCS, and select the Application icon. Once expanded, select the Migration icon. (Your icons may vary somewhat if your environment hasn’t been updated.)
Navigate through the Artifact Categories, and select the objects you want to export. Remember that selecting an artifact category will allow future exports to capture newly added artifacts, while selecting specific artifacts within categories will limit future extracts to those just those specific artifacts.
Select the Export button and provide an export name. I selected “Planning” and named my export “Full_Planning”. Assuming that I have copied the exportSnapshot() function from the Common Helper Functions for Groovy, I only need a single line of code to re-execute an LCM export:
At this point, you should have a fresh LCM export sitting in the Inbox/Outbox.
Initiating an LCM Import
I wouldn’t typically automate an LCM import into an application, however this could conceivably be useful if you’re refreshing a number of testing or training environments on a regular basis.
To import a snapshot using the Migration API, first copy the importSnapshot() function from the Common Helper Functions for Groovy. Then add the line highlighted below and run the script.
A quick check of the Migration Status Report will confirm the success of your LCM import.
Running the User Provisioning Report
Running user provisioning reports in an automated manner can be useful for organizations with rigorous IT audit and documentation requirements. To run this report using the Migration API, copy the waitForCompletion() function from the Common Helper Functions. You will also need to copy the provisionReport() function from the chapter “User Provisioning Report”. (This function isn’t currently listed in the Common Helper Functions for Groovy.)
Then add the following line to your script:
It is important to note that the User Provisioning Report will be placed into the Inbox/Outbox. From there it can be downloaded automatically with the downLoadFile() function.
The User Provisioning Report itself will look something like this:
Running the User Audit Report
While the User Provisioning Report will highlight all of the roles assigned to a give user (including the group through which they inherited a role), the User Audit Report shows when the user accessed the application and their associated IP address. This report doesn’t address specific activities undertaken within the application, but rather the fact that the app was accessed.
To run the User Audit Report using the REST API, you will need to copy the userAuditReport() function from the chapter “User Audit Report”. (This function isn’t currently listed in the Common Helper Functions for Groovy.)
Then add the following line to your script:
Like the User Provisioning Report, the User Audit Report will be placed into the Inbox/Outbox. From there it can be downloaded automatically with the downLoadFile() function.
The User Provisioning Report itself will look something like this:
You may have noticed that both report functions allow the specification of a report type (either “provisionreport” or “userauditreport”). The documentation suggests that the “provisionReport()” function goes with the “provisionreport” parameter, and the “userAuditReport()” function goes with the “userauditreport” parameter. This makes sense, but can you run an audit report with the “provisionReport()” function and vice versa? Here’s what I noted:
Wrap-up
So there you have it! You can now automate backups, migrations and usage reports using the REST API’s.