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.

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

Before you begin¶

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=fa5t5tat5;
• The Digital Integration.zip available from 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.

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.

FastStats broadcasting and responses¶

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.

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

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

Email response database configuration parameters¶

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 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 & 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.

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¶

Email broadcasting parameters¶

Example batch file¶

@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.