MPM Use Guide documentation update (#358)

* test

* clusterdashboard

* cluster

* beforeusingMPM

* Terminology

* GetStartedMPM

* GetStartedMPM

* MGdashboard

* test

* customers

* targets and transactions

* GetStarted

* GetStartedImages

* Terminology

* BeforeUsing

* MPManager

* ClusterDashboard

* MinigridDashboard

* Agents

* Customers

* Meters

* Targets

* Transactions

* Tickets

* Maintenance

* SMS

* Bulkregistration

* Order

* OderBulk

* SHS

* ebikes

* Androidapps

* Androidimagersize

* Remove test file

* Remove duplicated Agents

* Move Android apps and company registration out of get-started

* Fix linter

* Fix Linter

* Remove unneeded images

* Rename and move images

* Fix Terminilogy table

* Fix file names

* Bring back the refactoring warning

* Small reorder

---------

Co-authored-by: AndreaCabaneroS <ac@inensus.com>

docs/get-started.md

@@ -39,8 +39,22 @@ order: 1
 
 ## MicroPowerManager
 
-MicroPowerManager (MPM) is a decentralized utility and customer management tool.
-Manage customers, revenues and assets with this all-in one Open Source platform.
+MicroPowerManager (MPM) is an open source, free-of-charge customer relationship manager (CRM) software that enables companies in the rural electrification space to manage their portfolio of customers.
+
+It is designed to be suitable to both Mini-Grid operators as well as Solar-Some-System (SHS) and e-bike distributors.
+The software was originally developed by INENSUS GmbH and is now hosted and co-developed by EnAccess. This User Manual is designed for persons with a basic understanding of what a CRM tool, Mini-Grid and SHS are.
+
+The MPM package includes:
+
+1. The **website interface** (where company-level data in regards to gathered revenues and potentially technical operational data) can be accessed. Customer complaints and technical faults can also be managed in a centralized manner via this interface. “Bulk-registration” of an existing portfolio of customers (transferring customer data from legacy systems to MPM software) can be offered by EnAccess as-a-service.
+
+2. **MPM Android Apps**:
+
+   2.1. **Customer Registration App**: it is required to be able to register new customers.
+
+   2.2. **Agent/Merchant App**: serves as the bilateral communication channel between the company headquarters (users of MPM website interface) and the team of agents on site, managing and responding to customer complaints. The Agent App is also used to manually generate STS tokens (where customers are not able to do so themselves with their own phones).
+
+   2.3. **SMS Gateway App**: required to enable the possibility of sending bulk SMS to customer portfolio via the MPM website interface as well as communicating via SMS with company's agents/maintenance service providers via the MPM website interface.
 
 ## Get Started
 

docs/usage-guide/agents.md

@@ -5,5 +5,8 @@ order: 7
 # Agents
 
 As outlined above, Agents are company staff that are on site (or close to the site) and are able to support customers with tasks such as token generation (in exchange for cash payments), selling appliances, report customer issues to the company headquarters, etc.
+
 The user can register a new Agent on the MPM account by going to the “Agents” menu and then pressing on “+”.
-The defined log in credentials by the user are then to be shared with the Agent, for him/her to be able to use the Agent account. For more information on how to generate and manage tickets, kindly see the section “Tickets” below.
+
+The defined log in credentials by the user are then to be shared with the Agent, for them to be able to use the Agent account.
+For more information on how to generate and manage tickets, kindly see the section “Tickets” below.

docs/usage-guide/android-apps.md

@@ -0,0 +1,85 @@
+---
+order: 19
+---
+
+# Android Apps
+
+As outlined in the “Get Started with MPM section”, the MPM software package comes with 3 Android Apps, which are presented in more detail in this section:
+
+The 3 apps (APK files) can be downloaded and installed as follows:
+
+1. Accessing this link: <https://cloud.micropowermanager.com/#/welcome>
+
+2. Click on the APK app files via your phone (Android required) – For Agent App Android version 6 or above is required)
+
+3. Apps get installed
+
+4. Once the app is installed on the phone, you will be asked for an URL. Following URL can be used: <https://cloud.micropowermanager.com>
+
+5. Log in to the apps with the login credentials used to access MPM website interface (in case you have access to the website interface) or with the credentials given to you by management.
+
+For more information on how to use the Android Apps, kindly check the "Android Apps" section of this user manual.
+
+![App Overview](images/apps-overview.png)
+
+## Customer Registration App
+
+New customer profiles can be created via this app or through the website directly. The Customer Registration App enables the user/Agent to register new SHS and e-bike devices. The Agent/user has to first install the app by following the steps outlined on the “Get Started with MPM” section. The app can be accessed using the log in credentials provided to the Agent/user by the company management.
+
+Once logged in, the user should go to “Add Customer” on the bottom right of the screen and introduce the relevant customer data. Kindly note that the “Meter Type”, “Tariff”, “Connection Group”, “Connection Type” and “Sub Connection Type” fields are only relevant for mini-grid customers (not SHS and e-bike devices). The device’s ID as per the manufacturer should be inserted on the field “Serial Number”. This will serve as the device identified to receive payments for that device.
+
+The app also enables the user to access the customer list for the systems for which it is in charge (see bottom left of the screenshot below).
+
+![Customer Registration App Overview](images/customer-registration-app-overview.png)
+
+## Agent/Merchant App
+
+The purpose of the Agent app is to:
+
+1. **Generate electricity tokens** for registered devices (in case the customer cannot use mobile money, it can rely on a local Agent to generate a token on his/her behalf after a cash payment). The Agent hands in the generated token by the app, which the customer can then use to top-up the applicable device (electricity meter, SHS or e-bike). To generate a token, follow these steps:
+
+   a) Select the “Customers” Menu on the Agent/Merchant app
+
+   b) Select the customer for which a token should be generated
+
+   c) Click on the “+” at the bottom right of the skin
+
+   d) Insert the currency amount the customer has paid (which should be converted into a token)
+
+   e) Press “Continue” and then “Confirm”.
+
+   f) The app will give you the token, which you then share with the customer.
+
+   ![Agent App Token Generation](images/agent-app-token-generation.png)
+
+2. Sell an “Appliance” to a customer:
+
+   a) Select the “Customers” Menu on the Agent/Merchant app
+
+   b) Select the customer to which an appliance is to be sold
+
+   c) Click on the “Appliance” logo at the bottom of the screen
+
+   d) Click on “+” and define the appliance data (name, cost, etc.).
+
+   ![Agent App Selling Appliance](images/agent-app-selling-appliance.png)
+
+3. Issue a ticket for a customer:
+
+   a) Select the “Customers” Menu on the Agent/Merchant app
+
+   b) Select the customer to which a ticket is to be issued
+
+   c) Click on the “Tickets” logo at the bottom right of the screen
+
+   d) Click on “+” and insert customer issue to be resolved.
+
+   ![Agent App Create Ticket](images/agent-app-create-ticket.png)
+
+## SMS Gateway App
+
+Kindly be aware that this app has created issues with service providers. The privacy settings and new features of Android may interfere/block the proper functioning of this app. These issues are pending to be resolved.
+
+The purpose of the app is to enable SMS-sending from and to the MPM website interface as well as to be able to send SMS to your customer portfolio through the same website. For this feature to work, the SMS Gateway App must be installed on the applicable mobile phone (following the steps outlined on the “Get Started with MPM”). Click then on the Copy Device Token and share the token with the headquarters staff. The users with access to the MPM account’s website interface can then insert the device token under the “Settings” page, thereby interlinking this phone with the MPM account.
+
+![SMS Gateway App Overview](images/sms-gateway-app-overview.png)

