If you’re inserting records from R you may want to turn off the assignment rules or even bypass duplicate rules and alerts to save records. Beginning in Version 0.1.3 of the salesforcer package many functions have a
control argument that will allow you to fine tune the behavior of calls to the Salesforce APIs. This vignette will introduce the different options you can control and how to pass them into the salesforcer functions you’re already familiar with.
This new feature can be seen in the
sf_create (and many other functions) as
control=list(...). The dots mean that you can pass any number of controls directly into the function. For example, the following code will create a record, but prevent its creation from showing up in the Chatter feeds by setting the
You will notice that the argument
DisableFeedTrackingHeader can be included right into the function without any documentation existing for it in the
sf_create function. This is because the dots (
...) allow you to pass over a dozen different control parameters and that documentation would be tedious to create and maintain over multiple functions in the package. However, you will notice in the documentation entry for the
control argument there is a link to a function called
sf_control which you can use to directly to pass into
control or simply to review its documentation of all the possible control parameters and their defaults. This is where you can review the various control options in more detail before trying to set them.
You may have also noticed that the argument DisableFeedTrackingHeader was formatted as a list with an element inside called
disableFeedTracking set to
TRUE. This may seem redundant but there are two reasons for this. First, this is exactly how the Salesforce APIs documents these options, which are typically referred to as “headers” because they are passed as a named header of the HTTP request and then the header fields and values are provided for that header. Second, some headers have multiple fields and values so a list is the only way to provide multiple named fields and values under a single header entity. For example, the DuplicateRuleHeader, which controls whether the duplicate rules can be overridden when inserting records from the API, has three fields:
runAsCurrentUser. Supplying all three requires a list-like structure, which may seem redundant in other cases, but is necessary to follow.
Finally, you will notice in the example call that the
api_type argument is set to “SOAP”. This is because the
DisableFeedTrackingHeader is a control that is only available when making calls via the SOAP API. You will receive a warning when trying to set control parameters for APIs or operations that do not recognize that control. For example, the following code tries to set the
BatchRetryHeader for a call to the SOAP API which does not acknowledge that control. That control is only used with the Bulk 1.0 API since its records as submitted in batches and automatic retry can be controlled.
If this type of control structure is new to you, take a look at the documentation for the
glm.control functions. The way these two functions behave is exactly how functions like
sf_control work with each other. As demonstrated above you can pass any number of arbitrary controls into the function and they are all gathered up into the control by
control = list(...). However, you can specify the control directly like this:
You may already be taking advantage of the
line_ending arguments which are control arguments that were explicity included in functions. These argument essentially hard coded values to pass the
LineEndingHeader control parameters. Starting with the 0.1.3 release it is no longer necessary and preferable not to have an argument like
all_or_none listed explicity as an argument since it can be provided in the
control argument. Note: the
all_or_none argument and other explicit control arguments will still be available in salesforcer 0.1.3 but will provide a deprecated warning. They will be removed in the next CRAN release of the package so it will be important to update your code now if you are explicitly passing these arguments and see a deprecation warning.