Address review feedback on XM Directory migration

  - Document the changed mailing-list column names in NEWS
  - Fix fetch_mailinglist roxygen param/example to use mailingListId
  - Warn when multiple XM Directories exist and document QUALTRICS_DIRECTORY_ID in
  the user-facing functions
  - Add tests covering directory discovery, the no-directory abort, and the
  multiple-directory warning

Author: apilipshen

NEWS.md

@@ -3,8 +3,19 @@
 - Migrated `all_mailinglists()` and `fetch_mailinglist()` from the deprecated
   Research Core Contacts API endpoints to the XM Directory API endpoints, ahead
   of Qualtrics retiring the old endpoints on June 30, 2026 (#386). The directory
-  ID is now discovered automatically from the API, so existing code requires no
-  changes.
+  ID is discovered automatically from the API (or can be set with the
+  `QUALTRICS_DIRECTORY_ID` environment variable), so no change to your code is
+  needed to keep these functions working.
+
+  Note that the XM Directory endpoints return a **different data shape**, so code
+  that referenced the old column names will need to be updated:
+
+  - `all_mailinglists()`: the `id` column is now `mailingListId`; the
+    `libraryId`, `category`, and `folder` columns are no longer returned; and
+    `contactCount`, `ownerId`, and creation/modification date columns are now
+    included.
+  - `fetch_mailinglist()`: the `id` column is now `contactId`, and
+    `externalDataReference` is now `extRef`.
 
 # qualtRics 3.2.2
 

R/all_mailinglists.R

@@ -1,5 +1,12 @@
 #' Retrieve a data frame of all mailing lists from Qualtrics
 #'
+#' @details
+#' This function uses the Qualtrics XM Directory API. The directory it queries
+#' is discovered automatically from your account. If your account has more than
+#' one XM Directory, set the `QUALTRICS_DIRECTORY_ID` environment variable to
+#' the directory ID you want to use; otherwise the first directory returned by
+#' the API is used (with a warning).
+#'
 #' @template retry-advice
 #' @importFrom purrr map_df
 #' @importFrom purrr flatten

R/fetch_mailinglist.R

@@ -2,8 +2,15 @@
 #' Download a mailing list from Qualtrics
 #'
 #' @param mailinglistID String. Unique ID for the mailing list you want to
-#'   download. Returned as `id` by the [all_mailinglists][qualtRics::all_mailinglists]
-#'   function.
+#'   download. Returned as `mailingListId` by the
+#'   [all_mailinglists][qualtRics::all_mailinglists] function.
+#'
+#' @details
+#' This function uses the Qualtrics XM Directory API. The directory it queries
+#' is discovered automatically from your account. If your account has more than
+#' one XM Directory, set the `QUALTRICS_DIRECTORY_ID` environment variable to
+#' the directory ID you want to use; otherwise the first directory returned by
+#' the API is used (with a warning).
 #'
 #' @template retry-advice
 #' @importFrom dplyr bind_rows
@@ -30,7 +37,7 @@
 #' mailinglists <- all_mailinglists()
 #'
 #' # Retrieve a single mailing list
-#' mailinglist <- fetch_mailinglist(mailinglists$id[1])
+#' mailinglist <- fetch_mailinglist(mailinglists$mailingListId[1])
 #' }
 #'
 

R/utils.R

@@ -183,6 +183,20 @@ fetch_directory_id <- function() {
     rlang::abort("No XM Directories found for this Qualtrics account.")
   }
   dir_id <- dirs[[1]]$directoryId
+  if (length(dirs) > 1) {
+    rlang::warn(
+      c(
+        glue::glue(
+          "This Qualtrics account has {length(dirs)} XM Directories; ",
+          "using the first one (\"{dir_id}\")."
+        ),
+        i = paste0(
+          "Set the QUALTRICS_DIRECTORY_ID environment variable to choose a ",
+          "specific directory."
+        )
+      )
+    )
+  }
   Sys.setenv(QUALTRICS_DIRECTORY_ID = dir_id)
   dir_id
 }

man/all_mailinglists.Rd

@@ -0,0 +1,72 @@
+skip_on_cran()
+
+test_that("fetch_directory_id discovers the directory ID from the API when unset", {
+  withr::local_envvar(list(
+    "QUALTRICS_API_KEY" = "abcdef",
+    "QUALTRICS_BASE_URL" = "t.qualtrics.com",
+    "QUALTRICS_DIRECTORY_ID" = ""
+  ))
+  local_mocked_bindings(
+    qualtrics_api_request = function(...) {
+      list(result = list(elements = list(
+        list(directoryId = "POOL_discovered123")
+      )))
+    }
+  )
+
+  expect_identical(fetch_directory_id(), "POOL_discovered123")
+  # Discovered ID is cached in the environment variable for the session:
+  expect_identical(Sys.getenv("QUALTRICS_DIRECTORY_ID"), "POOL_discovered123")
+})
+
+test_that("fetch_directory_id uses the cached env var without calling the API", {
+  withr::local_envvar(list(
+    "QUALTRICS_API_KEY" = "abcdef",
+    "QUALTRICS_BASE_URL" = "t.qualtrics.com",
+    "QUALTRICS_DIRECTORY_ID" = "POOL_cached123"
+  ))
+  local_mocked_bindings(
+    qualtrics_api_request = function(...) {
+      stop("qualtrics_api_request should not be called when the ID is cached")
+    }
+  )
+
+  expect_identical(fetch_directory_id(), "POOL_cached123")
+})
+
+test_that("fetch_directory_id aborts when no directories are found", {
+  withr::local_envvar(list(
+    "QUALTRICS_API_KEY" = "abcdef",
+    "QUALTRICS_BASE_URL" = "t.qualtrics.com",
+    "QUALTRICS_DIRECTORY_ID" = ""
+  ))
+  local_mocked_bindings(
+    qualtrics_api_request = function(...) {
+      list(result = list(elements = list()))
+    }
+  )
+
+  expect_error(fetch_directory_id(), "No XM Directories found")
+})
+
+test_that("fetch_directory_id warns and uses the first when multiple directories exist", {
+  withr::local_envvar(list(
+    "QUALTRICS_API_KEY" = "abcdef",
+    "QUALTRICS_BASE_URL" = "t.qualtrics.com",
+    "QUALTRICS_DIRECTORY_ID" = ""
+  ))
+  local_mocked_bindings(
+    qualtrics_api_request = function(...) {
+      list(result = list(elements = list(
+        list(directoryId = "POOL_first123"),
+        list(directoryId = "POOL_second456")
+      )))
+    }
+  )
+
+  expect_warning(
+    dir_id <- fetch_directory_id(),
+    "QUALTRICS_DIRECTORY_ID"
+  )
+  expect_identical(dir_id, "POOL_first123")
+})