The following individuals contributed to the development of this user manual and tutorial:

This chapter provides instructions on deploying GeoPrism Registry to a server.

GeoPrism Registry is configured to use HTTP by default. Any SSL/HTTPS configuration should be done outside of the GeoPrism Registry web container. The recommended way to do this is to use a reverse proxy.

GeoPrism Registry is an online platform aiming at providing the functionalities of a common geo-registry (CGR) for the simultaneous hosting, maintenance, update and sharing of lists as well as associated hierarchies and spatial data for the geographic objects core to development in general and public health in particular.

A CGR provides a container accessible by any information system to obtain reliable information on geography through time. Subsequently, information systems’ users can benefit from this information to improve geographically based decision making and support a more systemic approach to solving developmental problems in general and public health ones in particular.

The CGR concept was born to fill a gap in the information system architecture currently observed in countries, concerning the capability for any piece of information or data to be properly contextualised geographically through time.

While the concept initiated from the health sector, a CGR is designed to manage any type of geographic object and this across multiple organisations, making it a key tool to support the National Spatial Data Infrastructure (NSDI) by allowing for any information system to:

• Contextualize data from different sources in both space and time

• Use geographic objects as the common link between these sources

• Aggregate data according to different hierarchies

• Support the creation of maps based on the same geography

• Facilitate spatio-temporal analyses including but not limited to trend analysis

GeoPrism Registry is certified as a Digital Public Good (DPG) of the DPG Alliance.

Hosted at https://docs.geoprismregistry.com/

The standard hardware for the target machine is an AWS r4.large server (16 GB RAM), as GeoPrism Registry tends to be memory intensive, and 500GB gp2 (general purpose SSD) hard drives.

The software requirements are as follows:

• Docker version 20.0 or greater

• docker-compose version 3

GeoPrism Registry supports the management of lists, spatial data and hierarchies across multiple organizations, so that only those with the responsibility to maintain data for a given organization can do so within that organization only.

Organizations can only be created by users with the System Administrator role.

1. Go to the Settings module.
2. Scroll down to the Organizations section and click on the + icon.
3. Complete the Organization modal that opens up.

   Form field

   Description

   Unique ID

   Unique identifier of the organization.

   Name

   Name of the organization in the default and any installed locales.

   Contact

   Details of the primary contact point of the organization in the default and any installed locales.

4. Click Submit. The organization now appears in the table under the Organizations section in the Settings module.

GeoPrism Registry is certified as a Digital Public Good (DPG) of the DPG Alliance.

The exported localized Excel file contains the following four worksheets:

1. Exceptions: Messages provided to the user in case the action performed by the user was invalid

2. Core Exceptions: Messages provided to the user when reaching an exception core to the platform functionalities

3. UI Text: Terms and sentences used in the user interface

4. Registry Metadata: Terms and sentences related to the Geo-Object Types and hierarchies that have been created in GeoPrism Registry

To add a locale in the exported spreadsheet, for each tab:

1. In the column on the right of the defaultLocale, look for the header generated for the installed locale (e.g., pt_MZ).

2. In this column, add the translation of each term from the defaultLocale column in the corresponding cell. For example:\

The Geoprism Registry is a Java 11 web application built on-top of Tomcat 8.5.

The Geoprism Registry WAR (Web Application Resource) can further be broken down into the following projects:

Each organization in GeoPrism Registry is managed separately by users with a Registry Administrator role for that organization. Users with the System Administrator role can invite users to create an account with a Registry Administrator role for a given organization.

When logged in as a System Administrator:

2. Scroll to the ‘User Accounts’ section and click on the Invite User button.\
3. In the ‘Invite a User’ modal, fill in the email address of the user you want to invite, and check the Registry Administrator role for the relevant organization (for the Ministry of Health in the example presented here):\
4. Click Submit.

5. The invited user receives an email to create a GeoPrism Registry account, and once logged in, this user can access GeoPrism Registry as a Registry Administrator for the relevant organization.

1. Navigate to the Settings page and scroll to the Localization section.\
3. Click Submit.

GeoPrism Registry can be localized to different languages. The default locale of the system is English, however support for other locales can be added. Localization management must be done by a System Administrator.

GeoPrism Registry currently supports the following localization tasks:

• Extending the system to support new locales

• Exporting the localized values of the system to an Excel spreadsheet

• Importing the localized values from an Excel spreadsheet

• Uninstalling locales

You must install all the locales you expect your users to need. Sometimes there are slightly different locales that all need to be included because a browser may have only one version and not the other. As an example, Khmer has two locale versions (kh_KM and kh). Both of these locales must be installed and imported to ensure the Khmer language is shown in all browsers.

1. Navigate to the Settings page and scroll to the 'Localization' section.\
2. Click the + button to open the modal for installing a new locale.\
3. Select the language and country (the list of countries does not relate to the language that has been selected at this stage), and provide a display label for the new locale in the default locale and any existing locales.

4. Click Submit.

The language toggle is used to switch GeoPrism Registry to any locale that is installed.

1. Expand the menu options from the hamburger menu in the top right of GeoPrism Registry.

2. If any additional locale(s) has/have been installed, the option(s) will appear in the dropdown as displayed below. If no additional locales are installed the language toggle will not appear.\
3. Select the locale option you would like to use. The page will refresh and the application will display GeoPrism Registry in that locale (assuming all terms/sentences have been translated for that locale).\

Existing locales can be uninstalled through the Settings module.

1. Navigate to the Settings page and scroll to the Localization section.\
2. Click on the garbage bin icon next to the locale you want to uninstall. A modal appears asking you to confirm whether you want to delete (uninstall) the locale.\
3. Click Delete to confirm and the locale will be uninstalled.

The data coming in and out of a Fast Healthcare Interoperability Resources (FHIR) instance is transformed through the use of the Java Service IOC architecture. A developer can add a new transformation by creating a JAR file that registers its classes as implementations of the FHIR interfaces. The following sections describe a step-by-step process to create a new FHIR implementation in the system.

The logo displayed in the top left of GeoPrism Registry is configurable by a System Administrator.

1. Navigate to the Settings page from the burger menu.\
2. Under the Branding section, click on the edit icon (pencil) for the logo entry.\
3. Drag and drop a file containing the logo into the modal.\
4. Click Upload. The logo will be uploaded and should appear in the upper left corner of GeoPrism Registry.

GeoPrism Registry uses email settings to send email notifications to users of the system, in particular account creation invitations and automated change request notifications. Email configuration must be done by a System Administrator.

GeoPrism Registry is not directly capable of sending emails by itself. It must be connected to a remote email server which is capable of sending those emails on behalf of GeoPrism Registry. These instructions will enable you to configure the connection with that remote email server.

1. Navigate to the Settings page from the burger menu.\
2. Under the Email section, click Configure.\
3. Enter the values in the displayed form.

   Field

   Description

   Server

   The server URL hosting the SMTP system (e.g., email-smtp.us-west-2.amazonaws.com)

   Username

   Username with ability to send emails

   Password

   Password for the user

   Port

   Port used to provide access to the SMTP server. This is configured on the email server, not the GeoPrism Registry server

   From

   An email address used to send emails

   To

   An email address used to receive emails

4. Click Submit

First create a new Maven project and add the georegistry-server as a dependency:

<project
  xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.terraframe</groupId>
  <artifactId>fhir-implementation</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>jar</packaging>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>net.geoprism</groupId>
      <artifactId>georegistry-server</artifactId>
      <version>0.16.1-SNAPSHOT</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.1</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

All GeoPrism Registry text that can be localized is found in the localization spreadsheet. The localization spreadsheet can only be exported by a System Administrator.

1. Navigate to the Settings page and scroll to the 'Localization' section.\
2. Click the Export Localization button to export the localization spreadsheet.

Create the following text files inside the META-INF/services folder of your resources directory:

