Add country - rodekruis/IBF-system GitHub Wiki

Note

Adding a country comes with adding at least one disaster type. This means we can infer from this guide also how to add a new disaster type to an existing country. Some elements of the below list can be skipped in that case.

To add a country, we must choose a supported disaster type, map layers, and indicators.

Table of Contents

  1. Add new country configuration
  2. Add administrative boundaries
  3. Add dynamic layers
  4. Add mock data
  5. Add static layers
  6. Layer and indicator descriptions
  7. Configure Geoserver
  8. Add Early Actions
  9. Configure notifications
  10. Add country user
  11. Create manuals
  12. Update country-specific code

Add to production

1. Add new country configuration

Add new country configuration to countries.json. Refer to existing examples for guidance.

{ // this is an example country config to add Malawi flood
   "countryCodeISO3": "MWI", // as defined in https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
   "countryName": "Malawi",
   "disasterTypes": [ "floods" ], // disasterType from /services/API-service/src/scripts/json/disaster-types.json
   "countryDisasterSettings": [
      { // configure disaster type per country
         "disasterType": "floods", // /services/API-service/src/scripts/json/disaster-types.json
         "adminLevels": [ 3 ], // which administrative levels the user can navigate to
         "defaultAdminLevel": 3, // which administrative level to load by default (should be highest adminLevel)
         "activeLeadTimes": [ "0-day", "1-day", "2-day", "3-day" ], // which leadTimes to load
         "eapLink": "https://510ibfsystem.blob.core.windows.net/about-trigger/MWI-EAP-document.pdf", // public link to Early Action Protocol
         "eapAlertClasses": { // only for floods: config to visualize forecast state
            "no": { "label": "No action", "color": "ibf-no-alert-primary", "value": 0 }, // possible forecast state
            "max": { "label": "Trigger issued", "color": "ibf-glofas-trigger", "value": 1 } // possible forecast state
         },
         "enableEarlyActions": true, // to show or hide early actions, defaults to true
      }
      // drought specific config: `droughtSeasonRegions`, `droughtRegions`, `monthlyForecastInfo`, `showMonthlyEapActions`
      // refer /services/API-service/src/scripts/json/countries.json#L47-L221
   ],
   "adminRegionLabels": { // configure labels for each administrative boundary
      "1": { "singular": "Region", "plural": "Regions" }, // admin level 1
      "2": { "singular": "District", "plural": "Districts" }, // admin level 2
      "3": { "singular": "Traditional Authority", "plural": "Traditional Authorities" } // admin level 3
   },
   "countryLogos": { "floods": [ "MWI-mrcs.png" ] }, // logo to show in portal and notifications
   "countryBoundingBox": { // geojson bounding box of administative boundary level 0
      "type": "Polygon",
      "coordinates": [ [ [ 35.7719047381, -16.8012997372 ], [ 35.7719047381, -9.23059905359 ], [ 32.6881653175, -9.23059905359 ], [ 32.6881653175, -16.8012997372 ], [ 35.7719047381, -16.8012997372 ] ] ]
   }
}

2. Add administrative boundaries

  • Collect the data from appropriate source and document where/when it was collected. Use mapshaper.org to reduce data size.
  • Data format: geojson. All features should be of type MultiPolygon.
  • File name format: <countryISO3code>_adm<adminLevel>.json. Example, MWI_adm3.json.
  • Required properties: ADM<adminLevel>_PCODE, ADM<adminLevel>_EN, and ADM<adminLevel - 1>_PCODE (parentPlaceCode).
  • Add the files to /services/API-service/src/scripts/git-lfs/admin-boundaries. Use existing data for reference.

3. Add dynamic layers

3.1. Admin area layers

In indicator-metadata.json, add countryCodeISO3 for:

  • trigger: this is a required indicator for all countries and disaster-types, indicating trigger status per admin-area.
  • Also required is the main exposure indicator, as defined per disasterType as actionsUnit in disasters.json.

Other indicators are optional:

  • any other pre-existing indicators that are relevant for this country.
  • add any new indicators for this country, in line with existing examples.
  • same for pre-existing or new layers in layer-metadata.json, in line with existing examples.

3.2. Raster layers

  • This deals with dynamic raster layers, e.g. flood_extent for floods.
  • In layer-metadata.json, add countryCodeISO3 for any pre-existing or new layers with type=wms.
  • You also need to set up the respective Geoserver layers for this. See point (7) below.

3.3. Point layers

  • Currently only example is typhoon_track for typhoon, which comes with custom modules in code, and is not easily extendable.

Note

dynamic refers here to the location of the points. Static point data (see point 5) can also have dynamically updated properties (e.g. exposure status), but not the location itself.

4. Add mock data

Add mock data for dynamic layers. Define scenarios trigger and no-trigger. In scenario trigger define at least 1 event. For this event, use mock data guide to create mock data for each dynamic admin-area indicator and adminLevel, dynamic raster layers, dynamic point layers, and dynamic line layers.

5. Add static layers

5.1. Admin area layers

  • Add any pre-existing or new static admin-area layers in indicators.json, in line with other examples.
  • There are no required static layers for a working portal, but typically populationTotal per admin-area is added.
  • Include seed-data for each layer

5.2. Raster layers

  • Add any pre-existing or new static admin-area layers in layers.json with type=wms, in line with other examples.
  • There are no required static layers for a working portal, but typically population raster is added.
  • Include seed-data for every layer in the (gitignored) input folder in raster-files folder.
  • Create a Geoserver layer for each layer, similar to how that is done for dynamic layers in point (7) below.

