Upgrade Guide

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

v5 to v6

v6 introduced following backward incompatible changes

  1. Redis is required. Redis connection is moved from sms.throttle.clientOptions and email.throttle.clientOptions to queue.connection. Update file src/config.local.[json|js|ts] from, for example,

    module.exports = {
  // ...
  sms: {
    throttle: {
      // ...
      datastore: 'ioredis',
      clientOptions: {
        host: '127.0.0.1',
        port: 6379,
      },
    },
  },
  // ...
  email: {
    throttle: {
      // ...
      datastore: 'ioredis',
      clientOptions: {
        host: '127.0.0.1',
        port: 6379,
      },
    },
  },
};

    to

    module.exports = {
  // ...
  sms: {
    throttle: {
      // ...
    },
  },
  // ...
  email: {
    throttle: {
      // ...
    },
  },
  queue: {
    connection: {
      host: '127.0.0.1',
      port: 6379,
    },
  },
};

    If you deployed NotifyBC using Helm and haven't customized Redis connection in file src/config.local.[json|js|ts], this change is taken care of.

  2. config minTime in email.throttle and sms.Throttle is replaced with max and duration. Effectively minTime=duration/max. By default max is 4 and duration is 1000, equivalent to default minTime of 250.

  3. Terms for node roles have changed. If you defined environment variable NOTIFYBC_NODE_ROLE with value other than slave, remove the environment variable; otherwise change it to secondary. If you deployed NotifyBC using Helm, this change is taken care of.

  4. config notification.broadcastSubRequestBatchSize is deprecated. If you defined it in src/config.local.js, remove it.

  5. Bitnami MongoDB Helm chart is updated from version 14.3.2 to 16.3.3, with corresponding MongoDB from 7.0.4 to 8.0.4. If you deployed NotifyBC using Helm, or if you are running MongoDB 7 and planning to upgrade to MongoDB 8, follow Upgrade 7.0 to 8.0. In particular, ensure setFeatureCompatibilityVersion is set to 7.0

    db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
db.adminCommand( { setFeatureCompatibilityVersion: "7.0" } )

  6. Default SMTP service is changed from localhost to Ethereal. Make sure to setup SMTP in production if haven't done so.

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

  • if NotifyBC is deployed from source code, run

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

    Replace

    • v6.x.x with a v6 release, preferably latest, found in GitHub such as v6.1.2.

  • if NotifyBC is deployed to Kubernetes using Helm,

    1. backup MongoDB database
    2. run
      git pull
git checkout tags/v6.x.x
helm upgrade <release-name> -f helm/platform-specific/<platform>.yaml -f helm/values.local.yaml helm
      Replace
      • v6.x.x with a v6 release, preferably latest, found in GitHub such as v6.1.2.
      • <release-name> with installed helm release name
      • <platform> with openshift or aks depending on your platform

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 operatorsMongoDB 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

    Replace

    • v5.x.x with a v6 release, preferably latest, found in GitHub such as v5.0.0.

  • 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

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.

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.

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'

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

Administrator API

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,
    },
  },
};
  1. Run
npm i && npm run build
  1. 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