1. net.geoprism.registry.etl.fhir.FhirDataPopulator

2. net.geoprism.registry.etl.fhir.FhirResourceProcessor

The contents of each text file should be the fully qualified name of the implementation:

com.terraframe.demo.DemoFhirDataPopulator

and

com.terraframe.demo.DemoFhirResourceProcessor

In order to make the implementations available on the server the developer needs to:

1. Build the custom JAR file.

2. Add the JAR file to the classpath of the geo-registry web application (e.g. Tomcat).

3. Restart the web application.

3.8.4.1. XSD definition

<xs:complexType name="dag">
    <xs:attribute name="code" type="xs:string" use="required" />
    <xs:attribute name="label" type="xs:string" use="required" />
    <xs:attribute name="description" type="xs:string" use="optional" />
  </xs:complexType>

Example:

<dag
    code="FLOWS_INTO"
    label="Flows Into (MOH)"
    description=" This DAG links bodies of water which flow into other bodies of water"/>  

GeoPrism Registry supports automatically building Geo-Object Types, Hierarchies, directed acyclic graphs, and undirected graphs using configurations defined in XML. This is useful for quickly setting up a GeoPrism Registry instance.

1. Navigate to the Geo-Objects and Hierarchies module from the burger menu.\
2. Scroll to the bottom of the left sidebar.

3. Click on the Import Types button.\
4. Select the organization the type will belong to and upload the type definition (see type definitions below) to be added to the system.\
5. Click OK.

3.8.3.1. XSD definition

<xs:complexType name="hierarchy">
    <xs:sequence>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="child" type="node" minOccurs="1" />
      </xs:choice>
    </xs:sequence>  
    <xs:attribute name="code" type="xs:string" use="required" />
    <xs:attribute name="label" type="xs:string" use="required" />
    <xs:attribute name="description" type="xs:string" use="optional" />
    <xs:attribute name="progress" type="xs:string" use="optional" />
    <xs:attribute name="acknowledgement" type="xs:string" use="optional" />
    <xs:attribute name="disclaimer" type="xs:string" use="optional" />
    <xs:attribute name="accessConstraints" type="xs:string" use="optional" />
    <xs:attribute name="useConstraints" type="xs:string" use="optional" />
    <xs:attribute name="extends" type="xs:string" use="optional" />
  </xs:complexType>

Example:

<hierarchy
    code="Health_geo"
    label="Health geography hierarchy (MOH)"
    description=" This hierarchy allows to link each health facility with the Shire in which it is located"
    progress="Final"
    disclaimer="This hierarchy is being distributed without warranty of any kind, either expressed or implied. The responsibility for the interpretation and use of the dataset lies with the user. In no event shall the Ministry of Health be liable for damages arising from its use"
    accessConstraints="The access to this hiearchy is limited  to the users of the Common Geo-Registry tool for demonstrations purposes only"
    useConstraints="The use of this hierarchy is limited  to the to the users of the Common Geo-Registry tool for demonstrations purposes only"
    acknowledgement="Please acknowledge the Department of Planning, Ministry of Health of the Middle Earth when using this hierarchy"
    extends="ADM_H">
    <child code="SHR">
      <child code="Health_facility" />
    </child>
  </hierarchy>

3.8.2.1. XSD definition

 <xs:complexType name="type">
    <xs:sequence>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="attributes" type="attributes" minOccurs="0" />
        <xs:element name="group-item" type="group-item" minOccurs="0" maxOccurs="unbounded" />
      </xs:choice>
    </xs:sequence>
    <xs:attribute name="code" type="xs:string" use="required" />
    <xs:attribute name="label" type="xs:string" use="required" />
    <xs:attribute name="description" type="xs:string" use="optional" />
    <xs:attribute name="visibility" type="visibility" use="optional" />
    <xs:attribute name="geometryType" type="geometryType" use="required" />
    <xs:attribute name="isGeometryEditable" type="xs:boolean" />
    <xs:attribute name="isGroup" type="xs:boolean" />
  </xs:complexType>

3.8.2.2. Attribute XSD definition

<!-- Common Attributes of all attributes -->
  <xs:attributeGroup name="attribute">
    <!-- name: The name of the attribute -->
    <xs:attribute name="code" type="xs:string" use="required" />
    <!-- label:The display label of the attribute -->
    <xs:attribute name="label" type="xs:string" />
    <!-- description: A description of the purpose of attribute -->
    <xs:attribute name="description" type="xs:string" />
  </xs:attributeGroup>
  <xs:complexType name="text">
    <xs:attributeGroup ref="attribute" />
  </xs:complexType>
  <xs:complexType name="term">
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
      <xs:element name="option">
        <xs:complexType>
          <xs:attribute name="code" type="xs:string" use="required" />
          <!-- label:The display label of the attribute -->
          <xs:attribute name="label" type="xs:string" />
          <!-- description: A description of the purpose of attribute -->
          <xs:attribute name="description" type="xs:string" />
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attributeGroup ref="attribute" />
  </xs:complexType>
  <xs:complexType name="classification">
    <xs:attributeGroup ref="attributeClassification" />
  </xs:complexType>
  <xs:attributeGroup name="attributeClassification">
    <xs:attributeGroup ref="attribute" />
    <xs:attribute name="root" type="xs:string" use="required" />
    <xs:attribute name="classificationType" type="xs:string" use="required" />
  </xs:attributeGroup>
  <xs:attributeGroup name="attributeDec">
    <xs:attributeGroup ref="attribute" />
    <xs:attribute name="precision" type="xs:integer" />
    <xs:attribute name="scale" type="xs:integer" />
  </xs:attributeGroup>
  <!-- Represents a Boolean object in the database -->
  <xs:complexType name="boolean">
    <xs:attributeGroup ref="attribute" />
  </xs:complexType>
  <!-- Represents a Double object in the database -->
  <xs:complexType name="integer">
    <xs:attributeGroup ref="attribute" />
  </xs:complexType>
  <!-- Represents a Decimal object in the database -->
  <xs:complexType name="decimal">
    <xs:attributeGroup ref="attributeDec" />
  </xs:complexType>
  <!-- Represents a Date object in the database -->
  <xs:complexType name="date">
    <xs:attributeGroup ref="attribute" />
  </xs:complexType>

Example:

<type
    code="Health_facility"
    label="Health facility (MOH)"
    description="Public health facilities under the management of the Ministry of Health"
    visibility="PUBLIC"
    geometryType="POINT"
    isGeometryEditable="true">
    <attributes>
      <term
        code="COOR_ACU"
        label="Coordinates accuracy">
        <option
          code="COA1"
          label="Unknown" />
        <option
          code="COA2"
          label="Low" />
        <option
          code="COA3"
          label="Moderate" />
        <option
          code="COA4"
          label="High" />
      </term>
      <term
        code="SOUR_COOR"
        label="Coordinates source">
        <option
          code="SCO1"
          label="Unknown" />
        <option
          code="SCO2"
          label="Low" />
        <option
          code="SCO3"
          label="MOH (GPS)" />
        <option
          code="COA4"
          label="UN (google Map)" />
      </term>
      <term
        code="HF_OWN"
        label="Health facility Ownership">
        <option
          code="HFO1"
          label="Unknown" />
        <option
          code="HFO2"
          label="Government" />
        <option
          code="HFO3"
          label="Private" />
      </term>
      <text
        code="HD_NA_EN"
        label="Health facility head name"
        description="Full name of the health facility head in English" />
      <text
        code="HD_PS_EN"
        label="Health facility head position"
        description="Position of the health facility head in English" />
      <text
        code="D_NBR_G"
        label="Health facility phone number"
        description="General phone number of the health facility" />
      <term
        code="HF_T"
        label="Health facility type">
        <option
          code="HFT1"
          label="Unknown" />
        <option
          code="HFT2"
          label="National Hospital" />
        <option
          code="HFT3"
          label="Referral Hospital" />
        <option
          code="HFT4"
          label="Health Centre" />
        <option
          code="HFT5"
          label="Health Post" />
      </term>
      <text
        code="HF_OWN_G"
        label="Name governmental agency (ownership)"
        description="Name of the governmental agency managing the health facility" />
    </attributes>
    <group-item
      code="Referral_hospital"
      label="Referral Hospital (MOH)"
      description="Health facility were general care diagnostic services, limited surgical procedure and access to specialist consultation for patients referred from health centers are being provided" />
    <group-item
      code="National_hospital"
      label="National Hospital (MOH)"
      description="Health facility providing the same services as a referral hospital as well as a range of more highly specialized services" />
    <group-item
      code="Health_post"
      label="Health Post (MOH)"
      description="Health facility were only primary health care are being provided" />
    <group-item
      code="Health_centre"
      label="Health Centre (MOH)"
      description="Health facility were enhanced level of care is being provided" />
  </type>

