Add labkey.security.renameContainer (#92)

cnathe · web-flow · commit eb4bb1de1f66 · 2023-05-02T16:55:48.000-05:00
Rlabkey v2.11.0
- Add labkey.security.renameContainer and related documentation
diff --git a/Rlabkey/DESCRIPTION b/Rlabkey/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: Rlabkey
-Version: 2.10.0
-Date: 2023-04-03
+Version: 2.11.0
+Date: 2023-05-02
 Title: Data Exchange Between R and 'LabKey' Server
 Author: Peter Hussey 
 Maintainer: Cory Nathe <cnathe@labkey.com>
diff --git a/Rlabkey/NAMESPACE b/Rlabkey/NAMESPACE
@@ -35,6 +35,7 @@ export(labkey.security.createContainer)
 export(labkey.security.deleteContainer)
 export(labkey.security.getContainers)
 export(labkey.security.moveContainer)
+export(labkey.security.renameContainer)
 export(labkey.security.impersonateUser)
 export(labkey.security.stopImpersonating)
 export(labkey.provenance.createProvenanceParams)
diff --git a/Rlabkey/NEWS b/Rlabkey/NEWS
@@ -1,3 +1,6 @@
+Changes in 2.11.0
+  o Add labkey.security.renameContainer
+
 Changes in 2.10.0
   o Update documentation to reflect removal of "apikey|" and "session|" prefixes from API keys and session keys
   o Issue 47202: Options to reduce payload of getContainers.api response: includeChildWorkbooks, includeStandardProperties
diff --git a/Rlabkey/R/labkey.security.R b/Rlabkey/R/labkey.security.R
@@ -92,6 +92,33 @@ labkey.security.moveContainer <- function(baseUrl=NULL, folderPath, destinationP
     return (fromJSON(response))
 }
 
+## Renames an existing container at the given container path. This action allows for updating the container
+## name, title, or both.
+##
+labkey.security.renameContainer <- function(baseUrl=NULL, folderPath, name=NULL, title=NULL, addAlias=TRUE)
+{
+    baseUrl=labkey.getBaseUrl(baseUrl)
+
+    ## check required parameters
+    if (missing(baseUrl) || is.null(baseUrl) || missing(folderPath))
+        stop (paste("A value must be specified for both baseUrl and folderPath."))
+    if (missing(name) && missing(title))
+            stop (paste("A value must be specified for either name or title."))
+
+    params <- list()
+    if(is.null(name)==FALSE) {params <- c(params, list(name=name))}
+    if(is.null(title)==FALSE) {params <- c(params, list(title=title))}
+    if(is.null(addAlias)==FALSE) {params <- c(params, list(addAlias=addAlias))}
+
+    ## normalize the folder path
+    folderPath <- encodeFolderPath(folderPath)
+
+    url <- paste(baseUrl, "admin", folderPath, "renameContainer.api", sep="")
+    response <- labkey.post(url, toJSON(params, auto_unbox=TRUE))
+
+    return (fromJSON(response))
+}
+
 labkey.security.impersonateUser <- function(baseUrl = NULL, folderPath, userId = NULL, email = NULL)
 {
     baseUrl=labkey.getBaseUrl(baseUrl)
diff --git a/Rlabkey/man/Rlabkey-package.Rd b/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 2.10.0\cr
-Date: \tab 2023-04-03\cr
+Version: \tab 2.11.0\cr
+Date: \tab 2023-05-02\cr
 License: \tab Apache License 2.0\cr
 LazyLoad: \tab yes\cr
 }
diff --git a/Rlabkey/man/labkey.getFolders.Rd b/Rlabkey/man/labkey.getFolders.Rd
@@ -47,6 +47,7 @@ The available folders are returned as a three-column data frame containing
 \code{\link{labkey.security.createContainer}},
 \code{\link{labkey.security.deleteContainer}},
 \code{\link{labkey.security.moveContainer}}
+\code{\link{labkey.security.renameContainer}}
 }
 \examples{
 \dontrun{
diff --git a/Rlabkey/man/labkey.security.createContainer.Rd b/Rlabkey/man/labkey.security.createContainer.Rd
@@ -33,6 +33,7 @@ Returns information about the newly created container.
 \code{\link{labkey.security.getContainers}},
 \code{\link{labkey.security.deleteContainer}},
 \code{\link{labkey.security.moveContainer}}
+\code{\link{labkey.security.renameContainer}}
 }
 \examples{
 \dontrun{
diff --git a/Rlabkey/man/labkey.security.deleteContainer.Rd b/Rlabkey/man/labkey.security.deleteContainer.Rd
@@ -26,6 +26,7 @@ Returns a success message for the container deletion action.
 \code{\link{labkey.security.getContainers}},
 \code{\link{labkey.security.createContainer}},
 \code{\link{labkey.security.moveContainer}}
+\code{\link{labkey.security.renameContainer}}
 }
 \examples{
 \dontrun{
diff --git a/Rlabkey/man/labkey.security.getContainers.Rd b/Rlabkey/man/labkey.security.getContainers.Rd
@@ -36,6 +36,7 @@ path, type, folderType, and effectivePermissions.
 \code{\link{labkey.security.createContainer}},
 \code{\link{labkey.security.deleteContainer}},
 \code{\link{labkey.security.moveContainer}}
+\code{\link{labkey.security.renameContainer}}
 }
 \examples{
 \dontrun{
diff --git a/Rlabkey/man/labkey.security.moveContainer.Rd b/Rlabkey/man/labkey.security.moveContainer.Rd
@@ -31,6 +31,7 @@ Returns a success message for the container move action with the new path.
 \code{\link{labkey.security.getContainers}},
 \code{\link{labkey.security.createContainer}},
 \code{\link{labkey.security.deleteContainer}}
+\code{\link{labkey.security.renameContainer}}
 }
 \examples{
 \dontrun{
diff --git a/Rlabkey/man/labkey.security.renameContainer.Rd b/Rlabkey/man/labkey.security.renameContainer.Rd
@@ -0,0 +1,47 @@
+\name{labkey.security.renameContainer}
+\alias{labkey.security.renameContainer}
+\title{Rename an existing container at the given container path}
+\description{
+Renames an existing container at the given container path.
+This action allows for updating the container name, title, or both.
+}
+\usage{
+labkey.security.renameContainer(baseUrl=NULL, folderPath,
+    name=NULL, title=NULL, addAlias=TRUE)
+}
+\arguments{
+  \item{baseUrl}{A string specifying the \code{baseUrl} for the labkey server.}
+  \item{folderPath}{A string specifying the \code{folderPath} to be renamed. Additionally, the container entity id is also valid.}
+  \item{name}{The new container name. If not specified, the container name will not be changed.}
+  \item{title}{The new container title. If not specified, the container name will be used.}
+  \item{addAlias}{Add alias of current container path for the current container name (defaults to true).}
+}
+\details{
+This function renames an existing container at the given container path on the LabKey server.
+A new container name and/or title must be specified. If a new name is provided but not a title, the name will also
+be set as the container title.
+}
+\value{
+Returns a success message for the container rename action.
+}
+
+\author{Cory Nathe}
+\seealso{
+\code{\link{labkey.getFolders}},
+\code{\link{labkey.security.getContainers}},
+\code{\link{labkey.security.createContainer}},
+\code{\link{labkey.security.deleteContainer}}
+\code{\link{labkey.security.moveContainer}}
+}
+\examples{
+\dontrun{
+
+library(Rlabkey)
+
+labkey.security.renameContainer(baseUrl="http://labkey/", folderPath = "/home/OriginalFolder",
+    name = "NewFolderName", title = "New Folder Title", addAlias = TRUE
+)
+
+}
+}
+\keyword{IO}

Original file line number	Diff line number	Diff line change
`@@ -47,6 +47,7 @@ The available folders are returned as a three-column data frame containing`
`47`	`47`	`\code{\link{labkey.security.createContainer}},`
`48`	`48`	`\code{\link{labkey.security.deleteContainer}},`
`49`	`49`	`\code{\link{labkey.security.moveContainer}}`
	`50`	`+\code{\link{labkey.security.renameContainer}}`
`50`	`51`	`}`
`51`	`52`	`\examples{`
`52`	`53`	`\dontrun{`
Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,7 @@ Returns information about the newly created container.`
`33`	`33`	`\code{\link{labkey.security.getContainers}},`
`34`	`34`	`\code{\link{labkey.security.deleteContainer}},`
`35`	`35`	`\code{\link{labkey.security.moveContainer}}`
	`36`	`+\code{\link{labkey.security.renameContainer}}`
`36`	`37`	`}`
`37`	`38`	`\examples{`
`38`	`39`	`\dontrun{`
Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,7 @@ Returns a success message for the container deletion action.`
`26`	`26`	`\code{\link{labkey.security.getContainers}},`
`27`	`27`	`\code{\link{labkey.security.createContainer}},`
`28`	`28`	`\code{\link{labkey.security.moveContainer}}`
	`29`	`+\code{\link{labkey.security.renameContainer}}`
`29`	`30`	`}`
`30`	`31`	`\examples{`
`31`	`32`	`\dontrun{`
Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@ path, type, folderType, and effectivePermissions.`
`36`	`36`	`\code{\link{labkey.security.createContainer}},`
`37`	`37`	`\code{\link{labkey.security.deleteContainer}},`
`38`	`38`	`\code{\link{labkey.security.moveContainer}}`
	`39`	`+\code{\link{labkey.security.renameContainer}}`
`39`	`40`	`}`
`40`	`41`	`\examples{`
`41`	`42`	`\dontrun{`
Original file line number	Diff line number	Diff line change
`@@ -31,6 +31,7 @@ Returns a success message for the container move action with the new path.`
`31`	`31`	`\code{\link{labkey.security.getContainers}},`
`32`	`32`	`\code{\link{labkey.security.createContainer}},`
`33`	`33`	`\code{\link{labkey.security.deleteContainer}}`
	`34`	`+\code{\link{labkey.security.renameContainer}}`
`34`	`35`	`}`
`35`	`36`	`\examples{`
`36`	`37`	`\dontrun{`