External Target Lists

Introduction

A Targeting in Actito is a selection of profiles. It can be computed from criteria based on your licence data, or defined simply as a list of profile IDs provided in a file.

For mass campaigns, a target file can be uploaded via API call. However, this approach doesn't work for continuous processes — it is not compatible with active campaigns.

If you need to periodically trigger scenarios or campaigns with a target that changes daily and want to automate that update, the solution is an external target list.

Practical example:

• Your external tool computes profile lists for promotional or segmentation purposes, based on data not stored in Actito (e.g. cold or operational data)
• These lists are exported to an FTPS server
• Every day, a scenario is triggered to send an email to the profiles selected by your external tool

How external target lists work

External target lists are driven by files generated by your external tool, dropped onto a file transfer location (FTPS or SFTP), and automatically retrieved by Actito upon detection.

The retrieved file becomes available as a targeting criterion that can be used to trigger scenarios and campaigns, or to calculate segmentations. A validity period can be configured to ensure the file expires after a set amount of time — preventing profiles from being targeted repeatedly if your external tool encounters issues.

Setting up an external target list

Steps overview

1. Define the file transfer location
   • 1a. List existing file transfer locations
   • 1b. (Optional) Create a new file transfer location
2. Set up a file synchronization
3. Set up an external target list

Step 1a. List the file transfer locations in your licence

File transfer configurations are FTP(S) or SFTP servers used to move data between your external tool and Actito.

The server can be:

• Provided by Actito — always uses the FTPS protocol, set up by the Actito team
• Your own server — supports FTP(S) and SFTP (unsecured FTP is supported but not recommended)

To retrieve your file transfer configurations:

GET /file-transfers/v5/entities/MyEntity/filetransfer-configs

Example response:

{
  "_embedded": {
    "configurations": [
      {
        "id": "123456",
        "name": "An_Actito_FTP",
        "displayName": "Actito FTP",
        "connection": {
          "serverType": "FTP",
          "parameters": {
            "host": "ftp.actito.com",
            "port": 21,
            "passiveMode": true,
            "encryption": "EXPLICIT_OVER_TLS"
          },
          "authentication": {
            "type": "LOGINPASSWORD",
            "login": "actito"
          }
        }
      }
    ]
  }
}

Note the id of the Actito FTPS config. Then retrieve its locations (the directories of the server):

GET /file-transfers/v5/entities/MyEntity/filetransfer-configs/123456/locations

Example response:

{
  "_embedded": {
    "locations": [
      {
        "id": "987321",
        "name": "incoming_folder",
        "displayName": "Incoming Folder",
        "path": "/IN"
      },
      {
        "id": "987654",
        "name": "outgoing_folder",
        "displayName": "Outgoing Folder",
        "path": "/OUT"
      }
    ]
  }
}

Note the id of the /IN folder — this is where your files will be dropped.

tip

To drop files on the Actito FTPS, the IP address of your external tool must be whitelisted. Contact support or your account manager.

Step 1b. Create a new file transfer location (optional)

If you want to use your own server, create a file transfer config using the API specs:

POST /file-transfers/v5/entities/MyEntity/filetransfer-configs

Example — SFTP with SSH private key:

{
  "name": "SFTP_3RD_PARTY",
  "displayName": "SFTP Third Party",
  "connection": {
    "serverType": "SFTP",
    "parameters": {
      "host": "sftp.thirdparty.com",
      "port": 22
    },
    "authentication": {
      "type": "PRIVATE_KEY",
      "login": "actito"
    }
  }
}

Note the id from the response. For private key SFTP, also generate the key:

POST /file-transfers/v5/entities/MyEntity/filetransfer-configs/456789/generate-ssh-private-key

This returns the public key needed to configure your server. Then create the location:

POST /file-transfers/v5/entities/MyEntity/filetransfer-configs/456789/locations

{
  "name": "input_folder",
  "displayName": "Input folder",
  "path": "/IN"
}

Note the id from the response.

caution

If using your own server, you must provide its IP address to Actito for whitelisting. Contact support or your account manager.

Step 2. Set up a file synchronization

A file synchronization defines the active polling that automatically retrieves a file when it is detected on the FTP server.

info

File synchronizations are used in two Actito concepts:

• External target lists — to select existing profiles for use in a targeting (as described here)
• Triggered ETLs — to import file content into your Actito tables

When using an external target list, the profile IDs in the synchronized file must already exist in your profile table. Unknown IDs are ignored — any new data must be synced first.

POST /file-transfers/v5/entities/MyEntity/file-synchronizations

Example request body:

{
  "name": "external-target-calculation-filesync",
  "userName": "External Target Integration Flow",
  "location": {
    "type": "REMOTE",
    "remoteLocationId": "1"
  },
  "fileDescription": {
    "fileNamePattern": "external_target_$yyyyMMdd.csv",
    "mimeType": "text/csv"
  },
  "paused": false,
  "postAction": {
    "type": "DELETE"
  }
}

• remoteLocationId — the file transfer location ID from Step 1
• fileNamePattern — various date patterns are accepted; the declared mimeType must match the file extension
• Both TXT and CSV files are supported (including zipped archives). Since only a single column of IDs is needed, TXT is recommended

Note the id from the response.

Limits

• Maximum file size: 50 MB
• Maximum file synchronizations per licence: 60
• Maximum file retrievals per day (shared between triggered ETLs and external target lists): 600

Step 3. Set up an external target list

POST /external-target-lists/v5/entities/MyEntity/target-lists

Example request body:

{
  "name": "externalSegmentation",
  "displayName": "External Segmentation",
  "feeding": {
    "type": "FILE_SYNCHRONIZATION",
    "fileSynchronizationId": "12"
  },
  "validityRule": {
    "period": {
      "timeUnit": "DAY",
      "length": 1
    },
    "untilTime": "10:00"
  },
  "reportRecipients": [
    "report@actito.com"
  ]
}

• fileSynchronizationId — the ID from Step 2
• validityRule — defines how long the last retrieved file remains valid. Once expired, any targeting using it will error and no automated process will be triggered

tip

Set the validity period to just under the scheduled frequency of your marketing action. This ensures that if your file sync fails, campaigns won't re-trigger with a stale target.

Using an external target list

Once configured, users can select an external target list in the Actito interface by activating expert mode and choosing the File targeting module (see documentation).

The Expiration date column shows how long the current file remains valid.

caution

If using a CSV file, inform interface users of the separator and header name — these must be entered manually without autofill when defining targeting criteria.

Targetings referencing an external list can be used to automatically refresh a profile selection in:

• Saved targetings that trigger a scenario
• Newsletter campaigns
• Segmentation rules