Introduction

Carma Autoimport enables you to automatically synchronize recipient data from your databases into Carma lists.

 

Here is a scenario that explains the basics of Carma Autoimport:

A CRM system is collecting email addresses and phone numbers to clients who wish to be contacted. A database administrator set up a scheduled job to once every day export a portion of these addresses and phone numbers to a text file. The text file is then placed on Carma’s file server.
The Autoimport function in Carma is configured to pick up the file placed on the server and populate a list in Carma with its content.

 

Setup overview

The setup of an Autoimport consists of five parts:

1. Compost supplies this document and FTP1 login information

2. A Carma account administrator supplies user login information to Carma

3. The customer creates a file according to the file format specifications

4. A scheduled import needs to be set up that connects a specific filename with a specific list and also handles the scheduling on how often the system will look for a new file

5. To map the correct column header in the file to a property in Carma see to that correct information is entered in the mapping filed in Carma: Account settings > Profile attributes (below image). If a new column header is sent to Carma that hasn’t been added before, Carma will automatically create the new property.

1 Carma also support Secure Copy over SSH. This file transfer method provides greater security.

 

 

Choosing fields to be included in the file

What data that should be included in the file depends on what data you wish to either be presented in the sending or what data should be used for segmenting. Select only data that is relevant to your email content and segmentation needs to minimize unnecessary export and import time.

In some cases it’s only necessary to import email addresses or phone numbers. One requirement is that the recipients in your import file are identified by an id. This can be a primary key from a database or anything else that uniquely identify each recipient. The result of this is that the simplest import file must at least contain two columns (id and email address/phone number).

When no suitable id for recipients can be found you can choose to identify recipients by their email address or phone number. This is an inferior method and by doing so recipients that change their email address or phone number will be treated as new recipients in the system.

 

File format

Data uploaded to Carma for import must conform to the following specifications:

– Data must be sent as an unformatted plain text file.

– You must not surround data fields in quotes or double quotes.

– The first row in the file will be used as a mapping matrix to insert the file data into the correct property* in Carma.

– Newline must be represented by ASCII compatible characters (i.e. LF, CR or CR+LF).

– The only allowed ASCII control chars are horizontal tab, space, carriage return and line feed.

– Column header names may only contain ASCII alphanumeric characters (A-Z a-z 0-9), e.g. no space or underscore.

– Mobile numbers must start with 00[country code] or +[country code], e.g. 0046 or +46 (where 46 is country code for Sweden).

– Allowed file extensions are .txt and .csv (+.zip if compressed).

– The following file encodings are supported:
o UTF-8
o UTF-16
o ISO-8859-1
o ANSI

