Follow

Import Relational Data

The Import Relational Data command allows you to add and update Subscriber's data in a Relational Data table.  It requires the following arguments:  Command and Data. 

cmd=relationalsave&data=email,first,mytable.uniqueID,mytable.myNumber^john.doe@domain.com,John,1232,11

Within the data argument, subscriber data fields are required to identify the Subscriber to associate the Relational Data.  To identify the Subscriber, Email and First Name must be defined, or Customer Key in a customer key enabled Account.

The command is ‘relationalsave' and data will be stored in the table named 'myTable', fields named 'uniqueID' and 'myNumber' for the subscriber record with the email 'john.doe@domain.com' and first name 'John'.

 

NOTE: Only include commands related to Relational Data management in the batch process file. Separate other commands, such as Subscribe and Launch. 

Example

In order to manage Relational Data, the FTP API file Header must include the following arguments: Relational set to true (1) and Allow Duplicates set to false (0). 

Clear Data may also be set, but must be supported by the Relational Table defined in the commands. If Clear Data is defined in the header, then every table within the FTP API command file will be cleared of All data if the table allows Clear Data.  Please be very careful using this option, as it cannot be undone once complete.

Using all commands and arguments (please note the command is wrapped for display purposes only):

realm=realm
password=password
confirm_email=myemail@domain.com
relational=1
allow_duplicates=0
clear_data=1

cmd=relationalsave&data=email,first,interests.id,interests.category,interests.interest_type^jane@domain.com,Jane,1,boating,null

In the example above, the header indicates that the batch process is for Relational Data and that the data in all tables defined in the file will be removed before processing new data.  The command imports Relational Data for the fields named id, category, interest_type in the table interests for a single subscriber.

Multiple Subscribers

To update Relational Data for multiple subscribers with a single command, separate each subscriber record using the carat (^) character.  Each subscriber must include the same data fields defined in the command.  For example, the command below imports Relational Data for the fields named petid, name, species, and age in the table named 'pets' for three separate subscribers.  

cmd=relationalsave&data=email,first,pets.petid,pets.name,pets.species,pets.age^jane@domain.com,Jane,2,Meow,cat,5^john@domain.com,John,3,Deohgee,dog,9^jack@domain.com,Jack,4,Sally,dog,2

Customer Key

Some systems have the ability to define a unique Customer Key per subscriber.  If your account has Customer Key enabled, then you must include the customer_key in the data argument alongemail.  For example:

cmd=relationalsave&data=customer_key,email,pets.petid,pets.name,pets.species,pets.age^12453,jane@domain.com,Jane,2,Meow,cat,5

If the Customer Key is not included, the command will fail.

Results

Success

The Relational Data FTP API delivers two emails to the Confirmation Email address(es) defined in the Header.  The messages are generated when the Data (.dat) file is picked up, and then again when the process is complete.  The messages include the Realm ID, name of data file, number of rows in the file, added or updated, and the number of errors.

Errors

A Import Relational Data command will fail if a subscriber record for the Email plus First Name does not exist, table or data fields do not exist, or do not allow data update.  Failures will result in an email message sent to the Confirmation Email defined in the header.  The message contains information related to the failure. 

Find more details about errors in the TASKS > TASK HISTORY page.

Arguments

The Import Relational Data command supports the following arguments:

Name

Req?

Description

Argument

Header Relational

Yes

When working with Relational Tables, the Relational flag must be set.  By default, Relational is not enabled.

relational=[0,1]

DEFAULT==0

Header

Allow Duplicates

Yes Relational Data tables do not support the allow duplicates flag, so it must either be set to off (0), or not included in the Header.  See Conventions for more information.  allow_duplicates=[0,1]

DEFAULT==0

Header

Clear Data

  To remove all data in a table before importing new data, set Clear Data to 1.  A table must be created allowing the use of Clear Data, otherwise the flag is ignored.  See Data Management Options for more information. clear_data=[0,1]

DEFAULT==0

Command

Yes

Defines the command to use.

cmd=relationalsave

Realm

 

Name of the realm to run the command.  The realm is required in the Header, but optional in the command line to manipulate data for a child realm.

realm=[realm_name]

Data Yes

Subscriber and Table related data. To identify the Subscriber to which the data is related, the Subscriber Email and First Name are always required or Customer Key for accounts in which Customer Key is enabled.

Relational Table Unique ID is required, and additional fields are optional.  The Relational Data fields must be identified using the table name and the field name in the format:  

tableName.fieldname

data=[email,first,tableName.fieldname(s)]

data=[customer_key,tableName.fieldname(s)]

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk