Skip to content

A platform for community discussion. Free, open, simple.

FEATURE: Log staff actions for admin onboarding panel steps (#42032)

Keegan George400401632963
diff --git a/app/controllers/admin/onboarding_events_controller.rb b/app/controllers/admin/onboarding_events_controller.rb
new file mode 100644
index 00000000000..f3d806cbd38
--- /dev/null
+++ b/app/controllers/admin/onboarding_events_controller.rb
@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Admin::OnboardingEventsController < Admin::AdminController
+ STEPS = %w[select_theme invite_collaborators start_posting].freeze
+
+ def create
+ logger = StaffActionLogger.new(current_user)
+
+ case params.require(:event)
+ when "step_completed"
+ step = params.require(:step)
+ raise Discourse::InvalidParameters.new(:step) if !STEPS.include?(step)
+ logger.log_admin_onboarding_step_completed(step)
+ when "completed"
+ logger.log_admin_onboarding_completed
+ when "dismissed"
+ logger.log_admin_onboarding_dismissed
+ else
+ raise Discourse::InvalidParameters.new(:event)
+ end
+
+ head :no_content
+ end
+end
diff --git a/app/models/user_history.rb b/app/models/user_history.rb
index c1fca406fec..8049cf46561 100644
--- a/app/models/user_history.rb
+++ b/app/models/user_history.rb
@@ -170,6 +170,9 @@ class UserHistory < ActiveRecord::Base
notified_about_composer_education: 125, # not used anymore
recover_post: 126,
change_access_control_list_permissions: 127,
+ admin_onboarding_step_completed: 128,
+ admin_onboarding_completed: 129,
+ admin_onboarding_dismissed: 130,
)
end
@@ -301,6 +304,9 @@ class UserHistory < ActiveRecord::Base
change_site_setting_groups
upcoming_change_available
change_access_control_list_permissions
+ admin_onboarding_step_completed
+ admin_onboarding_completed
+ admin_onboarding_dismissed
]
end
diff --git a/app/services/staff_action_logger.rb b/app/services/staff_action_logger.rb
index 92e5c778879..700496704b6 100644
--- a/app/services/staff_action_logger.rb
+++ b/app/services/staff_action_logger.rb
@@ -319,6 +319,29 @@ class StaffActionLogger
)
end
+ def log_admin_onboarding_step_completed(step, opts = {})
+ raise Discourse::InvalidParameters.new(:step) if step.blank?
+
+ UserHistory.create!(
+ params(opts).merge(
+ action: UserHistory.actions[:admin_onboarding_step_completed],
+ subject: step,
+ ),
+ )
+ end
+
+ def log_admin_onboarding_completed(opts = {})
+ UserHistory.create!(
+ params(opts).merge(action: UserHistory.actions[:admin_onboarding_completed]),
+ )
+ end
+
+ def log_admin_onboarding_dismissed(opts = {})
+ UserHistory.create!(
+ params(opts).merge(action: UserHistory.actions[:admin_onboarding_dismissed]),
+ )
+ end
+
def log_update_site_setting_localizations(locale:, setting_names:, opts: {})
raise Discourse::InvalidParameters.new(:locale) if locale.blank?
raise Discourse::InvalidParameters.new(:setting_names) if setting_names.blank?
diff --git a/config/locales/client.en.yml b/config/locales/client.en.yml
index 3b154820901..90d8d05bfa4 100644
--- a/config/locales/client.en.yml
+++ b/config/locales/client.en.yml
@@ -8960,6 +8960,9 @@ en:
configure_category_type: "configure category type"
unconfigure_category_type: "unconfigure category type"
change_access_control_list_permissions: "change access control list permissions"
+ admin_onboarding_step_completed: "complete admin onboarding step"
+ admin_onboarding_completed: "complete admin onboarding"
+ admin_onboarding_dismissed: "dismiss admin onboarding"
screened_emails:
title: "Screened emails"
description: "When someone tries to create a new account, the following email addresses will be checked and the registration will be blocked, or some other action performed."
diff --git a/config/routes.rb b/config/routes.rb
index c8617125bab..62d94225b91 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -110,6 +110,8 @@ Discourse::Application.routes.draw do
put "user_count" => "site_settings#user_count"
end
+ post "onboarding/events" => "onboarding_events#create"
+
get "reports" => "reports#index"
get "reports/bulk" => "reports#bulk"
get "reports/:type" => "reports#show"
diff --git a/frontend/discourse/app/components/admin-onboarding/banner.gjs b/frontend/discourse/app/components/admin-onboarding/banner.gjs
index 76794f6f436..ff584d93f0c 100644
--- a/frontend/discourse/app/components/admin-onboarding/banner.gjs
+++ b/frontend/discourse/app/components/admin-onboarding/banner.gjs
@@ -10,6 +10,7 @@ import StartPostingOptions from "discourse/components/admin-onboarding/modal/sta
import ThemePickerModal from "discourse/components/admin-onboarding/modal/theme-picker";
import PredefinedTopicOption from "discourse/components/admin-onboarding/predefined-topics-option";
import OnboardingStep from "discourse/components/admin-onboarding/step";
+import { logOnboardingEvent } from "discourse/lib/admin-onboarding";
import { showCreateInviteModal } from "discourse/lib/invite-modal";
import { applyValueTransformer } from "discourse/lib/transformer";
import { defaultHomepage } from "discourse/lib/utilities";
@@ -163,6 +164,7 @@ export default class AdminOnboardingBanner extends Component {
@action
async endOnboarding({ skipped = true } = {}) {
await SiteSetting.update("enable_site_owner_onboarding", false);
+ await logOnboardingEvent(skipped ? "dismissed" : "completed");
this.dismissed = true;
STEPS.forEach((Step) => {
this.keyValueStore.remove(`onboarding_step_${Step.name}`);
diff --git a/frontend/discourse/app/components/admin-onboarding/step.gjs b/frontend/discourse/app/components/admin-onboarding/step.gjs
index 04878f5a236..ce3b0c5cadb 100644
--- a/frontend/discourse/app/components/admin-onboarding/step.gjs
+++ b/frontend/discourse/app/components/admin-onboarding/step.gjs
@@ -3,6 +3,7 @@ import { tracked } from "@glimmer/tracking";
import { concat } from "@ember/helper";
import { action } from "@ember/object";
import { service } from "@ember/service";
+import { logOnboardingEvent } from "discourse/lib/admin-onboarding";
import { currentThemeId, HORIZON_THEME_ID } from "discourse/lib/theme-selector";
import DButton from "discourse/ui-kit/d-button";
import dIcon from "discourse/ui-kit/helpers/d-icon";
@@ -40,7 +41,13 @@ export default class OnboardingStep extends Component {
throw new Error("performAction is required for OnboardingStep");
}
- markAsCompleted() {
+ // Awaits the audit write so callers that reload the page on completion can't
+ // cancel it in flight.
+ async markAsCompleted() {
+ // app events backing some steps can fire more than once, so only audit the
+ // first transition into the completed state
+ const alreadyCompleted = this.completed;
+
this.keyValueStore.set({
key: `onboarding_step_${this.name}`,
value: true,
@@ -48,6 +55,10 @@ export default class OnboardingStep extends Component {
this.completed = true;
this.appEvents.trigger(`onboarding-step:completed`, this.name);
+ if (!alreadyCompleted) {
+ await logOnboardingEvent("step_completed", this.name);
+ }
+
return this.args.onCompleted?.(this.name);
}
diff --git a/frontend/discourse/app/lib/admin-onboarding.js b/frontend/discourse/app/lib/admin-onboarding.js
new file mode 100644
index 00000000000..706c1f8a602
--- /dev/null
+++ b/frontend/discourse/app/lib/admin-onboarding.js
@@ -0,0 +1,21 @@
+import { ajax } from "discourse/lib/ajax";
+
+/**
+ * Records an admin onboarding event as a staff action log.
+ *
+ * Errors are swallowed on purpose: losing an audit entry must never interrupt
+ * the onboarding flow the admin is in the middle of.
+ *
+ * @param {"step_completed"|"completed"|"dismissed"} event
+ * @param {string} [step] name of the step, for `step_completed` events
+ */
+export async function logOnboardingEvent(event, step) {
+ try {
+ await ajax("/admin/onboarding/events", {
+ type: "POST",
+ data: { event, step },
+ });
+ } catch {
+ // intentionally ignored
+ }
+}
diff --git a/frontend/discourse/tests/acceptance/admin-onboarding-banner-test.gjs b/frontend/discourse/tests/acceptance/admin-onboarding-banner-test.gjs
index 0eacca80662..857d84cdb80 100644
--- a/frontend/discourse/tests/acceptance/admin-onboarding-banner-test.gjs
+++ b/frontend/discourse/tests/acceptance/admin-onboarding-banner-test.gjs
@@ -28,6 +28,8 @@ const withStep = (id, assert) => {
};
acceptance("Admin - Onboarding Banner", function (needs) {
+ let loggedEvents = [];
+
needs.user({
admin: true,
groups: [AUTO_GROUPS.admins],
@@ -40,6 +42,8 @@ acceptance("Admin - Onboarding Banner", function (needs) {
default_composer_category: 1,
});
+ needs.hooks.beforeEach(() => (loggedEvents = []));
+
needs.pretender((server, helper) => {
server.put("/admin/site_settings/enable_site_owner_onboarding", () => {
return helper.response(200, {
@@ -47,6 +51,11 @@ acceptance("Admin - Onboarding Banner", function (needs) {
});
});
+ server.post("/admin/onboarding/events", (request) => {
+ loggedEvents.push(helper.parsePostData(request.requestBody));
+ return helper.response(200, { success: "OK" });
+ });
+
server.post("/invites", () => {
return helper.response(200, {
success: "OK",
@@ -93,6 +102,11 @@ acceptance("Admin - Onboarding Banner", function (needs) {
await click(".admin-onboarding-banner .btn-close");
assert.dom(".admin-onboarding-banner").doesNotExist();
+ assert.deepEqual(
+ loggedEvents,
+ [{ event: "dismissed" }],
+ "logs a dismissed staff action"
+ );
});
test("it can complete `start_posting` step with predefined data", async function (assert) {
@@ -223,6 +237,11 @@ acceptance("Admin - Onboarding Banner", function (needs) {
await click(".modal-close");
step.isChecked();
+ assert.deepEqual(
+ loggedEvents,
+ [{ event: "step_completed", step: "invite_collaborators" }],
+ "logs a step_completed staff action once"
+ );
});
test("it can open `select_theme` step", async function (assert) {
@@ -259,6 +278,10 @@ acceptance("Admin - Onboarding Banner - admin invites", function (needs) {
return helper.response(200, { success: "OK" });
});
+ server.post("/admin/onboarding/events", () => {
+ return helper.response(200, { success: "OK" });
+ });
+
server.post("/invites", () => {
return helper.response(200, {
id: 42,
diff --git a/spec/requests/admin/onboarding_events_controller_spec.rb b/spec/requests/admin/onboarding_events_controller_spec.rb
new file mode 100644
index 00000000000..a612e306dc0
--- /dev/null
+++ b/spec/requests/admin/onboarding_events_controller_spec.rb
@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+RSpec.describe Admin::OnboardingEventsController do
+ fab!(:admin)
+ fab!(:user)
+
+ describe "#create" do
+ context "when signed in as an admin" do
+ before { sign_in(admin) }
+
+ it "logs a staff action for a completed step" do
+ post "/admin/onboarding/events.json",
+ params: {
+ event: "step_completed",
+ step: "select_theme",
+ }
+
+ expect(response.status).to eq(204)
+
+ log = UserHistory.last
+ expect(log.action).to eq(UserHistory.actions[:admin_onboarding_step_completed])
+ expect(log.acting_user_id).to eq(admin.id)
+ expect(log.subject).to eq("select_theme")
+ end
+
+ it "logs a staff action when onboarding is completed" do
+ post "/admin/onboarding/events.json", params: { event: "completed" }
+
+ expect(response.status).to eq(204)
+ expect(UserHistory.last.action).to eq(UserHistory.actions[:admin_onboarding_completed])
+ end
+
+ it "logs a staff action when onboarding is dismissed" do
+ post "/admin/onboarding/events.json", params: { event: "dismissed" }
+
+ expect(response.status).to eq(204)
+ expect(UserHistory.last.action).to eq(UserHistory.actions[:admin_onboarding_dismissed])
+ end
+
+ it "rejects an unknown event without logging" do
+ expect {
+ post "/admin/onboarding/events.json", params: { event: "something_else" }
+ }.not_to change { UserHistory.count }
+
+ expect(response.status).to eq(400)
+ end
+
+ it "rejects an unknown step without logging" do
+ expect {
+ post "/admin/onboarding/events.json",
+ params: {
+ event: "step_completed",
+ step: "not_a_step",
+ }
+ }.not_to change { UserHistory.count }
+
+ expect(response.status).to eq(400)
+ end
+ end
+
+ it "denies access to a regular user" do
+ sign_in(user)
+
+ expect {
+ post "/admin/onboarding/events.json", params: { event: "completed" }
+ }.not_to change { UserHistory.count }
+
+ expect(response.status).to eq(404)
+ end
+
+ it "denies access to an anonymous user" do
+ expect {
+ post "/admin/onboarding/events.json", params: { event: "completed" }
+ }.not_to change { UserHistory.count }
+
+ expect(response.status).to eq(404)
+ end
+ end
+end
diff --git a/spec/system/admin_onboarding_banner_spec.rb b/spec/system/admin_onboarding_banner_spec.rb
index aeb3ac460c4..356575b31b3 100644
--- a/spec/system/admin_onboarding_banner_spec.rb
+++ b/spec/system/admin_onboarding_banner_spec.rb
@@ -37,6 +37,14 @@ describe "Admin Onboarding Banner" do
banner.close
expect(SiteSetting.enable_site_owner_onboarding).to eq(false)
+ try_until_success do
+ expect(
+ UserHistory.exists?(
+ action: UserHistory.actions[:admin_onboarding_dismissed],
+ acting_user_id: admin.id,
+ ),
+ ).to eq(true)
+ end
end
end
@@ -125,6 +133,14 @@ describe "Admin Onboarding Banner" do
expect(page).to have_css(".admin-onboarding-banner")
expect(banner.step_completed?("select_theme")).to eq(true)
expect(Theme.find(SiteSetting.default_theme_id).name).to eq(selected_name)
+
+ # the reload must not cancel the in-flight audit write
+ expect(
+ UserHistory.where(
+ action: UserHistory.actions[:admin_onboarding_step_completed],
+ acting_user_id: admin.id,
+ ).pluck(:subject),
+ ).to eq(["select_theme"])
end
end
@@ -153,6 +169,22 @@ describe "Admin Onboarding Banner" do
# Page reloads after theme selection; banner disappears when all steps complete
expect(banner).to be_not_visible
expect(SiteSetting.enable_site_owner_onboarding).to eq(false)
+
+ try_until_success do
+ expect(
+ UserHistory.where(
+ action: UserHistory.actions[:admin_onboarding_step_completed],
+ acting_user_id: admin.id,
+ ).pluck(:subject),
+ ).to contain_exactly("start_posting", "invite_collaborators", "select_theme")
+
+ expect(
+ UserHistory.exists?(
+ action: UserHistory.actions[:admin_onboarding_completed],
+ acting_user_id: admin.id,
+ ),
+ ).to eq(true)
+ end
end
end