– The file must be structured in a table format so that each line represents a table row with fields separated by a delimiter**. We recommend tab or triple hash (###) as delimiter.

– The file must not include byte order mark (BOM).

 

* To map the correct column header in the file to a property in Carma see to that correct information is entered in the mapping filed in Carma. You can get a property and file header overview for your existing properties in Carma on Account settings > Profile attributes.

** Choose a delimiter that won’t be represented as a data character in your file since this will result in offset data. Avoid delimiters such as “,” (comma), “.” (dot), “:” (colon) or “;” (semicolon).

 

 

Collection fields

To reduce the number of fields it’s sometimes convenient to merge a collection of properties to a single field. This can greatly reduce the time spent creating filters and managing properties in Carma.

To create a Collection field you will have to select a new set of delimiters that’s different from your normal field separator. The data is written to the Collection field delimited by this new separator according to the following specifications:

– Each value in the Collection field must start with the Collection field start delimiter

– Each value in the Collection field must end with the Collection end field delimiter

 

We recommend using curly brackets, parentheses or angled brackets as delimiters.

See section “Example layouts” for more information.

 

PLEASE NOTE: Data in a collection field can with great benefit be used for segmentation but is not suited to be presented with placeholders in an email since you have several values.

 

Calendar and time fields

Date and time values are organized from the most to the least significant: year, month, day, hour, minute, second, and fraction of second.

Each date and time value has a fixed number of digits that must be padded with leading zeros.

Representations can be done in one of two formats: a basic format with a minimal number of separators or an extended format with separators added to enhance human readability. The separator used between date values (year, month and day) is the hyphen, while the colon is used as the separator between time values (hours, minutes, and seconds).

The time zone used in Carma is Central European Time (CET).

 

Calendar dates

Carma uses all-numeric data notation [yyyy]-[MM]-[dd]. A four-digit year [yyyy] is used to avoid the year 2000 problem. [MM] indicates a two-digit month of the year, 01 through 12. [dd] indicates a two-digit day of that month, 01 through 31.

For example, “the 5th of April 2014” is represented as “2014-04-05”.

 

Time

Carma uses the 24-hour clock system. The accepted format is [hh]:[mm]:[ss].

It is acceptable to omit lower order time elements for reduced accuracy.

Date and time examples:

2013-04-05 13:37

2014-12-11 20:00:00

 

 

Example layouts

Here is a simple example file layout with three columns (id, name and email address). The first row is a header row and indicates how the file is organized. The delimiter chosen for this layout is tab.

Id <tab>name <tab>emailaddress

001 <tab>paul <tab>pm@compost.se

002 <tab>lars <tab>lh@compost.se

003 <tab>vegar <tab>vl@compost.se

004 <tab>tobbe <tab>th@compost.se

 

The example below is a layout using Collection fields with tab as field delimiter and curly brackets as collection delimiter:

Id name categories email

123 pm {clothing}{kitchen} pm@compost.se

345 lh {games}{music}{home} lh@compost.se

678 vl {health}{music}{movies} vl@compost.se

910 th {games}{clothing}{kids} th@compost.se

 

Archiving

As soon as a Schedule import is started it will rename the file to filename.archive.timestamp (timestamp is when the import started), example SE_CRM.csv.archive.[timestamp].

 

Server details

You can use both sFTP and FTP protocols on their standard ports with the credentials obtained from Carma support. The internet hostname of our file server is storage.carmamail.com.

If you have any questions regarding the different file transfer methods please contact Carma support. We recommend our clients to use sFTP since this will encrypt the data when transferred to Carma.

 

 

Import setup in Carma

To get the import running you need to, in Carma, enter information about the import, when the import should run and where Carma will find the file. These settings are found in Carma: Account settings > Scheduled imports (> create new).

 

Job name 

Name your import and select which list you want to use. Choose if you want to use automatic import mapping or an already created import schema.

Automatic import mapping is recommended and means Carma detects the file column headers and maps it into properties in Carma.

Select your file delimiter in the dropdown menu.

 

Schedule 

By scheduling your job you tell Carma when to import your file*. You can choose to run the import every day or specific days.

*Compost reserves the right to change the time for the import.

 

 

File settings

The last setting you need to enter is where the file is to be found: path, username and password information to the FTP.

The filename should be a fixes name, for example SE_CRM.csv. Enter the name and path in the field “File name format”. If you save the file in the root of your FTP account you don’t need to type any path except the filename. But if you save the file in a subfolder enter the exact path to the file: CRM/ SE_CRM.csv.

Use the supplied login credentials to connect to the server and upload the file to the root of your home folder. Allowed characters for file names are “A–Z 0–9 – _”.

To speed up the import process it is possible to compress the import files with ZIP. If multiple files are to be delivered, each file must be compressed into a separate ZIP file.

 

IMPORTANT: Don’t start an upload of a new file until the previous file has been renamed since this will risk that you overwrite a file that hasn’t yet been processed by Schedule imports.

 

Verifying the data

When the setup is completed you are responsible to verify that your data is represented correctly in Carma. This can easily be done by exporting all property values from the list in Carma and analyse it.

 

***

 

Autoimport multifile

Several files can be imported to the same list in Carma with additional data. This is common if a customer has several systems containing different data that should be imported to the same list. The solution is based on a master file with child files adding data to the list.

 

Naming convention multifile

The files in a multifile import must conform to the following specifications:

Filename

The master file should be named = [_]_Master.txt*. This file contains the original ID’s of active recipients and, if any, property updates. The master file sets the active recipients on the list. If a recipient in a child file is not included in the master file, the recipient will be updated with the new data but not activated.

There are two different child solutions. The child file either contains the data that should be added to the recipients in the file (A) or the filename contains the data that should be set on the recipients in the file (B).

A. This solution is used when the import data is in the file and should be added with an import. The import will use the row-header in the file to map the data to the correct property in Carma. The file must contain original ID and the properties you wish to update.

Filename: [_]_Child<numeric id if several child files will be sent>.txt, for example SE_CRM_Child1.txt.

B. This solution is used when a specific property should be updated with a value given in the filename. The only data aloud in the file is the original ID for each recipient who should be updated. Filename: [_]_Child_<row-header>_<propvalue>.txt, for example SE_CRM _Child_vip_YES.txt (where SE_CRM is the name of the import, Child defines the child file, vip is the property that should be updated and YES is the new property value).

* [_] = is dynamic, file format can be .txt

 

For the child file to be found it needs to be placed in the same folder as the master file and it must be in place before the scheduled import start. The child file also needs to have the same encoding and delimiter as the master file.

The same property may not be updated by more than one child file.

 

PLEASE NOTE: It´s not possible to include any of the following Carma properties with the child files city, country, emailaddress, firstname, lastname, middlename, mobilenumber, sex, title, zipcode

A child file import will clear the previously set values in the specific properties.

 

 

File examples:

– Master file: SE_CRM_Master.txt (contains original ID; email; sex; zip)

– Child file A: SE_CRM_Child1.txt (contains several properties that should be added on each recipient; original ID, value and level)

– Child file B: SE_CRM_Child_vip_YES.txt (only contains original ID)

If you add a new file, Carma will automatically include it in the next import.

With the above setup the properties that will be imported are:

– Original ID (Master file)

– Email (Master file)

– Sex (Master file)

– Zip (Master file)

– Value (Child file A)

– Level (Child file A)

– Vip (Child file B)

 

Master file with child update of recipients

In the case a child file contains a recipient that isn’t represented in the master file the recipient will not be active after the import.

 

Original ID overview

SE_CRM_Master.txt

SE_CRM_Child_vip_YES

SE_CRM_Child1.txt