Issue 48490: Add options parameter to labkey.insertRows, labkey.updateRows, labkey.deleteRows to support "auditBehavior" (#98)

- add options param to labkey.insertRows, labkey.updateRows, and labkey.deleteRows
- update related Rd doc files

Author: cnathe

Rlabkey/DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Rlabkey
-Version: 3.0.0
-Date: 2023-11-06
+Version: 3.1.0
+Date: 2023-12-04
 Title: Data Exchange Between R and 'LabKey' Server
 Author: Peter Hussey 
 Maintainer: Cory Nathe <cnathe@labkey.com>

Rlabkey/NEWS

@@ -1,3 +1,7 @@
+Changes in 3.1.0
+  o Issue 48490: Add options parameter to labkey.insertRows, labkey.updateRows, labkey.deleteRows to support
+        specifying the "auditBehavior" and "auditUserComment" properties for the action
+
 Changes in 3.0.0
   o Issue 41677: Fix for domain get/save round tripping of domain indices (need to use list() for index columnNames)
   o Encode SQL parameters passed by labkey.executeSql to avoid rejection by web application firewalls

Rlabkey/R/labkey.deleteRows.R

@@ -14,7 +14,7 @@
 #  limitations under the License.
 ##
 
-labkey.deleteRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, toDelete, provenanceParams=NULL)
+labkey.deleteRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, toDelete, provenanceParams=NULL, options = NULL)
 {  
     baseUrl=labkey.getBaseUrl(baseUrl)
 
@@ -26,6 +26,8 @@ labkey.deleteRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, t
     if (missing(schemaName)) stop (paste("A value must be specified for schemaName."))
     if (missing(queryName)) stop (paste("A value must be specified for queryName."))
     if (missing(toDelete)) stop (paste("A value must be specified for toDelete."))
+    if (!missing(options) & !is.list(options))
+        stop (paste("The options parameter must be a list data structure."))
 
     ## normalize the folder path
     folderPath <- encodeFolderPath(folderPath)
@@ -38,6 +40,8 @@ labkey.deleteRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, t
     params <- list(schemaName=schemaName, queryName=queryName, apiVersion=8.3)
     if (!missing(provenanceParams))
         params$provenance = provenanceParams
+    if (!missing(options))
+        params <- c(params, options)
 
     p1 <- toJSON(params, auto_unbox=TRUE)
     cnames <- colnames(toDelete)

Rlabkey/R/labkey.insertRows.R

@@ -14,7 +14,7 @@
 #  limitations under the License.
 ##
 
-labkey.insertRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, toInsert, na=NULL, provenanceParams=NULL)
+labkey.insertRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, toInsert, na=NULL, provenanceParams=NULL, options = NULL)
 {  
     baseUrl=labkey.getBaseUrl(baseUrl)
 
@@ -23,6 +23,8 @@ labkey.insertRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, t
     if (missing(schemaName)) stop (paste("A value must be specified for schemaName."))
     if (missing(queryName)) stop (paste("A value must be specified for queryName."))
     if (missing(toInsert)) stop (paste("A value must be specified for toInsert."))
+    if (!missing(options) & !is.list(options))
+        stop (paste("The options parameter must be a list data structure."))
 
     ## Default showAllRows=TRUE
     showAllRows=TRUE
@@ -38,6 +40,8 @@ labkey.insertRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, t
     params <- list(schemaName=schemaName, queryName=queryName, apiVersion=8.3)
     if (!missing(provenanceParams))
         params$provenance = provenanceParams
+    if (!missing(options))
+        params <- c(params, options)
 
     p1 <- toJSON(params, auto_unbox=TRUE)
     cnames <- colnames(toInsert)

Rlabkey/R/labkey.query.import.R

@@ -22,7 +22,7 @@ labkey.query.import <- function(baseUrl=NULL, folderPath, schemaName, queryName,
     if (missing(baseUrl) || is.null(baseUrl) || missing(folderPath) || missing(schemaName) || missing(queryName) || missing(toImport))
         stop (paste("A value must be specified for each of baseUrl, folderPath, schemaName, queryName, and toImport."))
     if (!missing(options) & !is.list(options))
-        stop (paste("options must be a list data structure."))
+        stop (paste("The options parameter must be a list data structure."))
 
     ## normalize the folder path
     folderPath <- encodeFolderPath(folderPath)

Rlabkey/R/labkey.updateRows.R

@@ -14,7 +14,7 @@
 #  limitations under the License.
 ##
 
-labkey.updateRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, toUpdate, provenanceParams=NULL)
+labkey.updateRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, toUpdate, provenanceParams=NULL, options = NULL)
 {  
     baseUrl=labkey.getBaseUrl(baseUrl)
 
@@ -26,6 +26,8 @@ labkey.updateRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, t
     if (missing(schemaName)) stop (paste("A value must be specified for schemaName."))
     if (missing(queryName)) stop (paste("A value must be specified for queryName."))
     if (missing(toUpdate)) stop (paste("A value must be specified for toUpdate."))
+    if (!missing(options) & !is.list(options))
+        stop (paste("The options parameter must be a list data structure."))
 
     ## normalize the folder path
     folderPath <- encodeFolderPath(folderPath)
@@ -38,6 +40,8 @@ labkey.updateRows <- function(baseUrl=NULL, folderPath, schemaName, queryName, t
     params <- list(schemaName=schemaName, queryName=queryName, apiVersion=8.3)
     if (!missing(provenanceParams))
         params$provenance = provenanceParams
+    if (!missing(options))
+        params <- c(params, options)
 
     p1 <- toJSON(params, auto_unbox=TRUE)
     cnames <- colnames(toUpdate)

Rlabkey/man/Rlabkey-package.Rd

@@ -18,8 +18,8 @@ schema objects (\code{labkey.getSchema}).
 \tabular{ll}{
 Package: \tab Rlabkey\cr
 Type: \tab Package\cr
-Version: \tab 3.0.0\cr
-Date: \tab 2023-11-06\cr
+Version: \tab 3.1.0\cr
+Date: \tab 2023-12-04\cr
 License: \tab Apache License 2.0\cr
 LazyLoad: \tab yes\cr
 }

Rlabkey/man/labkey.deleteRows.Rd

@@ -6,7 +6,8 @@ Specify rows of data to be deleted from the LabKey Server
 }
 \usage{
 labkey.deleteRows(baseUrl, folderPath,
-    schemaName, queryName, toDelete, provenanceParams=NULL)
+    schemaName, queryName, toDelete,
+    provenanceParams=NULL, options=NULL)
 }
 \arguments{
   \item{baseUrl}{a string specifying the \code{baseUrl}for LabKey server}
@@ -17,6 +18,7 @@ labkey.deleteRows(baseUrl, folderPath,
   \item{provenanceParams}{the provenance parameter object which contains the options to include as part of a provenance recording.
     This is a premium feature and requires the Provenance LabKey module to function correctly, if it is not present this parameter will be ignored.
   }
+  \item{options}{(optional) a list containing options specific to the insert action of the query}
 }
 \details{
 A single row or multiple rows of data can be deleted.  For the \code{toDelete} data frame, version 0.0.5 or later accepts either a single column 
@@ -30,6 +32,14 @@ used \dQuote{behind the scenes} for database manipulation. It is the column name
 the Rlabkey functions when a column name is expected. To identify a particular column name in a dataset on
 a web site, use the \dQuote{export to R script} option available as a drop down option under the \dQuote{views} 
 tab for each dataset.
+
+The list of valid options for each query will vary, but some common examples include:
+    \itemize{
+        \item{ \code{auditBehavior (string)} : Can be used to override the audit behavior for the table the query is acting on.
+            The set of types include: NONE, SUMMARY, and DETAILED.}
+        \item{ \code{auditUserComment (string)} : Can be used to provide a comment from the user that will be attached to
+            certain detailed audit log records.}
+    }
 }
 \value{
 A list is returned with named categories of \bold{command}, \bold{rowsAffected}, \bold{rows}, \bold{queryName}, \bold{containerPath} and \bold{schemaName}.

Rlabkey/man/labkey.insertRows.Rd

@@ -6,7 +6,8 @@ Insert new rows of data into the database.
 }
 \usage{
 labkey.insertRows(baseUrl, folderPath,
-    schemaName, queryName, toInsert, na, provenanceParams=NULL)
+    schemaName, queryName, toInsert, na,
+    provenanceParams=NULL, options=NULL)
 }
 \arguments{
   \item{baseUrl}{a string specifying the \code{baseUrl}for the labkey server}
@@ -18,13 +19,22 @@ labkey.insertRows(baseUrl, folderPath,
   \item{provenanceParams}{the provenance parameter object which contains the options to include as part of a provenance recording.
     This is a premium feature and requires the Provenance LabKey module to function correctly, if it is not present this parameter will be ignored.
   }
+  \item{options}{(optional) a list containing options specific to the insert action of the query}
 }
 \details{
 A single row or multiple rows of data can be inserted.  The \code{toInsert} data frame must contain
 values for each column in the dataset and must be created with the \code{stringsAsFactors} option
 set to FALSE. The names of the data in the data frame must be the column names from the
 LabKey Server.To insert a value of NULL, use an empty string ("") in the data frame (regardless of the database column type). 
-Also, when inserting data into a study dataset, the sequence number must be specified..
+Also, when inserting data into a study dataset, the sequence number must be specified.
+\cr \cr
+The list of valid options for each query will vary, but some common examples include:
+    \itemize{
+        \item{ \code{auditBehavior (string)} : Can be used to override the audit behavior for the table the query is acting on.
+            The set of types include: NONE, SUMMARY, and DETAILED.}
+        \item{ \code{auditUserComment (string)} : Can be used to provide a comment from the user that will be attached to
+            certain detailed audit log records.}
+    }
 }
 
 \value{
@@ -70,7 +80,8 @@ newrow <- data.frame(
 
 insertedRow <- labkey.insertRows("http://localhost:8080/labkey",
     folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
-    toInsert=newrow)
+    toInsert=newrow, options=list(auditBehavior="DETAILED",
+    auditUserComment="testing audit comment for insert"))
 newRowId <- insertedRow$rows[[1]]$RowId
 
 selectedRow<-labkey.selectRows("http://localhost:8080/labkey",
@@ -85,7 +96,8 @@ updaterow=data.frame(
 
 updatedRow <- labkey.updateRows("http://localhost:8080/labkey",
     folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
-    toUpdate=updaterow)
+    toUpdate=updaterow, options=list(auditBehavior="DETAILED",
+    auditUserComment="testing audit comment for update"))
 selectedRow<-labkey.selectRows("http://localhost:8080/labkey",
     folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
     colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))

Rlabkey/man/labkey.updateRows.Rd

@@ -6,7 +6,8 @@ Send data from an R session to update existing rows of data in the database.
 }
 \usage{
 labkey.updateRows(baseUrl, folderPath,
-    schemaName, queryName, toUpdate, provenanceParams=NULL)
+    schemaName, queryName, toUpdate,
+    provenanceParams=NULL, options=NULL)
 }
 \arguments{
   \item{baseUrl}{a string specifying the \code{baseUrl}for the labkey server}
@@ -17,13 +18,21 @@ labkey.updateRows(baseUrl, folderPath,
   \item{provenanceParams}{the provenance parameter object which contains the options to include as part of a provenance recording.
     This is a premium feature and requires the Provenance LabKey module to function correctly, if it is not present this parameter will be ignored.
   }
+  \item{options}{(optional) a list containing options specific to the insert action of the query}
 }
 \details{
 A single row or multiple rows of data can be updated.  The \code{toUpdate} data frame should contain 
 the rows of data to be updated and must be created with the \code{stringsAsFactors} option
 set to FALSE. The names of the data in the data frame must be the column names from the
 labkey database.   To update a row/column to a value of NULL, use an empty string ("") in the data frame (regardless of the database column type).
-
+\cr \cr
+The list of valid options for each query will vary, but some common examples include:
+    \itemize{
+        \item{ \code{auditBehavior (string)} : Can be used to override the audit behavior for the table the query is acting on.
+            The set of types include: NONE, SUMMARY, and DETAILED.}
+        \item{ \code{auditUserComment (string)} : Can be used to provide a comment from the user that will be attached to
+            certain detailed audit log records.}
+    }
 }
 \value{
 A list is returned with named categories of \bold{command}, \bold{rowsAffected}, \bold{rows}, \bold{queryName}, \bold{containerPath} and \bold{schemaName}.
@@ -68,7 +77,8 @@ newrow <- data.frame(
 
 insertedRow <- labkey.insertRows("http://localhost:8080/labkey",
     folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
-    toInsert=newrow)
+    toInsert=newrow, options=list(auditBehavior="DETAILED",
+    auditUserComment="testing audit comment for insert"))
 newRowId <- insertedRow$rows[[1]]$RowId
 
 selectedRow<-labkey.selectRows("http://localhost:8080/labkey",
@@ -85,7 +95,8 @@ updaterow=data.frame(
 
 updatedRow <- labkey.updateRows("http://localhost:8080/labkey",
     folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
-    toUpdate=updaterow)
+    toUpdate=updaterow, options=list(auditBehavior="DETAILED",
+    auditUserComment="testing audit comment for update"))
 selectedRow<-labkey.selectRows("http://localhost:8080/labkey",
     folderPath="/apisamples", schemaName="lists", queryName="AllTypes",
     colFilter=makeFilter(c("RowId", "EQUALS", newRowId)))