docs/usage-guide/beforeusing.md

@@ -4,49 +4,56 @@ order: 2
 
 # Before using MPManager
 
-The key component(s) of the system is a mixture of meter/customer. That
-means both melts into each other a bit. The only way to register a
-customer or a meter is to register them both at the same time. For that
-reason from now on, every registered person will be mentioned as a
-**customer**.
+The key component(s) of the system is a mixture of device/customer. That means both melts into each other a bit. The only way to register a customer and a new device, is to register them both at the same time. For that reason from now on, every registered person will be mentioned as a **customer**.
 
-## Register a customer & meter
+## Register a customer & device
 
-There is an additional [Android
-Application](https://github.com/inensus/Customer-Meter-Registration>)
-that should be used to register a customer with a meter together. The
-application allows you to select the village where the customer lives,
-the meter manufacturer, and the energy tariff that should be assigned to
-the meter.
+**Registering new mini-grid customers (electricity meter devices):** To register new mini-grid customers, the Customer Registration App has to be used. After introducing the customer’s basic details (name, phone number, etc.), the app allows you to select the village where the customer lives, the meter manufacturer and the energy tariff that should be assigned to the meter. **Note that while new customers can be created via the website interface and existing meter devices can be re-assigned to customers, new meter devices can only be registered via the mentioned Customer Registration App.**
+
+**Registering SHSs and e-bike devices:** Registration of these devices can be done both via the Customer Registration App as well as the website interface. If user wants to use the app, there are two relevant inputs (on top of the usual customer data): 1) a dropdown menu listing all manufacturers integrated with MPM (including both SHS and electricity meter manufacturers) and 2) an input field to insert the device serial number (kindly note that the app requests for “meter serial number” but in fact also refers to “SHS serial number” or “e-bike serial number”, as applicable). Future development work would entail adapting this field name to a more generic “device serial number”.
+
+![MPM Architecture](images/mpm-architecture.png)
 
 ## Tariffs
 
