Skip to main content

Data Connections Admin

Data connections link Report Forge blueprints to external data sources. Workspace Admins manage all connections centrally — individual project teams configure how connections are used in blueprints, but the underlying credentials are managed at the workspace level.

Access: Workspace Settings → Data Connections (Workspace Admin only).

Connection types​

TypeProtocolUse in Report Forge
Kazinex PlannerInternal OAuthPull schedule data, milestones, and activity progress into blueprint fields
SharePoint OnlineMicrosoft OAuth (delegated)Sync a blueprint section with a SharePoint list; read/write rows
SharePoint On-PremisesSharePoint REST API + service accountSame as SharePoint Online, for on-premises deployments
External REST APIAPI key or OAuth 2.0Pull data from any HTTP API into blueprint computed or lookup fields
CSV/ExcelFile uploadOne-time or scheduled file import into a repeating section

Creating a connection​

Kazinex Planner connection​

Kazinex Planner connections are created automatically when a workspace is set up with both Planner and Report Forge modules. No manual configuration is required.

To verify the Planner connection is healthy:

  1. Go to Workspace Settings → Data Connections.
  2. Locate the Kazinex Planner entry.
  3. Status should show Connected. If Disconnected, see re-authentication below.

SharePoint Online connection​

  1. Go to Workspace Settings → Data Connections → + New connection.
  2. Select SharePoint Online.
  3. Click Authenticate with Microsoft — an OAuth consent window opens.
  4. Log in with a Microsoft account that has access to the target SharePoint sites.
  5. Grant the required permissions:
    • Sites.Read.All (minimum for read-only sync)
    • Sites.ReadWrite.All (required for write-back sync)
  6. After consent, the connection is created and listed with the authenticated account's email.
note

The Microsoft account used for authentication must remain active. If the account is deactivated or has its SharePoint permissions removed, the connection will fail. Use a service account or admin account that is not tied to a specific person's employment.

External REST API connection​

  1. Go to Data Connections → + New connection → External REST API.
  2. Configure:
FieldDescription
Connection nameDescriptive label
Base URLThe API's base URL
Authentication typeAPI key, Bearer token, or OAuth 2.0 client credentials
CredentialsAPI key value, token, or OAuth client ID/secret
Test endpointAn endpoint to ping to verify the connection
  1. Click Test connection — Report Forge pings the test endpoint and shows the HTTP response code.
  2. Click Save if the test succeeds.

Connection health monitoring​

The Data Connections dashboard shows the current status of every connection:

StatusMeaning
ConnectedLast sync/auth check successful
WarningConnection succeeded but data returned warnings (e.g. missing fields)
Auth failedOAuth token expired or credentials rejected — re-auth required
UnreachableCould not reach the external service (network, DNS, or service down)
DisabledConnection manually disabled by admin

Monitoring notifications: Workspace Admins receive an email notification when a connection moves from Connected to Auth failed. This notification fires at the first failure and again after 24 hours if not resolved.

Checking connection details​

  1. Click the connection name to open its detail view.
  2. The detail view shows:
    • Last successful sync timestamp
    • Last failure timestamp and error message
    • Count of blueprints using this connection
    • Recent sync log (last 50 events)

Re-authentication​

OAuth-based connections (SharePoint Online, Planner) use access tokens that expire. Report Forge automatically refreshes tokens using a refresh token — but refresh tokens also expire (typically every 90 days or when the account password changes).

SharePoint Online re-auth​

  1. Go to Data Connections → click the SharePoint connection.
  2. Click Re-authenticate.
  3. The Microsoft OAuth consent window opens — log in with the service account.
  4. After consent, the connection is re-authenticated.

Blueprints using this connection resume syncing automatically.

External REST API credential rotation​

When an API key or service credential is rotated:

  1. Go to Data Connections → click the connection.
  2. Click Edit credentials.
  3. Replace the old key/token with the new value.
  4. Click Test connection to verify.
  5. Click Save.

Connection lifecycle management​

Disabling a connection​

If a connection should temporarily stop syncing (e.g. during a system migration):

  1. Click the connection → Disable.
  2. All scheduled syncs using this connection pause.
  3. No data is lost — existing edition data remains.
  4. Re-enable when ready.

Deleting a connection​

Deleting a connection removes it permanently. Before deleting:

  1. Identify all blueprints using this connection: click the connection → Used by tab.
  2. For each blueprint, open the blueprint and remove the data connection configuration from affected fields.
  3. Verify no scheduled syncs reference this connection.
  4. Click Delete connection → confirm.
caution

Deleting a connection that is still used by blueprints will cause those blueprints' data-connected fields to fail silently (returning null). Always remove blueprint references before deleting the connection.

Troubleshooting​

Sync fails with "Permission denied"​

  • The Microsoft account used for SharePoint authentication lost access to the target site.
  • Resolution: Verify the account's SharePoint permissions. Re-authenticate or use a different account with site access.

Sync fails with "List not found"​

  • The SharePoint list was renamed, moved, or deleted.
  • Resolution: Open the blueprint → Data connection settings → re-map to the correct list.

API connection returns 401 Unauthorized​

  • The API key was revoked or the token expired.
  • Resolution: Obtain a new key/token from the external system. Update credentials in the connection.

Data is syncing but field values are wrong​

  • Column mapping between the SharePoint list and the Report Forge blueprint section has shifted (e.g. a column was added to the SharePoint list, shifting column positions).
  • Resolution: Open the blueprint → Data connection settings → review field mapping → correct any misaligned mappings.