Roundtrip Technical Design

Roundtrip Control	}APQ C3 FIN Roundtrip Control cube stores the roundtrip configurations and is used as basis for roundtrip orchestration.
Roundtrip Configuration	Set of roundtrip processing steps in the Roundtrip Control Cube with defined goal. For example hardcoding of source system data into FIN General Ledger cube.
Main Roundtrip Wrapper	Process }APQ.C3.FIN.Roundtrip.Main is a master process used to run selected Roundtrip Configuration implementing parameters prioritization and process synchronization as each of the roundtrip processing steps are run independently by RunProcess to avoid possible commit deadlocks. This implies commit is done after each Roundtrip Step is finished, traditional rollback mechanism applied to all child processes called from a wrapper doesn’t apply in this case. The wrapper supports running of parallel enabled roundtrip compatible processes either natively or through a compatible wrapper. Multi-year data processing is supported as the wrapper exposes pPeriodFrom and pPeriodTo parameters relating to T Year-Month dimension. The year-end rollover is handled in a sequence by the wrapper automatically should the above parameters span multiple years.
Roundtrip Step	Dimension }APQ C3 FIN Roundtrip Step contains basic building blocks of Roundtrip Configuration. The Roundtrip Steps are executed sequentially from the Main Roundtrip Wrapper. The Roundtrip Step may be linked either with a roundtrip compatible process or any process that can be called through a roundtrip compatible step execution wrapper. Roundtrip Compatible Process exposes set of roundtrip compatible parameters and implements semaphore logic signaling process termination to the main roundtrip wrapper. Roundtrip compatible process wrapper allows to plug-in non-compatible process with some limitations regarding custom parameters that are not compatible with roundtrip as these are allowed to receive only constant predefined values. Roundtrip Step allows to define default parameter values of the Roundtrip Compatible Parameters in relation to a Roundtrip Configuration.
Roundtrip Compatible Parameters	The parameters are linked to each Roundtrip Step and are passed to associated process following the prioritization logic described below. The Roundtrip Compatible Parameters are following: pDimPar pMaxThreads pVersion pYear pCurrency pCompany pBSEG1 pBSEG2 pBSEG3 pBSEG4 pConsolMeasure pMonthFrom pMonthTo pFullLoad pReattachRule pSkipM00ZeroOut The parameter values follow a specific hierarchy of precedence, ordered as follows below. This hierarchy ensures that more explicit or specific parameter values are prioritized over more general or default ones. The highest priority is given to the Forced Parameter Value if it's explicitly defined by a Roundtrip Step within a Roundtrip Configuration. Next in line is the Forced default Parameter Value of a Roundtrip Step if it's explicitly set. The third level of priority is assigned to the parameter value provided via the Main Roundtrip Wrapper when executing a Roundtrip Configuration. The last priority is given to the default parameter value of the process that is linked to the Roundtrip Step. Forced Parameter Value is setting the parameter value explicitly by adding prefix FORCE: to the parameter value. Example: pVersion – FORCE:ACT The parameters pYear, pMonthFrom, and pMonthTo can be adjusted by the Main Roundtrip Wrapper if processing over multiple years is necessary. The Main Roundtrip Wrapper does this by converting its own parameters, pPeriodFrom and pPeriodTo, into values for pYear, pMonthFrom, and pMonthTo. It then iterates through each year within the selected period and adjusts these parameters as required.
Process Message Cube	}APQ Process Response Message cube is an important part of the solution. Provides feedback to the user. Serves as a semaphore cube to indicate process termination to the Main Roundtrip Wrapper.
Process State Polling	This is technique used in the Main Roundtrip Wrapper to periodically check status of a Roundtrip Processing step that has been executed. The interval is configurable in Administration > System > Settings. Select Apliqo FPM Params \ Thread polling interval (seconds) parameter. Setting polling interval to very low value is not recommended as the lower the value the bigger risk of process locking occurring. The polling is based on issuing commit to Process Message Cube, query to process state and waiting for specified period. This waiting loop is executed for limited time period and error terminating Main Roundtrip Wrapped processing will be raised if the process did not acknowledge process status change. There are two phases of polling for process execution status. First phase: Checking that process was able to initialize – the timeout period is set in Administration > System > Settings. Select Apliqo FPM Params \ Maximum process initialization time allowed for parallel processing (seconds) parameter. Second phase: Checking that process was able to finish – the timeout period is set in Administration > System > Settings. Select Apliqo FPM Params \ Maximum run time allowed for parallel processing (seconds) parameter.
Parallel Enabled Roundtrip Processes	Many of the Roundtrip Processes were engineered to leverage parallel data processing, enhancing overall performance. Such processes can be easily identified by usage of pDimPar and pMaxThreads parameters, which instruct the process to parallelize on the pDimPar dimension and utilize up to pMaxThreads threads. Here's how it works: The main process, when required, initiates child processes or threads to carry out tasks in parallel, managing their synchronization to ensure proper data flow and task completion. The "main thread" is always the starting point for any parallel processing. This thread can always be identified by its ID, denoted as pThreadID = 0. To prevent any data conflicts, each thread gets its own unique "slice" of the source and target data areas. This is accomplished by assigning each thread unique elements of the parallel dimension (pDimPar). This ensures no two threads work on the same elements simultaneously, thereby avoiding any overwriting issues. This slicing mechanism utilizes each thread's pThreadID to distribute elements according to the order within the dimension. In other words, each thread selects elements at intervals that are multiples of its own pThreadID. This way, the data elements are evenly and uniquely divided among the threads for processing. In the case of processes that handle data transfer between cubes with different dimensional granularity (commonly those transferring data between operational and planning cubes), a mapping from the target to the source dimensionality is utilized. This could mean mapping from BSEG Plan to BSEG or PCoA to OCoA, for instance. This mapping enables the construction of appropriate parallel slices, ensuring that there's no conflict between data elements during processing. The main thread can operate in two distinct modes (settings through Adminstration > System > Settings, Apliqo FPM Params): Watcher only mode: In this mode, the main thread initiates child threads and simply waits for their completion. Once all child threads have finished their tasks, the main thread will then terminate. To enable this mode, set meaningful non-zero value to parameter Maximum run time allowed for parallel processing (seconds). Worker mode: In this mode, the main thread starts child threads but also takes part in the data processing like any child thread. Once it completes its task, it waits for all other child threads to finish. After all child threads have terminated, the main thread then terminates itself. To enable this mode, set 0 to parameter Maximum run time allowed for parallel processing (seconds). Child thread synchronization in main thread is accomplished with semaphores being set by each of the child threads in the }APQ C3 Thread Control cube. Main thread is polling status of all child threads and checks if all have finished in a loop with subsequent wait. The length of this waiting period is defined in the Apliqo FPM Params under the setting Thread polling interval (seconds). This dictates how frequently the main thread will request status updates from the child threads.