R/utils-control.R

In StevenMMortimer/salesforcer: An Implementation of 'Salesforce' APIs Using Tidy Principles

#' Auxiliary for Controlling Calls to Salesforce APIs
#'
#' Typically only used internally by functions when control parameters are passed
#' through via dots (...), but it can be called directly to control the behavior
#' of API calls. This function behaves exactly like \code{\link[stats]{glm.control}}
#' for the \code{\link[stats]{glm}} function.
#'
#' @importFrom purrr modify modify_if map
#' @param AllOrNoneHeader \code{list}; containing the \code{allOrNone} element with
#' a value of \code{TRUE} or \code{FALSE}. This control specifies whether a call rolls back all changes
#' unless all records are processed successfully. This control is available in
#' SOAP, REST, and Metadata APIs for the following functions: \code{\link{sf_create}},
#' \code{\link{sf_delete}}, \code{\link{sf_update}}, \code{\link{sf_upsert}}, \code{\link{sf_create_metadata}},
#' \code{\link{sf_delete_metadata}}, \code{\link{sf_update_metadata}}, \code{\link{sf_upsert_metadata}}.
#' For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_allornoneheader.htm}{here}.
#' @param AllowFieldTruncationHeader \code{list}; containing the \code{allowFieldTruncation}
#' element with a value of \code{TRUE} or \code{FALSE}. This control specifies the truncation behavior
#' for some field types in SOAP API version 15.0 and later for the following functions:
#' \code{\link{sf_create}}, \code{\link{sf_update}}, \code{\link{sf_upsert}}. For
#' more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_allowfieldtruncation.htm}{here}.
#' @param AssignmentRuleHeader \code{list}; containing the \code{useDefaultRule}
#' element with a value of \code{TRUE} or \code{FALSE} or the \code{assignmentRuleId} element.
#' This control specifies the assignment rule to use when creating or updating an
#' Account, Case, or Lead for the following functions: \code{\link{sf_create}},
#' \code{\link{sf_update}}, \code{\link{sf_upsert}}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_assignmentruleheader.htm}{here}.
#' @param DisableFeedTrackingHeader \code{list}; containing the \code{disableFeedTracking}
#' element with a value of \code{TRUE} or \code{FALSE}. This control specifies whether
#' the changes made in the current call are tracked in feeds for SOAP API calls made
#' with the following functions: \code{\link{sf_create}}, \code{\link{sf_delete}},
#' \code{\link{sf_update}}, \code{\link{sf_upsert}}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_disablefeedtracking.htm}{here}.
#' @param DuplicateRuleHeader \code{list}; containing the \code{allowSave},
#' \code{includeRecordDetails}, and \code{runAsCurrentUser} elements each with a
#' value of \code{TRUE} or \code{FALSE}. This control specifies how duplicate rules should be applied
#' when using the following functions: \code{\link{sf_create}}, \code{\link{sf_update}},
#' \code{\link{sf_upsert}}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_duplicateruleheader.htm}{here}.
#' @param EmailHeader \code{list}; containing the \code{triggerAutoResponseEmail},
#' \code{triggerOtherEmail}, and \code{triggerUserEmail} elements each with a
#' value of \code{TRUE} or \code{FALSE}. This control determines if an email notification should be sent
#' when a request is processed by SOAP API calls made with the following functions:
#' \code{\link{sf_create}}, \code{\link{sf_delete}}, \code{\link{sf_update}}, \code{\link{sf_upsert}},
#' \code{\link{sf_reset_password}}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_emailheader.htm}{here}.
#' @param LocaleOptions \code{list}; containing the \code{language} element. This control
#' specifies the language of the labels returned by the \code{\link{sf_describe_objects}}
#' function using the SOAP API. The value must be a valid user locale (language and country), such as
#' \code{de_DE} or \code{en_GB}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_localeheader.htm}{here}.
#' The list of valid user locales is available
#' \href{https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/api/sforce_api_objects_categorynodelocalization.htm#languagelocalekey_desc}{here}.
#' @param MruHeader \code{list}; containing the \code{updateMru} element with a value
#' of \code{TRUE} or \code{FALSE}. This control indicates whether to update the list
#' of most recently used items (\code{TRUE}) or not (\code{FALSE}) in the Recent Items
#' section of the sidebar in the Salesforce user interface. This works for SOAP API calls
#' made with the following functions: \code{\link{sf_create}}, \code{\link{sf_update}},
#' \code{\link{sf_upsert}}, \code{\link{sf_retrieve}}, \code{\link{sf_query}}. For more
#' information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_mruheader.htm}{here}.
#' @param OwnerChangeOptions \code{list}; containing the \code{options} element.
#' This control specifies the details of ownership of attachments and notes when a
#' record’s owner is changed. This works for SOAP API calls made with the following functions:
#' \code{\link{sf_update}}, \code{\link{sf_upsert}}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_ownerchangeoptions.htm}{here}.
#' @param QueryOptions \code{list}; containing the \code{batchSize} element.
#' This control specifies the batch size for query results . This works for SOAP or
#' REST API calls made with the following functions: \code{\link{sf_query}},
#' \code{\link{sf_retrieve}}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_queryoptions.htm}{here}.
#' @param UserTerritoryDeleteHeader \code{list}; containing the \code{transferToUserId} element.
#' This control specifies a user to whom open opportunities are assigned when the current
#' owner is removed from a territory. This works for the \code{\link{sf_delete}} function
#' using the SOAP API. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_userterritorydeleteheader.htm}{here}.
#' @param BatchRetryHeader \code{list}; containing the \code{Sforce-Disable-Batch-Retry} element.
#' When you create a bulk job, the Batch Retry control lets you disable retries
#' for unfinished batches included in the job. This works for most operations run through
#' the Bulk 1.0 API (e.g. \code{sf_create(., api_type = "Bulk 1.0")}) or creating
#' a Bulk 1.0 job with \code{\link{sf_create_job_bulk}}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/async_api_headers_disable_batch_retry.htm}{here}.
#' @param LineEndingHeader \code{list}; containing the \code{Sforce-Line-Ending} element.
#' When you’re creating a bulk upload job, the Line Ending control lets you
#' specify whether line endings are read as line feeds (LFs) or as carriage returns
#' and line feeds (CRLFs) for fields of type Text Area and Text Area (Long). This
#' works for most operations run through the Bulk APIs and/or creating a Bulk
#' job from scratch with \code{\link{sf_create_job_bulk}}. However, note that
#' as of \code{readr v1.3.1} all CSV files end with the line feed character
#' ("\\n") regardless of the operating system. So it is usually best to not specify
#' this argument. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/async_api_headers_line_ending.htm}{here}.
#' @param PKChunkingHeader \code{list}; containing the \code{Sforce-Enable-PKChunking} element.
#' Use the PK Chunking control to enable automatic primary key (PK) chunking
#' for a bulk query job. This works for queries run through the Bulk 1.0 API either via
#' \code{sf_query(., api_type = "Bulk 1.0")}) or \code{\link{sf_query_bulk}}. For
#' more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/async_api_headers_enable_pk_chunking.htm}{here}.
#' @template api_type
#' @template operation
#' @examples
#' \dontrun{
#' this_control <- sf_control(DuplicateRuleHeader=list(allowSave=TRUE,
#'                                                     includeRecordDetails=FALSE,
#'                                                     runAsCurrentUser=TRUE))
#' new_contact <- c(FirstName = "Test", LastName = "Contact-Create")
#' new_record <- sf_create(new_contact, "Contact", control = this_control)
#'
#' # specifying the controls directly and are picked up by dots
#' new_record <- sf_create(new_contact, "Contact",
#'                         DuplicateRuleHeader = list(allowSave=TRUE,
#'                                                    includeRecordDetails=FALSE,
#'                                                    runAsCurrentUser=TRUE))
#' }
#' @export
sf_control <- function(AllOrNoneHeader=list(allOrNone=FALSE),
                       AllowFieldTruncationHeader=list(allowFieldTruncation=FALSE),
                       AssignmentRuleHeader=list(useDefaultRule=TRUE),
                       DisableFeedTrackingHeader=list(disableFeedTracking=FALSE),
                       DuplicateRuleHeader=list(allowSave=FALSE,
                                                includeRecordDetails=FALSE,
                                                runAsCurrentUser=TRUE),
                       EmailHeader=list(triggerAutoResponseEmail=FALSE,
                                        triggerOtherEmail=FALSE,
                                        triggerUserEmail=TRUE),
                       LocaleOptions=list(language="en_US"),
                       MruHeader=list(updateMru=FALSE),
                       OwnerChangeOptions=list(options=list(list(execute=TRUE,
                                                                 type="EnforceNewOwnerHasReadAccess"),
                                                            list(execute=FALSE,
                                                                 type="KeepAccountTeam"),
                                                            list(execute=FALSE,
                                                                 type="KeepSalesTeam"),
                                                            list(execute=FALSE,
                                                                 type="KeepSalesTeamGrantCurrentOwnerReadWriteAccess"),
                                                            list(execute=FALSE,
                                                                 type="SendEmail"),
                                                            list(execute=FALSE,
                                                                 type="TransferAllOwnedCases"),
                                                            list(execute=TRUE,
                                                                 type="TransferContacts"),
                                                            list(execute=TRUE,
                                                                 type="TransferContracts"),
                                                            list(execute=FALSE,
                                                                 type="TransferNotesAndAttachments"),
                                                            list(execute=TRUE,
                                                                 type="TransferOpenActivities"),
                                                            list(execute=TRUE,
                                                                 type="TransferOrders"),
                                                            list(execute=FALSE,
                                                                 type="TransferOtherOpenOpportunities"),
                                                            list(execute=FALSE,
                                                                 type="TransferOwnedClosedOpportunities"),
                                                            list(execute=FALSE,
                                                                 type="TransferOwnedOpenCases"),
                                                            list(execute=FALSE,
                                                                 type="TransferOwnedOpenOpportunities"))),
                       QueryOptions=list(batchSize=500),
                       UserTerritoryDeleteHeader=list(transferToUserId=NA),
                       BatchRetryHeader=list(`Sforce-Disable-Batch-Retry`=FALSE),
                       LineEndingHeader=list(`Sforce-Line-Ending`=NA),
                       PKChunkingHeader=list(`Sforce-Enable-PKChunking`=FALSE),
                       api_type = NULL,
                       operation = NULL){

  # determine which elements were supplied, dropping the function call itself
  supplied_arguments <-  as.list(match.call()[-1])

  # now eval them to no longer be objects of class "call"
  supplied_arguments <- supplied_arguments %>%
    map(eval) %>%
    # convert boolean args to lowercase
    modify(~modify_if(., is.logical, tolower))

  # check that they are all lists
  list_argument <- sapply(supplied_arguments, is.list)
  if(!all(list_argument)){
    if(!all(names(which(!list_argument)) %in% c("api_type", "operation"))){
      mismatched_warn_str <- c()
      for(n in names(which(!list_argument))){
        if(!(n %in% c("api_type", "operation"))){
          mismatched_warn_str <- c(mismatched_warn_str, n)
        }
      }
      mismatched_warn_str <- paste0(mismatched_warn_str, collapse=", ")
      stop(
        sprintf(paste0("The following control arguments were not provided as lists: \n%s\n\n",
                       "Review the argument defaults in 'sf_control()' for help formatting."),
                mismatched_warn_str)
        , call. = FALSE
      )
    }
  }

  # check that the controls valid for the API and operation
  supplied_arguments <- filter_valid_controls(supplied_arguments,
                                              api_type = api_type,
                                              operation = operation)

  return(supplied_arguments)
}

