Promote Shadow Application
/essbase/rest/v1/applications/actions/shadowPromote
Promotes the shadow application as the base application. Conceptually, the promote operation is equivalent to moving the Essbase application directory from a source to destination location, at the file system level.
Essbase must stop (unload) both applications, if they are running, before promoting. At the time of unloading, if the destination application is serving any ongoing operations, such as queries, Essbase terminates those operations and attempts to unload the application.
If a graceful unload process fails or takes longer than permitted by the input argument timeoutToForceUnloadApp (unit=seconds), Essbase forcefully terminates the application.
Example: if you specify 60 seconds for the timeout, but the termination of ongoing requests and graceful unloading of the application does not complete within one minute, Essbase triggers a forceful termination. After termination, Essbase promotes the shadow application.
The promote operation is supported on all applications, including aggregate storage, block storage, and Hybrid mode.
Note: when moving an existing application, only the application and cube artifacts (such as metadata and data) are replaced from the source to destination.
During a promotion, all security layer associations on the destination application, such as users, groups, and security filters, are retained, while that of shadow/source are lost. The same rule applies for partition definitions.
Example: If users X and Y had read-access to App1, and an admin promotes a shadow App2 to replace App1, both X and Y will be able to access App1.
If user Z had access to App2, then after promotion, Z is not able to access App1.
Promotion from shadowed application to base is honored only if there are no changes to the number of cubes and cube names. In other words, if a cube gets renamed or if there is any addition or deletion of an application after it was shadowed, then promotion of such an application fails with an error, leaving both applications as they were.
Example: ASOAppNew.cubeNew cannot be replaced as ASO.cube. ASOAppNew.cube can be replaced as ASO.cube.
Tips: You need not unload or stop the application prior to calling this promotion API. Essbase loads the application to gather information, and unloads it prior to moving the applications.
Request
- application/json
- application/xml
shadowAppName: Name of the hidden shadow application that needs to be promoted to base.
primaryAppName: Name of the primary application.
timeoutToForceUnloadApp: Time interval (in seconds) to force unload in the event of applications performing an ongoing requests even after time interval.
runInBackground: Specify true to schedule 'Shadow Promote' as a Job; otherwise, specify false.
object-
primaryAppName:
string
Name of the primary, non-shadow application.
-
runInBackground(optional):
boolean
Specify true to schedule 'Shadow Promote' as a Job; otherwise, specify false.
-
shadowAppName:
string
Unique shadow application name which is a copy of the source.
-
timeoutToForceUnloadApp:
integer(int32)
Time interval (in seconds) to wait before forcefully unloading/stopping an application, if it is performing ongoing requests. If a graceful unload process fails or takes longer than permitted by this timeout, Essbase forcefully terminates the application.
Response
- application/json
- application/xml
200 Response
OK
Promote shadow application completed successfully.
400 Response
Bad Request
Failed to promote shadow application.
500 Response
Internal Server Error.
503 Response
Service Unavailable
Naming exception or server exception.