Package 'brightspaceR'

Description

Constructs a filter list for use with bs_create_ads_job() and bs_get_ads(). Produces the ⁠[{Name, Value}]⁠ array format that the Brightspace dataExport create endpoint expects.

Usage

bs_ads_filter(
  start_date = NULL,
  end_date = NULL,
  parent_org_unit_id = NULL,
  roles = NULL
)

Arguments

Value

A list of list(Name = ..., Value = ...) filter objects.

Examples

bs_ads_filter(start_date = "2024-01-01", end_date = "2024-12-31")
bs_ads_filter(parent_org_unit_id = 6606)
bs_ads_filter(roles = c(110, 120))

Description

Check ADS export job status

Usage

bs_ads_job_status(job_id)

Arguments

Value

A list with export_job_id, name, status (integer), status_text (character), and submit_date.

Examples

if (bs_has_token()) {
status <- bs_ads_job_status("abc-123")
status$status_text
}

Description

Get or set the Brightspace API version

Usage

bs_api_version(version = NULL)

Arguments

Value

Character string of the API version.

Examples

bs_api_version()
bs_api_version("1.49")

Description

Filters or redacts columns based on a YAML-driven field policy. This is the same logic the MCP server uses to strip PII before data reaches the AI model.

Usage

bs_apply_field_policy(df, dataset_name, policy = NULL)

Arguments

Details

The policy supports three modes per dataset:

allow

Only the listed fields are kept; all others are dropped.

redact

The listed fields have their values replaced with "[REDACTED]"; all other fields pass through.

all

All columns pass through unchanged.

If dataset_name is not found in the policy, the data frame is returned unchanged.

Value

The input data frame with the field policy applied.

Examples

df <- data.frame(
  UserId = 1L, FirstName = "Jane", Organization = "Org1",
  stringsAsFactors = FALSE
)
bs_apply_field_policy(df, "Users")

Description

Aggregates quiz attempt data into per-user per-quiz performance summaries including best, average, and latest scores.

Usage

bs_assessment_performance(quiz_attempts)

Arguments

Value

A summarised tibble with one row per user per quiz per org unit.

Examples

if (bs_has_token()) {
attempts <- bs_get_dataset("Quiz Attempts")
bs_assessment_performance(attempts)
}

Description

Aggregates assignment submission data per assignment per org unit, including grading rates and score statistics.

Usage

bs_assignment_completion(assignment_submissions)

Arguments

Value

A summarised tibble with one row per assignment per org unit.

Examples

if (bs_has_token()) {
submissions <- bs_get_dataset("Assignment Submissions")
bs_assignment_completion(submissions)
}

Description

Initiates an OAuth2 Authorization Code flow with PKCE to authenticate with the Brightspace Data Hub API. The resulting token is cached to disk for reuse across sessions and automatically refreshed when expired.

Usage

bs_auth(
  client_id = "",
  client_secret = "",
  instance_url = "",
  redirect_uri = "",
  scope = ""
)

Arguments

Details

The first authentication requires an interactive R session (browser-based login). After that, cached credentials are used automatically — including in non-interactive scripts run via Rscript.

Value

Invisibly returns TRUE on success.

Examples

if (bs_has_token()) {
bs_auth()
bs_auth(
  client_id = "my-client-id",
  client_secret = "my-secret",
  instance_url = "https://myschool.brightspace.com"
)
}

Description

Authenticates using an existing refresh token, without requiring browser interaction. Ideal for non-interactive scripts and scheduled jobs.

Usage

bs_auth_refresh(
  refresh_token,
  client_id = Sys.getenv("BRIGHTSPACE_CLIENT_ID"),
  client_secret = Sys.getenv("BRIGHTSPACE_CLIENT_SECRET"),
  instance_url = Sys.getenv("BRIGHTSPACE_INSTANCE_URL"),
  scope = ""
)

Arguments

Value

Invisibly returns TRUE on success.

Examples

if (bs_has_token()) {
bs_auth_refresh(refresh_token = "my-refresh-token")
}

Description

Sets authentication credentials without going through the browser-based OAuth2 flow. Useful for non-interactive environments or when you already have a valid token.

Usage

bs_auth_token(
  token,
  instance_url,
  client_id = Sys.getenv("BRIGHTSPACE_CLIENT_ID"),
  client_secret = Sys.getenv("BRIGHTSPACE_CLIENT_SECRET")
)

Arguments

Value

Invisibly returns TRUE.

Description