#' Return the Accepted Control Arguments by API Type
#'
#' @template api_type
#' @return \code{character}; a vector of strings indicating which control arguments
#' are accepted by the specified API.
#' @note This function is meant to be used internally. Only use when debugging.
#' @keywords internal
#' @export
accepted_controls_by_api <- function(api_type = c("SOAP", "REST", "Bulk 1.0", "Bulk 2.0", "Metadata")){
  this_api_type <- match.arg(api_type)
  switch(this_api_type,
         "SOAP" = c("AllOrNoneHeader", "AllowFieldTruncationHeader", "AssignmentRuleHeader",
                    "DisableFeedTrackingHeader", "DuplicateRuleHeader",
                    "EmailHeader", "LocaleOptions",
                    "MruHeader", "OwnerChangeOptions",
                    "QueryOptions", "UserTerritoryDeleteHeader"),
         "REST" = c("AllOrNoneHeader", "AssignmentRuleHeader", "QueryOptions"),
         "Bulk 1.0" = c("LineEndingHeader", "BatchRetryHeader", "PKChunkingHeader"),
         "Bulk 2.0" = c("LineEndingHeader"),
         "Metadata" = c("AllOrNoneHeader"),
         character(0))
}

#' Return the Accepted Control Arguments by Operation
#'
#' @template operation
#' @return \code{character}; a vector of strings indicating which control arguments
#' are accepted by the specified operation.
#' @note This function is meant to be used internally. Only use when debugging.
#' @keywords internal
#' @export
accepted_controls_by_operation <- function(operation = c("create" , "insert",
                                                         "update", "upsert",
                                                         "delete", "undelete", "hardDelete",
                                                         "query", "queryall", "retrieve",
                                                         "convertLead", "merge",
                                                         "describeSObjects",
                                                         "resetPassword")){
  record_creation_controls <- c("AllOrNoneHeader", "AllowFieldTruncationHeader",
                                "AssignmentRuleHeader", "DisableFeedTrackingHeader",
                                "DuplicateRuleHeader", "EmailHeader", "MruHeader")
  query_controls <- c("MruHeader", "QueryOptions", "PKChunkingHeader")
  bulk_controls <- c("BatchRetryHeader", "LineEndingHeader")
  this_operation <- match.arg(operation)
  switch(this_operation,
         "create" = c(record_creation_controls, bulk_controls),
         "insert" = c(record_creation_controls, bulk_controls),
         "update" = c(record_creation_controls, bulk_controls, "OwnerChangeOptions"),
         "upsert" = c(record_creation_controls, bulk_controls, "OwnerChangeOptions"),
         "delete" = c("AllOrNoneHeader", "DisableFeedTrackingHeader", "EmailHeader",
                      "UserTerritoryDeleteHeader", bulk_controls),
         "undelete" = c("AllOrNoneHeader", "AllowFieldTruncationHeader"),
         "hardDelete" = bulk_controls,
         "query" = query_controls,
         "queryall" = query_controls,
         "retrieve" = c("MruHeader"),
         "convertLead" = c("AllowFieldTruncationHeader", "DisableFeedTrackingHeader"),
         "merge" = c("AllowFieldTruncationHeader", "DisableFeedTrackingHeader"),
         "describeSObjects" = c("LocaleOptions"),
         "resetPassword" = c("EmailHeader"),
         character(0))
}

