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 allows you to 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 allow data export and upload 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 your FERG folders are to be created (used to store the .xml and .bat files used when scheduling FERG; bulk insert folder must be accessible from SQL Server)
• Decide where you want the FastStats Email Response Gatherer to be installed (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 URL, Username, Password, and PIN
• The Instiller List Name and Message Name (available from the Instiller UI)
• The Instiller API Username, Password, API Key, and API ID

Process summary¶

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

1. A broadcast is initialised through the FastStats Web Service 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 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. A campaign can then be scheduled 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 messages are sent from Instiller 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 click Start Wizard.

4. Enter the name of the Database Server where you wish to store the response database, then click Test Connection.

   

   Note

   The Database Server name can be found by launching SSMS and finding 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 click Next.

   

   Note

   The Response Database may already exist—see the Notes column. If it does, click X to exit the installer without completing this process.

7. Click Next on the Review actions step.

8. Click Run Scripts, then click Finish.

Linking the response database to the FastStats service¶

1. Open the FastStats Configurator.
2. Click FastStats Services.

3. Select the FastStats Service for the system to link to the response database, then click 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. Click Test Connection, then click OK to close the dialogue 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. Click OK on the Web Service Chooser dialogue box.

4. Click Client Configuration.

   

5. Select the Discoverer client associated with your system and click Edit.

   

6. On the Plugins tab, ensure the Apteco.Discoverer.Plugins.EmailBroadcasting check box is selected, then click 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 click Edit.

   

3. Click 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. Click 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. Click 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	Allows you to 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 click Next.

2. Drag a selection from FastStats with the contact(s) that you wish to send a test message to.

   

   Note

   Email Broadcasting Details Form: 1. Enter the Username. 2. Enter the Password. 3. Click 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 do not see a list, do not proceed—something is wrong in a previous configuration.

   

3. Complete the Email Broadcasting Details form, then click Finish.

   Field	Description
   List Name drop-down	Click on the List Name retrieve button and select a list from the drop-down (for Instiller, the List is defined by the Message)
   Message Name	Click on 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 the list has been processed

4. If you entered a message name, a Broadcast Warning message displays. Click Yes to commit this action.

5. Once the list has been uploaded (and if applicable the message delivery has been scheduled), the wizard will complete. Click 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. Click Next, accept the terms, and select an installation directory (default: C:\Program Files\Apteco\FastStats Email Response Gatherer x64).
4. Click 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 click 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) and the location for log files.

Creating the batch files: Create or modify the batch file using Notepad++ or a similar text editor, and save 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 click Next.
3. Select the Trigger interval and enter the Start Date and Time, then click Next.
4. Select Start a program, then click Next.
5. Click Browse and navigate to the folder containing your batch files. Select the file and click Open.
6. Optionally, provide the name of the XML configuration file in the Add arguments box, then click Next.
7. Check the Summary, then click 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 click 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 click Next.
4. Drag the Email variable that you used in the Email Broadcasting wizard onto the drop box, then click Next.
5. Locate the folder where you wish to store the virtual variable, then click Next, enter any notes, then click 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 click Next.
7. Click OK, then click Finish.

PeopleStage broadcasting and responses¶

Defining the broadcast channel in PeopleStage¶

1. Open PeopleStage, select File > Administration > Channel Editor.

2. Click 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 the channel is used (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 set to Communication Key for Instiller
   Message Content Type	Always Broadcaster Template

   Note

   The Encoding is set to 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 to map to the Instiller fields.

5. Click 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 a sample list before processing.

Configuring Instiller¶

If you wish to automatically broadcast the list to a message either from the Email Broadcast wizard or PeopleStage, you need to create a message within Instiller using Instiller Templates.

The following items are required in Instiller:

• 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 FERG 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 location is set by cd D:\FastStats\FERG in the batch file.

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