Upgrade Guide

Major version can only be upgraded incrementally from immediate previous major version, i.e. from N to N+1.

v1 to v2

Upgrading NotifyBC from v1 to v2 involves two steps

1. Update your client code if needed
2. Upgrade NotifyBC server

Update your client code

NotifyBC v2 introduced backward incompatible API changes documented in the rest of this section. If your client code will be impacted by the changes, update your code to address the incompatibility first.

Query parameter array syntax

In v1 array can be specified in query parameter using two formats

1. by enclosing array elements in square brackets such as &additionalServices=["s1","s2] in one query parameter
2. by repeating the query parameters, for example &additionalServices=s1&additionalServices=s2

In v2 only the latter format is supported.

Date-Time fields

In v1 date-time fields can be specified in date-only string such as 2020-01-01. In v2 the field must be specified in ISO 8601 extended format such as 2020-01-01T00:00:00Z.

Return status codes

HTTP response code of success calls to following APIs are changed from 200 to 204

• most PATCH by id requests except for Update a Subscription
• most PUT by id requests except for Replace a Subscription
• most DELETE by id requests except for Delete a Subscription (unsubscribing)

Administrator API

• Password is saved to Administrator in v1 and UserCredential in v2. Password is not migrated. New password has to be created by following Create/Update an Administrator's UserCredential .
• Complexity rules have been applied to passwords.
• login API is open to non-admin

Upgrade NotifyBC server

The procedure to upgrade from v1 to v2 depends on how v1 was installed.

Source-code Installation

1. Stop NotifyBC
2. Backup app root and database!
3. Make sure current branch is tracking correct remote branch

   git remote set-url origin https://github.com/bcgov/NotifyBC.git
   git branch -u origin/main
   

4. Make a note of any extra packages added to package.json
5. Run git pull && git checkout tags/v2.x.x from app root, replace v2.x.x with a v2 release, preferably latest, found in GitHub such as v2.9.0.
6. Make sure version property in package.json is 2.x.x
7. Add back extra packages noted in step 4
8. Move server/config.(local|dev|production).(js|json) to src/ if exists
9. Move server/datasources.(local|dev|production).(js|json) to src/datasources/db.datasource.(local|dev|production).(js|json) if exists. Notice the file name has changed.
10. Move server/middleware.*.(js|json) to src/ if exists. Reorganize top level properties to all or apiOnly, where all applies to all requests including web console and apiOnly applies to API requests only. For example, given

module.exports = {
  initial: {
    compression: {},
  },
  'routes:before': {
    morgan: {
      enabled: false,
    },
  },
};

if compression middleware will be applied to all requests and morgan will be applied to API requests only, then change the file to

module.exports = {
  all: {
    compression: {},
  },
  apiOnly: {
    morgan: {
      enabled: false,
    },
  },
};

11. Run

npm i && npm run build

11. Start server by running npm run start or Windows Service

OpenShift Installation

1. Run

   git clone https://github.com/bcgov/NotifyBC.git
   cd NotifyBC
   

2. Run

   oc delete bc/notify-bc
   oc process -f .openshift-templates/notify-bc-build.yml | oc create -f-
   

   ignore AlreadyExists errors

3. Follow OpenShift Build

4. For each environment,

   1. run

      oc project <yourprojectname-<env>>
      oc delete dc/notify-bc-app dc/notify-bc-cron
      oc process -f .openshift-templates/notify-bc.yml | oc create -f-
      

      ignore AlreadyExists errors

   2. copy value of environment variable MONGODB_USER from mongodb deployment config to the same environment variable of deployment config notify-bc-app and notify-bc-cron, replacing existing value

   3. remove middleware.local.json from configMap notify-bc

   4. add middleware.local.js to configMap notify-bc with following content

      module.exports = {
        apiOnly: {
          morgan: {
            enabled: false,
          },
        },
      };
      

   5. Follow OpenShift Deploy or Change Propagation to tag image

OpenShift template to Helm

Upgrading NotifyBC on OpenShift created from OpenShift template to Helm involves 2 steps

1. Customize and Install Helm chart
2. Migrate MongoDB data

Customize and install Helm chart

Follow customizations to create file helm/values.local.yaml containing customized configs such as

• notify-bc configMap
• web route host name and certificates

Then run helm install with documented arguments to install a release.

Migrate MongoDB data

1. backup data from source

   oc exec -i <mongodb-pod> -- bash -c 'mongodump -u "$MONGODB_USER" \
   -p "$MONGODB_PASSWORD" -d $MONGODB_DATABASE --gzip --archive' > notify-bc.gz
   

   replace <mongodb-pod> with the mongodb pod name.

2. restore backup to target

   cat notify-bc.gz | oc exec -i <mongodb-pod-0> -- \
   bash -c 'mongorestore -u "$MONGODB_USERNAME" -p"$MONGODB_PASSWORD" \
   --uri="mongodb://$K8S_SERVICE_NAME" --db $MONGODB_DATABASE --gzip --drop --archive'
   

   replace <mongodb-pod-0> with the first pod name in the mongodb stateful set.

If both source and target are in the same OpenShift cluster, the two operations can be combined into one

oc exec -i <mongodb-pod> -- bash -c 'mongodump -u "$MONGODB_USER" \
-p "$MONGODB_PASSWORD" -d $MONGODB_DATABASE --gzip --archive' | \
oc exec -i <mongodb-pod-0> -- bash -c \
'mongorestore -u "$MONGODB_USERNAME" -p"$MONGODB_PASSWORD" \
--uri="mongodb://$K8S_SERVICE_NAME" --db $MONGODB_DATABASE --gzip --drop --archive'

v2 to v3

v3 introduced following backward incompatible changes

1. Changed output-only fields failedDispatches and successDispatches to dispatch.failed and dispatch.successful respectively in Notification api. If your client app depends on the fields, change accordingly.
2. Changed config notification.logSuccessfulBroadcastDispatches to notification.guaranteedBroadcastPushDispatchProcessing and reversed default value from false to true. If you don't want NotifyBC guarantees processing all subscriptions to a broadcast push notification in a node failure resilient way, perhaps for performance reason, set the value to false in file /src/config.local.js.

After above changes are addressed, upgrading to v3 is as simple as

git pull
git checkout tags/v3.x.x
npm i && npm run build

or, if NotifyBC is deployed to Kubernetes using Helm.

git pull
git checkout tags/v3.x.x
helm upgrade <release-name> -f helm/platform-specific/<platform>.yaml -f helm/values.local.yaml helm

Replace v3.x.x with a v3 release, preferably latest, found in GitHub such as v3.1.2.

v3 to v4

v4 introduced following backward incompatible changes that need to be addressed in this order

1. The precedence of config, middleware and datasource files has been changed. Local file takes higher precedence than environment specific file. For example, for config file, the new precedence in ascending order is

   1. default file /src/config.ts
   2. environment specific file /src/config.<env>.js, where <env> is determined by environment variable NODE_ENV
   3. local file /src/config.local.js

   To upgrade, if you have environment specific file, merge its content into the local file, then delete it.

2. Config smtp is changed to email.smtp. See SMTP for example.

3. Config inboundSmtpServer is changed to email.inboundSmtpServer. See Inbound SMTP Server for example.

4. Config email.inboundSmtpServer.bounce is changed to email.bounce. See Bounce for example.

5. Config notification.handleBounce is changed to email.bounce.enabled.

6. Config notification.handleListUnsubscribeByEmail is changed to email.listUnsubscribeByEmail.enabled. See List-unsubscribe by Email for example.

7. Config smsServiceProvider is changed to sms.provider. See Provider for example.

8. SMS service provider specific settings defined in config sms are changed to sms.providerSettings. See Provider Settings for example. The config object sms now encapsulates all SMS configs - provider, providerSettings and throttle.

9. Legacy config subscription.unsubscriptionEmailDomain is removed. If you have it defined in your file /src/config.local.js, replace with email.inboundSmtpServer.domain.

10. Helm chart added Redis that requires authentication by default. Create a new password in helm/values.local.yaml to facilitate upgrading

# in file helm/values.local.yaml
redis:
  auth:
    password: '<secret>'

After above changes are addressed, upgrading to v4 is as simple as

git pull
git checkout tags/v4.x.x
npm i && npm run build

or, if NotifyBC is deployed to Kubernetes using Helm.

git pull
git checkout tags/v4.x.x
helm upgrade <release-name> -f helm/platform-specific/<platform>.yaml -f helm/values.local.yaml helm

Replace v4.x.x with a v4 release, preferably latest, found in GitHub such as v4.0.0.

v4 to v5

v5 introduced following backward incompatible changes

1. Replica set is required for MongoDB. If you deployed NotifyBC using Helm, replica set is already enabled by default.

2. If you use default in-memory database, data in server/database/data.json will not be migrated automatically. Manually migrate if necessary.

3. Update file src/datasources/db.datasource.local.[json|js|ts]

   1. rename url property to uri
   2. for other properties, instead of following LoopBack MongoDB data source, follow Mongoose connection options. In particular, host, port and database properties are no longer supported. Use uri instead.

   For example, change

   {
     "name": "db",
     "connector": "mongodb",
     "url": "mongodb://127.0.0.1:27017/notifyBC"
   }
   

   to

   {
     "uri": "mongodb://127.0.0.1:27017/notifyBC"
   }
   

   If you deployed NotifyBC using Helm, this is taken care of.

4. API querying operators have changed. Replace following Loopback operators with corresponding MongoDB operators at your client-side API call.

   Loopback operators	MongoDB operators
   eq	$eq
   and	$and
   or	$or
   gt, gte	$gt, $gte
   lt, lte	$lt, $lte
   between	(no equivalent, replace with $gt, $and and $lt)
   inq, nin	$in, $nin
   near	$near
   neq	$ne
   like, nlike	(replace with $regexp)
   like, nlike, options: i	(replace with $regexp)
   regexp	$regex

5. API order filter syntax has changed. Replace syntax from Loopback to Mongoose at client-side API call. For example, if your client-side code generates following API call

   GET http://localhost:3000/api/configurations?filter={"order":["serviceName asc"]}
   

   change to either

   GET http://localhost:3000/api/configurations?filter={"order":[["serviceName","asc"]]}
   

   or

   GET http://localhost:3000/api/configurations?filter={"order":"serviceName"}
   

6. In MongoDB administrator collection, email has changed from case-sensitively unique to case-insensitively unique. Make sure administrator emails differ not just by case.

7. When a subscription is created by anonymous user, the data field is preserved. In earlier versions this field is deleted.

8. Dynamic tokens in subscription confirmation request message and duplicated subscription message are not replaced with subscription data, for example {subscription::...} tokens are left unchanged. Update the template of the two messages if dynamic tokens in them depends on subscription data.

9. Inbound SMTP Server no longer accepts command line arguments or environment variables as inputs. All inputs have to be defined in config files shown in the link.

10. If you deployed NotifyBC using Helm, change MongoDB password format in your local values yaml file from

    # in file helm/values.local.yaml
    mongodb:
      auth:
        rootPassword: <secret>
        replicaSetKey: <secret>
        password: <secret>
    

    to

    # in file helm/values.local.yaml
    mongodb:
      auth:
        rootPassword: <secret>
        replicaSetKey: <secret>
        passwords:
          - <secret>
    

After above changes are addressed, to upgrade NotifyBC to v5,

• if NotifyBC is deployed from source code, run

  git pull
  git checkout tags/v5.x.x
  npm i && npm run build
  

• if NotifyBC is deployed to Kubernetes using Helm,

  1. backup MongoDB database
  2. run

     helm uninstall <release-name>
     

     Replace <release-name> with installed helm release name
  3. delete PVCs used by MongoDB stateful set
  4. run

     git pull
     git checkout tags/v5.x.x
     helm install <release-name> -f helm/platform-specific/<platform>.yaml -f helm/values.local.yaml helm
     

     Replace
     • v5.x.x with a v5 release, preferably latest, found in GitHub such as v5.0.0.
     • <release-name> with installed helm release name
     • <platform> with openshift or aks depending on your platform
  5. restore MongoDB database