Omniconvert Dashboard v1.0.0
-------------------------

### 1. Description
- The extension offers different reports about your business health. These reports are nicely exposed in graphs.
- The extension offers a customer grouping functionality based on RFM segmentation, to help identify which customers are more valuable for the business.

### 2. Features
- Enable / Disable module.
- Set different periods for seeing some of the reports (graphs).
- Set the statuses of orders that should be excluded from chart reports.
- Set Omniconvert API settings for showing OMNICONVERT ACTIVITY figures.
- Set customer groups that should be left untouched by RFM aggregation.  
- [ACL](https://en.wikipedia.org/wiki/Access_control_list) (who can have access to this functionality) can be set for admin users from *System* -> *Permissions* -> *Roles* -> *Role resource* -> Omniconvert related areas.
- Reports are available on general / website / store level if you have a multi-store / multi-website configured Magento.

### 3. Compatible with
- Magento CE >= 1.9.1.0
- PHP >= 5.6  
Note: the extension may be compatible with lower versions, but these are the versions extension was developed on.

### 4. Usage
- As admin, go to *System* -> *Configuration* -> *[OMNICONVERT] Dashboard* and configure extension.  
- To see reports go to *Omniconvert* -> *Dashboard*

### 5. Technical specifications
##### 1. General considerations
- Reports are generated by crons that run once every night.
- An auxiliary script is provided with the module, so you can run the aggregators (same as crons) at any time.  
For aggregating data for the first time, it is recommended to run this script. Depending on your shop's number of lifetime orders, number of stores, it may take a while to aggregate all data. Run following commands for more details: 
```sh
cd [your_magento_site_root_dir]/shell/
php -f omniconvert.php help
```
##### 2. Models
- Aggregators (classes that indexes data in tables to be retrieved more easily on read time for each graph) reside in `Model/Aggregator` dir.  
Each aggregator has an associated core flag where last date aggregated is kept (`Omniconvert_Dashboard_Model_Aggregator_Abstract::getFlag()`). This flag is updated at the end of aggregation process. If does not have any date in it, or it 's state is 1, it means that a "full" aggregation is done (this flag has no effect on RFM customer groups as full aggregation is performed at every run). At the beginning of aggregation process date from this flag is checked (`Omniconvert_Dashboard_Model_Aggregator_Abstract::_isAlreadyAggregated()`) with current date, in order not to aggregate more than one time data for same day (this can happen especially for RS aggregator) which is used/started by the other aggregators depending on its data. This flag is also used to filter aggregated orders that were modified upon that last aggregated date next time (`Omniconvert_Dashboard_Model_Aggregator_Abstract::_getFirstCreatedAt()`)  
Aggregated orders are the one until the last full day before aggregators' run time. (`Omniconvert_Dashboard_Model_Aggregator_Abstract::getLastDateToAggregate()`)  
Operations to db are done via resource models, and are paginated (in batches).  
At the end of aggregation process, beside updating the last data aggregated flag, also any cache associated with resource model is deleted (it has expiration time set 1 day anyway, but for more correctness on data change delete it right away), cached data that is set by Charts models in order to save time between multiple accesses of Dashboard page.  
- Crons models reside in `Model/Cron` dir. They start aggregators if module is enabled, once per night (or see _<crontab><jobs>_ node from `etc/config.xml`)  
- Flags reside in `Model\Flag` dir. More info in Aggregators section above.  
- Resource models (operate with db) are kept in classes in `Model/Resource` dir.  
For aggregators they extend `Omniconvert_Dashboard_Model_Resource_AggregationAbstract` resource model. Operations upon db are mostly internally paginated / done in batches for safety not to overkill db. They provide also methods for cache saving, loading, cleaning of data. Cache expiration is 1 day (as data is indexed by daily basis and after that period it becomes stale). Cache is saved under the main magento cache tag for collections, so the _"Collection Data"_ checkbox should be refreshed if needed from _System_ -> _Cache Management_  
- Dashboard charts data retrieval is kept in classes in `Model/Charts` dir. They use the resource models to retrieve in the desired form needed data to show to users. Also, data is cached from here.  
- Source models are kept in  `Model/Source` dir. At the moment sources for select options for Cohort Analysis and Growth Trend graphs exists. Also for RFM exluded customer groups - takes all customer groups without the ones that are involved in RFM. If for example RFM functionality needs to be disabled, you can check all groups in this sys config field (or delete all RFM group definitions).  
- Sys config backend models are kept in `System/Config/Backend` for validating some system config fields.  
For _Customer Lifetime Value_ months select, a restriction of setting a max. of 4 options, and the max. month opt. must not be greater that 96 (last 8 years to show in graph should be enough).  
For _Revenue Structure_ a restriction of setting a max. of 5 order groupings.  
For ignored order statuses the after save method is overridden to dispatch the event of "full aggregation is required" if data has changed.  
- Observers are kept in `Model/Observer` dir.  
    - `Omniconvert_Dashboard_Model_Observer_ReaggregationRequiredDispatcher` is an observer registered on magento multiple events _store_save_after_, _store_delete_after_, _website_save_after_, _website_delete_after_ and just dispatches another event _omniconvert_dashboard_reaggregation_required_ because scope changes and full (re)aggregation should be done next time crons run.  
    - `Omniconvert_Dashboard_Model_Observer_ReaggregationRequiredHandler` is an observer registered on "internal" _omniconvert_dashboard_reaggregation_required_ event and marks the aggregators flags (sets their state to 1) to make a full (re)aggregation next time. Additional data can pe passed to this observer under the key 'aggregators' - an array with which aggregators need full (re)aggregation. If not passed, or sent empty - all aggregators are considered.  
    - `Omniconvert_Dashboard_Model_Observer_CustomerGridPrepareLayoutBefore` is used to add the 3 _R_ / _F_ & _M_ columns on customers grid if enabled from sys config.
    - `Omniconvert_Dashboard_Model_Observer_CustomerCollectionLoadBefore` is used to add the 3 attributes (R/F/M) to customers select. Works in conjunction with previous observer.  
- Api related requests are kept under `Model/Api` dir. It provides an abstract request and response model. Currently only a route for Omniconvert API is implemented, the "website stats" one (data retrieved here is used in _Dashboard_ - _OMNICONVERT ACTIVITY_ section).  
- RfmPoint and RfmGroup entities have full Magento models types (model, resource and collection). Resource model of Rfm Groups also implements some aggregation logic.  

##### 3. Helpers
 - `Omniconvert_Dashboard_Helper_Data` contains methods for  
    - retrieving system config settings,
    - logging related module messages under the `var/log/Omniconvert_Dashboard.log` file
    - retrieving scoping tree  
##### 4. Blocks  
 - In the _Adminhtml_ folder admin blocks are kept. For _Dashboard_ a custom block with custom template was used. For _RFM Points_ and _RFM Groups_ standard Magento grid & form blocks were used.

##### 5. Skin
- External libraries used are:
    - Bootstap (v3.3.7) for styling (but only some components (like grid, buttons, tables...), not the entire library, check bootstrap.config.json link to customized lib - if you need more components in the future start from that link).
    - Opentip (v2.4.6) (js + its css) library for tooltips that works on Prototype Js.  
jQuery was avoided to be used in order to keep the Prototype Js culture that Magento is build upon. (even if life would be more simpler with it :))


