IEM Patch Installation

This document describes how to install and configure GreenArrow Engine’s IEM Patch. It starts with a list of what GreenArrow will need to install this patch for you. This is followed by installation instructions, in case you’d like to install the patch yourself, or are curious about what’s done during the patch installation process.

Information Needed by GreenArrow

In order for GreenArrow to install GreenArrow Engine’s IEM integration patch, we’ll need the following information:

An SSH account with permission edit your IEM installation’s files, upload new files, and create new cron jobs.
Login information for an IEM user who is able to edit their SMTP server settings. This will be needed to send a test campaign following the patch installation.
If your IEM installation’s database is running on a different physical server than your GreenArrow Engine installation, root level access to your operating system and database will be needed so that your database can be configured to allow remote connections. If you’re using MySQL, the root level user is typically named root, and if you’re running PostgreSQL, the root level user is typically named postgres. Alternatively, you can perform the steps listed in the MySQL or PostgreSQL section below if you’d prefer not to grant this level of access.

Installation Instructions

MySQL

Most IEM installations use email_ as a prefix to their table names. If your installation uses a different prefix, or none at all, update the the table names in these instructions to match your installation.

Run the following MySQL commands on the same database that IEM uses. We recommend running these commands while logged in as the same MySQL user that IEM uses, so that this user will have the correct permissions on the email_greenarrow_queue table:

ALTER TABLE email_lists ADD COLUMN mailroute varchar(100);
CREATE TABLE email_greenarrow_queue (
id int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY,
event_type varchar(15) NOT NULL,
listid varchar(255),
email varchar(255),
statid varchar(255),
bounce_type varchar(255),
bounce_rule varchar(255),
bounce_message varchar(255),
bounce_time int(11)
);

Grant the MySQL account that IEM is using permission to SELECT and DELETE rows in the email_greenarrow_queue table. If you created this table while logged in with the MySQL account that IEM is using, then these permissions should be present by default.
Create a MySQL account that has permission to SELECT and INSERT rows in the email_greenarrow_queue table. For example you could login as the MySQL root user, then run the following two commands, replacing iem_db with your database name, 127.0.0.1 with the IP address that connections will be coming from, and password with the actual password to assign to the new user:
```
CREATE USER 'greenarrow'@'127.0.0.1' IDENTIFIED BY 'password';
GRANT SELECT, INSERT ON iem_db.email_greenarrow_queue TO 'greenarrow'@'127.0.0.1';
```
If your MySQL installation is running on a different physical server than your GreenArrow Engine installation, verify that the MySQL server is configured to accept connections remotely, and that there are no firewall rules that would prevent a MySQL user from logging in from your GreenArrow Engine server. GreenArrow’s base IP address can be determined by contacting GreenArrow technical support, or running the following command on your GreenArrow server.
```
curl http://automation.whatismyip.com/n09230945.asp && echo
```

PostgreSQL

Most IEM installations use MySQL as their database. If your installation uses PostgreSQL, contact GreenArrow technical support for details on how to configure it.

Patch Installation

There are three versions of the patch:

IEM Patch 1.07 - For IEM 6.1.3 and 6.1.4 installations.
IEM Patch 1.06 - For IEM 6.1.2 installations that have the bugfix described on this page applied.
IEM Patch 1.05 - For IEM 6.1.2 installations.

These instructions assume that you’re applying version 1.07 of the patch. If that’s not the case, you’ll need to update some of the commands to match the version that you are applying.

Change to the parent directory of your IEM installation’s document root. For example, this might be /var/www/html:
```
cd /var/www/html
```

Download the patch:

wget https://www.greenarrowemail.com/docs/downloads/iem-greenarrow-patch-1.07.patch

Create a pre-patch copy of IEM in case any bugs are discovered that Interspire tech support is needed for. For example, if IEM is installed in the iem directory, you could run:
```
cp -a iem iem.prestine
```

Test if the patch will apply cleanly:

cd iem
patch -p1 --dry-run < ../iem-greenarrow-patch-1.07.patch

If you are installing this on an unmodified version of IEM Version 6.1.4, we have seen some cases where all “hunks” of this patch will fail. If --dry-run is showing 100% failure, you can try running this:

dos2unix admin/com/ext/interspire_email/email.php admin/com/ext/interspire_email/email.php admin/com/install/schema.mysql.php admin/com/install/schema.pgsql.php admin/com/language/default/stats.php admin/com/templates/lists_form.tpl admin/com/templates/send_step3.tpl admin/functions/api/jobs_autoresponders.php form.php

You would then need to re-run the --dry-run to see if this fixed the failures.

Apply the patch:

patch -p1 < ../iem-greenarrow-patch-1.07.patch

Verify that the file ownership and permissions are set properly.

Patch Configuration

Verify the following settings in the admin/includes/config_greenarrow.php file:
1. GREENARROW_INTEGRATION_ENABLED - set to 1 to enable the patch’s functionality, or 0 to disable it.
```
GREENARROW_INTEGRATION_ENABLED=1
```
2. GREENARROW_SENDID_LISTID_PREFIX - gives a unique alphabetical ListID prefixes to each IEM installation that you’re using, so that GreenArrow Engine will know which installation to send bounce and spam complaint data back to. This is a short alphabetical string, such as z and is not case sensitive:
```
GREENARROW_SENDID_LISTID_PREFIX=z
```
Create a new crontab entry for the same user that’s running IEM’s send.php process. If GreenArrow Engine is not installed on the same server as IEM, or not installed in the default location, then you’ll need to adjust the path to PHP to match your server’s configuration. A typical <iem_install_path> value is /var/hvmail/apache/htdocs/iem:
```
# IEM / GreenArrow Integration
* * * * * /var/hvmail/apache/php/bin/php -f <iem_install_path>/admin/cron/greenarrow_integrate.php
```

GreenArrow Engine Configuration

This is not currently documented. Please contact GreenArrow technical support with the following information for each IEM installation, so that GreenArrow’s can be properly configured to hand bounce and spam complaint data off to IEM:

Login info for the MySQL or PostgreSQL user that will insert rows into the email_greenarrow_queue table:
1. Username
2. Password
3. Database name
4. Database type (MySQL or PostgreSQL)
5. Address of the database server (IP address or fully qualified domain name).
The alphabetical ListID prefix being used by the installation. For example, z.

IEM Configuration

This is the final step to perform before conducting end-to-end testing. The IEM Patch Usage Instructions document describes how to configure IEM.

Testing

GreenArrow technical support can perform end-to-end testing for you. If you’d like us to do this, please contact us with login information for an IEM user who is able to edit their SMTP server settings.

Reversing the Patch

If you need to reverse the patch for some reason, the files that are modified by it are listed below:

admin/com/ext/interspire_email/email.php
admin/com/install/schema.mysql.php
admin/com/install/schema.pgsql.php
admin/com/language/default/stats.php
admin/com/templates/lists_form.tpl
admin/com/templates/send_step3.tpl
admin/functions/api/jobs_autoresponders.php
admin/functions/api/lists.php
admin/functions/api/send.php
admin/functions/api/subscribers.php
admin/functions/lists.php
admin/functions/send.php
form.php

You can reverse the patch by either restoring the original copies of each of the above files, or by using a patch command, as shown below:

patch -R -p1 < iem-greenarrow-patch-1.07.patch