Training Material for UN Open GIS Spiral 1

==Introduction==
The OSGeo UN Committee promotes the development and use of open source software that meets UN needs and supports the aims of the UN. Following a meeting between OSGeo Board of Directors and the UN GIS team at FOSS4G in Seoul, Korea in September 2015, the Committee has mainly worked on the UN Open GIS Initiative, a project “...to identify and develop an Open Source GIS bundle that meets the requirements of UN operations, taking full advantage of the expertise of mission partners including partner nations, technology contributing countries, international organisations, academia, NGOs, private sector. The strategic approach shall be developed with best and shared principles, standards and ownership in a prioritized manner that addresses capability gaps and needs without duplicating efforts of other Member States or entities. The UN Open GIS Initiative strategy shall collaboratively and cooperatively develop, validate, assess, migrate and implement sound technical capabilities with all the appropriate documentation and training that in the end provides a united effort to improve the effectiveness and efficiency of utilizing Open Source GIS around the world.” (more details at [ https://wiki.osgeo.org/wiki/UnitedNations_Committee]).
==Purpose of this document==
This educational material is designed as a step-by-step software learning guide for the users of the UN GeoSHAPE platform for data collection. Geoshape is a free and open source geospatial platform created from various open source projects. You can visit www.geoshape.org for more information. This Quick Start provides a guide on how to 1. Create, edit and share critical data on an integrated dynamic map in near real time. 2. View map updates by users from anywhere in the world and 3. Use GeoSHAPE exchange in connected and disconnected environments.The training material is intended to provide all the materials needed to run a 5 day course on UN GeoSHAPE platform for data collection. The course is structured with content to suit novice, intermediate and advanced users.
==Target Audience==
The primary target audience is, therefore, professionals at local, regional, national or international agencies especially those in developing countries.
== License==
This educational material has been authored by Ketty Adoch under the framework of the UN OSGeo Challenge, with the mentorship of Christina Hupy from Boundless who sponsored the production of this material. The material is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License.
==Module 1: Core Concepts==
*Vector Data: It is the type of map data that is represented as points, lines, polygons on the map. 
*Raster Data: It is any sort of pixel data or digital image where each pixel corresponds to a continuous location or area on the earth’s surface. 
*Coordinate Reference Systems: CRS or SRS (Spatial Reference System) are used to describe real-world positional locations on a map.
*Map projection: Map projection is the systematic transformation (mathematical computation) that can be used to project a point represented as latitude, longitude on the surface of a sphere into locations on a plane.
*Rendering: Rendering to tiles refers to the process of drawing vector or raster data to a png or jpeg which can then be sent to a web or mobile client (web-browser, or mobile app).
*Development: Developers build web applications on top of a web stack which is comprised of an operating system (usually in reference to the server’s operating system), programming language(s) for client and server side code, a database, and a server (such as Apache or IIS). 
*Web stack and Web Applications: The web-client application refers to the main portion of the web application that a user interfaces with from a browser. The client-side portion of the application talks to the server (requests and sends data), performs rendering and any client-side calculations.
==Module 2: Components of GeoSHAPE Exchange for data collection==
GeoSHAPE is the integration of a geospatial portal (GeoNode), a web mapping client (MapLoom), and a mobile application (UN AnyWhere)
*Geonode: GeoNode is the main user facing web application and geospatial portal.
*Maploom: Maploom is the web mapping client which has been embedded in Geonode. Maploom allows you to view, create and edit geospatial features. It also supports connecting to any other server that supports OGC standards: wms, wfs, wcs.
*GeoServer: GeoServer sits behind GeoNode and serves all the vector and raster data. You can directly interact with Geoserver by going to the following endpoint and using the admin credentials used in GeoNode: https://<qualified ip address or domain name>/geoserver
*GeoGig: Geoserver supports numerous datastores one of which is postgres/postgis. During upload, you can choose to upload your layer into a GeoGIG datastore instead of PostGIS. Geogig is a distributed version control system inspired by Git/Github which has been designed for Geospatial vector data.
*UN AnyWhere: UN AnyWhere is an Android mobile application which is designed to work with GeoSHAPE. The GeoSHAPE server can work without being connected to the internet and each mobile device can also work without being connected to the GeoSHAPE server. 
*Tileset: This is a package that contains all tiles (images) for an Area of Interest. For example, if you want to use UN AnyWhere in Yumbe, Uganda, your Area of interest will be the boundaries of Yumbe. The tileset will need to contain every single image at every zoom level. There are typically 18 zoom levels.
Open the Geoshape web page by typing the domain name or ip address in the web browser and login. 
The Sample data that accompanies this resource is freely available and comes from the following sources:
*Water Point data from OpenStreetMap using the Overpass API
 (​http://www.openstreetmap.org/​)
*Administrative boundaries through downloading district boundary, from Data.ug
 (​http://www.data.ug/​)
*The combined sample data is in shapefile format and may be downloaded from here
==Module 3: Using GeoSHAPE Exchange for data collection==
===Lesson 1: Basic User (MapLoom Basic)===
====Create New Map====
1. Click the ‘Map’ tab on the menu bar and select ‘Create Map’ from the drop down menu
====Add different layers for example from your server, other relevant servers or partners====
2. Click the Add Layers (+) button in the Layer’s field.The Add Layers Window will open.You can then search for a layer of interest using the Title of the Layer as a Keyword.
3. Click from the listed records to select the layers of interest. In this example, two layers highlighted with the blue color, are selected.
4. Click ‘Add Layers’ to add the selected layers to the map. Information about the two layers is rendered on the new map.
====Save the New Map with an appropriate name====
5. Click the Save button in the Layers field and Enter an appropriate title and abstract for the New Map then click Save. The title makes your map discoverable when other users search for the map using the title.
====Draw Geometry, Edit attributes of the new feature and Save====
6. In this case, we want to add information to the Water point layer. Click the Zoom In (+) or Zoom Out (-) button on the right hand side of GeoShape Exchange page. We’ll add new water point data and edit attribute information, hence the need to Zoom In (+), such that the point is placed in the ‘right’ location. Click the Add feature button, Click the correct location on the map.
7. Click the Accept feature button and go on to Edit the attributes of the new feature. Or Click the Cancel feature button to remove the added feature.
8. Click the feature to view feature information embedded in a pop up window. Additional options include; Use the feature in a spatial filter, View Table, Show History, Edit Attributes, Edit Geometry and Delete Feature.
====Show/Hide layers====
9.Toggle Visibility function allows you to turn a layer’s display on and off without having to delete the layer from the map. Click the ‘Toggle Visibility’ button to Show or Hide layers.
===Lesson 2: Advanced User===
====Lesson 2.1: Add Layers to GeoSHAPE====
* Click the Data tab on the menu bar and Select Upload Layer menu item
* Browse to the folder on your local machine which has the data you wish to upload
* Select all files or select the zip file
3.Click the choose file(s) button and then select the dataset of interest. In this case, select the drinking_water file and then Click Open.
4. Click the drinking_water.shp file under Manage your data and then Click the Create Layer button at the bottom of the window which pops-up.
5. Manage your data by filling in an appropriate title, a category and description. Click Continue.
6. If your layer has an attribute for time configuration; either start and end time or both and you’d like to enable the playback feature, select Yes. Otherwise, select No.
7. Enabling version control allows you to see the history of changes for a layer and who made them. Select Yes to enable version control. Otherwise select No.
8. Click either the Everyone or Just Me button to determine who is able to view your layer.
9. Review the Configuration and Click the Start Import button to start uploading the layer.
10. If the Import is successful, you’ll see the screen below. You can then view the uploaded layer by clicking the View Layer button.
11. Once you click the View Layer link above, the Layer Information page opens. Here, you can:
*Download the Layer
*View Metadata detail
*Edit Layer
*See the list of maps using the layer
*Create a Map
*See the list of styles associated with this layer
*Change layer permissions
*See the Owner of the layer, the point of contact, the metadata author
12. Additionally, you can:
*View the layer attributes
*Layer Ratings
*Layer Comments
*Layer History in Geogig
===Lesson 2.1.1: MapLoom Advanced===
====Change basemap====
1. The option to change basemap is accessed under the Layers list. Click the Layers list. You can make the prefered basemap visible by clicking the Toggle Visibility button.
2. Click the Toggle Visibility button on the MapBox Satellite layer to change the basemap from OpenStreetMap to MapBox Satellite. You’ll see a new basemap, as shown in the screenshot below.
====Searching====
1. By typing the name of a place of interest in the search bar, you are able to locate the place on a map. For instance, search for a place in Uganda called ‘Yumbe’, by typing the place name in the search bar. Click the Search button in the search bar.
2. The search results will show three different places called Yumbe. Select your prefered place of interest by Clicking one of the places listed in the search results. You’ll notice two yellow points appear on the map.
3. Click one of the yellow points on the map to view more location information like the coordinates, the bounding box. You are also able to pin the the search result in the layer list.
====View the history of a feature/layer====
2.The notifications about a feature can also be viewed when you click the Notifications button.
====Managing Conflicts====
1. Conflicts may arise when the same data is edited by different users. To resolve a conflict, perform a refresh of data snapshot by clicking the refresh icon on the top left hand side of map such that the data in your server is up to date.
===Lesson 2.1.2: Synchronizing with other repos and distributed servers===
There are four ways to synchronize with new data sources; 
*Refresh layers after editing
*Synchronizing to get data from a partner organisation
*Synchronizing from a remote instance
*Merge two repositories
====Refresh layers after editing====
1. To create new features, follow Lesson 1: Draw Geometry, Edit attributes of the new feature and Save 
2. Click the Refresh button to update the layers
====Synchronization from the server of a partner organisation==== 
1. Open the Synchronization options by Clicking the Synchronization button found on the top left hand side of the map. 
2. Click the Add Sync button, the window below will open. Under Name, you can type the link to a different server, or another GeoSHAPE instance of another organisation. Under Repo, specify the user repo, which defaults to the master repo. Under Remote, specify the remote repository, which defaults to the repository from the partner organisation.
3. Click Add, to include these settings in your GeoSHAPE instance.
====Synchronization from a remote instance====
1. A remote instance may be another of the GeoSHAPE instances you use to manage data and operations. Under synchronization, Click the Remote Options button. 
2. The Remote Config window will open. In this window, specify the user/local Repo. Also specify the Remote option. Under Remote Name, type the name of the remote repo and under URL, type the url of the remote repo. Lastly, provide the Username and Password for authentication. Click Save to keep and effect the settings.
====Merge two repos====
1. For scenarios where it is recommended to create a single repo from two repositories, this synchronization option can be employed. Click the Merge' button under the synchronization options. The Merge window will open. Specify the required settings and click Merge'Bold text to effect the buttons.
===Lesson 2.1.3: Creating a Layer in QGIS===
1. To create a layer in QGIS, the following QGIS resource may be used.
===Lesson 2.2: Styling a layer===
====Simple style editor====
1. Click the title of the layer in the layer list to expand the layer options.
2. The Style options will open,and default to the Simple format of styling. In the option below, you are able to;
*Select from the pull down menus under Symbol to change shape, size and color of the symbol
*Select the Attribute you want the symbol to represent
*Choose the Stroke. The stroke allows you to change the outline of the shape to solid, dotted or dashed. Click the color block to choose a new color
*Turn on attribute Label for the layer
*Once you are done making changes, Click the Save Layer Style button to effect the changes
====Unique style editor====
1. Click the arrow to the right of the ‘Simple’ header to go to the Unique format options. In this option, the style editor allows you to;
*Classify the attribute data by Classifying qualitative groups and makes each value it’s own color after you select a Color Palette.
*Under Classification, Select the attribute from the pull down menu whose data will be classified
*Select a Color Palette from the drop down menu 
*Turn on attribute Label for the layer
*Once you are done making changes, Click the Save Layer Style button to effect the changes
===Lesson 2.3: GeoSHAPE functionality(GIS Administrator)===
===Lesson 2.3.1: Managing Users===
====Create user accounts====
1. Depending on how the Exchange instance was configured, you may have to register for an account. If the Register link is not displayed, then you will need to contact the Site Systems Administrator to have an account created.
Once the Systems Administrator creates a new account and sends you log in credentials, then you may fill out the required fields in the window below. Remember to change your password.
====Create / manage groups====
1. Click the About link on the GeoSHAPE Exchange toolbar and Select Groups from the drop down menu. A list of all previously created groups will be displayed.
2. Click the Create a New Group button. Populate the fields with the required information and click Create. 
Note: You’ll notice that by default, the creator of the group is the ‘Group Manager’. Additionally, all the layers and maps created by this user are added to the new group and can be seen by members of the group.
3. Once you open the Group, you’ll notice there are more management options to the right; Click through each link to customize settings for your Group
====Applying permissions to maps and layers====
1. Click the ‘Data’ tab on the menu bar and select ‘Layers’ from the drop down menu. A list of layers will be displayed. 
2. On the left of the page, you’ll notice the ‘Workspace’ options. Identify the layers you’d like to add to the workspace; Click the ‘Add to workspace’ button. 
3. Adding a layer to the workspace, activates the ‘Set Bulk Permissions’ button.
4. Click the ‘Set Bulk Permissions’ button. The window below opens. You can adjust the different permission options for the selected resources; specify which users can view selected resources, specify which groups can view selected resources. 
5. Click ‘Apply Changes’ to save and effect the permissions for the selected resources.
===Lesson 2.4: GeoSHAPE Mobile (UN AnyWhere)===
====Downloading and Installing the apk====
#To install the mobile version of GeoSHAPE also called UN AnyWhere/Arbiter, you download the [apk] and install on your Android mobile device. 
# Find the UN AnyWhere apk file on your device, Click the apk file to install the application.
# Once the installation is complete, UN AnyWhere will appear as an icon on your device’s home screen or app window.
# Click on the icon to launch UN AnyWhere. The page below will open. You can then fill in the login credentials which include the url of your GeoSHAPE instance, the username and password.
Note: Once you’ve downloaded your layers and maps, UN AnyWhere lets you use them offline (no network or wifi connection). When you have connectivity through either 3G or 4G cellular network, or wifi, you can sync your edits with the server and you’ll receive updates made by others as well.
====Navigation====
1. On the initial login, UN AnyWhere attempts to download all of the metadata for all the layers from your the web version of GeoSHAPE Exchange to the mobile application. You’ll see a screen like the one below, showing all the layers retrieved from the web version of your GeoSHAPE Exchange instance.
The main navigational functionality include the following; 
*Map area, where the geographical features are rendered
*Pencil or Add icon, used when placing an element on the map
*Settings button, used to access the project settings. The project settings can be altered to suit your project needs
*Basemap layers icon, used for manipulating basemap layers
*Find Me icon , used for centering the map area to the GPS coordinates of the device
*Zoom-in and Zoom-out controls
Additionally, Click the ‘Settings’ button to access the following functionality, as shown in the image below;
*Enable Mapbox Telemetry
*Access your GeoSHAPE instance on the Web
*View changes and Sync your data to and from the server
*Refresh and download new layers and metadata from your GeoSHAPE instance to your mobile device
*Remove All Data from the device
*Log-out from the mobile application
====Create Project====
1. To create a new project, Click your layer of interest from the listed layers. UN AnyWhere will open the application with a map of the last location you worked on. You can then start adding new data to the layer.
====Switch Basemap====
1. One of the map layers on your selection list is the OpenStreetMap basemap.Other basemap layers include the satellite imagery. You can select between the available base-maps. Both these maps cannot be edited in anyway but serve to provide locational context when collecting data in the field. Click the basemap icon, in order to switch between the Satellite image and OpenStreetMap.
====Select Area of Interest====
1. The Area of Interest (AOI) is the map area you’ll be working on while out in the field. You can either pan the map, Zoom in or out (pinch in or outward with your fingers).
2. If you are satisfied with the chosen AOI, syncing of the existing data then takes place. The result is an up-to-date map tile which you can use to support accurate field data collection.
3. Depending on whether you’ll be on-line or off-line, you’ll need to reconnect to your GeoSHAPE Exchange instance in order to push your field work data to the GeoSHAPE instance.
4. While in the field and online, the selected layers will be styled. for example, the point features may have a blue fill (or a different color) as shown below. If you happen to be working offline, the blue fill for the symbol style will not show.
====Creating Point, Line and Polygon Data====
1. To add a new point feature, Select the layer you’d like to edit from the layer list, then Click the Add icon found in the upper right margin.
2. To place the new point feature, Zoom in to the correct location and Click the location on the map where you want to add the new feature.
3. If you are in the field, it’s advisable to use the GPS fix functionality together with basemap information to inform where to click on the map. However if you are adding new features remotely, then the basemap information will guide you- the GPS fix functionality cannot be used since you are not on the ground.
3. If you are satisfied with the location of the new point feature, Click the Check Mark button
4. The attribute table of the new point feature will appear. Enter the attribute details and then click the Check Mark button found in the upper right corner of the mobile app.
5. Click Save if satisfied with the edits or Cancel if you like to discard the changes.
6. The same procedure above may be followed when Creating a Line or Polygon feature.
Note: If you are in the field and working offline, the newly edited feature will be saved to your mobile device. You’ll have to connect to Wifi, 3G or 4G internet to sync the edits with your qualified GeoSHAPE Exchange instance.
6. To sync all changes, revert to the Layer List view by Clicking the arrow found in the upper left corner of the app window. You should be able to see the status of recently edited layers. A layer whose edits need to be synced with the GeoSHAPE instance has the icon as seen in the image below.
7. To start synchronizing edits with the GeoSHAPE Exchange instance, Click the Settings icon. This will open the Settings option, then Click the View Changes option, followed by Sync All. Then Click OK.
8. You’ll notice that features saved in an offline mode and need to be synced to the qualified GeoSHAPE Exchange instance, will have a different color fill compared to the features which are already synced. For example the screenshot below shows point features with a red and purple fill- the point features with a red fill color have been synced with the GeoSHAPE Exchange instance and exist both on the mobile and web application, while the point features with a purple fill color are saved on the mobile device only and therefore need to be synced with the GeoSHAPE Exchange instance once you have access to internet connectivity.
====Edit geometry for map elements====
1. After saving the new feature and successfully syncing with the GeoSHAPE Exchange instance, the Feature Saved panel appears. Click Done to return to your map display and add another feature.
====Take a photo, associate it with map elements====
Note: In order for the picture/photo functionality to work, a “photos” attribute field should be defined in the layer you’re editing. The camera icon only appears if you have the “photos” attribute field defined.
1. After adding the feature to the map, Add the photo by Clicking the Camera icon found at the bottom of the attribute table. 
2. Take a photo using the camera on your mobile device.
3. Click the Checkmark icon to accept and save the picture.
4. The X icon cancels the picture and returns to the attribute table. The rotate icon removes the picture but returns to the active camera mode so that a new picture can be
taken.
====Do a GPS fix====
1. UN AnyWhere has a functionality for locating your current position using the GPS receiver built into the device. Click the GPS fix icon in the upper right corner.
====Appendix 1: Further learning material====
Note: Much as the links below may be helpful resources with regard to using the software, please note that several functionalities in GeoSHAPE Exchange may have changed since the materials below were developed. 
*[Video: GeoSHAPE Overview]
*[Website: GeoSHAPE Exchange for Data Collection]
*[GeoSHAPE on Github]
*[Geoserver Schema]
*[TileBundler on Github]