Allow require reason on storage changes

Rlabkey/DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Rlabkey
-Version: 3.4.6
-Date: 2026-02-17
+Version: 3.4.X
+Date: 2026-X
 Title: Data Exchange Between R and 'LabKey' Server
 Authors@R: c(person(given = "Peter",
                     family = "Hussey",

Rlabkey/NEWS

@@ -1,3 +1,7 @@
+Changes in 3.4.7
+  o Pass auditUserComment to labkey.storage.delete for attaching a reason to the audit log record
+  o labkey.storage.create and labkey.storage.update now accept an optional auditUserComment entry inside the props list (recorded as the "Reason" on the resulting audit event)
+
 Changes in 3.4.6
   o Incorporate new filter types for Array (Multi-value text choice) fields
   o Update listToMatrix to handle cases where the list elements are an array of strings, which will return a comma separated string in the response

Rlabkey/R/labkey.storage.R

@@ -50,15 +50,18 @@ labkey.storage.update <- function(baseUrl=NULL, folderPath, type, props)
     return (fromJSON(response))
 }
 
-labkey.storage.delete <- function(baseUrl=NULL, folderPath, type, rowId)
+labkey.storage.delete <- function(baseUrl=NULL, folderPath, type, rowId, auditUserComment=NULL)
 {
     baseUrl=labkey.getBaseUrl(baseUrl)
 
     ## check required parameters
     if (missing(baseUrl) || is.null(baseUrl) || missing(folderPath) || missing(type) || missing(rowId))
         stop (paste("A value must be specified for each of baseUrl, folderPath, type, and rowId."))
 
-    params <- list(type = type, props = list(rowId = rowId))
+    props <- list(rowId = rowId)
+    if (!is.null(auditUserComment))
+        props$auditUserComment <- auditUserComment
+    params <- list(type = type, props = props)
     url <- labkey.buildURL(baseUrl, "storage", "delete.api", folderPath)
     response <- labkey.post(url, toJSON(params, auto_unbox=TRUE))
 

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.4.6\cr
-Date: \tab 2026-02-17\cr
+Version: \tab 3.4.X\cr
+Date: \tab 2026-X\cr
 License: \tab Apache License 2.0\cr
 LazyLoad: \tab yes\cr
 }

Rlabkey/man/labkey.storage.delete.Rd

@@ -9,13 +9,14 @@ Storage items can be of the following types: Physical Location, Freezer, Primary
 Storage Unit Type, or Terminal Storage Location.
 }
 \usage{
-labkey.storage.delete(baseUrl=NULL, folderPath, type, rowId)
+labkey.storage.delete(baseUrl=NULL, folderPath, type, rowId, auditUserComment=NULL)
 }
 \arguments{
   \item{baseUrl}{a string specifying the \code{baseUrl}for the LabKey server}
   \item{folderPath}{a string specifying the \code{folderPath} }
   \item{type}{a string specifying the type of storage item to delete }
   \item{rowId}{the primary key of the storage item to delete }
+  \item{auditUserComment}{optional reason text that will be attached to the audit log record for this storage change. }
 }
 \value{
 A list containing a data element with the property values for the deleted storage item.
@@ -75,6 +76,16 @@ freezer <- labkey.storage.delete(
     type="Freezer",
     rowId=freezer$data$rowId
 )
+
+## supply an auditUserComment ("reason for change") that will be attached to the
+## audit log record for this delete
+plateType <- labkey.storage.delete(
+    baseUrl="http://labkey/",
+    folderPath="home",
+    type="Storage Unit Type",
+    rowId=plateType$data$rowId,
+    auditUserComment="Retiring this plate type per lab SOP-42"
+)
 }
 }
 \keyword{IO}

Rlabkey/man/labkey.storage.update.Rd

@@ -13,7 +13,7 @@ labkey.storage.update(baseUrl=NULL, folderPath, type, props)
   \item{baseUrl}{a string specifying the \code{baseUrl}for the LabKey server}
   \item{folderPath}{a string specifying the \code{folderPath} }
   \item{type}{a string specifying the type of storage item to update }
-  \item{props}{a list properties for the storage item (i.e. name, description, etc.), must include the RowId primary key }
+  \item{props}{a list properties for the storage item (i.e. name, description, etc.), must include the RowId primary key. May also include an optional \code{auditUserComment} entry, which is recorded as the "Reason" on the resulting audit event. }
 }
 \value{
 A list containing a data element with the property values for the updated storage item.
@@ -43,6 +43,19 @@ plateType = labkey.storage.update(
     type="Storage Unit Type",
     props=list(rowId=plateType$data$rowId, positionFormat="NumAlpha", positionOrder="ColumnRow" )
 )
+
+## include an auditUserComment in the props list to attach a "Reason" to
+## the audit log record for this update
+plateType = labkey.storage.update(
+    baseUrl="http://labkey/",
+    folderPath="home",
+    type="Storage Unit Type",
+    props=list(
+        rowId=plateType$data$rowId,
+        description="Switched to AlphaNum positions",
+        auditUserComment="Switching to AlphaNum positioning per lab SOP-42"
+    )
+)
 }
 }
 \keyword{IO}