-Its basically the energy price per kWh with an optional access
-rate/subscription fee. The operator is free to define the period of that
-fee. Ex: Every 7 days.
+It is basically the energy price per kWh with an optional access rate/subscription fee. The operator is free to define the period of that fee. Ex: Every 7 days. Such a subscription fee may also not be introduced at all. This feature only applies for mini-grid meter device type, NOT for SHS and e-bikes. For SHS and e-bikes, the payment scheme is set up at the time of registering the device on MPM.
+
+To define payment schemes for SHS and e-bikes go to “Appliance” menu (see “Appliance” section below).
 
 ## Payment Channels
 
-or now, the system supports only incoming payments from Airtel Tanzania
-and Vodacom Tanzania. Both providers are accepting Mobile Money and
-notify the MPManager over a secure tunnel.
+The list of payment channels through which MPM can receive mobile money is outlined on the section “Getting Started with MPM above”.
 
 ## Payments
 
-Each incoming payment has to contain the meter number. That is the
-unique number that is used to identify the other channels where the
-money could spend. After payment is been received the system
-automatically checks these further points; 1. Missing Asset Type Rates 2. Not paid Access Rates 3. Convert the money to energy and generate an
-STS-Token for the calculated energy amount. At the end of the payment
-process, the customer will be notified about each step.
+Each incoming payment has to contain the device serial number. That is the unique number that is used to identify the other devices where the money could be spend. After payment has been received, the system automatically checks no outstanding debt from the customer remains to be paid, before generating the applicable token.
+
+![Payment Flow Detailed](images/payment-flow-detailed.png)
+
+MPM is designed in a way that the transferred money by the customer will first be used to clear outstanding debt by that customer (from an appliance loan and tariff access (if applicable)) before being converted into a token. Therefore, only the remaining money after debt clearing will be converted into a token for the device number for which the transaction has been done.
+
+Note: a device number is required even if the customer intends not to generate a token for any of the devices (electricity meter, SHS or e-bike) but simply repay an appliance. In which case the customer should transfer the money amount matching the outstanding appliance debt (to avoid MPM generating a token for that device with the surplus amount).
+
+Note: If the entered device serial number is not valid, the system refuses the payment automatically.
+
+## Selling an Appliance
+
+The system supports to sell SHS and e-bike devices as well as appliances to customers on a rate basis plan. User can create whatever appliance it uses to sell (water pump, electric pressure cooker, mill, TV, etc.). The steps to sell a SHS or e-bike to a customer as well as registering a new electricity device are explained on the subsection “Register a customer & device” above.
+
+In this subsection, the procedure to sell/assign a new appliance (non-device) to a customer is outlined:
+
+1. If the customer is not registered, first use MPM website interface to register a new customer (see “Customers” section below”). If the customer already exists, skip this point.
+
+2. Go to the “Appliance” menu of the website interface, click on “+” and define a new appliance (name and appliance cost/price).
+
+3. Go to the “Customer” menu, find the customer to which the created appliance is to be sold, go to “Sold Appliances”, click “+” and assign the mentioned customer the recently created appliance. MPM asks the user to select one of the 2 re-payment scheme options:
 