Verifies which API capabilities are available with the current token by making lightweight test calls to each endpoint group. Checks are grouped into Tier 1 (BDS) and Tier 2 (ADS) so you can see at a glance which tier is working. Useful for diagnosing 403 errors.

Usage

bs_check_scopes()

Value

A tibble with columns tier, scope, endpoint, status ("OK" or error message), printed as a summary table.

Examples

if (bs_has_token()) {
bs_auth()
bs_check_scopes()
}

Description

Convert column names from PascalCase to snake_case

Usage

bs_clean_names(df)

Arguments

Value

A data frame with snake_case column names.

Examples

df <- data.frame(UserId = 1, FirstName = "A")
bs_clean_names(df)

Description

Reads Brightspace OAuth2 credentials from a YAML configuration file using the config package. The function looks for a brightspace key in the config file and returns the credentials as a named list.

Usage

bs_config(
  file = "config.yml",
  profile = Sys.getenv("R_CONFIG_ACTIVE", "default")
)

Arguments

Value

A named list with elements client_id, client_secret, instance_url, redirect_uri, and scope, or NULL if the file does not exist or the brightspace key is missing.

Examples

if (bs_has_token()) {
# Read from default config.yml
cfg <- bs_config()
cfg$client_id

# Read from a custom file and profile
cfg <- bs_config(file = "my-config.yml", profile = "production")
}

Description

Interactively creates or updates a config.yml file with Brightspace OAuth2 credentials. If the file already exists, the brightspace section is updated while preserving other settings.

Usage

bs_config_set(
  client_id,
  client_secret,
  instance_url,
  redirect_uri = "https://localhost:1410/",
  scope = paste("datasets:bds:read", "datahub:dataexports:read",
    "datahub:dataexports:download", "reporting:dataset:list", "reporting:dataset:fetch",
    "reporting:job:create", "reporting:job:list", "reporting:job:fetch",
    "reporting:job:download", "users:profile:read"),
  file = "config.yml",
  profile = "default"
)

Arguments

Value

Invisibly returns the file path.

Examples

if (bs_has_token()) {
bs_config_set(
  client_id = "my-client-id",
  client_secret = "my-secret",
  instance_url = "https://myschool.brightspace.com"
)
}

Description

Computes engagement metrics from Learner Usage ADS data including progress percentage, days since last visit, and passes through all raw activity counts. No composite score is computed here — use bs_engagement_score() to add one.

Usage

bs_course_engagement(learner_usage, tz = NULL)

Arguments

Value

A tibble with all learner_usage identity columns plus computed metrics: progress_pct, days_since_visit.

Examples

if (bs_has_token()) {
usage <- bs_get_ads("Learner Usage")
engagement <- bs_course_engagement(usage)
}

Description

Creates a per-course dashboard view with engagement, progress, and optionally award-based completion metrics. completion_rate_progress uses content progress (available from Learner Usage alone); completion_rate_awards uses certificate issuance (more authoritative but requires Awards Issued dataset).

Usage

bs_course_summary(learner_usage, awards = NULL)

Arguments

Value

A summarised tibble with one row per course, sorted by n_learners descending.

Examples

if (bs_has_token()) {
usage <- bs_get_ads("Learner Usage")
bs_course_summary(usage)

awards <- bs_get_ads("Awards Issued")
bs_course_summary(usage, awards = awards)
}

Description

Submits a new export job for the named ADS dataset. Use bs_ads_job_status() to poll for completion, then bs_download_ads() to retrieve the result.

Usage

bs_create_ads_job(name, filters = list())

Arguments

Value

A tibble with one row containing export_job_id, dataset_id, name, status, status_text, submit_date.

Examples

if (bs_has_token()) {
job <- bs_create_ads_job("Learner Usage")
job$export_job_id
}

Description

Removes cached credentials from the current session and optionally from disk.

Usage

bs_deauth(clear_cache = TRUE)

Arguments

Value

Invisibly returns TRUE.

Examples

if (bs_has_token()) {
bs_deauth()
}

Description

Returns a tibble showing each extract (full + diffs + merged total) with its creation date, row count, and download status. Use this to verify that all differential extracts were successfully downloaded and merged.

Usage

bs_diff_manifest(data)

Arguments

Value

A tibble with columns extract, created_date, rows, status, or NULL if the data has no manifest attribute.

Examples

if (bs_has_token()) {
users <- bs_get_dataset_current("Users")
bs_diff_manifest(users)
}

Description

