Jump to: navigation, search

List Automation

Use the List Automation feature to scan FTP sites for lists matching a specified rule criteria. When a list matching the criteria is found, one of the following occurs:

  • The list is loaded into Engage as a contact list.
  • The list is loaded into Engage, which then initiates a sub-campaign.
  • Contacts within the list are appended to a suppression list.

Creating a List Automation Job

To create a new list automation job, go to the Lists-->List Automation page and click New. Give the job a name, and then specify the following:

Schedule

Specify the day, time, and frequency of runs. In other words, specify when and how often the system should scan an FTP site in search of a list matching your rule criteria. Scheduling runs can be done in one of two ways:

Scheduling Options

To choose from the available scheduling options, click the Schedule radio button and specify the following:

  • Schedules every - This is the frequency of the run. For example, if you schedule a run on Wednesday from 1 pm to 2 pm, and in this field you select 15 minutes, four runs will take place between 1 pm and 2 pm on Wednesday. Minimum frequency is 15 minutes; maximum is 60 minutes.
  • Day/s of the Week - The day/s in which the run will take place. You can select one or multiple days of the week, or you can select All if you want the run to take place every day for this particular job.
  • Start time - This is the time the list automation task becomes active each day and the first time the system will look for a file.
  • End time - This is the time the task becomes inactive. If, for example, you set it to 8 pm, the task will become inactive at 8 pm and the system will stop making FTP connection attempts.
  • Time Zone - The time zone associated with the start and end time of the run.

Cron Expression

Alternatively, you can click the Crontab string radio button and enter a string of five values that represent a run schedule and frequency. The system will convert the string into a time interval and schedule the run/s accordingly.

Important
The following syntax rules apply:
  • There should be five fields. If you choose not to enter an integer in a field, use an asterisk to replace it.
  • Each field is separated by one space (for example 15 * * * *, not 15****).
  • If a field contains a series of integers separated by commas, spaces are not permitted between the integers and commas (for example 15,30,45, not 15, 30, 45).
  • If a field contains a range of values, do not enter a space within the field (for example, 15-30, not 15 - 30).
  • Wildcards are not supported in the Minute field, and job runs are limited to a maximum of 12 runs per hour.

The tables below present the following information:


Cron Fields and Values

The following image represents a Crontab (Cron table) and the table below it describes the supported fields and values in a Cron string.

thumb|center|500px|Crontab

Field Description Supported Values
1 Minute 0 to 59 (Note: wildcards are not supported in this field)
2 Hour 0 to 23, or * for no specific value
3 Day of Month 1 to 31, or * for no specific value
4 Month 1 to 12, or * for no specific value
5 Day of Week 0 to 6 (0 represents Sunday), or * for no specific value

Supported Cron Notations

The table below lists supported notations within a Cron string.

Notation Description
Asterisks (*)

This is a wildcard used in place of integers.
For example, if you specify 15 in the Minute field but insert an asterisk (*) in the Hour field, the command becomes Execute a run 15 minutes past every hour.
Note: Wildcards are not supported in the Minute field.

Commas (,)

Used to separate values in a single field.
For example, if you specify 15,30,45 in the Minute field, the command becomes Execute a run 15, 30, and 45 minutes past the specified hour.

Important
Remember - do not insert spaces between integers and commas. For example, write 15,30,45 instead of 15, 30, 45. Otherwise, the system will throw an error.
Dashes (-)

Used to denote a numerical range.
For example, if you specify 15-30 in the Minute field, the command becomes Execute a run every minute between 15 and 30 minutes (inclusive) past the specified hour.

Important
Remember - do not insert spaces within the field. For example, write 15-30 instead of 15 - 30. Otherwise, the system will throw an error.

Cron Examples

The table below lists valid Cron examples.

String Description
15 * * * * Executes a run at 15 minutes past the hour, every hour.
0 17 * * 3 Executes a run at 5 pm on Wednesday.
15-30 7 * * 0 Executes a run every minute between 15 and 30 minutes (inclusive) past 7 am on Sunday.
15 14 * * 1,3,4 Executes a run at 2:15 pm on Monday, Wednesday, and Thursday.
0 3 8 9 2,3 Executes a run at 3 am on the 8th of the month AND on Tuesday and Wednesday in September.

File Transfer Options

Specify the FTP site and the login credentials used to access it. Supported FTP address formats are as follows:

  • ftp://hostname/[directory]
  • sftp://hostname/[directory]
  • ftp:hostname/[directory]
  • sftp:hostname/[directory]

Next, leave the Delete files after import box checked (recommended) to delete the files from the FTP site after they've been imported into Engage. If you uncheck the box (not recommended), the file will remain on the remote site.