-At the end of the payment process the customer will be notified about
-each step.
+   a) **Installation count based**: user defines the down payment, the number of instalments under which the total appliance cost is to be financed, and the rate type (monthly or weekly). MPM gives as output the instalment amount the customer has to pay.
 
-If the entered meter number is not valid the system refuses the payment
-automatically.
+   b) **Instalment cost based**: unlike the case above, in this case the user defines the instalment amount (as well as total appliance cost and payment rates (weekly or monthly). MPM then calculates the number of instalments under which the total appliance cost is to be paid.
 
-## Selling an Asset
+   Note: Future development work would include to update the Agent App so that not only appliances but also SHS and e-bike devices can be registered (right now Agent App does not enable to add a device with a serial number).
 
-The system supports to sell assets to customers on a rate basis plan. A
-water pump or a milling machine will be a good example of that.
+![New Appliance](images/new-appliance.png)
+![Customer Sold Appliance](images/customer-sold-appliance.png)
+![Appliance Payment Scheme](images/appliance-payment-scheme.png)

docs/usage-guide/bulk-registration.md

@@ -0,0 +1,7 @@
+---
+order: 16
+---
+
+# Bulk registration
+
+MPM enables the possibility to register a bulk of existing customers (from another CRM system/software or database) at once (rather than registering each customer one by one). This is a manual customized process. If you are interested on this feature, kindly request support to EnAccess.

docs/usage-guide/clusterdashboard.md

@@ -4,10 +4,23 @@ order: 5
 
 # Cluster Dashboard
 
-The cluster dashboard is built similar to the clusters dashboard. There
-are small informative boxes at the top of the screen. The financial
-overview and the map are based on Mini-Grids instead of clusters.
+The cluster dashboard provides an overview of the portfolio of systems (whether mini-grids or solar home systems (SHS)) that the user has. A "cluster" is understood to bundle several mini-grids, which in turn (potentially) bundle several villages (although a single village can be assigned to a mini-grid). Each village bundles in turn several devices (whether electricity meters, solar home systems or e-bikes. Where customers are mini-grid customers, they are registered via the energy meter number. Where customers are solar home system or e-bike users, the SHS or e-bike serial number is used for registration purposes.
 
-There are two new sections available; 1. Revenue Analysis: That is the
-place where all targets of MiniGrids are shown together. 2. Revenue
-Trends: That is a chart that breaks down the revenue to customer groups.
+The cluster dashboard is composed of the following sections:
+
+1. Small informative boxes at the top of the screen summarize total # of clusters, # of registered customers (applicable for SHS), # of connected meters (applicable for mini-grids) and total revenue.
+
+2. A financial overview of the revenue collected for the selected period.
+
+3. A map visualizing where the clusters/mini-grids/SHSs/e-bikes are installed.
+
+In order to add a new mini-grid, cluster or village to the MPM account, following steps must be undertaken (as depicted on the photos below):
+
+1. Click on "Locations" at the top right of the screen
+
+2. Select applicable option.
+
+3. Fill the required fields.
+
+   ![New Mini-Grid 1](images/new-mini-grid-1.png)
+   ![New Mini-Grid 2](images/new-mini-grid-2.png)