#' Filter Out Control Arguments by API or Operation
#'
#' @param supplied \code{list}; a list of input data regarding the control arguments
#' along with the with API and operation information to make a complete assessment
#' of which control arguments are applicable.
#' @template api_type
#' @template operation
#' @return \code{character}; a vector of strings returning only the control arguments
#' that are accepted by the specified API and operation.
#' @note This function is meant to be used internally. Only use when debugging.
#' @keywords internal
#' @export
filter_valid_controls <- function(supplied, api_type = NULL, operation = NULL){

  if(is.null(api_type) & !is.null(supplied$api_type)){
    api_type <- supplied$api_type
  }
  # remove the api_type from the supplied args, if it exists
  supplied$api_type <- NULL

  if(is.null(operation) & !is.null(supplied$operation)){
    operation <- supplied$operation
  }
  # remove the api_type from the supplied args, if it exists
  supplied$operation <- NULL

  if(!is.null(api_type) ){
    valid <- accepted_controls_by_api(api_type)
    # provide a warning before dropping
    if(length(setdiff(names(supplied), valid)) >  0){
      warn_w_errors_listed(sprintf(paste0("Ignoring the following controls which ",
                                          "are not used in the %s API: %s"),
                                   api_type,
                                   paste0(setdiff(names(supplied), valid), collapse=", ")))
    }
    supplied <- supplied[intersect(names(supplied), valid)]
  }

  if(!is.null(operation)){
    valid <- accepted_controls_by_operation(operation)
    # provide a warning before dropping
    if(length(setdiff(names(supplied), valid)) >  0){
      warn_w_errors_listed(sprintf(paste0("Ignoring the following controls which ",
                                          "are not used in the %s operation: %s"),
                                   operation,
                                   paste0(setdiff(names(supplied), valid), collapse=", ")))
    }
    supplied <- supplied[intersect(names(supplied), valid)]
  }

  return(supplied)
}