Send Notification

In the Send Notification section of the page, indicate if you want the results of a run to be sent to the email address you specify on the Events page. To specify the email address:

  1. Go to Settings-->Events.
  2. Click the Event Notification tab.
  3. In the List Automation section, check the box next to List failure and/or List successfully loaded and enter the email address for the notification.

Rules

When the system scans an FTP site and finds a list, the action it takes from that point on will be determined by the rules you set in this section.

To start, select one of the following from the Action type menu:

  • Import file - Saves it as a contact list in Engage. It appears on the Lists page with all other contact lists.
  • Send new outbound - Loads the list into Engage and initiates a sub-campaign using that list from the campaign specified in the Campaign menu.
  • Suppress file - Appends the contacts within the list to an existing suppression list.

The table below describes each rule and identifies its associated action type.

Tip
You can add multiple sets of rules by clicking the plus sign (+) to the far right of a rule set.
Rule Action Type Description
File format operation Applies to all action types Select an operator from the list. This is used to narrow the search for files on an FTP site. See the example below.
File name format Applies to all action types

Specify the full or partial name of a file, depending on the operator you selected.

Important
To mitigate the risk of retrieving the wrong file or skewing auditing results, you should always use unique and descriptive file naming conventions.

For example, let's say you're looking for a CSV file that contains the word Collections in the file name. From the File format operation list, select the operator Contains, and then in the File name format box, type Collections. If, during the run, the system sees a file that contains Collections in its name, it will grab the list and load it into Engage.

Days of the week Applies to all action types

Select the day/s of the week to apply the rule.

You can select one or multiple days, or you can select All to include every day of the week.

Suppression list Suppress file

Select the suppression list for the contacts being loaded into Engage.

Related Documentation: Suppression Lists

Upload rule (Optional)
  • Import file
  • Send new outbound

Apply an upload rule to a list being loaded into Engage. If you use an upload rule, the Specification file option is removed because upload rules already contain specification files.

Important
The following tokens are supported:
  • <ACCOUNT> - account name
  • <ACCOUNT_UID> - account uid
  • <DATE:yyyyMMdd> - date format


Related Documentation: List Rules

Specification file (Optional) Applies to all action types.

Apply a specification file to a list being loaded into Engage. This field will not apply if you've selected an upload rule because the upload rule already contains a specification file.

Related Documentation: Specification Files

Campaign
Send new outbound

Select the campaign that will use the list being loaded into Engage.

Related Documentation: Campaign Configuration

Strategy Send new outbound

Select the associated strategy for the campaign and list.

Related Documentation: Templates and Strategies

List Automation Job Details

When you create a new list automation job, the details and status of the job appear in a table on the Lists-->List Automation page. The table contains the following fields:

  • Name - The job name.
  • List Source - Your username to the FTP site and the FTP site address. For example johnsmith@ftp.xyz.com.
  • Last Run - The date and time the system last scanned the FTP site for a list matching your rules.
  • Status - The current status of the job.
  • Modified - The date and time you created or modified the job.
  • Schedule - The scheduled start day and start and end time. If you used a Cron expression, the string is displayed here.
  • #Success - An accumulation of successful runs. For example, if the system finds and uploads a list on three runs, the number 3 will display in this field.
  • #Failures - An accumulation of failed runs. Examples of a failed run could include a failed connection to an FTP site or a partial file transfer. It does not count or display the number of times the system executed a run but failed to locate a list matching the rule criteria. If there are any failed runs, a download icon will appear next to the total. Click the icon to view the details of each failed run.
  • Actions -
    • Run Now - Activates a run immediately. The originally scheduled run will still take place.
    • Disable List Automation - Stops all subsequent runs. Disabling a list automation doesn't delete the job from the job list. You can open and edit the job at any time to reschedule runs or hit the Play icon to restart it.
    • Delete List Automation - Deletes the job entirely.
    • History - See Job History below for more information.

ListAuto JobandHistory.png

Job History

From the Lists-->List Automation page, you can click Job History (document icon) to open the View History page for that job. The following information displays for each run.

  • Last Run - the date and time of the last run.
  • Duration - the duration of the run.
  • Status - The status of the run.
  • #Success - An accumulation of successful runs. For example, if the system finds and uploads a list on three runs, the number 3 will display in this field.
  • #Failures - An accumulation of failed runs. Examples of a failed run could include a failed connection to an FTP site or a partial file transfer. It does not count or display the number of times the system executed a run but failed to locate a list matching the rule criteria. If there are any failed runs, a download icon will appear next to the total. Click the icon to view the details of each failed run.

Related Topics

This page was last edited on February 14, 2019, at 16:43.
Comments or questions about this documentation? Contact us for support!