| Title: | Connect to Your 'IBM Acoustic' Data |
| Version: | 0.2.1 |
| Description: | Authentication can be the most difficult part about working with a new API. 'ibmAcousticR' facilitates making a connection to the 'IBM Acoustic' email campaign management API and executing various queries. The 'IBM Acoustic' API documentation is available at https://developer.ibm.com/customer-engagement/docs/. This package is not supported by 'IBM'. |
| License: | CC0 |
| Encoding: | UTF-8 |
| LazyData: | true |
| Depends: | R (≥ 4.0.0) |
| Imports: | jsonlite (≥ 1.7.0), httr (≥ 1.4.1), XML (≥ 3.99-0.5) |
| RoxygenNote: | 7.1.1 |
| NeedsCompilation: | no |
| Packaged: | 2020-08-27 23:13:37 UTC; c.umphlett |
| Author: | Chris Umphlett [aut, cre], Avinash Panigrahi [aut] |
| Maintainer: | Chris Umphlett <christopher.umphlett@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2020-08-28 05:20:03 UTC |
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)
Detect Faulty XML Request
Description
Searches the results content for the tag "<FaultString>". If it is found it gives the user a message and exits the function.
Usage
check_for_faulty_xml(request_obj)
Value
Message to the console.
Check Request Status
Description
This function is called by other functions that submit jobs to the Acoustic/Silverpop API. It checks the status code returned and tells the user if there was an error code and exits the function.
Usage
check_request_status(request_obj)
Value
If status code is not 200, a message to console
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 Job Id of Submitted Job
Description
This function is called by other functions that submit jobs to the Acoustic/Silverpop API. It extracts the Job Id from the XML returned by the API call.
Usage
get_job_id(request_obj, path)
Arguments
request_obj |
Name of the object returned from API call, should always be "request". |
path |
XML path to the job id. |
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.
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)
Stop Function Quietly
Description
Quit a function execution without printing error messages. The idea came from a Stack Overflow answer https://stackoverflow.com/questions/14469522/stop-an-r-program-without-error.
Usage
stop_quietly()
Value
Exits a function.