Downloads the result of a completed ADS export job, unzips it, and returns a tidy tibble with proper types and snake_case names.

Usage

bs_download_ads(job_id, dataset_name = NULL)

Arguments

Value

A tibble of the dataset contents.

Examples

if (bs_has_token()) {
result <- bs_download_ads("abc-123", "Learner Usage")
}

Description

Downloads all available datasets and returns them as a named list of tibbles. Names are snake_case versions of the dataset names.

Usage

bs_download_all(extract_type = c("full", "diff"))

Arguments

Value

A named list of tibbles.

Examples

if (bs_has_token()) {
all_data <- bs_download_all()
all_data$users
all_data$org_units
}

Description

Downloads a specific dataset extract as a ZIP file, unzips it, reads the CSV, and returns a tidy tibble with proper types.

Usage

bs_download_dataset(
  schema_id,
  plugin_id,
  extract_type = c("full", "diff"),
  extract_id = NULL,
  dataset_name = NULL
)

Arguments

Value

A tibble of the dataset contents.

Examples

if (bs_has_token()) {
datasets <- bs_list_datasets()
users <- bs_download_dataset(
  datasets$schema_id[1],
  datasets$plugin_id[1]
)
}

Description

Adds a weighted composite engagement_score column to any tibble that has raw activity count columns. Default weights reflect relative effort/depth (login is passive, assignment is active). Users should override for their context.

Usage

bs_engagement_score(df, weights = list())

Arguments

Value

The input tibble with an engagement_score column appended.

Examples

if (bs_has_token()) {
usage <- bs_get_ads("Learner Usage")
scored <- bs_engagement_score(usage)
scored <- bs_engagement_score(usage, weights = list(login_count = 2))
}

Description

Aggregates engagement metrics from Learner Usage data by course, department, or user.

Usage

bs_engagement_summary(learner_usage, by = c("course", "department", "user"))

Arguments

Value

A summarised tibble sorted by mean_progress descending (or last_activity for user grouping).

Examples

if (bs_has_token()) {
usage <- bs_get_ads("Learner Usage")
bs_engagement_summary(usage, by = "course")
bs_engagement_summary(usage, by = "department")
bs_engagement_summary(usage, by = "user")
}

Description

Builds the enriched enrollment table by joining enrollments with org units and users, adding analysis-friendly column aliases. Original column names are preserved for compatibility; friendly aliases are added for readability.

Usage

bs_enrich_enrollments(
  enrollments,
  org_units,
  users,
  course_type = "Course Offering"
)

Arguments

Value

A tibble with both original and friendly column names, filtered to the specified course type.

Examples

if (bs_has_token()) {
enroll <- bs_get_dataset("Enrollments and Withdrawals")
org_units <- bs_get_dataset("Org Units")
users <- bs_get_dataset("Users")
enriched <- bs_enrich_enrollments(enroll, org_units, users)
}

Description

Removes test/system accounts using a two-layer filter: ID string length and an optional exclusion list. This eliminates the repeated boilerplate of removing test users before analysis.

Usage

bs_filter_test_users(
  df,
  min_id_length = 30,
  exclusion_list = NULL,
  id_col = "org_defined_id"
)

Arguments

Value

A filtered tibble with test users removed.

Examples

if (bs_has_token()) {
users <- bs_get_dataset("Users")
real_users <- bs_filter_test_users(users)
real_users <- bs_filter_test_users(users, exclusion_list = c("testuser01"))
}

Description

High-level function that finds the dataset by name, creates an export job, polls until complete, downloads the result, and returns a tidy tibble. Intended for interactive use.

Usage

bs_get_ads(name, filters = list(), poll_interval = 5, timeout = 300)

Arguments

Value

A tibble of the dataset contents.

Examples

if (bs_has_token()) {
usage <- bs_get_ads("Learner Usage")
usage <- bs_get_ads("Learner Usage",
  filters = bs_ads_filter(start_date = "2024-01-01"))
}

Description

Get the schema for an ADS dataset

Usage

bs_get_ads_schema(dataset_name)

Arguments

Value

A schema list, or NULL if no schema is registered.

Examples

bs_get_ads_schema("Learner Usage")

Description

Convenience wrapper that finds a dataset by name, downloads the latest full extract, and returns a tidy tibble.

Usage

bs_get_dataset(name, extract_type = c("full", "diff"))

Arguments

Value

A tibble of the dataset contents.

Examples