3.8.5.1. XSD definition

<xs:complexType name="undirected-graph">
    <xs:attribute name="code" type="xs:string" use="required" />
    <xs:attribute name="label" type="xs:string" use="required" />
    <xs:attribute name="description" type="xs:string" use="optional" />
  </xs:complexType>

Example:

<undirected-graph
    code="ADJECENT_TO"
    label="Adjecent To (MOH)"
    description="Links locations which are adjecent to each other"/>  

Some example files can be accessed here:

DHIS2 must be configured to allow GeoPrism Registry to connect to it. This is accomplished using DHIS2’s 'OAuth2 Clients' configuration. This can be found in the DHIS2 'System Settings' app. Clicking the blue + button on the right allows us to create a new OAuth client.

To configure the OAuth client, fill in the following:

• Name: georegistry

• Client ID: georegistry

• Client Secret: <already pre-filled>

• Grant Types:

  • Password: unchecked

  • Refresh token: unchecked

  • Authorization code: checked

• Redirect URIS (if your GeoPrism Registry instance is not using HTTPS, you should use HTTP here instead):

  • If your CGR server is of version 1.0, this URL looks like:

    https://<GeoPrism Registry instance URL>/cgrsession/ologin

  • If your CGR server is of version 1.1, this URL looks like: https://<GeoPrism Registry instance URL>/api/cgrsession/ologin

  • If your CGR server is of version 1.2+, this URL looks like: https://<GeoPrism Registry instance URL>/api/session/ologin

Take note of the Client Secret which is generated here. We will need it when configuring GeoPrism Registry External Systems with OAuth.

Click save to create the new OAuth2 client in DHIS2.

Although we try our best to automatically migrate your server when upgrading versions, there are times when this is simply not possible. In this section we will attempt to cover some of the most common migrations you might encounter when running our software yourself via a Docker container.

The general steps for performing any sort of migration can be broken down as follows:

1. Create a clone environment of your production server where we will test these steps

2. Perform all required steps as outlined in the "Orient DB Migration" and/or "PostgreSQL Migration" sections below on the cloned environment, keeping track of the exact commands relevant for your environment and making note of any issues or cavaets.

3. Set your docker-compose.yml file (in the test environment) to the new GeoPrism Registry / Postgres / OrientDB versions and run docker compose down then docker compose pull. Then do a docker compose up. When the GeoPrism Registry boots, it will automatically run any additional patches or migration scripts as necessary. Be patient as this step can take time.

4. Check the logs for any errors and make sure the test server is operational and responding.

5. Allocate a "downtime window" for your server so as to disturb users as little as possible

6. Perform a snapshot / backup of your production server

7. Stop the webserver with docker stop georegistry

8. Perform the steps exactly as they were performed on the test environment, except this time on the live production environment

Orient DB Migration

If a newer version of the GeoPrism Registry requires a major upgrade of your Orient DB software, a manual data migration must be performed.

The official OrientDB migration documentation can be found here:

Since the official OrientDB migration documentation can be either confusing, lacking in detail, or simply not targeted towards the way we use their software, we will walk you through the detailed steps here.

1. Stop the webserver with docker stop georegistry

2. Create a database dump of the Orient DB server. This command includes variables (starting with $) which must be replaced before running. docker exec georegistry-orientdb bash -c 'bin/console.sh "connect remote:localhost/georegistry $ORIENTDB_ROOT_USER $ORIENTDB_ROOT_PASS; export database /orientdb/backup/$ORIENTDB_MAJOR_VERSION.json"'

   1. The default orientdb root username is 'root'

   2. The default orientdb root password is 'root'

   3. The OrientDB major version should not include the fix version. For example, '3.2'.

3. Kill the Orient DB server docker rm -f georegistry-orientdb

