Documentation (Usage Guide) update (#593)

* agentcommissions

* SHSregistration

* ebikes

* terminologydevice

* clarificationnote

* appliances

* applianceshift

* pluginshift

* agentadjustment

* appclarification

* shsregistrationwebsite

* clarificationsellingapp

* interlinkingsections

* Fix lint

* Rename images

* Remove broken image

---------

Co-authored-by: AndreaCabaneroS <[email protected]>

Author: dmohns

docs/usage-guide/agents.md

@@ -4,9 +4,33 @@ 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.
+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 “+”.
+Agents require the apps to do their work (see [Android apps](/usage-guide/android-apps)).
+
+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 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.
+For more information on how to generate and manage tickets, see [Tickets](/usage-guide/tickets).
+
+## Agent Commission Types
+
+Agents receive cash from customers on site.
+An agent's outstanding balance is the money it owes the company (i.e. it is the money it has collected on behalf of the company and has to transfer accordingly).
+
+The "risk balance" is the maximum amount of money that an agent can collect before it has to transfer the money to the company.
+When that balance is reached, agents will not be able to collect money anymore (generate tokens) or sell appliances (his account on the app will not work. So, when the agent sends the balance money to the company, then headquarters has to manually adjust the outstanding balance by that agent through MPM desktop.
+This is done by creating a “receipt” on the specific agent’s profile.
+When that receipt is created, balance of agent is removed/decreased to 0.
+
+Agents are paid on a commission-basis. There are 2 commission types:
+
+- **Energy commission:** % of the energy transaction that is kept by the agent. Sample says 0.1 = 0.1%).
+- **Appliance commission:** % of the appliance value that is kept by the agent. Sample says 0.1 = 0.1%).
+
+## Assigning or changing the commission of an agent
+
+1. Create a commission type under Agent --> Commission type (click on the ":heavy_plus_sign:" button at the top right corner).
+2. You either create a new agent, or you go to the page of the specific agent for which you want to change the commission type.
+3. If you create a new agent, you select the commission type you want form the drop box.
+4. If you edit it from an existing agent, you go to the agent, press the “pencil” drawing  commission field, and select from the dropdown.

docs/usage-guide/appliances.md

