# Instiller

Integration type: Pre-defined

This guide details the processes required to integrate Apteco software with the Instiller email service provider (ESP).

## Integration options

- **FastStats**: for a one-off broadcast, use a combination of the Email Broadcasting and Email Responses wizards to upload your list, schedule a broadcast campaign, and receive responses back into your FastStats system.
- **PeopleStage**: automate data uploads for unattended and scheduled marketing broadcasts. PeopleStage lets you define and implement marketing process flow diagrams that react to the responses you receive from the ESP.
- **Export and upload a file**: access generic FTP support to export and upload data to third-party digital broadcast providers.

> [!NOTE]
>
> Apteco approves this integration with Instiller, combining Apteco software with Instiller software. Doing so doesn't affect the intellectual property rights indemnity provided in the Apteco software "End User Licence Agreement".

Instiller integrates with your FastStats system by utilising a RESTful transport over HTTP/S, in conjunction with SFTP.

## Before you begin

> [!WARNING]
>
> This guide assumes you have the relevant Apteco software system administration experience. This includes experience with the FastStats Administrator, SQL Server, and the areas of the Apteco software that relate to creating selections and campaigns. You need the appropriate system and SQL Server administrator permissions to install the relevant components successfully. You will also need access to the broadcaster web-based control panel and all the relevant information from Instiller.

**Useful to have before you start:**