#' Of All Args Return Ones Matching Control Arguments
#'
#' @param args \code{character}; a vector of strings that represent the function
#' arguments.
#' @return \code{character}; a vector of strings returning only the function arguments
#' that match control arguments so that users can specify them directly in each
#' function and not have to construct a control object every time in order to
#' pass only one or two control arguments.
#' @note This function is meant to be used internally. Only use when debugging.
#' @keywords internal
#' @export
return_matching_controls <- function(args){
  possible_controls <- formals(sf_control)
  idx <- names(args) %in% names(possible_controls)
  return(args[idx])
}


# HELD BACK CONTROL OPTIONS BECAUSE THEY MAY BE CONFUSING OR NOT FEASIBLE GIVEN
# THE WAY THE PACKAGE IS CURRENTLY WRITTEN:

#CallOptions=list(client=NA, defaultNamespace=NA)
#' CallOptions \code{list}; containing the \code{client} and \code{defaultNamespace}
#' elements. This control specifies the call options needed to work with a specific client.
#' This control is only available for use with the Partner WSDL and works for most all functions
#' in this package. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_calloptions.htm}{here}.

#LimitInfoHeader=list(current="20",
#                     limit="250",
#                     type="API REQUESTS")
#' LimitInfoHeader \code{list}; containing the \code{current}, \code{limit},
#' and \code{type} elements. This control determines if limit information for the organization should
#' be returned in the header each request response. This works for most all functions,
#' except \code{\link{sf_auth()}}. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_limitinfo.htm}{here}.

