Add rforcecom.getObjectDescription

Add method to replicate rforcecom.getObjectDescription and another function that will return a tibble with one per field for a requested object.

Closes #10

NAMESPACE

@@ -37,6 +37,7 @@ export(rforcecom.bulkAction)
 export(rforcecom.bulkQuery)
 export(rforcecom.create)
 export(rforcecom.delete)
+export(rforcecom.getObjectDescription)
 export(rforcecom.getServerTimestamp)
 export(rforcecom.login)
 export(rforcecom.query)
@@ -63,6 +64,7 @@ export(sf_delete)
 export(sf_delete_job_bulk)
 export(sf_delete_metadata)
 export(sf_describe_metadata)
+export(sf_describe_object_fields)
 export(sf_describe_objects)
 export(sf_end_job_bulk)
 export(sf_get_job_bulk)

NEWS.md

@@ -2,11 +2,12 @@
 
 ### Features
 
-  * Nothing Yet!
+  * Add **RForcecom** backward compatibile version of `rforcecom.getObjectDescription()`
+  * Add `sf_describe_object_fields()` which is a tidyier version of `rforcecom.getObjectDescription()`
 
 ### Bug Fixes
 
-  * Nothing Yet!
+  * Fix bug where Username/Password authenticated sessions where not working with api_type = "Bulk 1.0"
 
 ---
 

R/compatibility.R

@@ -269,6 +269,27 @@ rforcecom.retrieve <- function(session, objectName,
   return(resultSet)
 }
 
+#' salesforcer's backwards compatible version of rforcecom.getObjectDescription
+#'
+#' @importFrom purrr map_df
+#' @template session 
+#' @template objectName
+#' @return Object descriptions
+#' @note This function returns a data.frame with one row per field for an object.
+#' @export
+rforcecom.getObjectDescription <- function(session, objectName){
+
+  .Deprecated("sf_describe_objects")
+
+  obj_dat <- sf_describe_objects(object_names = objectName, 
+                                 api_type="SOAP")[[1]]
+
+  obj_fields <- map_df(obj_dat[names(obj_dat) == "fields"], 
+                       as.data.frame, 
+                       stringsAsFactors=FALSE)
+  return(obj_fields)
+}
+
 #' Run Bulk Action
 #'
 #' This function is a convenience wrapper for submitting bulk API jobs

R/read-metadata.R

@@ -1,6 +1,6 @@
 #' Read Object or Field Metadata from Salesforce
 #' 
-#' This function takes a a request of named elements in Salesforce and 
+#' This function takes a request of named elements in Salesforce and 
 #' returns their metadata
 #'
 #' @importFrom XML newXMLNode addChildren xmlParse xmlToList
@@ -66,3 +66,32 @@ sf_read_metadata <- function(metadata_type, object_names, verbose=FALSE){
 
   return(resultset)
 }
+
+#' Describe Object Fields
+#' 
+#' This function takes the name of an object in Salesforce and returns a description 
+#' of the fields on that object by returning a tibble with one row per field.
+#' 
+#' @importFrom readr type_convert cols
+#' @importFrom dplyr as_tibble
+#' @template object_name
+#' @note The tibble only contains the fields that the user can view, as defined by 
+#' the user's field-level security settings.
+#' @return A \code{tbl_df} containing one row per field for the requested object.
+#' @examples
+#' \dontrun{
+#' acct_fields <- sf_describe_object_fields('Account')
+#' }
+#' @export
+sf_describe_object_fields <- function(object_name){
+
+  stopifnot(length(object_name) == 1)
+
+  # suppress deprecation warnings
+  suppressWarnings(obj_fields_dat <- rforcecom.getObjectDescription(objectName=object_name))
+  obj_fields_dat <- obj_fields_dat %>% 
+    as_tibble() %>%
+    type_convert(col_types=cols())
+
+  return(obj_fields_dat)
+}

README.Rmd

