GreenArrow Email Software Documentation

Upgrade From Legacy Event Processor

Introduction

This guide will walk you through what you need to do to upgrade from the Legacy Event Processor and the Legacy Delivery Attempt Log to the “latest and greatest.” For an introduction to the event processor, and to see a description of what’s different about it – see the Event Processor documentation.

The legacy event processor was configured using a variety of different files:

/var/hvmail/control/record_events.simplemh.scomp
/var/hvmail/control/record_events.simplemh.bounce_all
/var/hvmail/control/record_events.simplemh.bounce_bad_address
/var/hvmail/control/record_events.simplemh.unsub
/var/hvmail/control/record_events.simplemh.open
/var/hvmail/control/record_events.simplemh.click
/var/hvmail/control/record_events.delivery_attempt.json
/var/hvmail/control/event_processor.json
/var/hvmail/control/delivery_attempt_logfile.json

And for Studio, events were controlled using database fields.

While the legacy event processor will continue to be supported in its current state (i.e. new features will not be added to it, but we will maintain support for it in the form of any relevant bug fixes), we encourage all customers to adapt to the new event processor as they are ready to make the migration.

The new event processor is controlled by our single configuration file:

/var/hvmail/control/greenarrow.conf

This guide will walk you through converting to the new event processor.

Questions About Upgrading

What are the advantages to upgrading?

  1. Deliver the same events to multiple destinations.

  2. Deliver in batches, leading to event delivery efficiency.

  3. Configure in greenarrow.conf, as opposed to many different configuration files.

  4. Events are delivered faster – typically within a few seconds of event occurrence.

Can I upgrade to the new event processor?

Yes, you can upgrade to the new event processor! The new event processor supports all features of the Legacy Event Processor.

What versions of GreenArrow support the new event processor?

GreenArrow v4.270.0 and beyond support the new event processor.

What if I’m using the legacy event processor’s ability to filter events by mail class?

The automatic configuration converter documented below does not handle this case. However, the new event processor does support this. See the event_delivery_filter_mail_class directive for more information, or contact GreenArrow Technical Support for assistance.

What if I’m using the legacy event processor’s ability to write events to a logfile?

Good news! As of GreenArrow v4.285.0 the new event processor supports writing to logfiles. You can simply follow the upgrade instructions below and you will be converted to the new logfile.

What if I’m using the Legacy Delivery Attempt Log to deliver events to a logfile or a program?

If you’re using the Legacy Delivery Attempt Log to deliver events to a logfile or a program, you’ll need to carry out a special step while upgrading to the new event processor. Those steps are described in the Upgrade Procedure below.

Upgrade Procedure

You can upgrade to the new event processor “atomically” – meaning that if you follow this procedure, no duplicate events will be generated (and no events will be missed).

(1) Determine if you’re using the Legacy Delivery Attempt Log

You can determine if you’re using the Legacy Delivery Attempt Log by running the following command:

grep enabled /var/hvmail/control/delivery_attempt_logfile.json

If it shows something like "enabled": true, or "enabled": 1, then you’re using the Delivery Attempt Log.

In that case, you’ll now need to stop the logfile writer:

svc -d /service/hvmail-logfile-writer

Stopping the logfile writer during the upgrade procedure will ensure that duplicate events do not get delivered to your logfile/program in the transition.

(2) Determine your new greenarrow.conf configuration

Start by running the following command. If you are a candidate for the new event processor, it will emit the greenarrow.conf syntax needed to deliver your events using the new event processor.

$ greenarrow events convert_legacy_configuration
event_delivery_destination destination-1 {
  event_delivery_url `http://example.com`
  event_delivery_events engine_open, bounce_bad_address.studio, studio_subscriber_created
  event_delivery_disable_batching yes
  event_delivery_format json
  event_delivery_serialize_all_columns yes
}

If the above command gives you an error, it’ll describe the reason your configuration isn’t compatible for easy conversion to the new event processor.

Otherwise, copy and paste the event_delivery_destination block(s) to your /var/hvmail/control/greenarrow.conf configuration file.

Do not reload configuration at this time.

(3) Disable legacy event creation

Run the following to disable legacy event creation:

echo 0 > /var/hvmail/control/record_events.simplemh.scomp
echo 0 > /var/hvmail/control/record_events.simplemh.bounce_all
echo 0 > /var/hvmail/control/record_events.simplemh.bounce_bad_address
echo 0 > /var/hvmail/control/record_events.simplemh.unsub
echo 0 > /var/hvmail/control/record_events.simplemh.open
echo 0 > /var/hvmail/control/record_events.simplemh.click


$ /var/hvmail/postgres/default/bin/psql -U greenarrow greenarrow -c '
  UPDATE s_system_configs SET
    event_notification_studio_click=false,
    event_notification_studio_open=false,
    event_notification_studio_unsub=false,
    event_notification_bounce_all=false,
    event_notification_bounce_bad_address=false,
    event_notification_scomp=false,
    event_notification_studio_subscriber_created=false,
    event_notification_studio_subscriber_updated=false;
'

Edit the following file and set the enabled key to false:

/var/hvmail/control/record_events.delivery_attempt.json

(4) Reload configuration to activate the above changes

Run GreenArrow’s standard configuration reload to activate the changes you made above:

greenarrow_config reload

(5) Wait for the legacy event processor’s queue to drain

Monitor the following command, waiting for the __legacy__ event destination’s queue to drain to 0:

$ greenarrow events status
+------------------+-----------------------------+-----------------------+
| Destination Name | Event Count (First Attempt) | Event Count (Retries) |
+------------------+-----------------------------+-----------------------+
| destination-1    |                           0 |                     0 |
| __legacy__       |                         100 |                   n/a |
+------------------+-----------------------------+-----------------------+

(6) Remove the legacy event processor’s configuration

Now you can edit the following file:

/var/hvmail/control/event_processor.json

Typically you can replace its contents with this in order to disable event delivery:

{
  "event_destinations": [
    {
      "matches": {
        "all": true
      },
      "destination": {
        "type": "drop_from_queue"
      }
    }
  ],
  "use_json_for_http_post": true
}

(7) Disable the Legacy Delivery Attempt Log and restart the logfile writer

If in Step 1 above you determined that you’re using the Legacy Delivery Attempt Log then you’ll want to disable it now.

To do this, edit the following file:

/var/hvmail/control/delivery_attempt_logfile.json

Typically you can replace its contents with this:

{
  "enabled": false,
  "filename": "",
  "filename_append_date": false,
  "pipe_command": "",
  "format": "json",
  "include_status": {
    "success": true,
    "deferral": false,
    "failure": true,
    "failure_toolong": true,
    "connmaxout": false
  },
  "include_first_attempt_regardless_of_status": true,
  "include_local_channel": false
}

Now you can restart the logfile writer to resume normal operation:

svc -u /service/hvmail-logfile-writer

 Legacy Event Processor
Network Services 

Copyright © 2012–2023 GreenArrow Email