@@ -0,0 +1,32 @@
+---
+order: 21
+---
+
+# Appliances
+
+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 here [Register a customer & device](/usage-guide/beforeusing#register-a-customer-device).
+
+## Selling an Appliance
+
+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:
+
+   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.
+
+   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.
+
+Kindly note that appliances can also be sold through the Agent App (see "Android Apps" section for further information).
+
+> [!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).
+
+![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/beforeusing.md

@@ -6,11 +6,20 @@ order: 2
 
 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**.
 
+> [!INFO]
+> MicroPowerManager users cannot create other devices.
+> Each new device (whether a mini-grid pre-paid meter, SHS or e-bike) must be assigned under a pre-defined cluster, mini-grid project and village (i.e. even if a company is only managing 100 SHSs (and no mini-grid customers), a “mini-grid project” must be defined in MPM under which the 100 SHSs are registered.
+> Potential development work would include substituting the term “mini-grid” for “catchment area”.
+
 ## Register a customer & device
 
 **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”.
+**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”.
+
+If user wants to register a new SHS or e-bike device via the website interface, applicable menu section should be clicked (left side bar, click on "Solar Home System" or "e-bike"). Then click on the "+" button at the top right corner of the applicable screen and introduce requested data (device serial number, manufacturer, appliance (device) type.) Kindly check the "Solar Home Systems" and "E-bike" sections of the documentation to see a screenshot of the applicable menus.
 
 ![MPM Architecture](images/mpm-architecture.png)
 
@@ -35,25 +44,3 @@ MPM is designed in a way that the transferred money by the customer will first b
 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:
-
-   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.
-
-   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.
-
-   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).
-
-![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/company-registration.md

@@ -11,10 +11,12 @@ order: 3
 3. Create a password for password protected areas, so that only the team members with knowledge of the password can access sensitive information (Password protected areas are: Tariff-setting, Targets-setting, Overall company Settings, Addition of locations (village, mini-grid, cluster)\*.
 4. Create the locations (under “Settings”) where your systems/devices are to be located (every device must be assigned to a cluster, mini-grid and village).
 5. Register your customers (with applicable device numbers) and assign them appliances (where applicable), as follows:
-   a) To register new mini-grid customers, the Customer Registration App is required. Basic customer data together with the electricity meter serial number are required (kindly see the “Register a customer & device” section for further information.
-   b) To register new Solar-Home System (SHS) customers, e-bike customers or assign/sell new appliances to existing customers, kindly check the “Register a customer & device” section of this User Manual.
+   a) To register new mini-grid customers, the Customer Registration App is required. Basic customer data together with the electricity meter serial number are required (kindly see the “Before Using MPM” section for further information.
+   b) To register new Solar-Home System (SHS) customers, e-bike customers or assign/sell new appliances to existing customers, kindly check the “Before Using MPM” section of this User Manual.
 
-\*Password-setting to protect some sections of your account can only be generated at account setting stage. To change this password ex-post, you will have to contact EnAccess (Enaccess can change the password directly on the database).
+> [!WARNING]
+> Password-setting to protect some sections of your account can only be generated at account setting stage.
+> To change this password ex-post, you will have to contact EnAccess (EnAccess can change the password directly on the database).
 
 ## MPM Software Plug-ins
 
@@ -46,31 +48,7 @@ sequenceDiagram
 In order to use MPM software to manage your customer portfolio, you will have to activate the relevant (manufacturer) plug-ins as well as the relevant telecommunication provider plug-ins.
 For example, if you have Calin pre-paid meters or SunKing Solar Home Systems in your portfolio, you should activate the “Calin” and “SunKing” plug-ins to be able to manage your customers with MPM software. Additionally, if your customers rely on Airtel or Vodacom, you should activate the applicable Airtel or Vodacom plug-ins to enable MPM to generate tokens when receiving mobile money payments.
 
-Currently the following manufacturer plug-ins are available:
-
-- Spark Meter
-- Steama Meter
-- Calin Meter
-- Calin Smart Meter
-- Kelin Meter
-- Stron Meter
-- Microstar Meter
-- Gomelong Meter
-- SunKing Solar Home System (SHS)
-- Angaza Solar Home System (SHS)
-- DalyBms (e-bike)
-
-Currently the following telecommunication provider plug-ins are available:
-
-- Swifta Payment
-- Mesomb Payment
-- Viber Messaging
-- Wave Money Payment
-- Wavecom Payment
-- Airtel Tanzania (plug-in activation requires additional support by EnAccess)
-- Vodacom Tanzania (plug-in activation requires additional support by EnAccess)
-- Airtel Uganda (plug-in activation requires additional support by EnAccess)
-- Vodacom Mozambique (integration currently on-going)
+See [Plugin Overview](/usage-guide/plugin-overview) to have an overview of active and available plug-ins.
 
 Note that the activated plug-ins can be changed/removed/added later on from the website interface (under “Settings”).
 

docs/usage-guide/ebikes.md

@@ -5,3 +5,7 @@ order: 18
 # E-bikes
 
 This is the section listing all e-bike devices registered under your company account. It is the analogous section to the “Meter” and “Solar Home Systems” menus for mini-grid connections and SHS devices, respectively.
+
+E-bike devices can be registered via the Customer Registration App (see "Android Apps" section) or directly through the website interface (Select "E-bike" menu on the left sidebar --> Click "+" --> introduce device data as requested.)
+
+![New E-Bike](images/new-ebike.png)

docs/usage-guide/images/new-ebike.png

@@ -5,3 +5,7 @@ order: 17
 # Solar Home Systems
 
 This is the section listing all SHS devices registered under your company account. It is the analogous section to the “Meter” menu for mini-grid connections.
+
+SHS devices can be registered via the Customer Registration App (see "Android Apps" section) or directly through the website interface (Select "Solar Home System" menu on the left sidebar --> Click "+" --> introduce device data as requested.)
+
+![New SHS](images/new-shs.png)