@@ -29,7 +29,7 @@ Bulk 2.0, and Metadata APIs. Package features include:
   * Retrieve and modify metadata (Custom Objects, Fields, etc.) using the Metadata API with: 
     * `sf_describe_objects()`, `sf_create_metadata()`, `sf_update_metadata()`
   * Utilize backwards compatible functions for the **RForcecom** package, such as: 
-    * `rforcecom.login()`, `rforcecom.query()`, `rforcecom.create()`, `rforcecom.update()`
+    * `rforcecom.login()`, `rforcecom.getObjectDescription()`, `rforcecom.query()`, `rforcecom.create()`
   * Basic utility calls (`sf_user_info()`, `sf_server_timestamp()`, `sf_list_objects()`)
 
 ## Table of Contents  
@@ -232,21 +232,34 @@ read_obj_result[[1]][first_two_fields_idx]
 
 The data is returned as a list because object definitions are highly nested representations. 
 You may notice that we are missing some really specific details, such as, the picklist 
-values of a field with type "Picklist". You can get that information using the function 
-`sf_describe_object()` function which is actually part of the REST and SOAP APIs. 
-It is recommended that you try out the various metadata functions `sf_read_metadata()`, 
-`sf_list_metadata()`, `sf_describe_metadata()`, and `sf_describe_objects()` in order 
-to see which information best suits your use case.
+values of a field with type "Picklist". You can get that information using the 
+`sf_describe_object_fields()` or `sf_describe_objects()` functions which are based 
+on calls from  REST and SOAP APIs. Here is an example using `sf_describe_object_fields()` 
+where we get a `tbl_df` with one row for each field on the Account object: 
+
+```{r soap-describe-object-fields}
+acct_fields <- sf_describe_object_fields('Account')
+acct_fields %>% select(name, label, length, soapType, type)
+```
+
+If you prefer to be more precise about collecting and formatting the field data you 
+can work directly with the nested lists that the APIs return. In this example we 
+look at the picklist values of fields on the Account object.
 
 ```{r rest-describe-objects}
 describe_obj_result <- sf_describe_objects(object_names=c('Account', 'Contact'))
+# confirm that the Account object is queryable
 describe_obj_result[[1]][c('label', 'queryable')]
-# show the first two returned fields of the Account object
-the_type_field <- describe_obj_result[[1]][[58]]
-the_type_field$name
+# show the different picklist values for the Account Type field
+the_type_field <- describe_obj_result[[1]][[59]]
+the_type_field$label
 map_df(the_type_field[which(names(the_type_field) == "picklistValues")], as_tibble)
 ```
 
+It is recommended that you try out the various metadata functions `sf_read_metadata()`, 
+`sf_list_metadata()`, `sf_describe_metadata()`, and `sf_describe_objects()` in order 
+to see which information best suits your use case.
+
 Where the Metadata API really shines is when it comes to CRUD operations on metadata. 
 In this example we will create an object, add fields to it, then delete that object.
 

_pkgdown.yml

@@ -65,6 +65,7 @@ reference:
       - '`sf_retrieve_metadata`'
       - '`sf_describe_metadata`'
       - '`sf_describe_objects`'
+      - '`sf_describe_object_fields`'
   - title: Salesforce Org Utility Functions
     desc: Functions used for basic calls to understand the org.
     contents:
@@ -74,3 +75,17 @@ reference:
       - '`sf_list_resources`'
       - '`sf_list_api_limits`'
       - '`sf_list_objects`'
+  - title: Backward Compatibility with RForcecom
+    desc: Functions that mirror RForcecom to ease code transitions between salesforcer and RForcecom
+    contents:
+      - '`rforcecom.login`'
+      - '`rforcecom.getServerTimestamp`'
+      - '`rforcecom.getObjectDescription`'
+      - '`rforcecom.create`'
+      - '`rforcecom.update`'
+      - '`rforcecom.upsert`'
+      - '`rforcecom.delete`'
+      - '`rforcecom.retrieve`'
+      - '`rforcecom.search`'
+      - '`rforcecom.query`'
+      - '`rforcecom.bulkQuery`'