4. Remove all data inside the mounted volume rm -rf data/orientdb/databases/*

5. Run Orient DB of the new version. This command includes variables (starting with $) which must be replaced before running. docker run --name georegistry-orientdb2 -e ORIENTDB_ROOT_PASSWORD="$ORIENTDB_ROOT_PASS" -e ORIENTDB_OPTS_MEMORY="-Xms512M -Xmx2G" -d -v /data/orientdb/databases:/orientdb/databases -v /data/orientdb/backup:/orientdb/backup orientdb:$ORIENTDB_MAJOR_VERSION

6. Import the backup into the new Orient DB. This command includes variables (starting with $) which must be replaced before running. docker exec georegistry-orientdb2 bash -c 'bin/console.sh "CREATE DATABASE remote:localhost/georegistry $ORIENTDB_ROOT_USER $ORIENTDB_ROOT_PASS; connect remote:localhost/georegistry $ORIENTDB_ROOT_USER $ORIENTDB_ROOT_PASS; import database /orientdb/backup/$ORIENTDB_MAJOR_VERSION.json.gz"'

7. Kill the temporary Orient DB server docker rm -f georegistry-orientdb2

PostgreSQL Migration

Upgrading PostgreSQL is fairly straightforward and reliable.

The official PostgreSQL migration documenation can be found here:

The basic steps for performing an upgrade on our default docker compose environment are as follows:

1. Stop the webserver with docker stop georegistry

2. Run a new Postgres of the new version. This command includes variables (starting with $) which must be replaced before running. docker run --name georegistry-postgres2 -d -p 5482:5432 --network $CGR_DOCKER_NETWORK --link georegistry-postgres -v /data/postgres-migrate:/var/lib/postgresql/data -e POSTGRES_PASSWORD=$POSTGRES_ROOT_PASSWORD postgis/postgis:$NEW_POSTGRES_VERSION

   1. The default postgres root username is postgres.

   2. The default postgres root password is georegistry.

   3. The NEW_POSTGRES_VERSION variable is a Docker image tag and should also include a PostGIS version. For example, '14-3.2'.

   4. The value for the CGR_DOCKER_NETWORK variable can be found by running docker inspect georegistry-postgres. The georegistry network name is autogenerated and will be listed in the "Networks" section of the inspect output.

3. Restore old Postgres into new Postgres. This command includes variables (starting with $) which must be replaced before running. docker exec -t georegistry-postgres2 bash -c "(PGPASSWORD=$POSTGRES_ROOT_PASSWORD pg_dumpall --host georegistry-postgres --port 5432 --username postgres --no-password && echo -e \"\n\nALTER ROLE postgres PASSWORD '$POSTGRES_ROOT_PASSWORD';\" && echo -e \"\n\nALTER ROLE georegistry PASSWORD '$POSTGRES_APP_PASSWORD';\") | psql -d postgres --host 127.0.0.1 --port 5432 --username postgres --no-password"

   1. The default Postgres app password is georegistry.

4. Delete temporary Postgres containers docker rm -f georegistry-postgres && docker rm -f georegistry-postgres2

5. Delete the old Postgres data directory rm -rf /data/postgres

6. Copy the postgres data from the new version to the standard directory mv /data/postgres-migrate /data/postgres

Registering an external system allows to specify a persistent configuration for integrating with external systems. The external system registration is where synchronizations can be triggered (DHIS2 and FHIR only), modified, and generally referenced to understand how the integration is defined. Its primary function is for GeoPrism Registry to share its content with an external system. By storing both a standard GeoPrism Registry identifier and external system identifier, GeoPrism Registry can maintain a mapping between object instances in the two systems. The external identifiers are set in the system through the data import process.

Registering an external system can only be done by a Registry Administrator or System Administrator. If a Registry Administrator creates the external system it will only be available to the organization that Registry Administrator is a member of. A System Administrator must assign the external system to an organization.

Setting up an external system synchronization enables a user to push data to that external system. Synchronization configurations require an external system to be registered and the external identifiers to be set through the data import process.

GeoPrism Registry currently supports integrations with the following systems:

The following sections provide more details on synchronizing with each system.

4.2.1.1. Registration

The process for registering a DHIS2 instance in GeoPrism Registry is as follows:

1. Navigate to the Settings page using the burger menu.\
2. Scroll down to the 'External Systems' section and click on the + button to open the Registration modal.\
3. Select DHIS2 from the Type dropdown and fill out the other fields (details on each field are provided in the table below).\

4.2.1.2. Enable OAuth

1. At the bottom of the External System modal, you will see a section for OAuth. Click the Enable OAuth Integration button.\
2. A form for configuring the OAuth integration will expand. Client ID, Profile Location, Token Location and Authorization Location should be filled out automatically. It is not recommended to change these values.\
3. Enter the Secret Key from the DHIS2 OAuth Client in the OAuth Secret Key field. You will need to get this from the DHIS2 instance.\
4. Click Submit.

4.2.1.3. Compatibility

Some GeoPrism Registry features may not work with some versions of DHIS2.

The following table lists the OAuth integration possibilities for each DHIS2 version, as tested by TerraFrame.

4.2.1.4. Import

If Geo-Object data is already present as organization units in a DHIS2 instance, it must first be imported using the Import from an external system option in the Import module.

4.2.1.5. Synchronization

GeoPrism Registry supports using a DHIS2 external system synchronization to push data to a DHIS2 instance. The purpose of the external system synchronization is to define how Geo-Object Types in a specific hierarchy will map to organization units in a DHIS2 instance. The latest version of the Geo-Objects will be synchronized with DHIS2, as GeoPrism Registry currently does not support exporting at a specific date.

The following steps are to be followed to enable the synchronization:

1. Navigate to the Settings page.\
2. Find the External System Synchronizations section and click on the Register Synchronization button.\
3. Click the Create button on the Synchronization Configurations page.\
4. Fill out the fields in the Synchronization Configuration modal and click Submit.\

4.2.1.6. Matching organization units

The Org Units section of the configuration modal allows you to map each organization unit level in DHIS2 to a Geo-Object Type in GeoPrism Registry. There is no limit to the number of levels that can be matched, however no more levels should be matched than exist in the DHIS2 instance being synchronized with. Additionally, the matched Geo-Object Type of each level should be a direct child of the level before it.

The Geo-Objects in GeoPrism Registry are matched to their DHIS2 counterparts using the external identifiers of the GeoPrism Registry Geo-Objects and the identifiers of the organization units in DHIS2. It is important to note that this matching does not use the Code properties from either system. If a Geo-Object does not have an external identifier, then it will be considered new and will be created as a new organization unit in DHIS2 if the synchronization type is set to ‘Org Units and Relationships’. GeoPrism Registry will then save the external identifier of that new organization unit in the database to be used for future updates. If the Geo-Object has an external identifier while DHIS2 does not have an organization unit with a matching identifier in their system, an error will be shown.

The DHIS2 Synchronization Type specifies what data will be synchronized to DHIS2.

4.2.1.7. Matching organization unit groups

Geo-Object Types (levels) can be matched to an organization unit group, so that only selected organization units within that group are synchronized. The ‘Org Unit Group’ dropdown lists all organization unit groups which currently exist in the DHIS2 instance. When a Geo-Object Type is matched to a group, all Geo-Objects that are of that Geo-Object Type will be assigned to the selected organization unit group the next time the system synchronizes with this configuration.

This behavior operates in an additive fashion only. Any organization units which are already assigned to the organization unit group will not be affected.

4.2.1.8. Custom attribute matching

If a Geo-Object Type is matched which contains custom attributes, the custom attribute matcher will be displayed.

This attribute matching is specific to a Geo-Object Type and level. In order for a DHIS2 attribute to be a valid selection for the matching, it must be applied to organization units, and it must be close enough in Type to be a candidate. Here are the appropriate selection types:

The following DHIS2 value types cannot be mapped to attributes in GeoPrism Registry:

• Tracker Associate

• Coordinate

• Organization Unit

• File Resource

• Image

If an attribute in GeoPrism Registry is not matched to one in DHIS2 (either because there were no valid selections, or the dropdown was intentionally left as ‘not matched’), then the data in that attribute will not be synchronized with DHIS2. It will not, however, prevent the rest of the attributes or relationships from being synchronized.

4.2.1.9. Term matching

A. Option sets

GeoPrism Registry Term-type attributes can be matched to DHIS2 option sets. When the Target Type is set to ‘Option Set’, the Target Attribute dropdown will populate with all DHIS2 attributes which contain an option set and are assigned to organization units. When a GeoPrism Registry Term-type attribute is matched to a valid option set in the DHIS2, then the user interface expands to allow matching between GeoPrism Registry terms and DHIS2 options.

If a Geo-Object does not have values for the Term-type attribute, then the attribute will not be set on the DHIS2 organization unit. Geo-Objects with terms which have not been matched (‘Not Mapped’) will not be exported and an error will occur.

B. Organization unit groups

Terms can also be mapped instead to organization unit groups. This can be done by selecting ‘Org Unit Group’ in the Target Type dropdown.

Geo-Objects will be assigned to the organization unit group as matched in the above screenshot. This provides some basic support for organization unit group synchronization.

Similar to option set matching, if a Geo-Object does not have a value for the Term-type attribute, then it will not be assigned to an organization unit group. Geo-Objects with terms which have not been matched (‘Not Mapped’) will not be exported and an error will occur.

This behavior operates in an additive fashion only. Any organization units which are already assigned to the organization unit group will not be affected.

If a level is matched to a DHIS2 organization unit group, and the Geo-Object Type also contains a term which is matched to DHIS2 organization unit groups, then the synchronized organization unit will be added to all organization unit groups which have been matched (in an additive fashion).

4.2.1.10. DHIS2 to GeoPrism Registry plugin

GeoPrism Registry provides a plugin which can be downloaded and installed onto a DHIS2 instance. When installed onto DHIS2, this plugin behaves as a standard DHIS2 app, which will redirect to the GeoPrism Registry instance configured in the external system.

To download the DHIS2 to GeoPrism Registry plugin:

1. Navigate to an existing DHIS2 external system configuration form from the GeoPrism Registry Settings page.

2. Click the Download DHIS2 Plugin button, which will download a zip file called “cgr-dhis2-app.zip” to your computer.\
4. Successful installation will display the link to GeoPrism Registry in DHIS2.

This section covers the key components of GeoPrism Registry.

Geographic features are features of the Earth, natural (e.g., rivers) or artificial (e.g., buildings), physical (e.g., roads) or abstract (e.g., administrative division). Each sector has its own set of geographic features that are core to the implementation of its programs and activities. Those core to the health sector, for example, include but are not limited to: health facilities, vaccination points, settlements, ambulances, patients, roads and administrative divisions.

GeoPrism Registry does nevertheless only handle geographic features for which it makes sense to establish and maintain a master list. These include fixed features such as health facilities, schools, bridges, or villages; artificially-created features such as administrative units, foci or health areas; or mobile features such as vehicles or individuals. A master list for other geographic features would either not be necessary (e.g., roads, rivers)* or not applicable (e.g., continuous features like topography or population distribution). A geographic object, or Geo-Object, is itself the computer representation of a geographic feature. It can be represented as a point, line, or polygon on a map (more details on this in the next section).

*GeoPrism Registry does nevertheless provide the possibility to handle geographic objects represented by lines and can handle roads and rivers should master lists exist for them.

GeoPrism Registry supports integrating with external systems to help facilitate the exchange of data between systems. Registering an external system enables GeoPrism Registry to send data to an external system instance in a predictable way. This is useful to ensure that data in another system is using updated data from the curated data in GeoPrism Registry.

GeoPrism Registry is being used to simultaneously host, maintain, update and share lists as well as associated hierarchies and spatial data for the geographic objects core to development in general and public health in particular.

The following sections describe in more detail these different elements, as well as those associated with them (geographic features, geographic object types, data elements, classification tables).

4.2.2.1. Registration

The following steps describe how to register a Reveal external system. A Reveal external system enables the ability to import Geo-Object data with identifiers from a Reveal system and to read data using the REST API that includes the Reveal external identifiers:

1. Navigate to the Settings page.

2. Find the External Systems section and click the + button to open the Registration modal.\
3. Select 'Reveal' from the Type dropdown and fill out the modal fields.\

4.2.2.2. Import

4.2.2.3. Synchronization

The Reveal external system registration enables the GeoPrism Registry REST API to be used to query Geo-Objects with Reveal identifiers in a Reveal format. Reveal external systems do not have a configurable interface for pushing data like DHIS2 systems, but automated synchronizations could be made with external programs that utilize the GeoPrism Registry REST API.

4.2.3.1. Registration

The process for registering a FHIR instance in GeoPrism Registry is as follows:

1. Navigate to the Settings page using the burger menu.\
2. Scroll down to the External Systems section and click on the + button to open the Registration modal.\
3. Select 'FHIR' from the Type dropdown and fill out the other fields (descriptions in the table below).\

   Field name

   Description

   Required?

   Type

   The type of external system.

   Yes

   Organization

   The organization the user belongs to. An external system will only be available to data and users within this organization.

   Yes

   ID

   The identifier for this external system.

   Yes

   Label

   The label of the external system.

   Yes

   Description

   A description of the external system.

   No

   URL

   The URL for the FHIR system.

   Yes

   System

   The FHIR system to use when exporting or importing

   Yes

4.2.3.2. Compatibility

4.2.3.3. Synchronization

External system synchronizations enable the ability to push and pull data between a GeoPrism Registry instance and a FHIR instance.

A. Pushing data to FHIR instance from a GeoPrism Registry instance

1. Navigate to the Settings page.

2. Find the External System Synchronizations section and click the + button to register synchronizations.

3. Click the create button on the Synchronization Configurations page.\
4. Fill out the modal fields being sure to select Export for the Synchronization Type.\

   Field

   Description

   Label

   Label of the synchronization configuration.

   Organization

   The organization the synchronization configuration will be available to.

   Hierarchy

   The hierarchy this synchronization will use to push data to an external system.

   External System

   The registered external system that this synchronization will use to push data to an external system.

   Org Units

   A mapping between the Geo-Object Types in the selected GPR hierarchy and the types in the DHIS2 instance.

5. Click Submit.

B. Pulling data from a FHIR instance to a GeoPrism Registry instance

1. Navigate to the Settings page.

2. Find the External System Synchronizations section and click the + button to register synchronizations.

3. Click the Create button on the Synchronization Configurations page.\
4. Fill out the modal fields being sure to select 'Import' for the Synchronization Type.\

   Field

   Description

   Label

   Label of the synchronization configuration.

   Yes

   Organization

   The organization the synchronization configuration will be available to.

   Yes

   External System

   The registered external system that this synchronization will use to push data to an external system.

   Yes

   Synchronization

   Export data to the FHIR instance or Import data to the GeoPrism Registry instance.

   Yes

   Type

   The GeoPrism Registry instance.

   Yes

   Implementation

   The custom implementation of a HAPI FHIR synchronization configuration.

   Yes
5. Click Submit.

C. Run a synchronization

1. Navigate to the Setting page.

2. Find the External System Synchronizations section and scroll to an existing configuration.

3. Click on the View button of the FHIR configuration.

4. Click the view button on the FHIR configuration row.
5. On the synchronization page click the “Run now“ button to queue a new synchronization job. The results of the job will appear in the “Jobs“ section lower on the page. The user can also click on “Generate Bundle“ to generate a JSON bundle of the data which would be exported.

\

Also referred to as spatial data, geospatial data corresponds to information about the locations and shapes of geographic features and the relationships between them, usually stored as coordinates and topology (e.g., geographic location of health facilities, boundaries of administrative units…).

As GeoPrism Registry only handles types of geographic objects that can be managed in a list, it stores these in vector format geographic information system (GIS) layers. Raster format GIS layers cannot be uploaded to the platform.

GeoPrism Registry is able to handle the three modes of representation of geographic features in the vector format: points, lines, or polygons (Figure 5.3).

The types of geographic objects (a.k.a. Geo-Object Types) handled by GeoPrism Registry can be categorized based on how they would be represented on a map:

• Fixed geographic objects that can be simplified by a point, for example: household, health facility, human settlement

• Fixed geographic objects that should be represented by polygons due to their much larger extent, for examples: administrative units, health districts, or by a line due to their shape, for example: road, river

• Mobile geographic objects, for example: individuals, patients, vehicles; the geography of these objects would either be obtained by considering them attached to a fixed geographic object or by simplifying them as a point that would be located through their geographic coordinates (latitude and longitude) taken at a given point in time.

In GeoPrism Registry, these can be further aggregated into groups of geographic object types having the same attribute configuration (e.g., health facilities as a Geo-Object Type group could group health posts, health centers, and hospitals).

The content hosted in GeoPrism Registry is meant to serve as the source of truth (ground reference) for any information system to properly contextualize, visualize, and analyze business data in both space and time. As such, this content is meant to present the highest level of quality possible across the six dimensions of data quality (uniqueness, completeness, timeliness, accuracy, validity, and consistency).

While GeoPrism Registry is meant to help improve and maintain the quality of this content across these dimensions, the higher the quality of this content at the time of uploading it in the platform, the lesser the work afterwards and the faster positive impacts can be seen.

The quality of the content before its upload in the platform can be ensured through the implementation of good data management practices throughout the overall geospatial data management cycle in Figure 5.4. The implementation of this cycle, and associated good practices, should ideally take place as part of the activities of the National Spatial Data Infrastructure (NSDI).

A list is a tabular representation of the data elements associated with all the active, and past active, geographic objects (records) of a given type at a given point in time.

Lists represent the most familiar way for users to look at the information associated with any type of geographic object. When they are authoritative and curated by the mandated governmental entity, these lists, referred as master lists in this case, also serve as a ground reference to assess the completeness, uniqueness, timeliness, validity, and consistency of the geospatial data also hosted in a common geo-registry, as well as a denominator for the implementation of any public health program.

For example:

Knowing how geographic objects relate to each other over time as part of different hierarchies is important not only to be able to aggregate information to support decision making, when applicable, but also to ensure relational consistency between geographic objects.

One of the functions of GeoPrism Registry is to capture and use not only geographic relationships that exist between geographic objects (is within, lives in) but also other types of relationships such as administrative (is reporting to), health-related (covers, providing service to, refers to), and associative (is part of).

These different relationships can be represented in distinct hierarchies like those included in Figure 5.1.

GeoPrism Registry focuses on all the information that allows to contextualize any piece of information in both space and time. It therefore only handles data elements meant to:

1. Uniquely identify,

2. Classify,

3. Locate, and

4. When applicable, contact

Other types of data elements, including programmatic ones (e.g., statistics), are not meant to be managed in GeoPrism Registry but in program-, or even sector-, specific information systems. Some of the reasons behind this are the sensitivities often linked to programmatic data, the difference in data flow between this type of data and the geographic objects they are attached to, as well as the difference in the management of the time dimension (e.g., the temporal validity of a statistic might be different from the temporal validity of the geographic object it is attached to). In addition, managing these data elements in these other systems allows the programs to benefit from functionalities that are not available within a registry, including, but not limited to, data collection, statistical analysis, or visualization (graphs, thematic maps).

• The data element code as implemented in GeoPrism Registry

• A short description of the data element

• The data element type

• The size of the data element (number of storage units)

• Whether the data element is considered as mandatory when adding a new record in the master list

Examples, notes, and, when applicable, the source (reference) of each data element can be added to the above information if it can help those in charge of managing GeoPrism Registry content and its users to have a clear understanding of each of these data elements. A classification table also needs to be defined for each of the data elements where the values are limited to a few options to ensure consistency across records, for example, type, ownership, etc. Such tables should at least contain the following for each option: a unique code, a label (English and local language) and/or acronym, a description (English and local language), and, when applicable, the source of the definition. The following table provides an example of a classification table for health facility types in Cambodia following this structure:

Geography evolves over time, for example the creation of a new district, the closing of a health facility, or a change of phone number for a community health worker. This is why a core function of GeoPrism Registry is to be able to capture the changes occurring over time for the geographic objects it hosts as well as to conserve the information as it was before the change and, when applicable, the information necessary to reconstruct that change (e.g., the unique identifier and name of the district from which a new district has been carved). This information is critical to perform trend analyses, especially in countries where the administrative structure changes frequently (e.g., to reconstruct disease prevalence trends across districts that have changed over time).

This capability of GeoPrism Registry allows for the retrieval of the lists and associated geospatial data for any geographic object at any point in time, over the entire period for which data has been uploaded in the platform.

The three main types of changes that can be captured in GeoPrism Registry for any given geographic object are as follows:

Figure 5.5 provides an illustration of these main types of changes for a health facility that opened on April 19, 1984, and closed definitively on April 1, 2021. Over that period, the health facility’s name, head, and phone number each changed once at different points in time.

For this kind of change, GeoPrism Registry has the capacity to:

• Set the period of existence of the geographic object (1984-04-19 to 2021-04-01)

• Capture and retain the value for each instance of the data elements that have changed through time, together with the period over which each value has been valid (e.g., Patrick Dupont over the 1984-04-19 to 2008-06-06 period and then Henri Dunant over the 2008-06-06 to 2021-04-01 period as the health facility head).

Capturing the above information is sufficient to understand changes occurring to any independently created geographic objects, i.e., geographic objects that are not being created out of already existing ones (e.g., infrastructures such as health facilities or schools as opposed to a district splitting into two).

The situation is different when looking at changes occurring through time for geographic objects that are being carved out from existing ones. For example, this occurs when boundaries change (e.g., split or merge) across administrative, health, statistical, or electoral units covering the entire territory of a given country.

When this is the case, capturing the period over which each unit has been in existence is not sufficient to rebuild these changes. To illustrate this, Figure 5.6 captures the changes over time for part of the districts of Uganda over the January 1, 1990, to June 30, 2005, period.

While the district of Soroti, for example, has been in existence over the complete period reported in Figure 5.6, its geographic extent has significantly changed twice over that same period. In this case, a common geo-registry should be able to capture the period of existence of the district of Soroti, as well as information on the two changes, including which instances (single occurrence) of the Soroti district the districts of Katakwi and Kaberamaido have been carved, in March 1997 and July 2007, respectively.

For such cases, GeoPrism Registry has the capacity to capture:

• The date of the change

• The type of change (split, merge, transfer, upgrade, downgrade)

• The type of geographic object before and after the change (same type in the case of a split, merge, or transfer or different type in the case of an upgrade or downgrade)

• The unique identifier and name of the geographic object before and after the change

• Notes allowing to understand and/or track the change (e.g., the legal document in which the change is recorded)

The primary objective of a common geo-registry is to share the authoritative data coming from the governmental entity having the official curation mandate over it. This is what is being referred to as the master data and information.

While this is the type of data and information that should be hosted as a priority GeoPrism Registry to serve as the source of truth, it is possible that either the master data/information is not available, not of quality (incomplete, out of date…), and/or not accessible.

In these cases, and to ensure the continuity of operations, GeoPrism Registry can host, manage, and share 'non-master' data/information in parallel or complementary to the master data/information (note that both types should be clearly differentiated), as well as facilitate the convergence of the two lists once the master version is available, of quality, and/or accessible.

Documenting the content of GeoPrism Registry in a way that informs the users if such content corresponds to their needs is key to the proper use of this content.

At this stage, GeoPrism Registry allows the authorized user to fill, manage and share a metadata profile for the following key elements managed in the platform:

• Organization

• User Geo-Object types and groups

• Hierarchies

• Lists

• Spatial data

Critical to data interoperability is the ability to uniquely, and therefore unequivocally, identify each of the geographic objects in GeoPrism Registry and ensure that this unique identifier is used across information systems. Therefore, it may be beneficial to use geography as a neutral platform for the integration of information and data coming from different sources.

While the selection of the appropriate coding scheme associated with each type of geographic object is not a functionality of the platform, GeoPrism Registry has the capacity to capture and maintain such a scheme.

The choice of an appropriate coding scheme to be associated with each type of geographic object is therefore critical, as modifying the scheme once implemented in different systems can not only be costly but also have a significant impact on data compatibility as well as on the trust in the common geo-registry's content.

The full value of a common geo-registry is expressed once its content is accessible to the largest number of users possible.

That said, it is possible that not all content can be made publicly accessible, at least not in the first instance, i.e., appropriate government approvals might be required, a certain level of quality needs to be reached, and/or the necessary policy and legal framework would need to be in place.

GeoPrism Registry currently provides two levels of access (referred to as visibility in the platform) for the Geo-Object Types, lists and spatial data it contains :

• Public: the item is accessible to any user from within the platform and to external users through an API

• Private: the item is only accessible to the organization having the curation mandate over it

Having these levels of accessibility for the content allows the platform to respect the current accessibility policy that each organization might want to apply to the content they are hosting in the platform while still benefiting from the functionalities it provides, but also to change such a level as the data sharing policy associated with this content evolves.

The following roles are currently implemented in GeoPrism Registry:

• System Administrator (SA): a user who is part of the GeoPrism Registry cross-sectoral governance structure, with the ability to configure the platform, manage organizations and Registry Administrators' user accounts, and view the public data across organizations.

• Registry Administrator (RA): a user attached to a given organization, who has all the privileges of a Registry Maintainer plus the ability to define user roles, create Geo-Object Types and hierarchies, and consult all the data under the mandate of their organization.

• Registry Maintainer (RM): a user attached to a given organization, who has all the privileges of a Registry Contributor plus the ability to edit the content for specific Geo-Object Types under the curation mandate of their organization.

• Registry Contributor (RC): a user attached to a given organization, who has the ability to consult content for specific Geo-Object Types under the curation mandate of their organization, and submit change requests for these.

There is no anonymous user available. Any GeoPrism Registry deployment is able to use the API to create an interface that provides access to all the public data stored on the platform.

This section describes ther roles currently implemented in GeoPrism Registry and the rights each of these roles has.

The legend for the numbers listed next to each role in Tables 5.1 and 5.2 is as follows:

1. For all organizations

2. For their organization, for all Geo-Object Types

3. For their organization, for Geo-Object Types over which the user has a curation mandate

Two examples on how to the decipher the table for each role:

• Cell highlighted in gray (Table 5.1): the System Administrator role can view the information of all organizations.

• Cell highlighted in blue (Table 5.1): The Registry Administrator can manage data elements (including classification tables) for all the Geo-Object Types and/or hierarchies private to their organization

The home page is the first view the user sees after logging into GeoPrism Registry. It is organized in such a way that it allows users to:

1. Access each module by clicking on the corresponding module icons

2. Access each module from the burger menu

3. Access the settings from the burger menu

4. Switch locales for the interface

5. Access their own user information by clicking on the username next to the burger menu

6. Log out from the burger menu\

For example, the home page will look like this when accessed by a user having a Registry Contributor role:

This section describes the user interface of GeoPrism Registry.

The modules currently included in GeoPrism Registry are as follows:

The general layout of modules is structured in four ways:

1. A unique window containing a set of fields to be completed (Import)

2. A unique window with horizontal sections that can expand depending on the actions being done (Scheduled Jobs, Change Requests, Curation)

3. A window separated into two vertical panels (Geo-Object Types and Hierarchies, Lists and Spatial Data)

4. A unique window with side panels that can be displayed or hidden (Explorer)

For types 1 and 2, the user will start from the top of the window to complete the desired action.

For type 3, the user will first have to select items (Geo-Object Types, hierarchies) in the left panel for the information to appear in the right panel and then be able to complete the desired action in that panel.

For type 4, the user might first have to expand one of the panels before being able to complete the desired action.

The GeoPrism Registry settings are accessible from the hamburger menu. The settings window is separated into different sections which are accessible depending on the user role:

The sandbox contains fake data that has been generated to facilitate testing sessions and demos that would cover a large number of use cases, including changes over time.

'Tolkien land' was initially created for a training that took place in the Philippines in 2019. It has since been expanded for GeoPrism Registry demonstration purposes.

6.1.3.1. Geo-Object Types

The Tolkien dataset contains Geo-Object Types under the curation mandate of three different organizations:

• Ministry of Home Affairs (MOHA)

  • Provinces - Polygons

  • Counties - Polygons

  • Shires - Polygons

  • Villages - Points

• Ministry of Health (MOH)

  • National Hospitals - Points

  • Referral Hospitals – Points

  • Health Centers – Points

  • Health Posts – Points

  • Catchment areas – Polygons

  • Community Health Workers - Points

• Ministry of Education (MOE)

  • Universities - Points

  • Colleges - Points

  • Secondary Schools - Points

  • Primary Schools - Points

6.1.3.2. Hierarchies

Organization-specific hierarchies based on the above Geo-Object Types and the geographic location (latitude/longitude) or the geographic extent (polygon) of each Geo-Object have also been configured for the Tolkien dataset.

The hierarchies created per organization are as follows:

• MOHA
• MOH
• MOH

There are two ways a user can log in to GeoPrism Registry. These methods are described in detail in the following sections.

This section describes how users are managed within GeoPrism Registry.

The fictional Tolkien dataset used in the GeoPrism Registry sandbox has been designed in such a way that it is distributed across three organizations:

• Ministry of Home Affairs (MOHA)

• Ministry of Health (MOH)

• Ministry of Education (MOE)

The sandbox is currently accessible through the following set of roles to external users:

Logging in using local GeoPrism Registry credentials is done as follows:

1. On the GeoPrism Registry login page, type the username and password assigned to you in the appropriate fields.\
2. Click the Login button.

6.3.2.1. Directly from the User Accounts section

2. Under the User Accounts section, click the Invite User button.\
4. Click the Submit button.

6.3.2.2. From the Manage Accounts section

2. Under the User Accounts section, click the Manage Accounts button.\
3. This will show you the table containing the list of the existing users. Check if the email address of the person you want to invite is not yet in the list of users. If this is not the case, click the Invite User button on the upper right corner.\
5. Click the Submit button.

GeoPrism Registry supports logging in with DHIS2 credentials using OAuth 2.0 for a specific DHIS2 instance.

2. From the GeoPrism Registry login page, click the Log in with DHIS2 button.\
3. If there is more than one DHIS2 external system registered, a dropdown will appear of all the registered DHIS2 instances. Select the instance you want to use to log in with, which will route you to the login screen of that instance. If there is only one system, you will be routed to the login screen of that instance without needing to select that instance from a dropdown.\
4. Log in to the DHIS2 instance. Once logged in, you will be asked to authorize GeoPrism Registry ('georegistry'). Click Authorize to continue.\
5. After clicking Authorize you will have access to the GeoPrism Registry instance you started with.

If you forgot your password, you may try to reset it using the Forgot Password functionality on the login page.

1. On the GeoPrism Registry login page, click on the Forgot password? link just below the login username and password fields.\
2. Enter your username.\
3. Click the Submit button. This will send an email to the address registered with your GeoPrism Registry account.\
4. Check the email address registered with your GeoPrism Registry account for an email with the verification link to reset your password. Click on that link.

5. A new page will open with a form to enter a new password. Enter your new password and confirm it in the form.\
6. Click the Submit button.

The GeoPrism Registry sandbox is a controlled testing and demo environment that resets at 12:00 AM GMT+1 every day. This allows users to test and learn about GeoPrism Registry's functionalities without the risk of affecting some specific content.

Because of this, the sandbox is used as the reference for all the examples included in the this tutorial.

This section describes how the GeoPrism Registry content is set up.

Enabling a user to access GeoPrism Registry with DHIS2 credentials makes it easier to access the system by only requiring that user to manage a username and password from one system (DHIS2). This section describes how to enable OAuth integration with a specific DHIS2 instance for a specific user.

You must create the user in GeoPrism Registry before you can log in with it using OAuth. This is required because GeoPrism Registry needs to know what roles from GeoPrism Registry to associate with this user. GeoPrism Registry does the user mapping based on the username, so the username of the user in GeoPrism Registry must exactly match the username of the user in DHIS2.

1. Navigate to an existing user in GeoPrism Registry and click the Edit button to open the User Management form. If an external system is configured correctly to enable OAuth with DHIS2, a button to Enable OAuth will appear.\
2. Click the Enable OAuth button to show the options of properly configured DHIS2 instances.\
3. Select the DHIS2 instance the user will authenticate with.

4. Click Submit.

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
3. Scroll down the Geo-Object Types column to the organization you are a part of and click the Add Group button.\
4. Fill out all the required fields and any optional fields that are relevant in the form that appears.

2. Under the User Accounts section, click the Manage Accounts button.\
4. The account information window for that user will pop up. Scroll down to the password field and click the Change Password button.\
5. The input field for the new password will show. Type the new password and confirm it.\
6. Click the Submit button at the bottom of the window.

Adding a Geo-Object Type to a group is done as follows:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
4. The Manage Geo-Object Type window will open. Scroll down to the Attributes section and click the + Add button.\
5. The Add a new attribute window will open. Select the data type of the new attribute you want to add that will apply to all geographic object types in the group and fill out all the required fields and any optional fields that are relevant.

6. Click the Submit button.

7. To add another attribute, repeat steps 4 to 6.

8. Once the custom attributes have been added, click the Submit button in the Manage Geo-Object Type window.

To edit a custom attribute for the group:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
5. The Edit Attribute window will open. Make the necessary changes to the attribute then click the Submit button.

6. To edit another attribute, repeat steps 4 to 6.

7. Once the custom attributes that need to be edited are edited, click the Submit button in the Manage Geo-Object Type window.

To delete custom attribute for the group:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
5. A message window will appear confirming if you want to delete the attribute. Click the Delete button.\
6. To delete another attribute, repeat steps 4 and 5.

7. Once the custom attributes that need to be deleted are deleted, click the Submit button in the Manage Geo-Object Type window.

2. Under the User Accounts section, click the Manage Accounts button.\
3. This will show you the table containing the list of the existing users. Click on the + icon at the bottom of the list.\
4. Fill out all the required fields and any optional fields that are relevant in the form that appears.

   • Field

     Description

     Required

     First name

     First name of the user in the default language (English).

     Required

     Last name

     Last name of the user in the default language (English).

     Required

     First name (local)

     First name of the user in the installed locale(s).

     Last name (local)

     Last name of the user in the installed locale(s).

     Phone number

     Phone number of the user.

     Phone number 2

     Alternative phone number of the user.

     Email address

     Email address of the user.

     Required

     Position/function

     The position and/or function the user holds in the organization they represent.

     Department

     The department the user is a part of.

     Username

     Username of the user. This username will be the name that is used to login and for display in the app where user identification is needed.

     Required

     Password

     Password used by the user to login.

     Required

     User status

     Sets the status of the user in the system. - Active is the default setting and enables all functionality that the user roles support. - Inactive disables the user from performing functions in the system but preserves the user in the system for tracking and auditing purposes.

     Required

6. Click the Submit button.

Adding a Geo-Object Type to a group happens as follows:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
3. Scroll down the Geo-Object Types column to the organization you are a part of and find the Geo-Object Type group you would like to add a Geo-Object Type to.

5. Fill out all the required fields and any optional fields that are relevant in the form that appears. Note that some of the fields cannot be edited as these properties are inherited from the Geo-Object Type group.\

   Field

   Description

   Required

   Code

   The unique human readable identifier. The code can be used to determine the uniqueness of a Geo-Object Type group if duplicate display labels exist in the system.

   Required

   Label (defaultLocale)

   The default display label for the Geo-Object Type group. The default value will be used if the default locale is selected in the language toggle or if another language is selected but no value exists for that language.

   Required

   Label… (for any other locale that is installed in the system)

   Display label for any locales installed in the system. A common geo-registry can have as many locales installed as needed. The system will allow the setting of the display label for each locale.

   Description (defaultLocale)

   The default description for the Geo-Object Type group. The default value will be used if the default locale is selected in the language toggle or if another language is selected but no value exists for that language.

   Description… (for any other locale that is installed in the system)

   Description for any locales installed in the system. A common geo-registry can have as many locales installed as needed. The system will allow the setting of the description for each locale.

   Group Geo-Object Type (Group Membership)

   The option for setting this Geo-Object Type as a group type. This is automatically selected and cannot be unchecked in this case.

   Private (Visibility)

   The option for setting if the Geo-Object Type Group is private or public. Private makes the Geo-Object Type group accessible only to people within the organization it belongs to. Public is visible (read only) to all organizations in the system.

   Geometry Type

   The geometry type (point, line, or polygon) that all instance data loaded to this Geo-Object Type group must adhere to.

   Enable geometry editing

   Sets whether the Geo-Object geometries can be edited through GeoPrism Registry's web-based editing tools.

   Organization

   The organization this Geo-Object Type group will be managed by.
6. Click the OK button. Once one or more group members have been created, you will be able to see them under the Geo-Object Type group in the Geo-Object Types section on the sidebar (e.g., Health facility (MOH) Geo-Object Type group in the image below).\

To edit the metadata of a group:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
4. The Manage Geo-Object Type window will open. Edit the group information as necessary.\
5. Click the Submit button.

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
4. The Manage Geo-Object Type window will open. Scroll down to the Attributes field and click the + Add button.\
5. The Add a new attribute window will open. Select the data type of the new attribute you want to add for the Geo-Object Type and fill out all the required fields and any optional fields that are relevant.\
6. Click the Submit button.

7. To add another attribute, repeat steps 4 to 6.

8. Once the custom attributes have been added, click the Submit button in the Manage Geo-Object Type window.

To edit a custom attribute for the Geo-Object Type:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
5. The Edit Attribute window will open. Edit the information as necessary.\
6. Click the Submit button.

7. To edit another attribute, repeat steps 4 to 6.

8. Once the custom attributes are edited, click the Submit button in the Manage Geo-Object Type window.

To delete a custom attribute for a Geo-Object Type:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
5. A message window will appear confirming if you want to delete the attribute. Click the Delete button.\
6. Once the custom attributes are deleted, click the Submit button in the Manage Geo-Object Type window.

To delete a group:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
4. A message window will appear confirming if you want to delete the group. Click the Delete button.\

To delete a Geo-Object Type:

2. If needed, expand the Geo-Object Types column on the sidebar by clicking the arrow at the end.\
4. A message window will appear confirming that you want to delete the Geo-Object Type. Click the Delete button.\

2. If needed, expand the Hierarchies column on the sidebar by clicking the arrow at the end.\
3. Scroll down the Hierarchies column to the organization you are a part of. Click the Add Hierarchy button.\
4. Fill out all the required fields and any optional fields that are relevant in the form that appears.

   Field

   Description

   Required

   Code

   The unique human readable identifier. The code can be used to determine the uniqueness of a hierarchy if duplicate display labels exist in the system.

   Required

   Label (defaultLocale)

   The default display label for the hierarchy.

   Required

   Label… (for any other locale that is installed in the system)

   Display label for any locales installed in the system. A common geo-registry can have as many locales installed as needed. The system will allow the setting of the display label for each locale.

   Description (Abstract) (defaultLocale)

   The default description for the hierarchy.

   Description (Abstract) (for any other locale that is installed in the system)

   Description for any locales installed in the system. A common geo-registry can have as many locales installed as needed. The system will allow the setting of the description for each locale.

   Organization

   The organization the hierarchy will belong to.

   Progress

   A description of the progress so far to create and curate the data for this list.

   Acknowledgement

   Acknowledgements relevant to the hierarchy definition.

   Disclaimer

   Any disclaimers relevant to the hierarchy definition.

   Access Constraints

   Access constraints relevant to the hierarchy definition.

   Use Constraints

   Use constraints relevant to the hierarchy definition.

   Contact name

   Full name of the person responsible for managing this hierarchy.

   Telephone number

   Telephone number of the person responsible for managing this hierarchy.

   Email Address

   Email address of the person responsible for managing this hierarchy.

5. Click the OK button.

To add a Geo-Object Type (group) to a hierarchy:

2. If needed, expand the Hierarchies column on the sidebar by clicking the arrow at the end.\
3. Scroll down the Hierarchies column to the organization you are a part of. Click the name of the hierarchy you want to add a Geo-Object Type (group) to to select it (the box of the selected hierarchy will change to a different color). This will display the area to add Geo-Object Type (group) as part of the hierarchy to the right of the Geo-Object Types and Hierarchies columns (represented by the rectangle with dotted lines).\
4. Find one of the Geo-Object Types (groups) that you want to add to the hierarchy in the Geo-Object Types column. If needed, expand the Geo-Object Types column in the sidebar by clicking the arrow at the end.\
5. Click and hold on the name of the Geo-Object Type (group) and drag it to the area to add it to the selected hierarchy.
6. The display area will now show the Geo-Object Type (group) you have added to the hierarchy.
7. To add another Geo-Object Type (group), click and hold on the name of the Geo-Object Type (group) and drag it on top of the Geo-Object Type that is already part of the hierarchy.

8. You will then have the option to choose whether to add this new Geo-Object Type (group) as a parent (above) or child (below) of the Geo-Object Type already in the hierarchy. Drag the Geo-Object Type (group) to the chosen place in the hierarchy (parent or child) until the selected place turns blue and drop it there.
9. Once added, you will see the new Geo-Object Type (group) connected to the other Geo-Object Type (group) in the hierarchy (either above or below the other Geo-Object Type (group), depending on the relationship you chose). In the example below, the Health Post Geo-Object Type was added as a child of the Health Center Geo-Object Type in the Health Facility Reporting Hierarchy.\
10. Repeat steps 4 to 7 to add other Geo-Object Types (groups) to complete the hierarchy.