5.3. Point layers

  • Add any pre-existing or new static point or line layers in 'layers.json' with type=point, in line with other examples.
  • Certain layers are mandatory based on disaster type,
disasterType layer
flood glofas_stations
  • No other required layers, but typically red_cross_branches is added.
  • Include seed-data for each layer.

5.4. Line layers

  • This currently deals with roads and buildings in flash-floods only, and comes with specific custom code modules.

6. Layer and indicator descriptions

Process (dummy) layer descriptions for all added layers and indicators in XLSX

  • NOTE: the below is not ideal, but currently needed, as otherwise any changes in indicator-metadata.json and layer-metadata.json might be overwritten inadvertently.
  • after adding all indicators and layers, run '_add-info-popup-xlsx-columns.js`
  • paste the resulting (gitignored) new-lines.csv at the bottom of layer-popup-info.xlsx
  • order all columns again by the first 3 columns (in that order) and save
  • run '_convert-layer-info-popup-xlsx-to-json.js`
  • open and save indicator-metadata.json and layer-metadata.json to apply prettier formatting again.
  • See for more details: README.md

7. Configure Geoserver

  • For any wms layer in layer-metadata.json, you need to set up Geoserver stores and layers for every possible leadTime
  • You need some (mock) data to do this, so see Mock raster data in Add/update mock scenarios to IBF on where to place this.
  • Subsequently run the mock trigger scenario, which automatically creates a file in the raster-files/output folder per relevant leadTime as defined in countries.json.
  • Create a Geoserver store+layer per relevant leadTime
    • Use the script _generate-geoserver-layers.js to easily generate this.
    • First adjust the static content of this script for your current country and disaster-type (search for FILL IN in the file)
      • the bounding box and related content
      • pick the right styleId
      • the right path of the tiff-file
    • Run once per required leadTime as defined in countries.json
    • At the end, run docker restart ibf-geoserver for the changes to take effect
    • Check the result by logging in the local Geoserver interface, through Layer Preview and choosing OpenLayers format.
  • If needed, for example if the static bounding box to fill in is unclear, you can create one layer manually and use that as base to update the script.
    • Log in to local Geoserver interface
    • Create a store based on GeoTiff file source.
    • with name <layerName>_<leadTime>_<countryCodeISO3>
    • and pointing to the right location file:workspaces/ibf-system/ibf-pipeline/output/<subfolder>/<filename.tif>
    • Create a layer based on the store with same name and set the right style under Publishing
  • Test if Geoserver layer is correctly found by portal by seeding & mocking and toggling on the respective layer in the portal

8. Add Early Actions

  • Not needed if enableEarlyActions=false in countries.json
  • Otherwise, add early actions to EAP-actions.json for right countryCodeISO3 and disasterType
    • areaOfFocus.id relates to areas-of-focus.json
    • If real data not available yet, dummy data can be added.
    • Note that the month property is only applicable if showMonthlyEapActions=true in countries.json.

9. Configure notifications

9.1. Set up email via Mailchimp

In Mailchimp

  • Add a new tag <countryCodeISO3> Test to all developer-users in the audience
  • Add a new segment <countryCodeISO3> Test, referring to this new tag
  • Get the segment ID by
  • Add the tag in .env MC_SEGMENTS as <countryCodeISO3>_<disasterType>:<segmentId> on local, ibf-test and ibf-demo
  • You can immediately create the producion tag+segment also as PROD - <countryCodeISO3> <disasterType>

In code

  • Add country in notification-info.json
  • Add trigger statement
  • Add logo
    • Paste all country logos from countries.json together in one .png
    • Upload to Mailchimp > Content Studio > My Files > Upload
    • Get the URL by selecting the picture > Expand 'View Details' > Copy URL
    • Paste it in notification-info.json
  • If applicable: set up WhatsApp or Telegram group, and add the link to join this group via linkSocialMediaUrl
  • Test sending an email by (loading triggered mock data first and) calling the /api/notification/send endpoint.

10. Add country user

Add new user to users.json.

11. Create manuals

11.1. Video manual

Upload on Youtube + edit link in bit.ly account (see IBF video manuals in Wiki) This is optional. If not provided, video content will be hidden in IBF dashboard.

11.2. PDF manual

Upload to https://510ibfsystem.blob.core.windows.net/manuals/IBF%20Manual-<country>-Published.pdf

12. Update country-specific code

Add countryCodeISO3 to country-time-zone-mapping.ts.

Add to production

To add a new country in a production instance, we must not use seed scripts as they will overwrite production configurations. Instead, process all the data changes preferably via migration files, or manually using API endpoints,

  1. Upload country (paste whole countries.json or just the new country)

Warning

when pasting whole countries.json always remove any countries/disaster-types that should remain deactivated

  1. Update disaster type (paste whole disaster-types.json or just the new disaster type)
  2. Update notification-info (paste whole notification-info.json or just the new country)
  3. Upload admin boundaries (once per admin level)

Warning

may fail for the defaultAdminLevel if there has ever been a trigger event for this country

  1. Update indicator-metadata and layer-metadata (paste whole *.json)
  2. Update static admin-area data (CSV files)
  3. Update EAP-actions (paste whole json or just the new actions)
  4. Update point layers and line layers (red cross branches, glofas stations, etc.)
  5. Create a new country user and store their password in Bitwarden

Also add new country to any (admin) all-country users: INSERT INTO "IBF-app".user_countries("user", country) VALUES('<user-email>', '<countryCodeISO3>')

⚠️ **GitHub.com Fallback** ⚠️