### 6. Install
- Copy files / folders in the Magento installation folder; be careful to put design/skin files in your current default theme.*  
Modules affects mostly the admin area, not the frontend, and is very unlikely to have a different admin theme, [here](http://www.suncrescent.net/2009/03/magento-how-to-change-the-admin-theme/) is an example how to achive that, but if you have a customization to your site as in the link above, just replace `adminhtml/default/default` with your current theme folders in the paths below.  
    - `app/code/community/Omniconvert` -> `[your_magento_site_root_dir]/app/code/community/`  
    - `app/design/adminhtml/default/default/layout/omniconvert` -> `[your_magento_site_root_dir]/app/design/adminhtml/default/default/layout/`
    - `app/design/adminhtml/default/default/template/omniconvert` -> `[your_magento_site_root_dir]/app/design/adminhtml/default/default/template/`  
    - `skin/adminhtml/default/default/omniconvert` -> `[your_magento_site_root_dir]/skin/adminhtml/default/default/`  
    - `app/locale/en_US/Omniconvert_Dashboard.csv` -> `[your_magento_site_root_dir]/app/locale/en_US/`  
    - `app/locale/ro_RO/Omniconvert_Dashboard.csv` -> `[your_magento_site_root_dir]/app/locale/ro_RO/`  
    - `shell/omniconvert.php` -> `[your_magento_site_root_dir]/shell/`
    - `app/etc/modules/Omniconvert_Dashboard.xml` -> `[your_magento_site_root_dir]/app/etc/modules/` 
- Log in into Magento's admin and if you have cache enabled, clear it (from *System* -> *Cache Management* -> Flush Magento Cache)
- IMPORTANT NOTE: the extension has some crons that aggregate data for reports, so Magento cron jobs setup is required. This should have already been done when you installed your Magento; if not, you may want to check this [link](http://devdocs.magento.com/guides/m1x/install/installing_install.html?_ga=2.70288407.66222111.1521056544-1572817907.1517314185#install-cron).  

### 7. Uninstall
- Remove the files and folders from chapter *6. Install*
- Run the following SQL queries on your database:
```sql
DELETE FROM `core_resource` WHERE `code` = 'omniconvert_dashboard_setup' LIMIT 1;
DELETE FROM `core_config_data` WHERE `path` LIKE 'omniconvert_dashboard%';
DELETE FROM `core_flag` WHERE `flag_code` LIKE 'omniconvert_dashboard%';
DROP TABLE `omniconvert_dashboard_rs`;
DROP TABLE `omniconvert_dashboard_clv`;
DROP TABLE `omniconvert_dashboard_ca`;
```  
- Manually delete any customer group this extension has installed from admin menu _Customers_ -> _Customers Groups_ -> click on particular group item -> click _Delete Customer Group_ button. Magento has by default a functionality that assignes any customer that was in that group to its website default group (customers from deleted group will not be left unnassinged to any group)