Merging a Regional Yap Server into a Zonal Yap Server

First posted February 2020; updated November 2022

Since Yap 3.0.0 (released in March 2019), it’s been possible to use a single Yap server with multiple Twilio accounts.  What this means is that a service body can handle the overhead of server management while another service body retains the management of phone numbers and billing.

Yap 3 also introduced the concept of configuration precedence.  This creates the ability to manifest all kinds of powerful capabilities without requiring access to the config.php on the server (critical for this situation where server management is handled by someone else).  It also has the ability to set a value at regional level while the hierarchy of the BMLT automatically cascades down to the member areas.

In 2020 one of us had to migrate a regional yap server to the zonal server; these notes have been updated in November 2022 based on doing a similar migration in another zone. Below is the process we followed; feel free to send an email to help@bmlt.app if you’d like more details.

Consider whether you may want to take a backup and overwrite your existing Yap database, or make a copy with a new install and config to do side by side testing.  You may also want to consider setting in the database config ahead of time or afterward.  You may also want to transfer any other settings in your top level config.php to the Config settings in the admin portal.  Keep in mind that service bodies will use the hierarchy, so if you set this as a regional level all the service bodies connected will inherit them.

To make things concrete, suppose that we are merging region R into zone Z. So R will be the source and Z the target. On the old server for R, suppose the region has service body ID 1, and there are 3 areas with service body IDs 2, 3, and 4. On the zonal server, these will have different IDs, say 201 for the region, and 202, 203, and 204 for its areas.

  1. Make sure that you’ve got the same version of yap for R and Z, upgrading if need be.
  2. Delete any configuration information for R from the target yap server, if there is any.  (There might not be any yet.) You can do that with this SQL command:
    DELETE FROM config where service_body_id in (201, 202, 203, 204);     
  3. Update the config table on R (or maybe better, a temporary copy of R) to use the new service body IDs. You can do this with SQL commands like this:
    UPDATE config SET service_body_id = 201 where service_body_id=1;
  4. Begin an export from your source yap server or temporary copy, select only data and exclude the flags and migrations tables.  See the screenshots to the right.  (Use a self-contained file.)
  5. After the file has been exported run the below on your system.  In the below example, “export.sql” is the file exported from Step 4 above.
    cat export.sql | sed -e "s/([0-9]*,/(NULL,/g" > export-mod.sql
    This will replace the id numbers on the records for region R with NULL.  (The idea is that the id numbers will change from the old and new databases, and MySQL will generate the new ones automatically when you import the data.)
  6. Import export-mod.sql into the target yap server.  “export-mod.sql” is the output from the command run locally in Step 5 above.
  7. Your phone numbers must have explicit service body overrides in order to pull configuration values from the database (you can use either override_service_body_id or override_service_body_config_id).  One changes your service body for call routing and the other selects configuration, respectively.