Alithya’s PowerShell Accelerator for Ground-to-Cloud EPM
Oracle provides a powerful toolset for interaction with the EPM Suite through a set of REST APIs and a downloadable product called EPM Automate that provides for command line access to a significant portion of the REST APIs. At many of our customers, we implement scripts to orchestrate and schedule processes. These processes execute EPM jobs, transfer metadata and data to the EPM Suite, and download data from the EPM Suite.
We believe in standards to facilitate common implementations across our large customer base and to manage the evolving nature of Oracle’s EPM Suite. Standardization improves our ability to support our customers, and we have taken steps to consolidate our scripting into a single preferred service accelerator that provides high-quality, implementation-proven script utilities in a packaged delivery.
When we started this effort, we established a set of criteria for what we wanted to accomplish:
- Provide scripts that work in either Windows or Linux environments.
- Apply scripting best practices in a packaged delivery.
- Improve quality, delivery performance, and supportability by having a set of scripted functions that are unit tested prior to first use at a customer.
- Provide a standard approach to setup of jobs including signing into EPM Automate.
- Provide a standard logging framework.
- Provide exception handling including emailing.
- Provide a standard approach to archival of transferred files.
- Provide a standard approach to post procedure clean-up of temporary files.
- Provide ability to run scripts individually and together.
- Allow the calling scripts to be easily readable.
Establishing the programming language was foundational and involved conversations about batch, Bash and PowerShell. Although each language has advantages and weaknesses, the Product team selected PowerShell for the following reasons:
- Robust interpreted programming language that includes standard capabilities such as variable, functions, loops, exception handling, etc.
- Native on Windows environments with a nice development environment, PowerShell-ISE.
- Can invoke commands and batch scripts easily.
- Intended future direction for Microsoft with strong on-line support.
- Open-sourced and available on Linux, testing showed that little or no modification to scripts is required for use in Linux environments.
What are we Providing? A Working Example
We provide a packaged set of utilities called EPMAutomatePowerShellUtilities as an accelerator to development of ground-to-cloud scripts. EPM Automate is in the name because we primarily use EPM Automate to accomplish an action, but also use the REST APIs when EPM Automate does not provide the required action.
To highlight the accelerator, lets document a working example with a customer implementing a Profitability and Cost Modeling Cloud Service (PCMCS) solution.
Customer is providing dimensional data and content data files and needs the following actions:
- Upload Dimensional Data and integrate into PCMCS
- Upload Content Data and Run Allocations
- Download Post Allocated Results
- Run all the above as a Single Script
First, the Boiler Plate
All customer scripts have the following boiler plate to provide common behavior
#Place your actions here!
What is going on?
- try … catch … finally – allows for exception handling and script resolution in a common pattern. Standardized exception handling improves the quality of the ETL process by ensuring that support personnel are notified via email for any process execution stoppage.
- - $PSScriptRoot/config/properties.ps1 – loads the variables required to run the scripts. For example, we load $ApplicationName which is the PCMCS application with which we are working. The properties.ps1 is a text file that requires very little maintenance after initial setup.
- - $epmautomatepowershellutilities/Utilities.ps1 – loads all the custom functions we provide.
- Pre-Job-Run $profile – sets up job and makes it ready to run including signing into EPM Automate.
- #Place your actions here! – this is where the custom actions are placed. See Scripts 1, 2, 3, and 4 below for examples of custom actions.
- Email-Exception – when an exception occurs, then email an error message including a zip of the temporary folder that contains process log and any other files that were created by custom actions.
- Post-Job-Run – clean up after custom actions are complete by signing out of EPM Automate and optionally removing temporary folder (configurable).
Script 1: UploadDimensionData.ps1 - Upload Dimensional Data and Integrate into PCMCS
We won’t repeat the boiler plate and focus on the custom actions:
Upload-DimData-And-Load $ApplicationName "$inboxFolder\Dimensional Data"
Deploy-Cube $ApplicationName -KeepData -RunNow
Readability is a huge factor here. We really don’t need to explain what these custom actions are doing, but let’s highlight a couple of things. First, the called function often looks a lot like a corresponding EPM Automate command; for example, “Enable-App” corresponds to the EPM Automate command “enableApp.” Second, we provide more complex calling functions such as “Upload-DimData-And-Load” to perform a set of common actions that run multiple commands - in this case the upload of multiple files - and then run the loadDimData command for all the uploaded files. Behind the scenes, an archive copy with a timestamp is placed in an archive folder for each of the uploaded files.
Script 2: UploadData.ps1 - Upload Content Data and Run Allocations
Again, without boiler plate:
Clear-POV $ApplicationName "VR_Working;SC_Forecast" -InputData -AllocatedValues -POVDelimiter ";"
Copy-POV $ApplicationName "NoVersion,SC_Forecast" "VR_Working,SC_Forecast" -isManageRule
Upload-Data-And-Load -ApplicationName $ApplicationName -Path "$inboxFolder\data" -DataLoadValue "OVERWRITE_EXISTING_VALUES"
Run-Calc -ApplicationName $ApplicationName -ModelPOV "VR_Working;SC_Forecast" -ExeType "ALL_RULES" -ClearCalculated -ExecuteCalculations -RunNow -isOptimizeReporting -POVDelimiter ";"
You’ll see a mix of EPM Automate analogs and a complex function that uploads all the content data and loads them into PCMCS. Again, the archival of uploaded files occurs during the Upload-Data-And-Load function.
Script 3 – DownloadResults.ps1 – Download Post Allocated Results
The custom actions are:
Export-Query-Results $ApplicationName "PCMCSDataExport.txt" "Post_allocated"
Script 4 – JustDoIt.ps1 – Perform all Three Steps
The boiler plate is built so that the Pre-Job-Run, Email-Exception, and Post-Job-Run understand when they are inside a calling script. This allows you to create a parent script to run multiple other scripts without modification of the called scripts.
Focusing on the custom actions:
In this parent script, EPM Automate is logged into a single time. Any exception results in full stop and a single email sent with an integrated process log.
The accelerator provides a high-quality framework allowing Alithya to focus on customer requirements and the actions needed to integrate with Oracle’s Cloud EPM suite. The low level, expected behaviors, such as exception reporting, logging, emailing, and file archival are available on day 1 of the engagement. With a focus on readability, these scripts are easily transferred to the support organization for long-term sustainability.
For long-term support, the customer can update the REST API version via the properties.ps1 file, and Oracle is providing EPM Automate updates that do not break prior scripts. If EPM Automate has a breaking change, the customer can update the utilities themselves or request an updated set from Alithya. Feedback from our customer base is positive with specific comments about the readability of the utilities and quality of initial deployment.
Overall, the accelerator is reducing the effort and time to deploy ground-to-cloud processes while improving the quality of deployment by reducing the time spent creating and debugging scripts.
Additionally, long-term support costs are lower through standardization of implementation patterns that allow support personnel to focus on what the script is accomplishing rather than how it is accomplishing it.
For comments, questions or suggestions for future topics, please reach out to us at firstname.lastname@example.org. Subscribe to receive notifications about new posts about Cloud updates and other Oracle Cloud Services such as Planning and Budgeting, Financial Consolidation, Account Reconciliation, and Enterprise Data Management. Follow Alithya on social media for the latest information about EPM, ERP, and Analytics solutions to meet your business needs.