if (bs_has_token()) {
users <- bs_get_dataset("Users")
grades <- bs_get_dataset("Grade Results")
}

Description

Downloads the latest full extract and all subsequent differential extracts for a dataset, then merges them to produce a current-as-of-today tibble.

Usage

bs_get_dataset_current(name, keep_deleted = FALSE)

Arguments

Value

A tibble of the merged dataset contents. The tibble carries a "bds_manifest" attribute with the extract breakdown (full, each diff, and merged total with row counts and download status). Retrieve it with bs_diff_manifest().

Examples

if (bs_has_token()) {
users <- bs_get_dataset_current("Users")
bs_diff_manifest(users)
}

Description

Get the schema for a dataset

Usage

bs_get_schema(dataset_name)

Arguments

Value

A schema list, or NULL if no schema is registered.

Examples

bs_get_schema("Users")
bs_get_schema("Grade Results")

Description

Returns the timezone set by bs_set_timezone(), defaulting to "UTC".

Usage

bs_get_timezone()

Value

Character string of the timezone.

Examples

bs_get_timezone()

Description

Joins grade results with grade object definitions and calculates grade percentages.

Usage

bs_grade_summary(grade_results, grade_objects)

Arguments

Value

A joined tibble with grade object name, type, max points, and calculated grade_pct and grade_label.

Examples

if (bs_has_token()) {
grades <- bs_get_dataset("Grade Results")
objects <- bs_get_dataset("Grade Objects")
bs_grade_summary(grades, objects)
}

Description

Check if authenticated with Brightspace

Usage

bs_has_token()

Value

Logical; TRUE if a token is available.

Examples

bs_has_token()

Description

Flags at-risk students from Learner Usage data based on configurable thresholds. Adds boolean risk flags and a composite risk score.

Usage

bs_identify_at_risk(learner_usage, thresholds = list())

Arguments

Value

A tibble with all original columns plus risk flags (never_accessed, low_progress, inactive, low_logins), risk_score (0-4), and risk_level (ordered factor: Low, Medium, High, Critical), sorted by risk_score descending.

Examples

if (bs_has_token()) {
usage <- bs_get_ads("Learner Usage")
at_risk <- bs_identify_at_risk(usage)
at_risk <- bs_identify_at_risk(usage, thresholds = list(progress = 30))
}

Description

Automatically detects shared key columns between two tibbles based on the schema registry and performs a join. Falls back to joining on common column names if schemas are not available.

Usage

bs_join(df1, df2, type = c("left", "inner", "right", "full"))

Arguments

Value

A joined tibble.

Examples

if (bs_has_token()) {
users <- bs_get_dataset("Users")
enrollments <- bs_get_dataset("User Enrollments")
bs_join(users, enrollments)
}

Description

Left joins a content objects tibble with a content user progress tibble on content_object_id and org_unit_id.

Usage

bs_join_content_progress(content_objects, content_progress)

Arguments

Value

A joined tibble.

Examples

if (bs_has_token()) {
content <- bs_get_dataset("Content Objects")
progress <- bs_get_dataset("Content User Progress")
bs_join_content_progress(content, progress)
}

Description

Left joins an enrollments tibble with a grade results tibble on org_unit_id and user_id.

Usage

bs_join_enrollments_grades(enrollments, grade_results)

Arguments

Value

A joined tibble.

Examples

if (bs_has_token()) {
enrollments <- bs_get_dataset("User Enrollments")
grades <- bs_get_dataset("Grade Results")
bs_join_enrollments_grades(enrollments, grades)
}

Description

Left joins an enrollments tibble with an org units tibble on org_unit_id.

Usage

bs_join_enrollments_orgunits(enrollments, org_units)

Arguments

Value

A joined tibble.

Examples

if (bs_has_token()) {
enrollments <- bs_get_dataset("User Enrollments")
org_units <- bs_get_dataset("Org Units")
bs_join_enrollments_orgunits(enrollments, org_units)
}

Description

Left joins an enrollments tibble with a role details tibble on role_id.

Usage

bs_join_enrollments_roles(enrollments, role_details)

Arguments

Value

A joined tibble.

Examples

if (bs_has_token()) {
enrollments <- bs_get_dataset("User Enrollments")
roles <- bs_get_dataset("Role Details")
bs_join_enrollments_roles(enrollments, roles)
}

Description

Left joins a grade results tibble with a grade objects tibble on grade_object_id and org_unit_id.

Usage

bs_join_grades_objects(grade_results, grade_objects)

Arguments

Value

