What to sync

The sync reads the workspaces you choose, on the schedule you set. This step makes both choices, and its check counts what the first scan would read.

Before you start

The scanner has passed. This check asks Power BI for the workspace list as the scanner.
If you want only some workspaces, their ids. Open a workspace’s report in Power BI: the id is the part of the address between /groups/ and /reports/. A Power BI admin can also copy it from Details beside the workspace’s name in the admin portal.

Source for the workspace id: Microsoft, Embed for your customers, under Workspace ID.

Steps

On step 4, What to sync, choose the workspaces. Under Workspaces to sync either:
- leave Every workspace Power BI lists ticked, which is the default; or
- untick it and list the ids under Only these workspaces, one per line.
Under Workspaces to skip list the ids the sync must never read, one per line. A workspace listed here is skipped even when it is also in the list above.
Tick Also sync people’s personal workspaces only if the book should describe models people keep in My workspace. It is off by default.
When the sync runs is a cron line, in the containers’ time zone, which is UTC unless you set one. The default runs at the start of every hour:
```
0 * * * *
```
The default is right for most companies. Power BI limits the list of changed workspaces to 30 calls an hour, so do not run it more often than that. A full scan also runs every night at 02:30 (powerbi.sync.full_scan_schedule, default 30 2 * * *), and you can start a sync by hand with pbmb sync run.
Press Check what the first sync scans. The worker asks Power BI for the list, so the page waits and asks again every few seconds.

A change in Power BI shows in the book within one scheduled sync, an hour by default.

Turn datasets on or off

To use the admin screen instead of the CLI, see Datasets on or off.

The workspace filter (powerbi.sync.workspaces.include and .exclude) chooses what the scanner reads. To hide one dataset while keeping its mirror current, turn that dataset off instead. As an admin on the sample tenant:

pbmb admin datasets list
pbmb admin datasets off Sales
pbmb admin datasets list --off

Sales now appears with enabled: false in the admin list. It disappears from metadata, search and book variants for everyone, including admins, and cannot be queried. The sync keeps reading it. The admin list shows every live dataset’s name, workspace and counts, even beyond the admin’s own Power BI rights; it shows no query data. Use a dataset id if several datasets share a name.

Turn it back on and check that it returns:

pbmb admin datasets on Sales
pbmb datasets show Sales

The metadata returns immediately for people with access. Search documents are rebuilt after either switch. Query log entries keep naming datasets that have been turned off.

New datasets start on by default. To review each new dataset before showing it:

pbmb admin settings set powerbi.datasets.new off
pbmb admin settings get powerbi.datasets.new

The answer is off. This setting affects only datasets first found by a later sync; it does not change existing ones. Set it to on to restore the default. Dataset switches are specific to this tenant and are not exported in book.yml.

For queries off while metadata stays visible and searchable, use the lighter custom.queries_off policy described in Custom fields. A custom policy cannot expose a dataset turned off by pbmb admin datasets off.

Check

The step passes with “The first sync scans N of the M workspaces Power BI lists.” Read the two numbers: N is what your choices select, and M is every workspace the scanner can see. If N is not what you expect, fix the lists and press the button again. You can also run:

pbmb admin check what_to_sync

If a sentence appears, find it on When a check fails.

Next: Sign-in.