DEV Community

Kayabyte
Kayabyte

Posted on Edited on Originally published at kayabyte.dev

Onboarding in Confluence: make new hires watch the right spaces automatically

#confluence #atlassian #productivity #onboarding

A new hire should see what their team writes from day one: the team space, the handbook, the incident log. In Confluence Cloud, watching is a personal setting, so nothing happens when someone joins the team. Here is what you can do with Confluence alone, and where it stops.

What new hires get by default

  • Autowatch is on by default, but it only covers pages a person creates, edits or comments on. A new hire watches nothing in the team space until they have worked on a page there.
  • Watching a space covers all its pages and blog posts, and the person has to switch it on (or an admin does it for them, see Option 3).
  • Watching does not give access. If the space is restricted, the new hire has to be able to see it first.

Option 1: a step in the onboarding checklist

Put a short "Follow these spaces" section on the onboarding page, with a link to each space and one line: open the space, select Watch. It costs nothing and works for a handful of spaces and one or two hires a month. It breaks when the list of spaces changes, when people skip the step, or when a new hire joins a team that follows eight spaces. Nobody checks that it was done.

Option 2: @mention on the key pages

For the few pages everyone must read, mention the new hire in a comment or add them to an announcement page. That is not a continuous feed from the space, and it is a manual job for each person.

Option 3: an admin adds the watch

The REST API can add a watch for someone else, one account at a time. It needs the Confluence Administrator permission, or Space Administrator on that space, plus the header X-Atlassian-Token: no-check:

curl -s -o /dev/null -w "%{http_code}\n" -u "you@example.com:your-api-token" -X POST \
  -H "X-Atlassian-Token: no-check" \
  "https://your-site.atlassian.net/wiki/rest/api/user/watch/space/TEAM?accountId=NEW_HIRE_ACCOUNT_ID"
Enter fullscreen mode Exit fullscreen mode

A 204 means the watch was added. Run by hand, it is one more onboarding task. Run on a schedule, it needs somewhere to run, and it cannot tell watches it added from watches people chose: someone who unwatched on purpose is added again, leavers keep watching, and a cleanup step does not know which watches it may remove. I wrote the whole script and its limits in How to make a Confluence group watch a space. If you prefer a ready-made one, there is a free MIT script here: github.com/kayabyte-2/atlassian-admin-scripts.

Option 4: let group membership drive the watches

If you already keep a group per team (say engineering), the cleaner design is that adding someone to the group makes them watch. Full disclosure: we build Group Watchers, so weigh this accordingly. Group Watchers works like this:

  • A rule maps one or more groups to a space or a single page. A space can have several rules.
  • Joiners: add the new hire to the group and the app adds their watch. It checks membership every hour, and right away when you change a rule or select Sync now.
  • Access: members who cannot see the space are skipped and counted in the rule status, then checked again every 6 hours, so a hire who gets space permission a day later still ends up watching.
  • Leavers: when someone leaves every group in a rule, the app removes the watch it added. You can switch that off, and watches people had before are never removed.
  • If a new hire unwatches, the app does not add them back.
  • It runs on Atlassian's Forge platform and makes no calls outside Atlassian.

Two limits: only Atlassian user accounts can watch, so portal-only customers and app accounts are skipped. And if an identity provider fills your groups, the new hire appears when your provisioning puts them there, so check how quick that is.

One more thing: will they get email?

A new watcher may see little in their inbox. Edits and new pages go into the daily digest by default, while comments are emailed straight away. Each person changes this under their profile picture, Settings, Email. Add one line about it to the onboarding page.

Which one to pick

  • A few spaces and rare hires: the checklist.
  • Key pages only: @mention.
  • Many spaces, frequent hires, groups you already maintain: group-driven watching, with a script you run or an app.

Confluence and Atlassian are trademarks of Atlassian. Kayabyte is independent and not affiliated with or endorsed by Atlassian.

Top comments (0)