# Optimizely

Integration type: Pre-defined

## Documentation

- [Optimizely (Episerver) Integration Guide](<https://help.apteco.com/assets/pdfs/admin/D061T3X003_Episerver_Integration_Guide.pdf>)
- [Optimizely Broadcaster Setup Pages](<https://help.apteco.com/assets/pdfs/admin/061_Broadcaster_Setup_Pages.pdf>)

This guide details the processes required to integrate Apteco FastStats and PeopleStage with Optimizely.

## 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.
- **Export and upload a file**: access generic FTP support that lets you export and upload data.

> [!NOTE]
>
> Apteco approves this integration with Optimizely. Using Apteco software with Optimizely software through this integration won't affect the intellectual property rights indemnity in the Apteco software "End User Licence Agreement".

Optimizely 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 relevant Apteco software system administration experience, particularly with the FastStats Administrator and SQL Server. You should also be familiar with the areas of the Apteco software that relate to creating selections and campaigns. You need the appropriate system and SQL Server administrator permissions. You will also need access to the Optimizely web-based control panel.

**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** (the bulk insert folder must be reachable from SQL Server)
- Virtual variables in FastStats to map to broadcast fields
- The Optimizely UI address, Username, Password, and Personal Identification Number (PIN)
- The Optimizely List Name and Message Name (available from the Optimizely UI)
- The Optimizely API Username, Password, and Client ID

> [!NOTE]
>
> You will need to configure an Optimizely Smart Campaign and a Message. Optimizely has deprecated the Classic Mailings feature. See Optimizely's help on migrating a Classic mailing: [webhelp.optimizely.com](<https://webhelp.optimizely.com/latest/en/home.htm>)

## Process summary

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

1. The FastStats Web Service initialises a broadcast using the Email Broadcasting Wizard, which inserts a job into the Web Service Control database (WS\_DB).
2. The FastStats Service picks this job up, uploads the list to the Optimizely SFTP site, and then uses RESTful communication to monitor the upload.
3. Optimizely 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 Optimizely web interface.
5. Optimizely sends messages to all recipients on the list.
6. Optimizely records any undelivered messages.
7. Optimizely 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 Optimizely sends messages automatically, giving you full control of the campaign scheduling from within Apteco software.

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

---

## Apteco system configuration

### Creating the response database

1. Open the **FastStats Configurator** and select **Database Management**.
2. Select the **Database Creation Wizard** option and select **Start Wizard**.
3. Enter the name of the **Database Server** and select **Test Connection**.

   > **Note**
   >
   > You can find the Database Server name by launching SQL Server Management Studio (SSMS). Look for the SQL Instance for your FastStats system, for example `TDWIN10B\SQLExpress`.
4. Enter a System name and your secure password.
5. 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.
6. Select **Next** on the Review actions step, then select **Run Scripts**, then **Finish**.

### Linking the response database to the FastStats service

1. Open the **FastStats Configurator** and select **FastStats Services**.
2. Select the **FastStats Service** for the system to link to the response database, then select **Properties**.
3. Select the system tab, select **Email Broadcasting** from the list on the left, and enter the database connection string to your response database.
4. Select **Test Connection**, then select **OK**. 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.
>
> For broadcasts to work correctly, ensure that the FastStats server has access to the relevant FTP site through port 443. Optimizely requires you to set up an FTP site.

### Installing the email response gatherer

1. Download the FastStats Email Response Gatherer installer from the **DigitalIntegration.zip**, available at [apteco.com/portal/software-releases](<https://www.apteco.com/portal/software-releases>).
2. Open the **EmailResponseGatherer64Setup.msi** from the `DigitalIntegration\EmailResponseGatherer` folder.
3. Follow the installation wizard to completion. Default directory: `C:\Program Files\Apteco\FastStats Email Response Gatherer x64`.

### Creating the configuration file

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 **Optimizely** from the Broadcaster drop-down list.
3. Enter the **Username** and **Password** to use with the Optimizely 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]
>
> Optimizely is a Predefined Broadcaster. The only required parameter is `FTPURL`. You can use the other fields to customise the collection.

### Scheduling the response gatherer

Set FERG to run on a scheduled basis using Windows Task Scheduler:

1. Open Windows **Task Scheduler** and select **Create Basic Task**.
2. Enter 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**, select **Browse**, navigate to the folder containing your batch files, select the file, and select **Open**.
5. Check the **Summary**, then select **Finish**.

---

## FastStats broadcasting and responses

> [!NOTE]
>
> You must log in as an administrator to perform the following tasks.

### Enable email broadcasting

1. Open the **FastStats Configurator** \> **Web Service** \> select **OK** \> select **Client Configuration**.
2. Select the Discoverer client associated with your system and select **Edit**.
3. On the Plugins tab, confirm you have selected **Apteco.Discoverer.Plugins.EmailBroadcasting**, 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, clear the **Inherit** check box for **Email Broadcasting (User Defined Fields)**, then select **Edit**.
3. Select **Add** to add a new template. Enter a **Name**, select the appropriate **Resolve Table**, and select Optimizely from the Broadcaster drop-down.

   > **Note**
   >
   > FastStats refers to the Optimizely integration as Optivo.

   | Field | Setting |
   | --- | --- |
   | Client ID | Your Optimizely Client ID |
   | `URN` Field Name | `URN` |
   | Email Field Name | Email |
   | Use Dated List | false |
   | Template List Name | `*ClosedLoopWebServiceTemplate: master` |
   | Upload Only Folder | `%LISTNAME%` |
   | Upload and Broadcast Folder | `%LISTNAME%\%MESSAGENAME%` |
   | Use Closed Loop | true |
   | Closed Loop Layout | `*Kunden ID\\|Email\\|Salutation\\|Title\\|Firstname\\|Lastname\\|mobile\\|fon\\|fax\\|...\\|Communication Key` |
   | Encoding | UTF8 |

   > **Note**
   >
   > You need to exit out of FastStats and log in again for these changes to take effect. You need to create the additional fields in the same order as the pipe-delimited text in the **Closed Loop Layout**.

### Adding a predefined broadcasting field set

1. From FastStats select **Tools** \> **Administrative Functions** \> **Setup Broadcasting Fields**.
2. Select **Add New Broadcasting Field** and enter the **Set Name** to match the **Template Name** in Optimizely.
3. Select **Add New Broadcasting Field** and complete each **Update Broadcasting Field** dialog until the list of broadcasting fields is complete.

   | Field | Description |
   | --- | --- |
   | Set Name | Template name in Optimizely |
   | Variable | Select the Variable that you wish to include in your sequence |
   | Output Style | Select Code or Description |
   | 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 |
4. At least one of the fields must be an **Email Address**.

### Checking your configuration

1. Select the Email Broadcasting icon from the Output Wizards panel.
2. Select the Upload Template and select **Next**.
3. Drag a selection from FastStats with the contacts you wish to send a test message to.
4. Complete the **Email Broadcasting Details** form and select **Finish**.

   | Field | Description |
   | --- | --- |
   | List Name drop-down | Select the List Name retrieve button and select a list |
   | Message Name | Select the Message Name retrieve button and select a message |
   | Email Address | Enter an Email Address for notification once the system has processed the list |
5. If you entered a message name, a Broadcast Warning message displays. Select **Yes** to commit this action.

### Email responses wizard

1. Open the **Email Responses** wizard.
2. Enter the name of the message used in the Email Broadcasting wizard, then select **Next**.
3. Check **Create a virtual variable from this information** if required, then select **Next**.
4. Follow the remaining steps to store the virtual variable.

---

## 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. Enter a **Channel Name**.

   | Field | Description |
   | --- | --- |
   | Broadcaster | Select Optimizely 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". This must correspond to the email field within Optimizely |
   | Upload but don't broadcast | (Optional): select to upload the list only |
   | Response File Key Type | Should be Communication Key for Optimizely |
   | Message Content Type | Always Broadcaster Template |

   | Field | Setting |
   | --- | --- |
   | Client ID | Your Optimizely Client ID |
   | `URN` Field Name | `URN` |
   | Email Field Name | Email |
   | Use Dated List | false |
   | Template List Name | `*ClosedLoopWebServiceTemplate: master` |
   | Upload Only Folder | `%LISTNAME%` |
   | Upload and Broadcast Folder | `%LISTNAME%\%MESSAGENAME%` |
   | Use Closed Loop | true |
   | Closed Loop Layout | `*Person URN\\|Email\\|Salutation\\|Title\\|Firstname\\|Lastname\\|fon\\|Message\\|Discount\\|Communication Key` |
   | Encoding | UTF8 |

   > **Note**
   >
   > You need to create the additional fields in the same order as the pipe-delimited text in the **Closed Loop Layout** parameter.
3. Add any additional variables on the **Additional Variables** tab.
4. Select **Save &amp; Close**.

### Broadcasting in PeopleStage

1. Drag your new Optimizely channel from the **Library** to your **Delivery step**.
2. Select from the available messages in Optimizely from the Message Name drop-down.
3. Deselect the **As above** check-box to use the same **List Name** as the **Message Name**.

---

## Configuring Optimizely

If you wish to automatically broadcast the list to a message, you need to create a message within Optimizely using a Smart Campaign.

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

Optimizely requires the following items:

### Recipients

Create a Recipient list which includes yourself for initial testing. You can either create a recipient or Import a recipient to a list.

### Smart campaign

1. Create a Smart Campaign with the following minimum items: Recipients, Wait Step, and Message.
2. Connect the steps.
3. **Recipients**: select the list to use.
4. **Wait Step**: set to Wait until the import finishes.
5. **Message**: create an Email message and personalise.

> [!NOTE]
>
> You can migrate a Classic Mailing to a Smart Campaign, but you need to activate it.

> [!TIP]
>
> The **Smart Campaign** name is the **Message name** used in the PeopleStage Delivery.

---

## API parameters

| Parameter | Description |
| --- | --- |
| FTPURL | The FTP location (including username and password) where Optimizely generates your responses |

### Email response gatherer parameters

| Parameter | Response table field | Optimizely extract file column |
| --- | --- | --- |
| PEMPRIVATEKEY |  | Path and filename of a private key if secure FTP requires one |
| FILEPATTERN | Response\* | Filters your responses to specific types when reading files from the FTP site |
| EMAILCOLUMNNAME | Email | Email address |
| URNCOLUMNNAME | Urn | FastStats Urn |
| COMMUNICATIONKEYCOLUMNNAME | CommunicationKey | FastStats Communication Key |
| TYPECOLUMNNAME | MessageType | Response type |
| DELIVERYDATECOLUMNNAME | DeliveryDate | Delivery date |
| CLICKURLCOLUMNNAME | ClickUrl | The address of the link the recipient clicked |
| CLICKDATECOLUMNNAME | ClickDate | Date the recipient clicked the link |
| DATEFORMAT |  | Date format (e.g. `dd.MM.yyyy HH:mm`) |
| MAXRETRIES | 1000 | Number of times to check if the extract file exists on the FTP site |
| DELIMITER | Tab | Type of delimiter used in the extract file |
| LookupBroadcastIdsOnTheFly | false | If `true`, Optimizely fetches and caches Broadcast IDs as needed |
| OnlyProcessRecordsWithBroadcastId | false | If `true`, only processes responses that originated from FastStats |

### Email broadcasting parameters

| Parameter | Default | Description |
| --- | --- | --- |
| Client ID |  | Your Optimizely Client ID |
| Urn Field Name | Urn |  |
| Email Field Name | Email |  |
| UseDatedList | false | Setting to `false` removes the date and time stamp from the end of the file name |
| Template List Name |  | `*ClosedLoopWebServiceTemplate: master` |
| Upload Only Folder | `%LISTNAME%` |  |
| Upload and Broadcast Folder | `%LISTNAME%\%MESSAGENAME%` |  |
| Use Closed Loop | true | Setting to use with Smart Campaign |
| Closed Loop Layout |  | `*Person URN\\|Email\\|...\\|Communication Key` |
| UploadEmptyLists | true | Set to `false` to prevent uploading empty lists |
| DatedListFormat | `yyyyMMdd-HHmmss` | Date format string for the date and time stamp |
| MaxImportWaitTime | 7200 | Maximum time to wait for Optimizely to import a list, in seconds |
| Encoding | UTF8 | Encoding of the incoming file |
| MailingListRetentionPeriod | 0 | Number of days to keep the uploaded mailing list |

### Example batch file

Batchfile

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

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

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