Skip to main content

SharePoint Sync Setup

This tutorial walks through the complete setup for syncing a SharePoint list with a Report Forge blueprint section — from authenticating the SharePoint connection to verifying live data in an edition.

Scenario: You have a SharePoint list called "Action Register" with your project's action items. You want these actions to appear automatically in the "Action Log" section of your Monthly Progress Report editions, so contributors don't have to manually re-enter data that already exists in SharePoint.

SharePoint list columns:

  • Title (single line)
  • Description (multiple lines)
  • Owner (single line)
  • Due Date (date and time)
  • Status (choice: Open, In Progress, Complete)
  • Priority (choice: High, Medium, Low)

Part 1 — Set up the SharePoint connection​

This is a workspace-level step done by a Workspace Admin.

Step 1 — Navigate to Data Connections​

  1. Go to Workspace Settings → Data Connections.
  2. Click + New connection → select SharePoint Online.

Step 2 — Authenticate with Microsoft​

  1. Click Authenticate with Microsoft.
  2. The Microsoft OAuth login window opens.
  3. Sign in with a Microsoft 365 account that has access to the SharePoint site containing the Action Register list.
tip

Use a service account or a shared admin account — not a personal account. If the individual leaves the organisation and their account is deactivated, the SharePoint connection will break.

  1. On the permissions consent screen, approve:
    • Sites.Read.All — allows reading SharePoint sites and lists.
    • If write-back is needed: Sites.ReadWrite.All.
  2. After consent, return to Report Forge — the connection is created.

Step 3 — Name the connection​

  1. The new connection appears in the Data Connections list.
  2. Click the connection → rename it to something descriptive: SharePoint — Project Action Register.
  3. Verify the Status shows Connected.

Part 2 — Configure the blueprint section​

This is done by a Blueprint Owner or Designer.

Step 4 — Open the blueprint​

  1. Open the Monthly Progress Report blueprint.
  2. Click Design mode.
  3. Navigate to the Action Log section (the repeating section you want to sync).

Step 5 — Set the data source​

  1. In the section settings panel (right), click Data source.
  2. Select SharePoint list.
  3. Select the SharePoint connection: SharePoint — Project Action Register.

Step 6 — Select the site and list​

  1. Site: Select your project SharePoint site from the dropdown.
  2. List: Select Action Register from the list dropdown.

Report Forge fetches the list's column structure.

Step 7 — Configure field mapping​

Click Auto-map first — Report Forge attempts to match column names automatically.

Review the mapping results:

SharePoint columnAuto-mapped toCorrect?
TitleTitle✓ (rename Action Log field to "Title" or accept)
DescriptionDescription✓
OwnerOwner✓
Due DateDue Date✓
StatusStatus✓
PriorityPriority✓

If any fields did not auto-map (shown with a warning), click + Add mapping and manually select the correct pairing.

Sync direction for each field:

  • All fields: Read only (SharePoint → Report Forge).
  • We are not writing back to SharePoint in this tutorial.

Step 8 — Configure the sync key (optional for read-only)​

For read-only sync, a sync key is optional. Skip this for now.

If you later need write-back, configure the sync key using the "ID" column (SharePoint's internal item ID) mapped to a hidden ID field in the blueprint.

Step 9 — Set the sync schedule​

  1. Sync trigger: On edition create — this pulls the latest SharePoint data every time a new edition is created. No manual trigger needed.
  2. Direction: Read only.
  3. Click Save sync configuration.

Part 3 — Test the sync​

Step 10 — Run a test sync​

  1. Still in the section settings, click Test sync.
  2. Report Forge pulls the first 5 rows from the Action Register list.
  3. The preview table shows the mapped values.

Check:

  • Are the field values correct (correct types, expected content)?
  • Do the Status field values match the Select options in the Report Forge Action Log section? (e.g. if SharePoint has "In Progress" but the Report Forge Select option is "InProgress" without space, they won't match — fix the options in the blueprint or the SharePoint list).

Step 11 — Fix any type mismatches​

Common issue: Status field mismatch

If SharePoint Choice values don't exactly match Report Forge Select options:

Option A (recommended): Update the Report Forge Select field options to match the SharePoint Choice values exactly.

Option B: Update the SharePoint Choice values to match the Report Forge options.

After fixing, click Test sync again to confirm.

Part 4 — Verify in an edition​

Step 12 — Create a test edition​

  1. Go to the Editions tab → + New edition.
  2. Select the Monthly Progress Report blueprint.
  3. Fill in edition settings and click Create.
  4. Report Forge automatically pulls the SharePoint Action Register data into the Action Log section (because sync trigger = On edition create).

Step 13 — Review the synced data​

  1. Open the edition → navigate to Action Log.
  2. The section should be populated with rows from the SharePoint list.
  3. Verify:
    • Row count matches the SharePoint list row count.
    • Field values are correct.
    • Status, Priority, and other Select fields show the correct options (not raw text).

If the section is empty or shows errors, recheck the field mapping and re-run Test sync in the blueprint settings.

Part 5 — Handle re-authentication​

Step 14 — Monitor connection health​

Check Workspace Settings → Data Connections monthly.

If the connection shows Auth failed:

  1. Click Re-authenticate.
  2. Log in with the service account.
  3. Grant consent again.
  4. Status returns to Connected.
  5. Any scheduled syncs that failed during the auth failure will not auto-retry — create a fresh edition or manually trigger a sync on affected editions.

Summary of what you've built​

  • A SharePoint connection authenticated with a service account.
  • A blueprint section (Action Log) linked to the Action Register SharePoint list.
  • Automatic data pull into new editions on creation — no manual re-entry of SharePoint action items.
  • Field mapping verified with a test sync.

Next steps to consider:

  • Add write-back sync (Report Forge → SharePoint) to push approved status updates back to the SharePoint list.
  • Add the Action Log section to the output template so synced actions appear in the published PDF report.
  • Set up a scheduled automation to generate and deliver the report PDF after each edition approval.