- **Database Connection String** made up of the database server instance name and FastStats system name, for example: `;Initial Catalog=RS_;User Id=faststats_service;Password=N0tARealPassw0rd;`
- The **Digital Integration.zip** available from [apteco.com/portal/software-releases](<https://www.apteco.com/portal/software-releases>)
- Decide where to create your **FERG folders** (used to store the `.xml` and `.bat` files used when scheduling FERG; bulk insert folder must be reachable from SQL Server)
- Decide where to install the **FastStats Email Response Gatherer** (typically on the same server as the FERG folders, but can be on any PC)
- Virtual variables in FastStats to map to broadcast fields
- The Instiller UI address, Username, Password, and Personal Identification Number (PIN)
- The Instiller List Name and Message Name (available from the Instiller UI)
- The Instiller API Username, Password, Key, and ID

## Process summary

The following diagrams describe a typical process from FastStats to Instiller, to the customer, and back to FastStats.

1. The Email Broadcasting Wizard initialises a broadcast through the FastStats Web Service, inserting a job into the Web Service Control database (WS\_DB).
2. The FastStats Service picks this job up, uploads the list to the Instiller SFTP site and then uses RESTful communication to monitor the upload.
3. Instiller then imports the contents of this list to its subscribers and associates them with a list name ready for use in any email campaigns.
4. You can then schedule a campaign using the Instiller web interface.
5. Instiller sends messages to all recipients on the list.
6. Instiller records any undelivered messages.
7. Instiller records a response for each interaction with a message (for example opens and clicks).
8. A scheduled job on the FastStats server initiates the FastStats Email Response Gatherer (FERG) which checks the SFTP site for response files.
9. These responses are then imported into the Response database (RS\_DB) ready for analysis by your FastStats system.

The key difference in this process is that Instiller sends messages automatically, allowing full control of the campaign scheduling from within Apteco software.

> [!NOTE]
>
> For the message to send automatically, you need to create a Message in Instiller.

---

## Apteco system configuration

### Creating the response database

1. Open the **FastStats Configurator**.
2. Select **Database Management**.
3. Select the **Database Creation Wizard** option and select **Start Wizard**.
4. Enter the name of the **Database Server** where you wish to store the response database, then select **Test Connection**.

   > **Note**
   >
   > You can find the Database Server name by launching SQL Server Management Studio (SSMS). Find the SQL Instance for your FastStats system, for example `TDWIN10B\SQLExpress`.
5. Enter a System name (for example `Holidays`) and your secure password.
6. Select the **Email Response** check box, then select **Next**.

   > **Note**
   >
   > The Response Database may already exist. See the **Notes** column. If it does, select **X** to exit the installer without completing this process.
7. Select **Next** on the Review actions step.
8. Select **Run Scripts**, then select **Finish**.

### Linking the response database to the FastStats service

1. Open the **FastStats Configurator**.
2. Select **FastStats Services**.
3. Select the **FastStats Service** for the system to link to the response database, then select **Properties**.
4. Select the system tab, select **Email Broadcasting** from the list on the left, and enter the database connection string to your response database.
5. Select **Test Connection**, then select **OK** to close the dialog box.
6. Select **Save** from the File menu.

> [!NOTE]
>
> You need to restart the FastStats service to pick up the changes. Select **Restart** in the **Managed Services** dialog box.

---

## FastStats broadcasting and responses

> [!NOTE]
>
> You must log in as an administrator to perform the following tasks. The Email Broadcasting Wizard is for FastStats use only.

### Enable email broadcasting

1. Open the **FastStats Configurator**.
2. Select **Web Service**.
3. Select **OK** on the Web Service Chooser dialog box.
4. Select **Client Configuration**.
5. Select the Discoverer client associated with your system and select **Edit**.
6. On the Plugins tab, select the **Apteco.Discoverer.Plugins.EmailBroadcasting** check box, then select **OK**.

### Configuration in FastStats

1. Open Apteco FastStats, select the **Users** explorer, right-click on the **Global** node then navigate to **Modify** \> **Plugin Configurations**.
2. Expand the **Wizard** node then clear the **Inherit** check box for **Email Broadcasting (User Defined Fields)**, then select **Edit**.
3. Select **Add** to add a new template.
4. Enter a **Name**, select the appropriate **Resolve Table** from the drop-down, and select Instiller from the Broadcaster drop-down.

   > **Note**
   >
   > Scroll to enter the Known Parameters information. `*` indicates a required parameter.

   | Field | Setting |
   | --- | --- |
   | API Key | Your Instiller API Key |
   | API ID | Your Instiller API ID |
   | Email Field Name | Email Address |
   | Use Dated List | true |
   | Urn Field Name | Reference Number |
   | Field Map Name | Your Field Map |
   | Encoding | Default |

   > **Note**
   >
   > You need to exit out of FastStats and log in again for these changes to take effect.

### Adding a predefined broadcasting field set

As Instiller is a predefined digital integrator, you need to define a predefined output sequence which identifies the variables uploaded in your list.

> [!NOTE]
>
> You must set up a message in Instiller before performing this step. See Configuring Instiller below.

1. From FastStats select **Tools** \> **Administrative Functions** \> **Setup Broadcasting Fields**.
2. Select **Add New Broadcasting Field**.
3. Enter the **Set Name** to match the **Template Name** in Instiller.

   > **Note**
   >
   > Use the Set Name to associate each new output field with a set.
4. Select **Add New Broadcasting Field** and complete each **Update Broadcasting Field** dialogue until the list of broadcasting fields is complete.

   | Field | Description |
   | --- | --- |
   | Set Name | Template name in Instiller |
   | Variable | Select the Variable that you wish to include in your sequence |
   | Header (Optional) | Give the variable a name so that it matches the field name in your Instiller Message |
   | Output Style | Select Code or Description from the Output Style drop-down |
   | Output Unclassified as Spaces | Select this check-box if you wish unclassified values to appear as spaces, or if this variable is an email or SMS field |
   | Email Field | Select this check-box when defining the Email field |
   | SMS Field | Select this check-box when defining the SMS field |
   | Sequence ID | Lets you order your variables in the set |
5. At least one of the fields must be an **Email Address**.

   > **Note**
   >
   > You can create multiple templates and sets and then reference these separately from your email broadcasts.

### Checking your configuration

To use the Email Broadcasting Wizard, select the Email Broadcasting icon from the Output Wizards section on the Wizards panel. This sends a test email.

1. Select the Upload Template; if you have multiple upload sequences configured, select the template from the drop-down list and select **Next**.
2. Drag a selection from FastStats with the contacts you wish to send a test message to.

   > **Note**
   >
   > Email Broadcasting Details Form: 1. Enter the **Username**. 2. Enter the **Password**. 3. Select the **Message** retrieve button. 4. After a short while you should be able to use the drop-down list to see the available messages from Instiller. If you don't see a list, don't proceed. Something is wrong in a previous configuration.
3. Complete the **Email Broadcasting Details** form, then select **Finish**.

   | Field | Description |
   | --- | --- |
   | List Name drop-down | Select the List Name retrieve button and select a list from the drop-down (for Instiller, the Message defines the List) |
   | Message Name | Select the Message Name retrieve button and select one from the drop-down, or leave blank if you only want to upload your list |
   | A copy of the list is saved to the directory below | Browse to the location where you wish to save a copy of the list |
   | Email Address | Enter an Email Address. FastStats uses this to notify you once it processes the list |
4. If you entered a message name, a Broadcast Warning message displays. Select **Yes** to commit this action.
5. Once you've uploaded the list (and scheduled the message delivery if applicable), the wizard completes. Select **Finish** to close the wizard.

---

## Email responses

### Installing the email response gatherer

1. Download the FastStats Email Response Gatherer installer from the **DigitalIntegration.zip**, available here: [apteco.com/portal/software-releases](<https://www.apteco.com/portal/software-releases>). Extract the zip file to your designated server.
2. Open the **EmailResponseGatherer64Setup.msi** from the `DigitalIntegration\EmailResponseGatherer` folder.
3. Select **Next**, accept the terms, and select an installation directory (default: `C:\Program Files\Apteco\FastStats Email Response Gatherer x64`).
4. Select **Install**, then **Finish**.

### Creating the response gatherer folders

Create folders to store the files used with the Response Gatherer.

| Type of file | Description |
| --- | --- |
| Batch (`.bat`) | Contains the information for Task Scheduler or command-line programs to run the Response Gatherer on a schedule |
| XML (`.xml`) | Contains the connection and communication parameters used to connect to the broadcaster |
| Text files (`.txt`) | The Response Gatherer generates two log files each time it runs: an Event log and a Details log |

> [!WARNING]
>
> The bulk insert directory must be reachable from the SQL Server. The user running the SQL Server Service must have read permissions to it.

### Creating the configuration file

> [!NOTE]
>
> You can use the Response Gatherer with multiple integrations by using an XML and matching batch file for each integration.

1. Browse to the directory where you installed the Email Response Gatherer and open **EmailResponseConfig.exe**. Enter your Connection String and select **Test**.
2. Select **Instiller** from the Broadcaster drop-down list.
3. Enter the **Username** and **Password** to use with the Instiller API.
4. Use **Add** to add all the required parameters for the Broadcaster.
5. Use the **File** menu to save the XML file to the batch and XML file folder.

> [!NOTE]
>
> Instiller is a Predefined Broadcaster. The only required parameter is `FTPURL`. You can use the other fields if you need to customise the collection.

#### Email response database configuration parameters

| Parameter | Description |
| --- | --- |
| Connection String | The connection string to the response database for your system |
| Timeout (secs) | The timeout for the connection and query steps; default is 1200 seconds |
| Bulk insert folder | The location to store results for optimised processing of large campaign volumes |
| PeopleStage Connection String | Used for certain broadcasters; not applicable with Instiller |

### Scheduling the response gatherer

Set FERG to run on a scheduled basis by providing it with the broadcaster's communication details in a `.xml` configuration file. Also provide the location for log files.

**Creating the batch files**: Create or modify the batch file using Notepad++ or a similar text editor. Save it to the batch and XML file directory.

**Using Task Scheduler**:

1. Open Windows **Task Scheduler**.
2. Select **Create Basic Task** and give it a **Name** and **Description**, then select **Next**.
3. Select the **Trigger** interval and enter the **Start Date** and **Time**, then select **Next**.
4. Select **Start a program**, then select **Next**.
5. Select **Browse** and navigate to the folder containing your batch files. Select the file and select **Open**.
6. Optionally, provide the name of the XML configuration file in the **Add arguments** box, then select **Next**.
7. Check the **Summary**, then select **Finish**.

### Email responses wizard

1. Open the **Email Responses** wizard.
2. Enter the name of the message that you used in the Email Broadcasting wizard, then select **Next**.
3. As the Email Response Gatherer starts collecting information from Instiller, you will see how customers are interacting with your broadcast. Check **Create a virtual variable from this information** if required, then select **Next**.
4. Drag the Email variable that you used in the Email Broadcasting wizard onto the drop box, then select **Next**.
5. Locate the folder where you wish to store the virtual variable, then select **Next**, enter any notes, then select **Next**.
6. Enter a **Description** for the virtual variable or drag an existing virtual variable onto the drop box if you wish to overwrite it. Modify the Security Attributes if applicable, then select **Next**.
7. Select **OK**, then select **Finish**.

---

## PeopleStage broadcasting and responses

### Defining the broadcast channel in PeopleStage

1. Open PeopleStage, select **File** \> **Administration** \> **Channel Editor**.
2. Select **Add Email Channel** through the context menu.
3. Enter a name in **Channel Name**.

   > **Note**
   >
   > (Optional) Select Yes from **Allow In Transactional Output** if you need to send multiple emails to the same email address.

   | Field | Description |
   | --- | --- |
   | Broadcaster | Select Instiller from the drop-down |
   | Username | Enter your API username |
   | Password | Enter your API password |
   | Variable Name | Select Email Address from the drop-down |
   | Variable Description Override | Enter the description, for example "Email Address". This must correspond to the email field within Instiller |
   | Upload but don't broadcast | Optional: select to upload the list only without initiating a broadcast |
   | Append to List | Deselected |
   | Reply Email Address | The email address that will receive notifications when you use the channel (not the reply email address for the email send) |
   | Number of Retries | Recommended (for Broadcast Channels) to leave this at 0 |
   | Response File Key Type | Should be Communication Key for Instiller |
   | Message Content Type | Always Broadcaster Template |

   > **Note**
   >
   > The Encoding is always UTF8 in the code.

   | Field | Description |
   | --- | --- |
   | API Key | Your Instiller API Key |
   | API ID | Your Instiller API ID |
   | Field Map Name | Your Instiller Field Map Name |
   | Use Dated List | True |
   | Urn Field Name | Your Instiller Urn Field Name |
   | Email Field Name | Your Instiller Email Field Name |
   | Encoding | UTF8 |

   See [API parameters](<#api-parameters>) for all the available parameters.
4. Add any additional variables on the **Additional Variables** tab.

   > **Tip**
   >
   > You can map actual variables from your FastStats System, or use an empty Virtual Variable (VV) text field created in FastStats. Map this to the Instiller fields.
5. Select **Save &amp; Close**.

### Broadcasting in PeopleStage

1. Drag your new Instiller channel from the **Library** to your **Delivery step**.
2. Select from the available messages in Instiller from the Message Name drop-down, or use PeopleStage's functionality to dynamically select a message.
3. Deselect the **As above** check-box to use the same **List Name** as the **Message Name**.

Selecting the **Requires Manual Approval** check box gives the option to view an example list before processing.

---

## Configuring Instiller

To automatically broadcast the list to a message from the Email Broadcast wizard or PeopleStage, you need to create a message within Instiller. Use Instiller Templates to do this.

> [!NOTE]
>
> This section isn't intended as a full manual on setting up your messages in Instiller. Refer to the Instiller help or contact Instiller for more information.

Instiller requires the following items:

- **Field Maps**: create a new Field Map to select the columns required for the uploads from Apteco. Enter the Name, API Identifier, First Row Headings, and Field Delimiter. Add the required CSV Columns from User Profile and Custom Fields.
- **Templates**: create a Template to associate with the list uploaded from Apteco.

### Create new template

1. Select **New Template**.
2. Enter the **Subject Line**, **Description**, **API Identifier**, and **Email Profile**.
3. Under Content, for HTML Source Edit Content, create the email including any columns from the Fields Map.
4. Save your Template.

---

## API parameters

### Email response gatherer parameters

| Parameter | Response table field | Instiller extract file column |
| --- | --- | --- |
| MESSAGEPERIOD |  | Time to wait after sending the message before pulling back responses, for example `1D` or `2W` |
| COMMUNICATIONKEYCOLUMNNAME | CommunicationKey | FastStats Communication Key |
| ConstantFields |  | Pipe-delimited field of key value constants, separated by `#`, for example `Key1#Value1\\|Key2#Value2` |
| ADDITIONALFIELDS |  | Any additional fields |
| CLICKDATECOLUMNNAME | ClickDate | Date the recipient clicked the link |
| CLICKURLCOLUMNNAME | ClickUrl | The address of the link the recipient clicked |
| DATEFORMAT |  | Date format used, for example `dd.MM.yyyy HH:mm` |
| DELIVERYDATECOLUMNNAME | DeliveryDate | Delivery date |
| EMAILCOLUMNNAME | Email | Email address |
| EXECUTIONBUFFER |  | Adds a buffer in minutes to the start of the response window |
| EXPORTTYPES |  | Pipe-delimited response types to collect. Default: `delivered\\|hard\\|soft\\|returned\\|open\\|output\\|complaints\\|clicks_info` |
| LOCALTIMEZONE |  | Time zone to store dates in |
| MESSAGEENDDATE |  | Message end date. Format: `yyyy-mm-dd` |
| MESSAGESTARTDATE |  | Message start date. Format: `yyyy-mm-dd` |
| ONLYPROCESSRECORDSWITHBROADCASTID | false | If `true`, only downloads responses to messages that originated from FastStats |
| TYPECOLUMNNAME | MessageType | Response type |
| URNCOLUMNNAME | URN | FastStats Urn |

### Email broadcasting parameters

| Parameter | Default | Description |
| --- | --- | --- |
| Admin From Email |  | The from email address that sends administrative emails |
| DatedListFormat | `yyyyMMdd-HHmmss` | The date format string for the date and time stamp |
| Field Map Name |  | Name of the Field Map in Instiller |
| Email Field Name |  | Name of the Email Field in Instiller |
| Encoding | UTF8 | Enter the encoding of the incoming file |
| File Mapping |  | A pipe-delimited list of header values that will overwrite any defined in your output sequences |
| UseDatedList | True | Setting to `false` removes the date and time stamp from the end of the file name |
| Urn Field Name |  | Name of Urn Field in Instiller |
| Target Automations |  | Target automations rather than individual templates |

### Example batch file

Batchfile

```bat
@echo off
REM *** File Name: Instiller.bat ***
D:
cd D:\FastStats\FERG
cls
SET FERG="%ProgramFiles%\Apteco\FastStats Email Response Gatherer x64\EmailResponseGatherer64.exe"
SET LOGFILE="Logs\Instiller.txt"
SET LOGFILEDETAILS="Logs\Instiller_Details.txt"
echo. >> %LOGFILE%
echo. >> %LOGFILEDETAILS%
echo %date% %time% - Starting FastStats Instiller Response Download >> %LOGFILE%
echo %date% %time% - Starting FastStats Instiller Response Download >> %LOGFILEDETAILS%
%FERG% Instiller.xml >> %LOGFILEDETAILS%
IF ERRORLEVEL 9003 goto FailedException
IF ERRORLEVEL 9001 goto FailedDownload
IF ERRORLEVEL 9000 goto FailedLogin
:OK
echo %date% %time% - FastStats Gathered Instiller Responses OK >> %LOGFILE%
goto Complete
:FailedLogin
echo %date% %time% - FastStats Gatherer Failed - Login Failed to Instiller >> %LOGFILE%
goto Complete
:FailedDownload
echo %date% %time% - FastStats Gatherer Failed - Downloading from Instiller >> %LOGFILE%
goto Complete
:FailedException
echo %date% %time% - FastStats Gatherer Failed - Instiller API Exception >> %LOGFILE%
goto Complete
:Complete
echo %date% %time% - Completed FastStats Instiller Response Download >> %LOGFILE%
```

## Troubleshooting

### Error received when running the response gatherer using a batch file

Error: `Could not read email response configuration file: Could not find file D:\FastStats\FERG\Instiller.xml`

`Instiller.xml` refers to the filename referenced in the batch file at `%FERG% Instiller.xml`. The batch file sets the location using `cd D:\FastStats\FERG`.

**Solution**: Make sure the file exists at that path, or change the filename in the batch file to match.