A joined tibble.

Examples

if (bs_has_token()) {
grades <- bs_get_dataset("Grade Results")
objects <- bs_get_dataset("Grade Objects")
bs_join_grades_objects(grades, objects)
}

Description

Left joins a users tibble with an enrollments tibble on user_id.

Usage

bs_join_users_enrollments(users, enrollments)

Arguments

Value

A joined tibble.

Examples

if (bs_has_token()) {
users <- bs_get_dataset("Users")
enrollments <- bs_get_dataset("User Enrollments")
bs_join_users_enrollments(users, enrollments)
}

Description

Retrieves all available ADS datasets from the Brightspace instance.

Usage

bs_list_ads()

Value

A tibble with columns: dataset_id, name, description, category.

Examples

if (bs_has_token()) {
ads <- bs_list_ads()
ads
}

Description

List all submitted ADS export jobs

Usage

bs_list_ads_jobs()

Value

A tibble of all submitted export jobs with columns: export_job_id, name, dataset_id, status, status_text, submit_date.

Examples

if (bs_has_token()) {
bs_list_ads_jobs()
}

Description

List all registered ADS dataset schemas

Usage

bs_list_ads_schemas()

Value

A character vector of registered dataset names (snake_case).

Examples

bs_list_ads_schemas()

Description

Retrieves all available BDS datasets from the Brightspace instance.

Usage

bs_list_datasets()

Value

A tibble with columns: schema_id, plugin_id, name, description, full_download_link, diff_download_link, created_date.

Examples

if (bs_has_token()) {
datasets <- bs_list_datasets()
datasets
}

Description

Retrieves available full and differential extracts for a specific dataset.

Usage

bs_list_extracts(schema_id, plugin_id)

Arguments

Value

A tibble with columns: extract_id, extract_type, bds_type, created_date, download_link, download_size.

Examples

if (bs_has_token()) {
datasets <- bs_list_datasets()
extracts <- bs_list_extracts(datasets$schema_id[1], datasets$plugin_id[1])
}

Description

List all registered dataset schemas

Usage

bs_list_schemas()

Value

A character vector of registered dataset names (snake_case).

Examples

bs_list_schemas()

Description

Calls ⁠/d2l/api/lp/(version)/organization/info⁠ and returns the org identifier.

Usage

bs_org_id()

Value

Character string of the root org unit ID.

Examples

if (bs_has_token()) {
bs_org_id()
}

Description

Applies bs_pseudonymise_id() to the person-referencing columns for a known Brightspace Data Set. Structural IDs (OrgUnitId, GradeObjectId, etc.) are left untouched.

Usage

bs_pseudonymise_df(df, dataset_name, key, columns = NULL)

Arguments

Value

The input data frame with person-referencing columns replaced by pseudonyms.

Examples

key <- openssl::rand_bytes(32)
df <- data.frame(UserId = c(1L, 2L), OrgUnitId = c(10L, 20L))
bs_pseudonymise_df(df, "Users", key = key)

Description

Replaces each value with an HMAC-SHA256 pseudonym of the form usr_a3f2b1c8. The same value + key always produces the same pseudonym, so joins and grouping work correctly within a session.

Usage

bs_pseudonymise_id(values, key)

Arguments

Value

A character vector the same length as values, with non-NA entries replaced by usr_ plus 8 hex characters.

Examples

key <- openssl::rand_bytes(32)
bs_pseudonymise_id(c(1, 2, NA, 3), key = key)

Description

Calculates retention metrics by course or department, including start rates, completion rates, and dropout rates.

Usage

bs_retention_summary(learner_usage, by = c("course", "department"))

Arguments

Value

A summarised tibble sorted by completion_rate.

Examples

if (bs_has_token()) {
usage <- bs_get_ads("Learner Usage")
bs_retention_summary(usage, by = "course")
}

Description

All analytics functions use this timezone for converting date columns.

Usage

bs_set_timezone(tz)

Arguments

Value

Invisibly returns the timezone string.

Examples

bs_set_timezone("Pacific/Auckland")
bs_set_timezone("America/New_York")

Description

Collapses enrollment records to keep only the latest enrollment date for each user-course combination.

Usage

bs_summarize_enrollments(enriched_enrollments, event_type = "Enroll")

Arguments

Value

A tibble with one row per user per course.

Examples

if (bs_has_token()) {
enriched <- bs_enrich_enrollments(enroll, org_units, users)
summary <- bs_summarize_enrollments(enriched)
}