Skip to main content

SharePoint Integration

Report Forge can synchronise a blueprint section's repeating rows with a SharePoint Online list — reading data from SharePoint into editions, and optionally writing approved edition data back to SharePoint.

How SharePoint sync works​

DirectionDescription
SharePoint → Report ForgeSharePoint list rows are pulled into a repeating section when an edition is created or refreshed.
Report Forge → SharePointWhen an edition is approved (or on a schedule), approved data is written back to the SharePoint list.

Sync is not real-time — it runs on demand (manual refresh) or on a configured schedule.

Prerequisites​

Before configuring SharePoint sync:

  1. A SharePoint Online connection must exist in Workspace Settings → Data Connections. See Data Connections Admin for setup.
  2. The Microsoft account used for authentication must have at least Read access to the target SharePoint site (or Edit access if write-back is required).
  3. The target SharePoint list must exist and be populated with at least one row (to allow column mapping).
  4. You need Blueprint Owner or Designer access to configure the sync.

Configuring sync on a blueprint section​

Step 1 — Open section settings​

  1. Open the blueprint in Design mode.
  2. Click the repeating section you want to sync.
  3. In the section settings panel (right), click Data source → SharePoint list.

Step 2 — Select the SharePoint site and list​

  1. Select the SharePoint connection from the dropdown (connections configured in Workspace Settings).
  2. Select the Site — the dropdown shows all sites accessible to the authenticated account.
  3. Select the List — the dropdown shows all lists in the selected site.

Step 3 — Configure field mapping​

Field mapping connects SharePoint list columns to blueprint section fields.

SettingDescription
SharePoint columnThe column in the SharePoint list
Report Forge fieldThe field in this blueprint section
Sync directionRead only / Write only / Read + Write
TransformOptional transformation: trim whitespace, format date, convert to uppercase

Automatic mapping: Click Auto-map — Report Forge attempts to match SharePoint column names to blueprint field names (exact match, case-insensitive). Review all auto-mapped fields — correct any mismatches.

Manual mapping: Click + Add mapping and manually select the SharePoint column and Report Forge field for each pair.

Unmapped columns: SharePoint columns that are not mapped are ignored. Report Forge fields not mapped receive null values from the sync.

Step 4 — Configure the sync key (for write-back)​

For write-back sync (Report Forge → SharePoint), configure a sync key — a field that uniquely identifies each row across both systems.

  • The sync key is used to match Report Forge rows to SharePoint list items.
  • Typical sync keys: a project reference number, a risk ID, an action item ID.
  • The sync key field must be present in both the SharePoint list and the blueprint section, mapped to each other.

Without a sync key, write-back is not possible.

Step 5 — Configure sync schedule​

SettingOptions
Sync triggerManual / On edition create / Scheduled
ScheduleHourly / Daily (08:00) / Weekly (Monday 08:00) / Custom cron
DirectionRead only / Write on approval / Read + Write on approval

Recommended for most use cases:

  • Sync trigger: On edition create (pulls latest SharePoint data when a new edition is created)
  • Direction: Read only (SharePoint → Report Forge)

For write-back:

  • Direction: Write on approval (pushes edition data to SharePoint when the edition is approved)

Step 6 — Save and test​

  1. Click Save sync configuration.
  2. Click Test sync — Report Forge performs a dry run:
    • Pulls the first 5 rows from the SharePoint list.
    • Shows the mapped values in a preview table.
    • Highlights any mapping errors (null values, type mismatches).
  3. If the test succeeds, the configuration is ready.

Manual sync (on demand)​

To trigger a manual sync on an existing edition:

  1. Open the edition → navigate to the synced section.
  2. Click the Sync button in the section header (appears only for sections with an active data connection).
  3. Report Forge pulls the latest data from SharePoint and updates the section rows.
caution

A manual sync replaces existing rows in the section with the current SharePoint data. Any manually entered rows not present in the SharePoint list will be removed. Use sync carefully if contributors have made manual additions since the last sync.

Handling sync conflicts​

A conflict occurs when the same row has been modified in both Report Forge and SharePoint since the last sync.

Conflict resolutionBehaviour
SharePoint wins (default)SharePoint data overwrites the Report Forge value
Report Forge winsReport Forge value is preserved; SharePoint is not overwritten
Newest winsThe most recently modified value (by timestamp) is retained

Configure conflict resolution in the section sync settings → Conflict resolution dropdown.

Field type compatibility​

SharePoint column typeMaps to Report Forge field type
Single line of textText
Multiple lines of textTextarea
NumberNumber
CurrencyCurrency
Date and timeDate or Datetime
Choice (single)Select
Choice (multiple)Multi-select
Yes/NoToggle
Person or groupText (display name)
LookupText (resolved value)
CalculatedComputed (read-only)

Type mismatches: If the SharePoint column type does not match the Report Forge field type, the value may be converted (e.g. Number → Text) or arrive as null. Review the test sync output to identify mismatches.

Re-authentication​

SharePoint connections use OAuth tokens that expire. If the connection shows Auth failed in Data Connections:

  1. Go to Workspace Settings → Data Connections → click the SharePoint connection.
  2. Click Re-authenticate.
  3. Log in with the service account that has SharePoint access.
  4. After consent, the connection is re-authenticated and pending syncs resume automatically.

See Data Connections Admin for the full re-auth procedure.

Troubleshooting​

Sync returns no rows:

  • Verify the SharePoint list has rows and the authenticated account can see them (check SharePoint list permissions).
  • Check if the list is filtered by a view that excludes all rows — the sync reads all rows regardless of the default view.

Field values show as null after sync:

  • The field mapping may be incorrect — check that the SharePoint column name and Report Forge field are correctly paired.
  • The SharePoint column value may be genuinely empty for those rows.

Write-back not updating SharePoint:

  • Verify the sync key field is mapped and contains matching values in both systems.
  • Verify the authenticated Microsoft account has Edit permissions on the SharePoint list.
  • Check the sync log in the section settings for specific error messages.