Find answers to more common troubleshooting questions here.

AddRecipient Error

AddRecipient API error and why it occurs.

Symptoms

The following error can occur during an AddRecipient API call:

AddRecipient Error: Unable to perform requested action. The Contact Source is shared and you are not a member of the owner’s organization.

Resolving the problem

The AddRecipient call with an account that does not exist within the same org as the contact source (database) to which you are trying to add a recipient causes this error.

Error executing import of list. Details: null

How to fix the Error executing import of list. Details: null

Symptoms

The ImportList API call produces the follow error: Error executing import of list. Details: null.

Resolving the problem

The reason this error can occur is due to an incorrect mapping file, where the column that is defined in the mapping file does not exist in the database, thus the ‘null’ error.

It could also be a misspelling in the mapping file of an existing column in the database. (For example, the column is specified in the mapping file as ‘Customer ID’, whereas, in the database, it is named ‘Customer_ID’.)

Error opening the export file API error

How to fix the opening the file API error.

Symptoms

Exporting information by using API, causes the ‘Error opening the export file’ message to appear.

Resolving the problem

This error involves the FTP/SFTP folder not working as expected, even when the API is bypassing the FTP and trying to add to stored files.

To resolve, log into your FTP and make sure that you have an upload and download directory, and that you are able to access them. Once confirmed that you have directories and can access them, resubmit the call, and it works. If there is still an error message, contact Client Support for more assistance.

Example:

