diff --git a/docs/user_guide/administration/farmer_geolocation.md b/docs/user_guide/administration/farmer_geolocation.md new file mode 100644 index 000000000..63ebc3b5c --- /dev/null +++ b/docs/user_guide/administration/farmer_geolocation.md @@ -0,0 +1,73 @@ +# Integrate geolocation + +This guide provides step-by-step instructions for integrating geolocation platforms such as MapTiler with the OpenSPP Farmer Registry module to enhance area-based functionality. + +## Prerequisites +To enable geolocation integration in OpenSPP, ensure the following: +- Your user account has the System Admin role. Learn more in this guide: {doc}`user_access`. +- Your OpenSPP instance has the Farmer Registry base module installed. Learn more in this guide: {doc}`../../getting_started/farmer_installation`. +- You have an API key for MapTiler to enable GIS functionality. You can retrieve this by checking their documentation [here](https://docs.maptiler.com/cloud/api/). +- Developer mode in OpenSPP is enabled to allow configuration of the MapTiler key. For details, refer to the {doc}`../../developer_guide/developer_mode`. + +## Objective +By the end of this guide, you will have configured MapTiler integration to enable area-based features in the Farmer Registry and will learn how to add, edit, and remove farm geolocation data using the map tools. + +## Process + +### Setting Up the API Key for MapTiler +As a System Admin, log in to your OpenSPP Farmer Registry instance. Go to **Settings**, then select **Technical**, and click **System Parameters**. + +![Settings menu with Technical and System Parameters options](farmer_geolocation/farmer_geolocation_system_parameters.png) + +Click the **New** button. Set the Key field to **spp_base_gis.map_tiler_api_key** and enter your MapTiler API key in the **value** field. + +![Setup farmer registry maptiler key](farmer_geolocation/farmer_geolocation_maptiler_key.png) + +```{note} +Keep your API key secure. Avoid sharing it publicly or storing it in version control systems. +``` + +Click the **Save** button to apply the configuration. Refresh your browser to see the changes. + +### Add Geolocation Data + +After setting up the API key for the geolocation platform, navigate to the Registry and click an existing farm group, then open the **Farm Details** tab. + +![Farm details tab](farmer_geolocation/farmer_geolocation_farm_details.png) + +#### Add Address Coordinates + +Under the **Farm Details** tab, click **Address Coordinates**. + +Click the Marker tool once, then select a location on the map to add a pin for the farm. + +![Marker button](farmer_geolocation/farmer_geolocation_marker_button.png) + +You can also click the **Find My Location** button to center the map on your current location. + +![Find my location button](farmer_geolocation/farmer_geolocation_find_my_location.png) + +#### Add Farm Land + +Under the **Farm Details** tab, click **Farm Land**. + +Click the polygon tool once, then click the map to add vertices until the area is outlined; double-click the final point to close the polygon. + +![polygon tool](farmer_geolocation/farmer_geolocation_polygon_tool.png) + +You can also click the **Find My Location** button to center the map on your current location. + +![Find my location button](farmer_geolocation/farmer_geolocation_find_my_location.png) + +### Remove Geolocation Data + +To remove geolocation data, navigate to the **Farm Details** tab, then open the tab for either **Address Coordinates** or **Farm Land**. + +Click the trash icon to remove the geolocation data. + +![Delete button](farmer_geolocation/farmer_geolocation_delete_button.png) + +```{note} +- The trash icon appears only when there is existing map data. +- Deletion cannot be undone. +``` \ No newline at end of file diff --git a/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_delete_button.png b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_delete_button.png new file mode 100644 index 000000000..0dde215d2 Binary files /dev/null and b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_delete_button.png differ diff --git a/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_farm_details.png b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_farm_details.png new file mode 100644 index 000000000..f83d246db Binary files /dev/null and b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_farm_details.png differ diff --git a/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_find_my_location.png b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_find_my_location.png new file mode 100644 index 000000000..aa1bcd09c Binary files /dev/null and b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_find_my_location.png differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_maptiler_key.png b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_maptiler_key.png similarity index 100% rename from docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_maptiler_key.png rename to docs/user_guide/administration/farmer_geolocation/farmer_geolocation_maptiler_key.png diff --git a/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_marker_button.png b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_marker_button.png new file mode 100644 index 000000000..18ea84c22 Binary files /dev/null and b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_marker_button.png differ diff --git a/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_polygon_tool.png b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_polygon_tool.png new file mode 100644 index 000000000..c1d923188 Binary files /dev/null and b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_polygon_tool.png differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/5.png b/docs/user_guide/administration/farmer_geolocation/farmer_geolocation_system_parameters.png similarity index 100% rename from docs/user_guide/registry_management/setting_up_farmer_registry/5.png rename to docs/user_guide/administration/farmer_geolocation/farmer_geolocation_system_parameters.png diff --git a/docs/user_guide/administration/index.md b/docs/user_guide/administration/index.md index 51c8c79b5..4cc40e3da 100644 --- a/docs/user_guide/administration/index.md +++ b/docs/user_guide/administration/index.md @@ -15,6 +15,8 @@ This section provides guides for a variety of administrative tasks and system ma - {doc}`inventory_configuration`: Learn how to configure the necessary inventory settings to support in-kind and basket entitlements. +- {doc}`farmer_geolocation`: Guide to enabling geolocation integration in the OpenSPP Farmer Registry to improve area-based operations. + - {doc}`incoming_email_configuration`: A guide to setting up automatic email retrieval and processing from a designated incoming mailbox. - {doc}`outgoing_email_configuration`: A guide to setting up outgoing email servers for automated messaging and data integration. @@ -41,6 +43,7 @@ User access Custom fields Indicator fields Import areas +Integrate geolocation Service points Inventory setup Incoming email setup diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 206c8327d..5b42d9a63 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -9,7 +9,6 @@ Guides for managing registrant data and registry operations: - {doc}`registry_management/register_individual` - {doc}`registry_management/import_export_registrant_data` -- {doc}`registry_management/setting_up_farmer_registry` - {doc}`registry_management/identity_management` - {doc}`registry_management/using_change_requests` - {doc}`registry_management/using_event_data` @@ -37,6 +36,7 @@ Administrative tasks and system management: - {doc}`administration/indicator_fields` - {doc}`administration/import_areas` - {doc}`administration/inventory_configuration` +- {doc}`administration/farmer_geolocation` - {doc}`administration/incoming_email_configuration` - {doc}`administration/outgoing_email_configuration` - {doc}`administration/hardware_integration` diff --git a/docs/user_guide/registry_management/index.md b/docs/user_guide/registry_management/index.md index 2cbfb181f..ae1059956 100644 --- a/docs/user_guide/registry_management/index.md +++ b/docs/user_guide/registry_management/index.md @@ -11,8 +11,6 @@ This section provides essential guides for managing the core of OpenSPP: the reg - {doc}`register_individual`: Details the process of manually creating individual and group records and associating individuals as members of a group. -- {doc}`setting_up_farmer_registry`: Instructions for installing and configuring the Farmer Registry module, including the generation of sample farmer data. - - {doc}`using_change_requests`: Explains how to use the Change Request module to update registrant information, including the workflow for initiating, validating, and approving changes. - {doc}`using_event_data`: This guide explains how to use the Event Data feature to record and track significant occurrences related to registrants over time. @@ -24,7 +22,6 @@ This section provides essential guides for managing the core of OpenSPP: the reg Register individuals Import/Export data -Farmer Registry setup Identity management Change requests Event data diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry.md b/docs/user_guide/registry_management/setting_up_farmer_registry.md deleted file mode 100644 index 50c3c0d5c..000000000 --- a/docs/user_guide/registry_management/setting_up_farmer_registry.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -myst: - html_meta: - "title": "Setting up Farmer Registry" - "description": "Step-by-step instructions for installing and configuring the Farmer Registry module in OpenSPP with sample data generation." - "keywords": "OpenSPP, Farmer Registry, module installation, sample data, MapTiler, GIS configuration" ---- - -# Setting up Farmer Registry - -This guide provides step-by-step instructions for installing the Farmer Registry module in OpenSPP and configuring it to generate sample farmer data. -The module extends OpenSPP with features for farmer registration and management. - -## Prerequisites - -To be able to setup farmer registry into your OpenSPP, you need to: - -- Ensure your user account has the **System Admin** role. - Learn more in this guide: {doc}`../administration/user_access` documentation. -- An API Key for MapTiler to enable GIS functionality. - You can retrieve this by checking their documentation [here](https://docs.maptiler.com/cloud/api/). -- Developer mode of OpenSPP should be enabled to set up the MapTiler key. - For details on configuring developer mode, refer to the {doc}`../../developer_guide/developer_mode` - -## Objective - -By the end of this guide, you will be able to set up the farmer registry. - -## Process - -### Installing the Farmer Registry - -Log in to OpenSPP, click on the menu icon, and then click Apps. - -![Setup farmer registry apps icon](setting_up_farmer_registry/setup_farmer_registry_apps_icon.png) - -2. Search for Farmer **Registry: Demo** and click **Activate** to install it. -This will also install the prerequisite modules. - -![Farmer Registry Demo module activation](setting_up_farmer_registry/2.1.png) - -3. Note that after installation, the button **Activate** will disappear. - -![Farmer Registry Demo module activated state](setting_up_farmer_registry/2.2.png) - -### Setting Up the API Key for MapTiler - -1. Go to **Settings**, select **Technical** and click **System Parameters**. - -![Settings menu with Technical and System Parameters options](setting_up_farmer_registry/5.png) - -2. Click the **New** button and set the Key field to **spp_base_gis.map_tiler_api_key** and enter the actual API Key for MapTiler in the **value** field. - -![Setup farmer registry maptiler key](setting_up_farmer_registry/setup_farmer_registry_maptiler_key.png) - -3. Click the **Save** icon. - -### Generating Sample Farmer Data - -1. Navigate to **Registry** from the top toolbar. - -2. Select **Configuration** and click on **Generate Sample Farmer Data**. - -![Registry Configuration menu with Generate Sample Farmer Data option](setting_up_farmer_registry/3.png) - -3. Click **New**. -On the displayed screen, create a label or name for this sample data in the **Name** field and enter the desired number of groups in the field **Number of Groups**. - -![Setup farmer registry define sample data](setting_up_farmer_registry/setup_farmer_registry_define_sample_data.png) - -4. Click the **Generate Sample Data** button located at the top-center of the page. -This will populate the registry with sample farmer data. - -![Setup farmer registry generate button](setting_up_farmer_registry/setup_farmer_registry_generate_button.png) \ No newline at end of file diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/1.png b/docs/user_guide/registry_management/setting_up_farmer_registry/1.png deleted file mode 100644 index 734db39c5..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/1.png and /dev/null differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/2.1.png b/docs/user_guide/registry_management/setting_up_farmer_registry/2.1.png deleted file mode 100644 index b80576391..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/2.1.png and /dev/null differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/2.2.png b/docs/user_guide/registry_management/setting_up_farmer_registry/2.2.png deleted file mode 100644 index d4a83c21f..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/2.2.png and /dev/null differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/3.png b/docs/user_guide/registry_management/setting_up_farmer_registry/3.png deleted file mode 100644 index faab7d497..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/3.png and /dev/null differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/4.png b/docs/user_guide/registry_management/setting_up_farmer_registry/4.png deleted file mode 100644 index f42170e1a..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/4.png and /dev/null differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/6.png b/docs/user_guide/registry_management/setting_up_farmer_registry/6.png deleted file mode 100644 index 9a3c97b1d..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/6.png and /dev/null differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_apps_icon.png b/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_apps_icon.png deleted file mode 100644 index 17d96a904..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_apps_icon.png and /dev/null differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_define_sample_data.png b/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_define_sample_data.png deleted file mode 100644 index 84ba1d118..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_define_sample_data.png and /dev/null differ diff --git a/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_generate_button.png b/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_generate_button.png deleted file mode 100644 index dac94e527..000000000 Binary files a/docs/user_guide/registry_management/setting_up_farmer_registry/setup_farmer_registry_generate_button.png and /dev/null differ