Package 'ibmAcousticR'

Connect to API and Obtain Access Token

Description

Prior to attempting this you must have a Client Id, Client Secret and Refresh Token. The first two are assigned on an organization level; the latter must be created by someone with an admin role in Acoustic and assigned to you.

Usage

acoustic_auth(org_client_id, org_client_secret, my_refresh_token, pod_number)

Arguments

org_client_id	Organization's Client Id.
org_client_secret	Organization's Client Secret.
my_refresh_token	Your personal Refresh Token.
pod_number	Pod number is the number in the URL, e.g. engage1.silverpop.com.

Details

Access tokens expire after four hours. Thus, this function should be run each time you utilize the package and may need to be re-called periodically if you have a session open for a long duration.

It is not recommended that these authentication parameters be stored directly in your code. There are various methods and packages available that are more secure; this package does not require you to use any one in particular.

More information on this available at https://developer.ibm.com/ customer-engagement/tutorials/ getting-started-oauth-watson-campaign-automation/ .

Value

A vector with the session's access token.

Examples

## Not run: 
access_token <- acoustic_auth(org_client_id = "abc",
org_client_secret = "xyz",
my_refresh_token = "123")

## End(Not run)

---

Get Export of All Email Contact Events

Description

This function submits a job to Acoustic that exports all email contact events. Various criteria are available to filter the export. Some, but not all, of these have been built into the parameters of this function. Reading the IBM Acoustic documentation is useful: https://developer.ibm.com/customer-engagement/tutorials/ export-raw-contact-events/

Usage

get_all_contacts(
  pod_number,
  session_access_token,
  start_date,
  end_date,
  date_type = "EVENT",
  event_types = "<ALL_EVENT_TYPES/>",
  export_format = 0,
  move_to_ftp = FALSE,
  exclude_deleted = FALSE,
  optional_columns = TRUE,
  file_name_prefix = "",
  confirm_email = ""
)

Arguments

pod_number	Pod number is the number in the URL, e.g. engage1.silverpop.com.
session_access_token	Access token obtained during this session.
start_date	Filter for emails sent on or after this date.
end_date	Filter for emails sent on or before this date.
date_type	Select whether the date filters should be on the event date or the email sent date ("EVENT" or "SENT").
event_types	There are 18 different events. By default all event types are returned. This parameter takes XML arguments where you can override the default and specify all of the events you want. See the Acoustic documentation for the full list.
export_format	Acoustic provides three delimiter file types: 0 (CSV), 1 (PIPE), or 2 (TAB). CSV is the default used here.
move_to_ftp	If TRUE (default is FALSE) will send files to SFTP server instead of being able to download manually from the portal.
exclude_deleted	Do you want to exclude contacts that have been deleted, can be TRUE/FALSE. Per Acoustic, "Inclusion of this element can greatly decrease the time to generate the metrics file and is useful whenever metrics for deleted contacts are not required."
optional_columns	Do you want to include six optional columns in the results, can be TRUE/FALSE. These columns are the mailing name, mailing subject, from email address, from email name, CRM campaign Id, and program Id.
file_name_prefix	Optional argument that should be used if you want to add a particular prefix to the file that you will download from your portal.
confirm_email	Optional argument to specify an email address where IBM will let you know when the job has completed.

Details

The date type is set to EVENT by default. If you filter by the sent date you may not get all applicable events, as some events (a future click) will not yet have happened. If you do filter by SENT date and are incrementally updating your data you should plan to go back and retroactively update past dates.

Job results are available as exports in the Silverpop portal by going to Resources -> Data Jobs.

It is not recommended that these authentication parameters be stored directly in your code. There are various methods and packages available that are more secure; this package does not require you to use any one in particular.

Value

A vector with the Job Id.

Examples

## Not run: 
access_token <- acoustic_auth(org_client_id = "abc",
org_client_secret = "xyz",
my_refresh_token = "123")

job_id <- get_all_contacts(pod_number, access_token,
"2020-01-01", "2020-01-05", event_types = "<CLICKS/>",
1, exclude_deleted = TRUE, optional_columns = TRUE)

## End(Not run)

---

Get Export of a Database or contact List

Description

This function submits a job to Acoustic that exports a particular database or contact list based on the list id. Various criteria are available to filter the export. Some, but not all, of these have been built into the parameters of this function. Reading the IBM Acoustic documentation is useful: https://developer.ibm.com/customer-engagement/tutorials/ export-from-a-database/

Usage

get_contact_list(
  pod_number,
  session_access_token,
  list_id,
  start_date,
  end_date,
  export_format = "CSV",
  move_to_ftp = FALSE,
  confirm_email = ""
)

Arguments

pod_number	Pod number is the number in the URL, e.g. engage1.silverpop.com.
session_access_token	Access token obtained during this session.
list_id	Acoustic id for the database or contact list (string).
start_date	Filter for emails sent on or after this date.
end_date	Filter for emails sent on or before this date.
export_format	Acoustic provides three delimiter file types: CSV, PIPE, TAB. CSV is the default used here.
move_to_ftp	If TRUE (default is FALSE) will send files to SFTP server instead of being able to download manually from the portal.
confirm_email	Optional argument to specify an email address where IBM will let you know when the job has completed.

Details

Job results are available as exports in the Silverpop portal by going to Resources -> Data Jobs.

It is not recommended that these authentication parameters be stored directly in your code. There are various methods and packages available that are more secure; this package does not require you to use any one in particular.

Value

A vector with the Job Id.

Examples

## Not run: 
access_token <- acoustic_auth(org_client_id = "abc",
org_client_secret = "xyz",
my_refresh_token = "123")

job_id <- get_contact_list(pod_number, access_token, list_id,
"2020-01-01", "2020-01-05", "PIPE")

## End(Not run)

---

Get the Status of a Submitted Job

Description

Prior to attempting this you must authenticate and obtain an access token, and then submit a call that is processed as a job to retrieve from the Acoustic portal. The function used to submit that job will provide the Job Id.

Usage

get_job_status(pod_number, session_access_token, desired_job_id)

Arguments

pod_number	Pod number is the number in the URL, e.g. engage1.silverpop.com.
session_access_token	Access token obtained during this session.
desired_job_id	Id for job for which you want the status.

Value

A vector with the session's access token.

Examples

## Not run: 
access_token <- acoustic_auth(org_client_id = "abc",
org_client_secret = "xyz",
my_refresh_token = "123")

job_id <- get_all_contacts(access_token)
get_job_status(1, access_token, "123456789")

## End(Not run)

---

Get List of Programs

Description

Get list of all programs in a particular date range. Prior to attempting this you must authenticate and obtain an access token.

Usage

get_programs(pod_number, session_access_token, start_date, end_date)

Arguments

pod_number	Pod number is the number in the URL, e.g. 1 in engage1.silverpop.com.
session_access_token	Access token obtained during this session.
start_date	Filter for programs created on or after this date.
end_date	Filter for programs created on or before this date.

Value

A data frame with the programs and program details.

Examples

## Not run: 
access_token <- acoustic_auth(org_client_id = "abc",
org_client_secret = "xyz",
my_refresh_token = "123")

get_programs(1, access_token, "2020-01-01", "2020-05-31")

## End(Not run)

---