FTP information:

  • Server/Host: transferX.silverpop.com (X = the instance of the Watson Campaign Automation.
  • Port/Protocol: 22/SFTP
  • Login information is the same as the login used for the Watson Campaign Automation account.

Error Saving Recipient

How to fix the Saving Recipient API error.

Symptoms

Note: This API is not supported for Flexible databases.

A contact is stuck in the ‘Pre-opt in’ state and you are trying to fully opt them into your Double Opt In Database. Once the DoubleOptInRecipient API call is submitted, you receive this error:

<?xml version=’1.0′?>
<Envelope>
  <Body>
    <RESULT>
    <SUCCESS>false</SUCCESS>
    </RESULT
    <Fault>
      <Request/>
      <FaultCode/>
      <FaultString>Error Saving Recipient:null</FaultString>
      <detail>
        <error>
          <errorid>120</errorid>
          <module/>
          <class>SP.SPI</class>
          <method/>
        </error>
      </detail>
    </Fault>
  </Body>
</Envelope>

Resolving the problem

This error occurs because the recipients' email address is in all upper case. Change the email address to all lower case and submit the call again.

<Envelope>
  <Body>
    <DoubleOptInRecipient>
      <LIST_ID>1234567</LIST_ID>
      <COLUMN>
        <NAME>EMAIL</NAME>
        <VALUE>example@domain.com</VALUE>
      </COLUMN>
    </DoubleOptInRecipient>
  </Body>
</Envelope>

The API process to double opt in a contact is done with the AddRecipient API call first. That places the recipient in a pre-opt in state. The DoubleOptInRecipient call does not need to be run if you are sending the mailing with the AddRecipient call and you are allowing the contact to confirm being added to the database. If you do not want to trigger the Autoresponder with either call, be sure to include the SEND_AUTOREPLY parameter and set the value to False.

<Envelope>
  <Body>
    <DoubleOptInRecipient>
      <LIST_ID>1234567</LIST_ID>
      <SEND_AUTOREPLY>False</SEND_AUTOREPLY>
      <COLUMN>
        <NAME>EMAIL</NAME>
        <VALUE>example@domain.com</VALUE>
      </COLUMN>
    </DoubleOptInRecipient>
  </Body>
</Envelope>

Error Validating Mailing when using Schedule Mailing API call

How to fix the validating mailing error.

Symptoms

The Error Validating Mailing appears when a template with a specific web form is used. However, the same template works perfectly fine when a different web form is associated to it.

Resolving the problem

A specific set of circumstances can cause this error to appear, but an understanding of how the Watson Campaign Automation pulls things together can help avoid this issue.

A web form is tied to a specific database. Therefore, you must check what contact source is being used for your Schedule Mailing.

In order to prevent the Error Validating Mailing message from appearing, you need to ensure that the new contact source has the required fields that the web form is utilizing.

API Error: ERR_INVALID_UPDATE_IF_FOUND

Error when making the UpdateRecipient API call

When making the UpdateRecipient API call, the following error occurs:

ERR_INVALID_UPDATE_IF_FOUND

What does this mean?

This happens for two reasons:

  • When the Recipient ID is not found in the database.
  • The element Encoded Recipient ID is being used.

To fix, check that the contact record exists in the database and confirm the Recipient ID by following these steps:

  1. Go to Data > view Data.
  2. Click the name of the database.
  3. Click the Search tab.
  4. Hover over the email address to get the Recipient ID that shows up at the bottom of the monitor screen. You can also right-click the email address, choose copy link address and paste link into new browser tab or window.

Recipient ID looks like: recipientId=81649683092.

Encoded Recipient ID

If Encoded Recipient ID is being used, be sure to obtain the encoding the correct way. Using a base 64 encoder to encode the recipient ID does not generate the code correctly.

The correct method can be found in the API Guide for UpdateRecipient:

  • ENCODED_RECIPIENT_ID

The encoded Recipient ID might be provided with a LIST_ID to look up a contact. When passing the Recipient ID, no key fields are required.

Note: The encoded Recipient ID can be obtained from a sent mailing when %%RECIPIENT_ID%% is placed in the mailing body.

If the error is still present after making corrections, contact Client Support.

Exception while validating mappings API error

How to fix the Exception while Validating Mappings API error.

Symptoms

Using the ImportList API call gives the following error:

Exception while Validating Mappings. java.lang.ArrayIndexOutOfBoundsException: 10 Unable to continue.

Resolving the problem

Look at the XML mapping file that is associated with the ImportList API call. If the XML has more than 10 sync fields, the datajob fails with that error. Reduce the number of sync fields to 10 or less and the job runs successfully.

Found UTF-8 BOM but encoding was iso-8859-1 API error

How to fix the Found UTF-8 BOM but encoding was iso-8859-1 APR error.

Symptoms

Running the ImportList API call, produces the following error:
Found UTF-8 BOM but encoding was iso-8859-1

Resolving the problem

Take the XML and CSV files and convert them to ANSI encoding by using a program such as Notepad++. Once the files are converted, upload them to the FTP folder and then try the import again.

Note: IBM® does not support third-party software such as Notepad++. Notepad++ is a suggestion only.

InsertUpdateRelationalTable API error

How to fix the InsertUpdateRelationalTable error.

Symptoms

The InsertUpdateRelationalTable API call pulls back conflicting result data. However, a <SUCCESS>true</SUCCESS> response was received, > and a list of failures under the <FAILURE failure_type='transient' description='Error saving row'> were sent as
well.

Resolving the problem

While the overall API submission was a success, there were some rows in your list that failed for various reasons. The most common reasons are invalid data or the incorrect field type match. For instance, in your import you have a row that has text within a field that is of the Date type in your Watson Campaign Automation database. Since the Date field requires a strict format, this row would display under the FAILURE parameter.

Example of the results data

<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>true</SUCCESS>
      <FAILURES>
        <FAILURE failure_type='transient' description='Error saving row'>
          <COLUMN name='event_date'>
            <![CDATA[05/30/2014]]>
          </COLUMN>
          <COLUMN name='event_registered_date'>
            <![CDATA[04/23/2014]]>
          </COLUMN>
          <COLUMN name='answers'/>
          <COLUMN name='questions'/>
          <COLUMN name='attending'/>
          <COLUMN name='mobility'/>
        </FAILURE>
      </FAILURES>
    </RESULT>
  </Body>
</Envelope>

To resolve the issue, simply review your rows and make sure that there are no discrepancies.

Invalid XML request API error

How to fix the Invalid XML Request API error.

Symptoms

The API call works in the Test Harness, but passing an XML request through a web browser, the following error results: Invalid XML Request.

Request submitted:

<Envelope>
  <Body>
    <RawRecipientDataExport>
      <MAILING_ID>5116805</MAILING_ID>
      <MOVE_TO_FTP/>
      <EXPORT_FORMAT>0</EXPORT_FORMAT>
      <ALL_EVENT_TYPES/>
      <EXCLUDE_DELETED/>
      <COLUMNS>
        <COLUMN>
          <NAME>INDIVIDUALID</NAME>
        </COLUMN>
        <COLUMN>
          <NAME>CONNECTIONID</NAME>
        </COLUMN>
        <COLUMN>
          <NAME>CAMPAIGN_RUN_DATE</NAME>
        </COLUMN>
        <COLUMN>
          <NAME>CELLNAME</NAME>
        </COLUMN>
      </COLUMNS>
    </RawRecipientDataExport>
  </Body>
</Envelope>

Note: The Jsessionid was valid at the time when fired through VB Script.

Resolving the problem

Currently, it is not possible to submit an API call through a web browser. The expectation is that a POST submission is used as opposed to GET request.

Local part of email address is blocked API error

How to fix the local part of email address is blocked API error.

Symptoms

An AddRecipient call such as shown here is submitted.

<Envelope>
  <Body>
    <AddRecipient>
      <LIST_ID>1234567</LIST_ID>
      <UPDATE_IF_FOUND>true</UPDATE_IF_FOUND>
      <CREATED_FROM>2</CREATED_FROM>
      <COLUMN>
        <NAME>Email</NAME>
        <VALUE>service@service.com</VALUE>
      </COLUMN>
    </AddRecipient>
  </Body>
</Envelope>

The API returns

<Envelope>
<Body>
  <RESULT>
    <SUCCESS>false</SUCCESS>
  </RESULT>
  <Fault>
  <Request/>
  <FaultCode/>
  <FaultString>
    <![CDATA[Local part of Email Address is Blocked.]]>
  </FaultString>

What does this error mean?

Resolving the problem

This message indicates the email address that is submitted in the API call, service@service.com, has a local prefix that exists on the Email Blocking List.

Remove this local prefix from the Email Blocking List within your Org. See for further instructions on removing or adding local prefixes to the list.

Map file does not exist API error

How to fix the Map file does not exist API error.

Symptoms

The ImportList API call pulls back the Map File Does Not Exist error. Use the resolution to fix it.

Resolving the problem

<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>false</SUCCESS>
    </RESULT>
    <Fault>
      <Request/>
      <FaultCode/>
      <FaultString>
        <![CDATA[Map File Does Not Exist: list_import_map.xml]]>
      </FaultString>
      <detail>
        <error>
          <errorid>306</errorid>
          <module/>
          <class>SP.Content</class>
          <method/>
        </error>
      </detail>
    </Fault>
  </Body>
</Envelope>

This error is generated when the Watson Campaign Automation is unable to locate the file name you specified in the SOURCE_FILE attribute of the ImportList API call. Verify that the file name you specified in the SOURCE_FILE attribute of the ImportList API call

  1. is uploaded to the Upload folder of your FTP account.
  2. Verify that the username that is used to execute the ImportList API call matches the username of the FTP account in which the file is uploaded.

Verify information and making corrections if needed, run the API call again. If it continues to fail, contact Client Support.

Recipient Opted In API error

How to correct the Recipient Opted in API error.

Symptoms

The following error occurs when the UpdateRecipient API is used:
Recipient has opted out of the list. If the status for the recipient is Opted In,the XML could contain errors in comparison to the database. The Unique Identifier in the database must match the RECIPIENT_ID that is used in the XML to update the contact
successfully.

Error Received

Success: falseFaultString: Error Adding Recipient

Error that is received when a database does not use email as the default Unique Identifier.

<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>false</SUCCESS>
    </RESULT>
    <Fault>
      <Request>
      <FaultCode>
      <FaultString>Error Adding Recipient 000111000111</FaultString>
      <detail>
        <error>
          <errorid>129</errorid>
          <module>
          <class>SPRecipients</class>
          <method>
        </error>
      </detail>
    </Fault>
  </Body>
</Envelope>

Resolving the problem

Match the RECIPIENT_ID to the Unique Identifier for the contact in the
database and submit the UpdateRecipient API.

For example, this user composed the UpdateRecipient XML for a contact. This users database does not use email as the default Unique Identifier only Unique_ID. The RECIPIENT_ID and the Unique_ID from the Watson Campaign Automation database must match or the user receives an error id of 129.

Email: testaddress@test.com

Recipient_ID: 000111000111 (IMC UID)

Unique_ID: 00220022 (Database UID)

<Envelope>
  <Body>
    <UpdateRecipient>
      <LIST_ID>9894201</LIST_ID>
      <RECIPIENT_ID>000111000111</RECIPIENT_ID>
      <COLUMN>
        <NAME>EMAIL</NAME>
        <VALUE>testaddress@test.com</VALUE>
      </COLUMN>
      <COLUMN>
        <NAME>Unique_ID</NAME>
        <VALUE>00220022</VALUE>
      </COLUMN>
    </UpdateRecipient>
  </Body>
</Envelope>

Session expires or is invalid API error

How to prevent the Session expires or is invalid error from occurring.

Symptoms

When using AddRecipient API or UpdateRecipient the following error can appear - Session has expired or is invalid. This is placed in as an extra layer of security. However, requiring a jsession id for the AddRecipient API is optional.

Resolving the problem

To remove the jsession checking for the AddRecipient API and the UpdateRecipient API use the following steps.

Note: Only Org Admins can perform this action.
  1. Login to the Watson Campaign Automation
  2. Navigate to the database that you are trying to add contacts to by going to Data > View Data.
  3. Click the desired database.
  4. Click
    Settings.
  5. Click
    Security Settings tab.
  6. Uncheck
    Authentication for Contact Actions API check box.
  7. Click
    Save.

ImportList API call error

ImportList API call produces an error when used.

Symptoms

A response similar to this example can occur when an ImportList API call is submitted.

<Envelope>
<Body>
  <RESULT>
    <SUCCESS>false</SUCCESS>
  </RESULT>
  <Fault>
  <Request/>
  <FaultCode/>
  <FaultString>
    <![CDATA[/app/content/ftp/df38ad2-136e120c9cf-37c504b367ce64f028215bda5330c1de]]>
  </FaultString>
  <detail>
  <error>

Resolving the problem

The error is usually due to logging in with one username for the FTP upload and a different username for the ImportList API call. You need to verify that you are using the same username for both and try again. Contact Client Support if the error still occurs.

API error 56 - throttling concurrent requests

Limitations on the number of concurrent requests per organization.

An organization-wide limit is placed on the number of concurrent requests that can be sustained at any time. If your organization reaches this limit, the following error is returned and processing is halted on any incoming requests until the number of concurrent connections is reduced.

Error message

Could not complete request for {YOUR_ORGANIZATION_ID}; the max number of concurrent authenticated requests through the API is {YOUR_ORGANIZATION_LIMIT}, and there are {CONCURRENT_REQUESTS_USED_BY_YOUR_ORGANIZATION} requests already active.

Unable to complete request. Required unique key column values were not provided

When executing an AddRecipient API call, the following error message is returned, 'Unable to complete request. Required unique key column values were not provided.' This can be caused by two possible issues.

If your Contact Source is a Flexible database (such as one used for CRM integration), be sure to specify Sync Fields for each database column that defines a unique contact.

Example

If you are looking to sync on an Email Address field and a CustomerID field, your AddRecipient call can include something similar to:

<SYNC_FIELDS>
  <SYNC_FIELD>
    <NAME>EMAIL</NAME>
    <VALUE>someonenew@domain.com</VALUE>
  </SYNC_FIELD>
  <SYNC_FIELD>
    <NAME>CustomerID</NAME>
    <VALUE>123-45-6789</VALUE>
  </SYNC_FIELD>
</SYNC_FIELDS>

If your Contact Source is a Flexible Database, be sure to include the Key Field exactly as it appears in your Database.

Example

If the key of your Database is NewKeyField, submitting an AddRecipient API call similar to:

<Envelope>
  <Body>
    <AddRecipient>
      <LIST_ID>123456</LIST_ID>
      <CREATED_FROM>1</CREATED_FROM>
      <UPDATE_IF_FOUND>true</UPDATE_IF_FOUND>
      <COLUMN>
        <NAME>EMAIL</NAME>
        <VALUE>someonenew@domain.com</VALUE>
      </COLUMN>
      <COLUMN>
        <NAME>NEWKEYFIELD</NAME>
        <VALUE>8675309</VALUE>
      </COLUMN>
    </AddRecipient>
  </Body>
</Envelope>

The API returns Error Code 211. You need to reference the Key Field exactly how it appears within the Watson Campaign Automation:

<NAME>NewKeyField</NAME>

Add contact to double opt-in database by using API

How to ensure that a contact is added into a double opt-in database.

Symptoms

The AddRecipient call is used to add a contact to a double opt-in database. However, the contact is stuck in the pre opt-in state.

Resolving the problem

The AddRepient call is just the first step for adding a contact to a Double Opt-In database.

The second step is to submit the DoubleOptInRecipient call. The DoubleOptInRecipient call moves the contact out of the pre opt-in state and into the fully opted in state. Make sure to add the <SEND_AUTOREPLY>TRUE</SEND_AUTOREPLY> to your code so your contact receives the confirmation autoresponder.

Email addresses do not show in database after a successful Add_Recipient call

Why a successful AddRecipient API call did not pull email addresses into a database.

Symptoms

The AddRecipient API call was successful but email addresses are not showing in the database.

Resolving the problem

Adding and defining the column elements within the XML adds the contacts and records the email address in the database.

Note: Bold elements in this example represent the column elements.
<AddRecipient>
  <LIST_ID>01010100</LIST_ID>
  <CREATED_FROM>2</CREATED_FROM>
  <CONTACT_LISTS>
    <CONTACT_LIST_ID>10101010</CONTACT_LIST_ID>
  </CONTACT_LISTS>
  <SYNC_FIELDS>
    <SYNC_FIELD>
      <NAME>EMAIL</NAME>
      <VALUE>example@pop.com</VALUE>
    </SYNC_FIELD>
  </SYNC_FIELDS>
  <COLUMN>
    <NAME>EMAIL</NAME>
    <VALUE>
    example@pop.com
    <VALUE>
  </COLUMN>
</AddRecipient>
</Body>
</Envelope>

API query creation with null or blank recipients

Creating an API Query to return blank/null recipients.

To create a query that includes blank or null recipients, the API call needs to specify these values.

Example Call

<Envelope>
  <Body>
    <CreateQuery>
      <QUERY_NAME>TestQuery</QUERY_NAME>
      <PARENT_LIST_ID>12345</PARENT_LIST_ID>
      <VISIBILITY>1</VISIBILITY>
      <CRITERIA>
        <EXPRESSION>
          <TYPE>TE</TYPE>
          <COLUMN_NAME>test_yes</COLUMN_NAME>
          <OPERATORS>!=</OPERATORS>
          <VALUES>Yes</VALUES>
        </EXPRESSION>
        <EXPRESSION>
          <AND_OR>OR</AND_OR>
          <TYPE>TE</TYPE>
          <COLUMN_NAME>test_yes</COLUMN_NAME>
          <OPERATORS>IS null</OPERATORS>
        </EXPRESSION>
      </CRITERIA>
    </CreateQuery>
  </Body>
</Envelope>

Does the purge database API work with flexible databases?

Purging a Flexible database with the PurgeDatabase API call.

Resolution

Yes, but it is suggested that contacts be purged from a Flexible database by using an associated query or contact list as the source. Specifying different Flexible databases for target and source does not result in any matches to be purged.

ImportList API call and update only feature

Use of the ImportList API call to update contacts.

Symptoms

The API ImportList call to update contacts within the database, is removing all of the
values that are assigned to selection fields.
Resolving the problem

To make updates with the ListImport API call, you do not need to include any columns within the mapping xml file except the unique identifier. If it's a Flexible database, include a SYNC_FIELD element for each database column that defines a unique contact.

Note: For Flexible databases, if more than one contact is found matching the lookup columns, all matching contacts are updated. If the ACTION tag is set to opt out, all matching contacts are opted out.

Example of Update_Only API Call

This example shows a mapping file for a database with no unique key where the columns EMAIL and Customer Id are being used to update contacts.

<LIST_IMPORT>
  <LIST_INFO>
    <ACTION>UPDATE_ONLY</ACTION>
    <LIST_NAME>Premier Accts</LIST_NAME>
    <LIST_VISIBILITY>0</LIST_VISIBILITY>
    <FILE_TYPE>0</FILE_TYPE>
    <HASHEADERS>true</HASHEADERS>
  </LIST_INFO>
  <SYNC_FIELDS>
    <SYNC_FIELD>
      <NAME>EMAIL</NAME>
    </SYNC_FIELD>
    <SYNC_FIELD>
      <NAME>Customer Id</NAME>
    </SYNC_FIELD>
  </SYNC_FIELDS>
  <MAPPING>
    <COLUMN>
      <INDEX>1</INDEX>
      <NAME>EMAIL</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
    <COLUMN>
      <INDEX>2</INDEX>
      <NAME>Customer Id</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
    <COLUMN>
      <INDEX>3</INDEX>
      <NAME>First_Name</NAME>
      <INCLUDE>true</INCLUDE>
    </COLUMN>
  </MAPPING>
</LIST_IMPORT>

Is SYNC FIELDS in the UpdateRecipient API call case-sensitive?

Ensure that duplicate contacts are not created when a Flexible database is in use.

Using a Flexible database, how can one ensure that duplicate contacts are not created when a database is updated by using API. The SYNC_FIELDS option is present in the XML. Is this SYNC_FIELD case sensitive?

Resolution

The Watson Campaign Automation checks your database to see whether there's an existing contact who matches the values on your listed SYNC_FIELDS. It matches the contact if the value stored on the database matches the exact value on the SYNC_FIELDS.

It's important to note that the Watson Campaign Automation stores all email addresses in lower-case text. The example shows how to update the recipient.

<Envelope>
  <Body>
    <AddRecipient>
      <LIST_ID>12344321</LIST_ID>
      <CREATED_FROM>1</CREATED_FROM>
      <UPDATE_IF_FOUND>true</UPDATE_IF_FOUND>
      <SYNC_FIELDS>
        <SYNC_FIELD>
          <NAME>EMAIL</NAME>
          <VALUE>somebody@domain.com</VALUE>
        </SYNC_FIELD>
      </SYNC_FIELDS>
      <COLUMN>
        <NAME>EMAIL</NAME>
        <VALUE>somebody@domain.com</VALUE>
      </COLUMN>
    </AddRecipient>
  </Body>
</Envelope>

Purging on a Flexible database

Using the OptOutRecipient call to purge a Flexible database.

When importing opt-outs, whether manual or recurring, Watson Campaign Automation looks for email address and opts out all instances of the email address from the database in question. If only one contact needs to be removed, use the OptOutRecipient API call.

Unable to edit recipient data in a Flexible database when multiple key fields are in use

Updating recipient data for a multi-keyed, Flexible database.

When a Flexible database uses more than one field as a key, it is not possible to edit either of these two pieces of data for any recipient by way of selecting the recipient within the UI.

To update this data, use the API available for the Watson Campaign Automation based on the following example and information:

In the example, the recipient ID is used to look up the individual and the columns to set the column values. The list has key1 and key2 as key fields.

<Envelope>
  <Body>
    <UpdateRecipient>
      <LIST_ID>146688</LIST_ID>
      <RECIPIENT_ID>2262575548</RECIPIENT_ID>
      <COLUMN>
        <NAME>key1</NAME>
        <VALUE>posttest</VALUE>
      </COLUMN>
      <COLUMN>
        <NAME>key2</NAME>
        <VALUE>posttest</VALUE>
      </COLUMN>
    </UpdateRecipient>
  </Body>
</Envelope>

This would require looking up the recipient ID, which can be done in two ways:

  1. If the recipient is getting to the form through a link in an Watson Campaign Automation email, the recipient ID can be passed in the URL by using personalization. In this case, you would use <ENCODED_RECIPIENT_ID> rather than <RECIPIENT_ID> since that is what gets passed in the mailing body.
  2. The other option would be to make a <SelectRecipientData> call first passing in the old key values. The recipient ID would be returned in the response XML and can be used to make the subsequent <UpdateRecipient> call.

UpdateRecipient for a Flexible database (EMail is one key)

Update a contact if the contact has Email and another field as a unique Identifier in a database.

If a contact has Email and another field as a unique Identifier in a database, you must clarify the <OLD_EMAIL> tag and other <COLUMN> tag that corresponds to the unique identifier before you can update the other fields value for that contact.

Sample code with Email and food as two unique identifiers of the database.

<Envelope>
  <Body>
    <UpdateRecipient>
      <LIST_ID>16502084</LIST_ID>
      <CREATED_FROM>2</CREATED_FROM>
      <OLD_EMAIL>(insert email address)</OLD_EMAIL>
      <COLUMN>
        <NAME>Food</NAME>
        <VALUE>Rice</VALUE>
      </COLUMN>
      <COLUMN>
        <NAME>Age</NAME>
        <VALUE>40</VALUE>
      </COLUMN>
    </UpdateRecipient>
  </Body>
</Envelope>

Using API to opt a contact back in to a Flexible database

Opting a user back into a Flexible database

You can use the UpdateRecipient API call with the OPT_OUTvalue set to 'false' to opt a user back into a Flexible database without creating a new record.

You need to obtain the ListID and the RecipientIDto submit the API call. To obtain these values, search for the
opted out contact under the Search tab by selecting Search Opt Outs and entering the email address.

OptOutGmail.jpg

Click the email address and you are taken to the Edit Contact screen. In your browser's address bar, you find the ListID and RecipientID values. You need to obtain these values, indicated by the yellow area, for the API call.

ListIDRecipientID.jpg

You can now plug in the ListID and RecipientID and run the UpdateRecipient API call with the OPT_OUT value set to 'false'.

<Envelope>
  <Body>
    <UpdateRecipient>
      <LIST_ID>XXXXXXX</LIST_ID>
      <CREATED_FROM>2</CREATED_FROM>
      <RECIPIENT_ID>XXXXXXXXXXX</RECIPIENT_ID>
      <COLUMN>
        <NAME>OPT_OUT</NAME>
        <VALUE>false</VALUE>
      </COLUMN>
    </UpdateRecipient>
  </Body>
</Envelope>

Opt-out multiple contacts from a contact list at the same time

Removing multiple contacts from a list.

Through the Watson Campaign Automation, you are able to manually remove multiple contacts from a contact list. However, there are times when this option is not practical and you need a more programmatic solution.

The RemoveRecipientAPI call can be used to remove single and multiple contacts from a contact list. Use a format similar to this example.

Note: Each envelope can have a maximum of 100 contacts.
<Envelope>
  <Body>
    <RemoveRecipient>
      <LIST_ID>10000</LIST_ID>
      <EMAIL>thisisatest@one.com</EMAIL>
    </RemoveRecipient>
    <RemoveRecipient>
      <LIST_ID>10000</LIST_ID>
      <EMAIL></EMAIL>
    </RemoveRecipient>
  </Body>
</Envelope>

Using COLUMN nodes in SendMailing API

Using COLUMN nodes to specify new values for a recipient record

When submitting the SendMailingAPI call, an attempt is made to use COLUMN nodes to specify new values for a recipient's record in
the template's associated database.

1. Why won't the FirstName column update the database value, but the mailing sends anyway?

Example 1

<Envelope>
  <Body>
    <SendMailing>
      <MailingId>5972</MailingId>
      <RecipientEmail>thisisatest@one.com</RecipientEmail>
      <COLUMNS>
        <COLUMN>
          <NAME>FirstName</NAME>
          <VALUE>NewFirstName</VALUE>
        </COLUMN>
        <COLUMN>
          <NAME>Email</NAME>
          <VALUE>thisisatest@one.com</VALUE>
        </COLUMN>
      </COLUMNS>
    </SendMailing>
  </Body>
</Envelope>

2. Why do I encounter error ID 128 - 'recipient is not found'?

Example 2

<Envelope>
  <Body>
    <SendMailing>
      <MailingId>5972</MailingId>
      <RecipientEmail>thisisatest@one.com</RecipientEmail>
      <COLUMNS>
        <COLUMN>
          <NAME>FirstName</NAME>
          <VALUE>NewFirstName</VALUE>
        </COLUMN>
        <COLUMN>
          <NAME>LastName</NAME>
          <VALUE>NewLastName</VALUE>
        </COLUMN>
      </COLUMNS>
    </SendMailing>
  </Body>
</Envelope>

Column nodes in a SentMailing API call can only be used when the database that is associated to the template is a Flexible database. Using COLUMN and providing new field values in a SendMailing API call does not update contacts records in the database.

If you want to update a recipient's record, you can use the AddRecipient call and UPDATE_IF_FOUND set to true, along with column values that identify the UIDs, if applicable.

  • In Example 1, the associated database is a Restricted database. EMAIL is the only column value that the call is relying upon. All other columns are ignored.
  • In Example 2, either the database is Restricted and the EMAIL column is not included in the API call, or all Unique Identifiers (UIDs) for the Flexible database are not included in the API call, which causes the recipient to not be found.

In either event, you can only use COLUMN nodes to identify contacts records in Flexible databases. Using COLUMN in a SendMailing API call does not update values that exist in the database.

What is a mapping file?

Explanation of a mapping file

A mapping file is an XML file that specifies the database properties. This file must be placed in the upload directory on the SFTP sever when performing a database upload through an API call. Click here for a mapping file example.

Click here.

When to use AddRecipient versus ImportList API

Various ways to add contacts to a database, each targeted at a specific user
need.

What is the Best Way to Add New Contacts to a database?

The Watson Campaign Automation offers a number of ways to add contacts to a database, each targeted at a specific user need.

There are three ways of adding a contact to your database:

  • One at a time by using the Watson Campaign Automation User Interface (UI)
  • One at a time by using the Watson Campaign Automation AddRecipient API
  • In a set by using the Watson Campaign Automation ImportList API

Adding Contacts Using the UI

While adding contacts using the UI is the easiest way to get started, if you wanted to create a test list or a seedlist. This method is not for day-to-day use as it is very time consuming and can result in errors. Typically, you are receiving the contacts to add in some electronic form, so the List Import feature is a more efficient approach.

Adding Contacts Using the Watson Campaign Automation AddRecipient API

The Watson Campaign Automationoffers a robust API,AddRecipient, for adding and updating contacts in your database using an API call. The call lets the user create or update a single contact at a time and is a good approach for when you want to trigger Watson Campaign Automation Programs when a contact is added.

Since the API is for the creation of a single contact, it is often not useful for synchronization of data between systems. The time delay for doing a round trip to theWatson Campaign Automation for each contact is often prohibitive for large loads.

A typical example for using AddRecipient is a Welcome Program that is triggered when a contact joins your website where you want the first message to go out as soon as possible.

However, if you want to wait an hour (or a day) before starting the Program, or are adding new contacts to the Watson Campaign Automation every hour, the ImportList API is a better solution.

Adding Contacts in Bulk by using the Import List API

Often a set of contacts is identified to be loaded at a fixed interval, such as a daily import from CRM, or an hour sync with the e-commerce system. The Watson Campaign Automation provides a set of APIs for bulk loading of these contacts.

Typically implemented in a system-to-system solution, these APIs lets you import millions of contacts in a single step, with error resilience, a single status, and an error report.

These APIs have a set of uses including:

  • Adding only new contacts from a source file that might contain existing contacts as well.
  • Updating only existing contacts from a source file.
  • Adding and updating contacts if both are present in the source file.
  • Opting out contacts who have asked to be removed from your communications by a means other than the Watson Campaign Automation provided solutions.
  • Appending new database columns to existing contacts.

Guidelines

Sometimes it is difficult to know which approach to loading contacts is appropriate for your needs. Here are some guidelines:

If you are adding contacts from an external system, versus opting in through a web form, determine how quickly you want to begin communicating with the contacts:

  • If you need to trigger a welcome program as soon as possible after the Contact has identified themselves, use the Add Recipient API.
  • If you can wait to trigger a Welcome Program, say hourly or daily, batch the contacts and use the ImportList API.
  • If you aren't triggering a Welcome Program, use the ImportList API. If you aren't currently using a Welcome Program, you might want to consider it. Research shows that a Welcome Program is a great way to begin a long-term relationship with your
    contacts!
  • If you are receiving updates from an external system in batch, such as an hourly integration with an e-commerce system or a nightly sync from your lead management system, use the ImportList API. If you expect to add more than 1000 contacts in an hour, the ImportList API has better performance.
  • Other than when creating simple test lists, most clients rarely use the UI to add or update contacts.

The ExportList API does not show the last modified in the report

How to obtain the Last Modified Date column from the ExportList API call

Symptoms

As of the 8.7 Release, the ability to export the Last Modified Date column by using the ExportList API was added. If that field
is not showing in the report, it is because the column is not exported by default by using the <EXPORT_TYPE>ALL</EXPORT_TYPE> tag. The column needs to be exported individually by using the <EXPORT_COLUMNS> tag. Keep in mind that the <EXPORT_COLUMNS> tag cannot be used along with the <EXPORT_TYPE> tag and takes precedence over it.

Resolving the problem

Example of how to implement this feature.

<Envelope>
  <Body>
    <ExportList>
      <LIST_ID>56008</LIST_ID>
      <EXPORT_TYPE>ALL</EXPORT_TYPE>
      <EXPORT_FORMAT>CSV</EXPORT_FORMAT>
      <ADD_TO_STORED_FILES/>
      <DATE_START>07/25/2003 12:12:11</DATE_START>
      <DATE_END>09/30/2005 14:14:11</DATE_END>
    </ExportList>
  </Body>
</Envelope>

You need to remove the EXPORT_TYPE tag and add the export column tags as follows:

<Envelope>
  <Body>
    <ExportList>
      <LIST_ID>56008</LIST_ID>
      <EXPORT_FORMAT>CSV</EXPORT_FORMAT>
      <ADD_TO_STORED_FILES/>
      <DATE_START>07/25/2003 12:12:11</DATE_START>
      <DATE_END>09/30/2005 14:14:11</DATE_END>
      <EXPORT_COLUMNS>
        <COLUMN>FIRST_NAME</COLUMN>
        <COLUMN>LAST_NAME</COLUMN>
        <COLUMN>Last Modified Date</COLUMN>
      </EXPORT_COLUMNS>
    </ExportList>
  </Body>
</Envelope>

<DELETE_BEFORE>MM/DD/YYYY HH:MM:SS</DELETE_BEFORE> parameter in the PurgeTable API call.

Specific questions about the <DELETE_BEFORE> parameter.

Overview

Using <DELETE_BEFORE>12/30/2015 12:00:00</DELETE_BEFORE> the record on the Relational Table with the earliest Created/Modified timestamp is 12/30/2015 at 6 PM GMT.

1. Does the parameter use GMT or the executing user's time zone for the date and time stamp? - The value is in the user's timezone.

2. Does a date and time conversion take place when the API call runs? - Conversion occurs when the data job runs.

3. Are the records to be purged determined by the created time stamp or last modified date time stamp of the record? - The records are purged based on the time the record was last modified.

File is not found in stored files after the RawRecipientDataExport API call runs

RawRecipientDataExport file is not found in stored files.

Symptoms

The RawRecipientDataExport API call runs but no files are found in the stored file
area.

Resolving the problem

If the RawRecipientDataExport call ran successfully and you received a notification that the data job is complete, a file is available for you to download. If the file cannot be found in your Stored Files, you have more than likely used the MOVE_TO_FTP option in the call. If so, you can either download the file from your sFTP download folder or you can rerun the API call without the MOVE_TO_FTP option so that it
goes to Stored Files.

With the MOVE_TO_FTP option:

<Envelope>
  <Body>
    <RawRecipientDataExport>
      <EVENT_DATE_START>11/01/2012 00:00:00</EVENT_DATE_START>
      <EVENT_DATE_END>11/30/2012 23:59:00</EVENT_DATE_END>
      <MOVE_TO_FTP/>
      <EXPORT_FORMAT>0</EXPORT_FORMAT>
      <EMAIL>admin@yourorg.com</EMAIL>
      <ALL_EVENT_TYPES/>
    </RawRecipientDataExport>
  </Body>
</Envelope>

Without the MOVE_TO_FTP option:

<Envelope>
  <Body>
    <RawRecipientDataExport>
      <EVENT_DATE_START>11/01/2012 00:00:00</EVENT_DATE_START>
      <EVENT_DATE_END>11/30/2012 23:59:00</EVENT_DATE_END>
      <EXPORT_FORMAT>0</EXPORT_FORMAT>
      <EMAIL>admin@yourorg.com</EMAIL>
      <ALL_EVENT_TYPES/>
    </RawRecipientDataExport>
  </Body>
</Envelope>

If your XML does not contain MOVE_TO_FTP and your file still can't be found in the Stored Files area of the Watson Campaign Automation, contact Client Support.

XML API Lifecycle

Understanding the lifecycle of logging in to the Watson Campaign Automation using XML API or user name and password.

The Watson Campaign Automation provides a rich set of APIs for interacting with your data and supports two types of authenticated API calls: OAuth and username/password.

The articles that follow describe how to:

  • Log in to the Watson Campaign Automation using the XML API and the importance of managing the lifecycle of a login
  • Login by using a user name and password
Note: OAuth is the preferred login method if possible in your environment.

Logging In

SESSION IDs and authenticated APIs.

Authenticated APIs require a SESSIONID for subsequent calls to allow the Watson Campaign Automation to identify the caller without having to log in for each request.

You need to be logged in for all of the authenticated API requests. This can be done by using the LoginRequest API, which authenticates your requests with a username and password from your IP and returns a SESSIONID.

You need to embed the SESSIONID from the LoginResponse in other API requests to identify yourself to the server. This information contains a sample LoginRequest and LoginResponse from the server for a successful authenticated user and a failure response for an unauthenticated user.

Login Request

<?xml version='1.0'?>
<Envelope>
  <Body>
    <Login>
      <USERNAME>username@organization.com</USERNAME>
      <PASSWORD>password</PASSWORD>
    </Login>
  </Body>
</Envelope>

Successful Login Response

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>true</SUCCESS>
      <SESSIONID>22EF3A6747EBA6E8581F123535A9C535</SESSIONID>
      <ORGANIZATION_ID>74a2b3b8-135169fb89f-9a23273f1f36308867b407a70afb05a1</ORGANIZATION_ID>
    <SESSION_ENCODING>jsessionid=22EF3A6747EBA6E8581F123535A9C535</SESSION_ENCODING>
    </RESULT>
  </Body>
</Envelope>

Failure Login Response

<?xml version='1.0' encoding='UTF-8'?>
<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>false</SUCCESS>
    </RESULT>
    <Fault>
      <Request/>
      <FaultCode/>
      <FaultString>
        <![CDATA[Unable to login user: Original link: <a
          href="mailto:username@organization.com" rel="freeklink" title="mailto:username@organization.com"
          /> - NOT_AUTHENTICATED. Attempt made from IP address: xxx.xxx.xxx.xxx]]>
      </FaultString>
      <detail>
        <error>
          <errorid>140</errorid>
          <module/>
          <class>SP.Admin</class>
          <method/>
        </error>
      </detail>
    </Fault>
  </Body>
</Envelope>

Logging out

Maintaining and releasing API sessions.

A logged in session maintains resources on the Watson Campaign Automation service. It is best to log out of the session when you are finished communicating with the Watson Campaign Automation. Logging out releases the resources in the Watson Campaign Automation.

Reusing the SESSIONID

Successful logins and validity of SESSIONIDs.

When a login successfully completes, the SESSIONID is returned in the response. This value must be included in all subsequent requests to the Watson Campaign Automation. This field must be included as a path parameter in the URL request.

Login and reuse the same session for up to 1 hour.

The SESSIONID is a key to data and resources that are stored on the Watson Campaign Automation server and can be valid for up to 1 hour. However, your logic detects errors from the Watson Campaign Automation if necessary. For a set of error codes and their meanings, consult the XML API developer content.

DELETE_BEFORE tag in PurgeTable API details

How to delete all rows that were imported into a relational table before a certain date.

Symptoms

How is the DELETE_BEFORE tag in the PurgeTable API call best used and is the last modified date available for certain rows?

Resolving the problem

API documentation defines the DELETE_BEFORE tag as:

"If included, only data that is last modified before the specified date/time is purged".

The following questions might arise:

  1. How can the relational table data last modified dates be accessed? - Last modified date is inaccessible through the Watson Campaign Automation. The Watson Campaign Automation stores the last modified date of each row but does not present it anywhere.
  2. What time zone can the timestamp be formatted in within the DELETE_BEFORE tags? - In your API call, format it in the submitting user's time zone. If the user who is submitting the call is set to GMT-4, then a DELETE_BEFORE value of 10/04/2013 08:43:00 will delete Relational Table records with a last modified date of before 10/04/2013 12:43:00 GMT.

Disassociate a relational table from a database

How to disassociate a relational table from a database.

Symptoms

Relational Table key not joined correctly.

Resolving the problem

It is possible to remove the association between the Relational Table and the database via the JoinTable API call by adding <REMOVE> to the call. <REMOVE> is an optional boolean element that is used to remove the relationship between a list and relational table. If specified, any MAP_FIELD elements are ignored.

Example

<Envelope>
  <Body>
    <JoinTable>
      <TABLE_ID>1935257</TABLE_ID>
      <LIST_ID>56737</LIST_ID>
      <REMOVE/>
    </JoinTable>
  </Body>
</Envelope>

Export relational tables

Using API to export a relational table.

Export Relational Table Using API

Use the ExportTable API call. You need to know the relational table name and path to complete the call.

Example of the ExportTable XML code

<Envelope>
  <Body>
    <ExportTable>
      <TABLE_NAME>Shared/Web Analytics/Purchases</TABLE_NAME>
      <EXPORT_FORMAT>CSV</EXPORT_FORMAT>
      <ADD_TO_STORED_FILES/>
      <DATE_START>07/25/2007 12:12:11</DATE_START>
      <DATE_END>09/30/2007 14:14:11</DATE_END>
    </ExportTable>
  </Body>
</Envelope>

Unable to delete a Relational Table via API

Response error 135, List has Dependents deleting a Relational Table.

About this task

When deleting a Relational Table through the DeleteTable API call, the following error occurs, Response error 135, List has Dependents.

Example

<Envelope>
  <Body>
    <DeleteTable>
      <TABLE_ID>123456</TABLE_ID>
      <TABLE_VISIBILITY>0</TABLE_VISIBILITY>
      <EMAIL>Email@ibm.com</EMAIL>
    </DeleteTable>
  </Body>
</Envelope>

Response

<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>false</SUCCESS>
    </RESULT>
    <Fault>
      <Request/>
      <FaultCode/>
      <FaultString>
        <![CDATA[Unable to delete list TABLENAME, List has Dependents.]]>
      </FaultString>
      <detail>
        <error>
          <errorid>135</errorid>
          <module/>
          <class>SP.ListJobs</class>
          <method/>
        </error>
      </detail>
    </Fault>
  </Body>
</Envelope>

To resolve the issue, you must remove the queries that are associated with the Relational Table
within the Watson Campaign Automation.

Procedure

  1. Go to Data > View Data> Relational Tables Tab
  2. Open the Relational Table (shared versus private).
  3. Go to the Queries tab, select all and delete queries that are associated.
  4. Delete Relational Table through the Watson Campaign Automation User Interface or the API.

Are the date ranges in a RawRecipientDataExport API call inclusive?

Date ranges and the RawRecipientDataExport call.

Overview

Most users specify an EVENT_DATE range when a RawRecipientDataExport API call is run. Events are returned that occurred during the specified Event Date range, and the time is formatted as such:

<EVENT_DATE_START>03/22/2013 00:00:00</EVENT_DATE_START>

<EVENT_DATE_END>03/23/2013 23:59:59</EVENT_DATE_END>

Is this time inclusive or will this date also include events that happened exactly on
03/23/2013 23:59:59?

Resolution

The date ranges applied to EVENT_DATE and SEND_DATE ranges in RawRecipientDataExport API calls are inclusive, and include events that occur on the second specified in the range.

Events brought back in the example EVENT_DATE range will be greater than or equal to 03/22/2013 00:00:00 and less than or equal to 03/23/2013 23:59:59.

Canceled mailing reports are not exported by RawRecipientDataExport API

Canceled mailing reports are not being exported

Symptoms

When a mailing is canceled during sending, the mailing is moved to the Sent tab. This canceled mailing looks like a completed mailing in the User Interface. However, when using a RawRecipientDataExport API, this mailing's report cannot be exported.

Resolving the problem

While you cannot see that difference between a canceled mailing and a completed mailing in the Watson Campaign Automation User Interface, you can run a Single Mailing Report and Export Tracking Data. Currently, the RawRecipientDataExport API does not pull this kind of mailing information. Send a feature enhancement request to the IBM Community.

Columns misaligned in an exported RawRecipientDataExport API

Misaligned columns in an exported csv file.

Symptoms

An exported .csv file of a RawRecipientDataExport API call contains misaligned columns due to a comma in one of the exported values.

Note: Can also occur when a Text Field-Type is exported that includes a comma in its value.

Resolving the problem

Use the 'EXPORT_FORMAT' parameter in your call and specify another file type:

  • 0 - Comma-Separated Value or CSV (Default format if not specified).
  • 1 - Pipe-Separated Value (PSV)
  • 2 - Tab-Separated Value (TSV)

Converting XML API responses for use in Microsoft Excel

How to convert XML API responses for use in Excel

Symptoms

Some XML API calls, such as GetSentMailingsForOrg and GetAggregateTrackingForOrg, generate XML responses and it might not be clear
how to easily get this information into a spreadsheet application like MS Excel.

Resolving the problem

Thanks to Excel's ability to parse XML, there are a few quick steps you can take to make it work.

  1. Get the full XML response.
    Note: If you are using the test harness, the right pane is holding the data that you want to bring in. In Firefox, right-click that response area and choose This Frame/View Source. From the window that opens, select everything and paste it into a plain text file (for example, Notepad on Windows or TextEdit on Mac). At the very beginning of the file, add <?xml version='1.0' standalone='yes' ?>. The XML response should begin with <envelope>, <success>, and <result> tags. Delete these from the beginning and from the end so that you are left only with a <body> tag and its contents.
  2. Save the file in UTF-8 format with an .xml extension when changes are made.

Now you're ready to open that file in Excel. The XML response shows up in a familiar spreadsheet format.

Example response before edits:

<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>TRUE</SUCCESS>
      <Mailing>
        <MailingId>37436332</MailingId>
        <ReportId>119474670</ReportId>
        <MailingName>
          <![CDATA[General Mailing Template (13)]]>
        </MailingName>
        <SentDateTime>2011-11-18 02:25:06.0</SentDateTime>
        <NumSent>1</NumSent>
        <NumSuppressed>0</NumSuppressed>
        <NumBounceHard>0</NumBounceHard>
        <NumBounceSoft>0</NumBounceSoft>
        <NumUniqueOpen>1</NumUniqueOpen>
        <NumUniqueClick>0</NumUniqueClick>
        <NumUnsubscribes>0</NumUnsubscribes>
      </Mailing>
      <Mailing>
        <MailingId>37436244</MailingId>
        <ReportId>119473755</ReportId>
        <MailingName>
          <![CDATA[General Mailing Template (12)]]>
        </MailingName>
        <SentDateTime>2011-11-18 01:54:05.0</SentDateTime>
        <NumSent>1</NumSent>
        <NumSuppressed>0</NumSuppressed>
        <NumBounceHard>0</NumBounceHard>
        <NumBounceSoft>0</NumBounceSoft>
        <NumUniqueOpen>1</NumUniqueOpen>
        <NumUniqueClick>0</NumUniqueClick>
        <NumUnsubscribes>0</NumUnsubscribes>
      </Mailing>
    </RESULT>
  </Body>
</Envelope>

Example response after edits:

Note: Make sure this is saved in UTF-8 format as a .xml file.
<?xml version='1.0' standalone='yes' ?>
<Body>
  <Mailing>
    <MailingId>37436332</MailingId>
    <ReportId>119474670</ReportId>
    <MailingName>
      <![CDATA[General Mailing Template (13)]]>
    </MailingName>
    <SentDateTime>2011-11-18 02:25:06.0</SentDateTime>
    <NumSent>1</NumSent>
    <NumSuppressed>0</NumSuppressed>
    <NumBounceHard>0</NumBounceHard>
    <NumBounceSoft>0</NumBounceSoft>
    <NumUniqueOpen>1</NumUniqueOpen>
    <NumUniqueClick>0</NumUniqueClick>
    <NumUnsubscribes>0</NumUnsubscribes>
  </Mailing>
  <Mailing>
    <MailingId>37436244</MailingId>
    <ReportId>119473755</ReportId>
    <MailingName>
      <![CDATA[General Mailing Template (12)]]>
    </MailingName>
    <SentDateTime>2011-11-18 01:54:05.0</SentDateTime>
    <NumSent>1</NumSent>
    <NumSuppressed>0</NumSuppressed>
    <NumBounceHard>0</NumBounceHard>
    <NumBounceSoft>0</NumBounceSoft>
    <NumUniqueOpen>1</NumUniqueOpen>
    <NumUniqueClick>0</NumUniqueClick>
    <NumUnsubscribes>0</NumUnsubscribes>
  </Mailing>
</Body>

Different Contacts have the same VISITOR KEY

Visitor keys and Contacts

Symptoms

When using WebTrackingDataExport API to export event historical CSV file, sometimes we can see multiple event records for different contacts (with different RECIPIENT_IDs) having the same VISITOR_KEY. Why?

Resolving the problem

The Watson Campaign Automation assigns a VISITOR_KEY to a visitor who uses a specific computer and web browser to visit a web site enabled with Watson Campaign Automation Web Tracking, or an Watson Campaign Automation Landing Page. The VISITOR_KEY is stored in browser cookies. The Watson Campaign Automation allows a Visitor_Key to be shared by multiple contacts who have been identified on the same computer and web browser.

For example, when a user submits a web form for the first time, the browser is assigned a Visitor Key which is linked to the Recipient_ID of the contact. But if the same browser is used to submit other contacts, all registered Recipient_IDs are still linked to the first Visitor Key. And when a single behavior event is registered, this event triggers multiple event records for the previous known visitor.

This happens when a user is submitting a web form with different contact information for testing purpose. There are some other scenarios where this can happen as well, such as clicking clickstream links from an Watson Campaign Automation Email.

To resolve this issue, clear browser cookies between tests.

How to find the DOMAIN_ID for a web tracking API

Steps to specify a Domain_ID for web tracking.

About this task

A Domain ID is a unique numeric value that is assigned by the Watson Campaign Automation to a user specified web site domain to track.

To find out this numeric value for a designated website domain, take the following steps within the Watson Campaign Automation.

Procedure

  1. Go to Reports > Reports Types > Expand the
    Web Sites section.
  2. Expand Web Tracking > Click Summary.
  3. Click the correct Domain Name.
  4. Once the report is finished, in the bottom left hand of the page, you see the letter
    i.
  5. Click the i.
  6. Get the DOMAIN_ID from the pop-up window.

Multiple mailing IDs in RawRecipientDataExport XML API call

Including more than one Mailing ID in an export.

If you want to include more than one Mailing ID in your RawRecipientDataExport, you must wrap each Mailing ID in <MAILING> tags.

Resolution

Example

<Envelope>
  <Body>
    <RawRecipientDataExport>
      <SEND_DATE_START>01/03/2013 00:00:00</SEND_DATE_START>
      <SEND_DATE_END>07/05/2013 23:59:00</SEND_DATE_END>
      <EXPORT_FORMAT>0</EXPORT_FORMAT>
      <MAILING>
        <MAILING_ID>XXXXXXXX</MAILING_ID>
      </MAILING>
      <MAILING>
        <MAILING_ID>XXXXXXXX</MAILING_ID>
      </MAILING>
      <ALL_EVENT_TYPES/>
      <EXCLUDE_DELETED/>
      <RETURN_MAILING_NAME/>
    </RawRecipientDataExport>
  </Body>
</Envelope>

The exported file shows results for both Mailing IDs in the Mailing_ID column.

Note: Your Mailing IDs are actual numbers and not Xs.

RawRecipientDataExport - Private mailings versus Shared mailings

Using the RawRecipientDataExport call to pull information from Private and Shared mailings.

When using RawRecipientDataExport with no specification on whether to target private or shared mailings, the API call pulls relevant data from Both. However, you might find differences in the results when you use the exact same call from a different user account.

If you have Automated Behavior Updates in your database and you create a query on opens for the previous day and perform a RawRecipientDataExport targeting just Opens, the results show as less than what you have in the query.

The reason is due to whether a mailing was sent from the Private folder of a user or the Shared folder.

When you run the RawRecipientDataExport API call, it looks at all the mailings' data that fit in your specified time frame in the Shared folder and then in the Private folder of the user who submits the call.

It will not look at mailings that are sent from the Private folder of another user. This is why you see a difference in results when using the exact same call between two different user accounts.

In the case of the query, the Watson Campaign Automation database with Automated Behavior Updates enabled, updates the Last Opened, Clicked, and Sent for all mailings sent within the entire Org regardless of whether it was sent from a shared location or a users' private folder.

RETURN SUBJECT in RawRecipientDataExport API

Quotation signs and commas escaped or not quotation qualified

Symptoms

When using the RETURN_SUBJECT optional element with RawRecipientDataExport API, the quotation signs and commas that are returned with the values for mailing subject line are not quote-qualified or escaped. This can cause the CSV (or other) file formatting to be broken. This does not affect the database fields/columns values returned.

For example, if a mailing subject line is: 'Hello, world!', the comma that is returned by RETURN_SUBJECT is not escaped. If user chooses CSV as RawRecipientDataExport result, the comma can cause the field to be broken down into two columns while it is opened in Microsoft Excel. This affects the rest of the columns that are returned for the same row.

Resolving the problem

There are two options to work around this problem:

  1. Stop using the RETURN_SUBJECT element.
  2. While a comma is in the subject line, use result file formats other than CSV to run RawRecipientDataExport API, such as TSV or PSV.

Running raw recipient data export API call on database returns an empty file

An empty file is returned when using the RawRecipientDataExport API call.

When the following XML is submitted:

<Envelope>
<Body>
  <RawRecipientDataExport>
  <LIST_ID>
  0000000/LIST_ID>
  <EVENT_DATE_START>04/25/2013 00:00:00</EVENT_DATE_START>
  <EVENT_DATE_END>05/02/2013 23:59:00</EVENT_DATE_END>
  <MOVE_TO_FTP/>

or

<ADD_TO_STORED_FILES/>
<EXPORT_FORMAT>0</EXPORT_FORMAT>
<EMAIL>emailhere</EMAIL>
<ALL_EVENT_TYPES/>
<EXCLUDE_DELETED/>
<COLUMNS>
  <COLUMN>
    <NAME>Email</NAME>
  </COLUMN>
  <COLUMN>
    <NAME>User_ID</NAME>
  </COLUMN>
</COLUMNS>
</RawRecipientDataExport>
</Body>
</Envelope>

The resulting file is an empty file with just field headers.

To fix this problem, add <INCLUDE_CHILDREN>

<Envelope>
  <Body>
    <RawRecipientDataExport>
      <LIST_ID>
      0000000/LIST_ID>
      <INCLUDE_CHILDREN/>
      <SEND_DATE_START>05/01/2013 00:00:00</SEND_DATE_START>
      <SEND_DATE_END>05/05/2013 23:59:00</SEND_DATE_END>
      <EVENT_DATE_START>05/05/2013 00:00:00</EVENT_DATE_START>
      <EVENT_DATE_END>05/05/2013 23:59:00</EVENT_DATE_END>
      <MOVE_TO_FTP/>
      <EXPORT_FORMAT>0</EXPORT_FORMAT>
      <EMAIL>emailhere</EMAIL>
      <ALL_EVENT_TYPES/>
      <EXCLUDE_DELETED/>
      <COLUMNS>
        <COLUMN>
          <NAME>Email</NAME>
        </COLUMN>
        <COLUMN>
          <NAME>User_ID</NAME>
        </COLUMN>
      </COLUMNS>
    </RawRecipientDataExport>
  </Body>
</Envelope>

Note: The include
children element allows retrieving mailings for queries and contact lists based on the specified
database.

What happens if you do not specify event date range and send date range

Event and send date range

Date range that is used if you don't specify an Event Date range and Send Date range in your Raw
Recipient Data Export API.

  • EVENT_DATE_START - If not specified, the Event Date Start defaults to the Send Date Start. If you do not specify Event Date Range or Send Date Range, the system defaults Event DateRange to the last 30 days.
  • EVENT_DATE_END - If you do not specify Event Date Range, the Event Date End defaults tothe Send Date End plus the number of days the Watson Campaign Automation is tracking the Organization'smailings. If you do not specify Event Date Range or Send Date Range, the system defaults the Event Date Range to the last 30 days.
  • SEND_DATE_START - If you do not specify Send Date Range, the Send Date Start defaults to Event Date Start minus the number of days the Watson Campaign Automation is tracking the Organization's mailings.
  • SEND_DATE_END - If you do not specify Send Date Range, the Send Date End defaults to the Event Date End.

What is the ALLOW CRM BLOCK element

CRM and the ALLOW_CRM_BLOCK element

In the GetMailingTemplates API, a <ALLOW_CRM_BLOCK> element sometimes appears in the XML reply.

If your database is CRM Enabled and your mailing template is associated to that CRM enabled database, contact list or query then this element appears in the API response. If your Mailing template has CRM Block, then the value would be true and if it does not, then the value would be false.

  • <ALLOW_CRM_BLOCK>true</ALLOW_CRM_BLOCK> - comes back if the mailing template has CRM Block.
  • <ALLOW_CRM_BLOCK>false</ALLOW_CRM_BLOCK> - comes back if your Mailing template does not have CRM Block.

The element is not documented in the public API Developers guide because the element is relevant only to those customers who have Salesforce Integration.

GetSentMailingsForList API call does not return mailings that were sent and then canceled

API call does not return mailings that were sent and then canceled.

GetSentMailingsForList API call does not return mailings that were sent and then canceled. See example code.

Example Code

<Envelope>
  <Body>
    <GetSentMailingsForList>
      <DATE_START>11/15/2012 00:00:00</DATE_START>
      <DATE_END>11/17/2012 23:59:59</DATE_END>
      <LIST_ID>-------</LIST_ID>
      <INCLUDE_CHILDREN/>
      <SENT/>
    </GetSentMailingsForList>
  </Body>
</Envelope>

<SENT/> is an Optional Mailing Type parameter to retrieve sent mailings. Within the Watson Campaign Automation, mailings that have are categorized as Sending Canceled instead of Sent do not appear when you use the Sent tag with the GetSentMailingsForList API call. To resolve this problem, omit the optional <SENT/> tag to get all types of mailings to be retrieved.

Example of Corrected Code

<Envelope>
  <Body>
    <GetSentMailingsForList>
      <DATE_START>11/15/2012 00:00:00</DATE_START>
      <DATE_END>11/17/2012 23:59:59</DATE_END>
      <LIST_ID>-----</LIST_ID>
      <INCLUDE_CHILDREN/>
    </GetSentMailingsForList>
  </Body>
</Envelope>

.NET API call to Receive JSession ID

Sample .NET code that can be used to submit a JSession ID for an API call.

Csharp.NET: (See BaseExample.cs in code samples that are attached).

protected string GetServletPostResponse(string xmlData, string sessionID)

{

string postContent = 'xml=' + System.Web.HttpUtility.UrlEncode(xmlData);

string url = baseURL;

if (sessionID != null)

{

url = url + ';jsessionid=' + sessionID;

}

return GetPostResponse(url, postContent);

}

VB.NET: (See BaseExample.vb in code samples that are attached).

Protected Function GetServletPostResponse(ByVal xmlData As String, ByVal sessionID As String) As String Dim postContent As String = 'xml=' + System.Web.HttpUtility.UrlEncode(xmlData)

Dim url As String = baseURL

If sessionID IsNot Nothing Then

url = url + ';jsessionid=' + sessionID

End If

Return GetPostResponse(url, postContent)

End Function

Assume identity API

Purpose of the Assume Identity API

Overview

"Enable use of Assume Identity API" setting allows Professional Services and CIS teams access to initiate API calls for your Org. Its primary function is to equip these teams with the ability to communicate with any user account in your org for running reports or retrieving data.

This functionality is disabled by default. It is recommended that you enable it only if requested to do so.

How many active API login sessions can run at any one time?

Active API sessions and how many can run at the same time.

Watson Campaign Automation API gives users the ability to maintain up to 10 active login sessions at any one time.

Watson Campaign Automation password does not work with API

What to do if your Watson Campaign Automation password doesn't work with API

The following characters are allowed in the passwords:

A-Z, a-z, 0-9,!@#$%^&*()-_=+[]{}.,;:?''/|`~

However, some combinations of characters in the password might not be accepted when API
calls are made.

These passwords allow the user access to their Org through the Watson Campaign Automation interface, but the API login calls fail.

When you make the call by using this password (example):

<Envelope>
  <Body>
    <Login>
      <USERNAME></USERNAME>
      <PASSWORD><b2H'U}&9></PASSWORD>
    </Login>
  </Body>
</Envelope>

You get the following response:

<Envelope>
  <Body>
    <RESULT>
      <SUCCESS>false</SUCCESS>
    </RESULT>
    <Fault>
      <Request/>
      <FaultCode/>
      <FaultString>Invalid XML Request</FaultString>
      <detail>
        <error>
          <errorid>51</errorid>
          <module/>
          <class>SP.API</class>
          <method/>
        </error>
      </detail>
    </Fault>
  </Body>
</Envelope>

Note: The Generate Temp Password option, in the Watson Campaign Automation might create a password that causes this problem.

Resolution

To solve this issue, you can change your password or wrap the password with CDATA
tags.

<Envelope>
  <Body>
    <Login>
      <USERNAME></USERNAME>
      <PASSWORD>
        <![CDATA[b2H'U}&9]]>
      </PASSWORD>
    </Login>
  </Body>
</Envelope>

XML API test harness shows an invalid XML request when attempting a login

Why a user is unable to log in to the API.

Symptoms

You choose Login as the API call and select the correct host. You enter your user name and password and you get the Invalid XML Request fault string.

Resolving the problem

The error occurs when you are using & (ampersand) in your password. To make your login successful you need to use the XML operator for the & (ampersand), which is &amp;

For example, if your password is 123&4, you enter 123&amp;4 into the test harness and log in.

XML API URLs

XML API URLs to use?

Each XML API URL is based on your Watson Campaign Automation Environment's Pod number. If you use login1.silverpop.com or engage1.silverpop.com to log in to Watson Campaign Automation, your API login is api1.ibmmarketingcloud.com/XMLAPI.

Engage1:

api1.ibmmarketingcloud.com/XMLAPI

Engage 2:

api2.ibmmarketingcloud.com/XMLAPI

Engage 3:

api3.ibmmarketingcloud.com/XMLAPI

Engage 4:

api4.ibmmarketingcloud.com/XMLAPI

Engage 5:

api5.ibmmarketingcloud.com/XMLAPI

Engage 6:

api6.ibmmarketingcloud.com/XMLAPI

Engage 7:

api7.ibmmarketingcloud.com/XMLAPI

Engage 8:

api8.ibmmarketingcloud.com/XMLAPI

Note: Remember to use http:// in front of the link.

Session expired error when an application makes an API call

Why an error occurs that states the session expired

The jsessionid is a legacy approach that is used for authenticating API requests. Our servers allow for a valid jsessionid to maintain a lifetime of 15 minutes. However, there do exist conditions in which the lifetime might be reduced, such as during moments of user inactivity or
changes by the load balancers in routing incoming API traffic.

To prevent this error, your application must contain logic to immediately call the Login API to retrieve a new, valid jsessionid when the old one expires. Alternatively, you might consider implementing OAuth 2.0 authentication method, which allows for greater security and more consistent access lifetimes.

Why use the authentication for Contact Actions feature withinthe Watson Campaign Automation?

Prevent users from starting any API calls unless successfully logged in.

Authentication for Contact Actions that are listed within the contact source access management area is used to prevent users from starting ANY API calls without first successfully doing a login API to get a session ID.

Note: Organization Administrators have access to override all of the functions that are available in the UI except Authentication for Contact Actions. For Authentication for Contact Actions, the contact source setting overrides the organization setting.

You need to make sure that you also check your list-level settings in order for this feature to work properly.

  1. Select your list by clicking the name of the list.
  2. Select the Fields tab.
  3. Select the Settings icon. On the Settings page, select the Security Settings tab.
  4. Select the Authentication for Contact Actions API check box.
  5. Select Save to save your changes.

Multiple mailing IDs in RawRecipientDataExport SOAP API

Specifying more than one mailing ID in a SOAP API export.

Symptoms

Can more than one mailing be specified by surrounding Mailing IDs in SOAP API call of RawRecipientDataExport as is done in API XML?

Resolving the problem

Specifying more than one Mailing ID, RawRecipientDataExport SOAP API is a little different from API XML.

In API XML, you can specify more than one mailing by surrounding each Mailing ID with <MAILING> parent element tags, to include as many Mailing IDs as you want.

Example

<MAILING>
  <MAILING_ID>5262609</MAILING_ID>
</MAILING>
<MAILING>
  <MAILING_ID>4667603</MAILING_ID>
</MAILING>
<MAILING>
  <MAILING_ID>5669841</MAILING_ID>
</MAILING>

In SOAP API, RawRecipientDataExport works only for two mailing IDs if
these codes are used.

<sil1:MAILING_ID>2158265</sil1:MAILING_ID>
<sil1:MAILING>
  <sil1:MAILING_ID>1728538</sil1:MAILING_ID>
</sil1:MAILING>

Note: The first Mailing ID is not wrapped with a MAILING tag and the second one is. Currently, RawRecipientDataExport SOAP API does not work on three or more Mailing IDs.

SURE_FROM_CODE and API

Explanation of SURE_FROM_CODE

Overview

The SURE_FROM_CODE is a generated variable that is inserted into a link inside a mailing. The contents of this variable are passed when an email is sent via API.

According to the XML API developer content,
SURE_FROM_CODE is an ID that can be returned in a mailing body and used to validate that a mailing is legitimate.

The SURE_FROM_CODE can be found in two different areas. Follow the steps to locate the code:

Under Create Mailings

  1. Go to Content > Create Mailing > Mailing Template.
  2. Name the mailing template.
  3. Click the Mailing Body tab.
  4. Click Save.
  5. Click the Personalization icon.
  6. Scroll to the end of the list, click SURE_FROM.
  7. SURE_FROM appears in the template.

Under View Mailings

  1. Go to Content > View Mailings > Templates.
  2. Click the name of the mailing template.
  3. Click the Mailing Body tab.
  4. Click the Personalization icon.
  5. Scroll to the end of the list, click SURE_FROM.
Note: Remember to save your template changes.

API ScheduleMailing subject line encoding

Encoding the subject line of a ScheduleMailing.

Subject line encoding for API allows any special characters that the Watson Campaign Automation allows including characters that are restricted by XML code. This applies to any API Mailing call with a Subject.

Example of a correctly encoded subject line

<Envelope>
  <Body>
    <ScheduleMailing>
      <TEMPLATE_ID>39032793</TEMPLATE_ID>
      <LIST_ID>8894623</LIST_ID>
      <MAILING_NAME>Subject Line Encoding2</MAILING_NAME>
      <SEND_HTML/>
      <SEND_AOL/>
      <SEND_TEXT/>
      <SUBJECT>
        <![CDATA[=?utf-8?B?U2lsdmVycG9wICYgQ29tcGFueQ==?=]]>
      </SUBJECT>
      <FROM_NAME>API Test Harness</FROM_NAME>
      <FROM_ADDRESS>email@email.com</FROM_ADDRESS>
      <REPLY_TO>email@email.com</REPLY_TO>
      <VISIBILITY>1</VISIBILITY>
    </ScheduleMailing>
  </Body>
</Envelope>

F2F API message body not being sent

Default message shows in Forward to Friend XML API.

Symptoms

F2F (Forward to Friend) XML API with a message body is not showing the message body, but rather the default.

Resolving the problem

Using the Forward to Friend (F2F) XML API via a mailing template that did not originally contain a F2F element is not able to build the F2F email body that is specified in the API call. It forwards the email that uses the original message body and not the one that can be specified within the API call:

<Envelope>
  <Body>
    <ForwardToFriend>
      <SENDER_EMAIL>myexample@domain.net</SENDER_EMAIL>
      <rs>MzM0NzI2MTkS1</rs>
      <m>6133</m>
      <RECIPIENTS>myexample@domain.net</RECIPIENTS>
      <MESSAGE>Forwarded Mailing</MESSAGE>
    </ForwardToFriend>
  </Body>
</Envelope>

Note: If the original message body does contain the F2F element, it cannot construct the F2F message body that includes that additional information that is passed along within the <MESSAGE> tag.

Naming a mailing with ScheduleMailing API

Characters that are allowed for naming a mailing.

Overview

The Watson Campaign Automation validates the mailing name and restricts the use of certain types of characters in the mailing name. Currently, the following characters can be used:

  • Spaces
  • Single quotation marks
  • A-Z, a-z, 0-9, # - _ ( ).

If a user tries to use any other disallowed characters, the following error shows:

'Only spaces, single quotes, and the following characters are allowed: A-Z, a-z, 0-9, # - _ ( ).
'

mailing_allow_character.png

However, the ScheduleMailing does not do this type of validation on the mailing name, which means mailing names with disallowed characters, such as pipe sign '|' or colon ':' can be created.

Make sure to use only the allowed characters from spaces, single quotation marks, and the following characters: A-Z, a-z, 0-9, # - _ ( ).

Note: Applies to the SaveMailing API call as well.

Purpose Of SURE_FROM_CODE Used By GetContactMailingDetails

Clarification or reason of the Element[SURE_FROM_CODE] within the Pre XML API operation and why it's required in the Mailing Body of the Mailing template.

The SURE_FROM_CODE can be thought of or similar to acting as a numeric UPC barcode so if a Recipient has questions about an email's
authenticity or wanted additional information regarding the Mailing then they would contact your organization and provide that SURE_FROM_CODE to validate which Mailing was received during that time.

The SURE_FROM_CODE can be only found in a generated Mailing template of the Sent Mailing in order for an ID to be returned, in the Mailing Body, and used to validate that the Mailing is legitimate.

When creating or editing a Mailing, SURE_FROM is a drop-down menu item located under "Insert Personalization" icon then you would provide the appropriate verbiage in the Mailing Body as below:
[note, please review "API What Is SURE_FROM_CODE?" in Related section to see actual steps]"To be
sure that this email is authentic, please contact COMPANY NAME at 1-800-985-9555 and provide the
following code:" [note, then the personalization code %%SURE_FROM%% would follow].The SURE_FROM_CODE
itself is not stored in the database, but only in the content of the Mailing and it can be generated
from a Mailing ID, Report ID and Recipient ID if you need it to locate a particular Mailing.The
SURE_FROM_CODE generated by an Automated Mailings which includes Auto-Responder, Automated Message
Groups and Program emails would generate an error so remember that it applies only to single
Mailings
.

Note: The SURE_FROM_CODE is only present in a Mailing if you have chosen the Mailing's personalization option SURE_FROM.

Links in API scheduled mailing are not being tracked

Links do not track even though link tracking is enabled in the actual mailing template.

About this task

When scheduling a mailing by using the API <ScheduleMailing> call, by using the SUBSTITUTION child element, you can pass through entire HTML. However, you might find that your links do not track even though link tracking is enabled in the actual mailing template.

To get around this, you need to set your links as DLL's (Dynamic Link Leaders).

For full details on building a Dynamic Link Leader URL, refer to the Transactional triggered messagingguide.

Procedure

  1. Under the Transact XML for Developers section, expand the section: Hyperlink Tracking and Personalization - Dynamic Link Leader (DLL). This gives detailed instructions on how to build DLL links.
  2. Expand the section beneath: 'Query String Parameters' for the different parameters.
    Note: Because this is the Transact XML guide, it refers to elements that are not required for normal Watson Campaign Automation. Specifically, you need to be concerned only with what goes into the actual <a href.....> tag. Everything external of this is not required.

How to put API XML data into Excel

Importing XML results into Excel for better display or calculations.

About this task

There can be a need to take the XML results from the test harness output and import into Excel for better display or calculations.

Note: IBM does not support Excel and information is provided as an option to organize data.

Procedure

  1. Run the API call and get results on the right side beginning with <Envelope>.
  2. Copy the entire results <Envelope> ... </Envelope>.
  3. Paste copied results in Notepad.
  4. Save the file and change the .txt extension to .xml.
  5. Open Excel, go to the Data tab, 'From Other Sources', select 'From XML Data Import'.
  6. Select the XML file.
  7. Click Open. A wizard pops up, click OK.
  8. Decide where you want to put the data, click OK and the data is imported into Excel.
Note: Use of special characters in the .xml file can cause errors upon import. However, using a .txt file with special characters allows the import to be successful.

 

3 comments on"WCA Troubleshooting"

  1. For the topic How to put API XML data into Excel – it should be noted that the XML should not contain & characters as it will cause the import to fail. Markets often use this character (and potentially other invalid characters) in the mailing subject line. A simple find and replace does the trick prior to importing.

    Cheers, Chris

    • Hi Chris,
      Not sure if anyone replied to you on this, but I am having it looked into. Apologies for the delay.

      Thank you

    • Hello Chris,
      I have made update to the How to put API XML data into Excel section. I found, after testing, that use of special characters anywhere in the .xml file can cause failure. However, to get around this, you can use a .txt file with special characters and the import will be a success.

      Thank you
      Jeri

Join The Discussion

Your email address will not be published. Required fields are marked *