#PackageVersionHeader=list(packageVersions=NA)
#' PackageVersionHeader \code{list}; containing the \code{packageVersions} element.
#' This header specifies the package version for each installed managed package in
#' API version 16.0 and later. This works for most all functions in this package.
#' For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_header_packageversionheader.htm}{here}.

#ContentTypeHeader=list(`Content-Type`="application/xml")
#' ContentTypeHeader \code{list}; containing the \code{Content-Type} element.
#' This header specifies the format for your request and response. Set the value of
#' this header to match the contentType of the job you’re working with. This works
#' for most all functions with the Bulk 1.0 API. For more information, read the Salesforce documentation
#' \href{https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/async_api_headers_content_type.htm}{here}.


# REST Translations
#  AllOrNoneHeader =  (allOrNone, currently in our batched data process)
#  AssignmentRuleHeader = Sforce-Auto-Assign
#  DuplicateRuleHeader = NONE!
#  QueryOptions = Sforce-Query-Options

# Bulk 1.0 Translations
#  AssignmentRuleHeader = assignmentRuleId (in the job info) (only if id?)
#  AllOrNoneHeader? = Unknown if SOAP works for Bulk 1.0 as well
#  DuplicateRuleHeader? = Unknown if SOAP works for Bulk 1.0 as well

# Bulk 2.0 Translations (does not use any headers)
# Just line ending?