Skip to content

Add country

Jump to bottom
jannisvisser edited this page Jan 17, 2025 · 3 revisions

GUIDE: Add new country

Adding a new country, by definition also involves adding at least 1 disaster-type. Adding additional disaster-types beyond this, can therefore be deduced from the same guideline.

Add country in local dev setup

The below guide ASSUMES:

  • pre-existing disasterType
  • only pre-existing indicators and layers
  1. Add country to countries.json
  • Add all properties in line with existing examples. Use dummy data first if needed. Collect correct data.
  • Add initial disaster-type to disasterTypes array, following disaster-type.enum.
  • Add initial disaster-type to countryDisasterSettings
    • Fill in generic required settings
      • disasterType: same as above
      • adminLevels: which administrative levels the user can navigate to.
      • defaultAdminLevel: which administrative level to load by default (should be highest adminLevel)
      • activeLeadTimes: which leadTimes to load. (NOTE: typhoon & drought contain all possible leadtimes here)
      • eapLink: link to EAP/SOP/About trigger doc.
    • Fill in generic non-required settings
      • isEventBased (default: false)
      • enableEarlyActions (default: true)
      • enableStopTrigger (default: true)
    • Fill in disaster-type-specific settings
      • drought: droughtSeasonRegions, droughtRegions, droughtEndOfMonthPipeline, showMonthlyEapActions
      • floods: eapAlertClasses
  1. Include administrative boundary data
  • You need an admin-boundary file for each adminLevel defined above
  • Collect the data from appropriate source and document where/when it was collected.
  • Typically the data is simplified using e.g. mapshaper.org to reduce data size.
  • Required format: geojson.
    • All features should be of type MultiPolygon, not Polygon
  • Required file name: _adm.json
  • Required field names:
    • ADM<adminLevel>_PCODE
    • ADM<adminLevel>_EN
    • ADM<adminLevel - 1>_PCODE (parentPlaceCode)
  • Add the files to API-service/src/scripts/git-lfs/admin-boundaries
  • It will be automatically included in seed-script
  1. Set up dynamic layers
  2. Dynamic admin-area layers - In indicator-metadata.json, add countryCodeISO3 for:
    • alert_threshold: this is a required indicator, indicating trigger/warning status per admin-area
    • Also required is the main exposure indicator, as defined per disasterType as actionsUnit in disasters.json
    • Not required, so can be done later:
      • 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. Set up dynamic 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.
  4. Set up dynamic 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.
  5. Create mock data for dynamic layers
  • You need to define scenarios trigger and no-trigger.
  • In scenario trigger define at least 1 event.
  • For this event, create mock data for
    • each dynamic admin-area indicator and adminLevel defined above.
    • each dynamic raster layer defined above
    • each dynamic point/lines layer defined above
  • See specific mock data guide for more details.
  1. Setup static layers
  2. Static 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 every layer - See specific guide: TO DO
  3. Static 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.
  4. Static point layers - Add any pre-existing or new static point or line layers in 'layers.json' with type=point, in line with other examples. - Required layers
    • For floods: glofas_stations - No other required layers, but typically red_cross_branches is added. - Include seed-data for every layer
  5. Static line layers - This currently deals with roads and buildings in flash-floods only, and comes with specific custom code modules. - See specific guide: TO DO
  6. 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
  1. Set up 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 per relevant leadTime
  • Log into the local Geoserver interface
  • Create a store per leadTime (so for e.g. drought this means 12 times, for all months of the year)
    • with name <layerName>_<leadTime>_<countryCodeISO3>
    • and pointing to the right location file:workspaces/ibf-system/ibf-pipeline/output/<subfolder>/<filename.tif>
  • Create a layer per store with same name and set the right style under Publishing
  • Test if file is referenced correctly through Layer Preview and choosing OpenLayers format.
  • Test if Geoserver layer is correctly found by portal by seeding & mocking and toggling on the respective layer in the portal
  1. 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.
  1. Set up notifications
  2. 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.
  3. Set up WhatsApp via Twilio - TO DO
  4. Set up country-specific user
  1. Set up manuals
  1. Add country-specific settings in code

Add country on production

For adding the new country to production, we cannot use seed-scripts like above. Instead, process all the data changes preferably via migration files, or otherwise manualy.

  1. Possible to update via API endpoints (manually) or underlying methods (migration files)
  • Upload country (paste whole countries.json or just the new country)
    • NOTE: watch out that whenever pasting whole countries.json to always remove first any countries/disaster-types that should be/stay deactivated on production
  • Update notification-info (paste whole notification-info.json or just the new country)
  • Upload admin-boundaries (once per admin-level)
  • NOTE: this may fail for the defaultAdminLevel if there has ever been a trigger event already for this country. If so, find a work
  • Update indicator-metadata and layer-metadata (paste whole *.json)
  • Update static admin-area data (CSV files)
  • Update EAP-actions (paste whole json or just the new actions)
  • Update any point/lines layers (red cross branches, glofas stations, etc.)
  • Create new country user and store password in Bitwarden
  1. Must currently be updated directly in database (manually) or via raw queries (migration files) 
  • Add new country to dunant-user: INSERT INTO "IBF-app".user_countries("user", country) VALUES('[email protected]', '<countryCodeISO3>')
  • If applicable: add/update
    • disaster
    • lead-times
    • areas-of-focus

Other

  1. Add static admin-area layers
  • Add indicator to indicator-metadata.json
  • Add countryCode in country_codes
  • If layer should also be shown in middle column: add country to aggregateIndicator as well
  • Set dynamic = false
  • Set colorBreaks if applicable (check with data-dev for specific classes/breaks)
  • Add data to API-service/src/scripts/git-lfs/admin-area-data
  • Add section in seed-admin-area-data.ts, in line with existing examples
  • If it is a static layer that will be updated (like Hotspot and IPC layers Ethiopia), then
    • also add the layer to Add layer to API-service/src/api/admin-area-dynamic-data/enum/dynamic-data-unit.ts
    • and test the respective pipeline(s) with data-dev
  1. Add dynamic admin-area layers
Clone this wiki locally