Zum Inhalt

SharePoint Document Integration

Newton now provisions project folders and manages files in SharePoint Online using the Microsoft Graph API. All SharePoint interactions use the OAuth On-Behalf-Of (OBO) flow so that user permissions in Microsoft 365 are respected.

Configuration

Set the following variables in your .env file:

Variable Description
SHAREPOINT_SITE_ID Full site ID ({hostname},{siteId},{webId}) used for all SharePoint API calls.
SHAREPOINT_DRIVE_ID Document library/drive ID belonging to the site.
SHAREPOINT_PROJECT_ROOT_PATH Root folder inside the drive where projects are created (default /Projekte).
SHAREPOINT_UPLOAD_CONFLICT_BEHAVIOR (Optional) One of replace, rename, or fail for upload conflicts (default replace).

Azure AD application configuration must already be in place for the existing OBO flow (AZURE_TENANT_ID, AZURE_API_CLIENT_ID, AZURE_API_CLIENT_SECRET).

Folder Structure

When provisioning a project, Newton creates the project root folder followed by the mandatory subfolders:

01_Angebote
02_Aufträge
03_Auftragsbestätigungen
04_Rechnungen
05_Verträge
06_Subunternehmer
07_Protokolle
08_Ausschreibungen_Vergaben

The project root folder name is generated from the project number and a sanitized project name, e.g. 12345678_Projekt_Alpha.

API Endpoints

All routes are guarded by JwtAuthGuard and RolesGuard. Users with the BackOffice, Management, ProjectManager, or Administrator role can access them.

Tip: You can retrieve both values with Microsoft Graph Explorer: GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path} for the site ID, then GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives to list drives and copy the desired drive ID.

Method & Path Description
POST /api/v1/documents/projects/:projectId/provision Ensures the SharePoint folder structure exists and returns folder metadata.
GET /api/v1/documents/projects/:projectId Lists documents stored for the project (metadata from Newton database).
POST /api/v1/documents/projects/:projectId/upload Uploads a file to one of the predefined SharePoint subfolders using Graph large-file upload. Body expects folderName and multipart field file.
GET /api/v1/documents/:documentId/download Streams the file from SharePoint to the client with the user’s delegated token.
DELETE /api/v1/documents/:documentId Deletes the file in SharePoint and removes its metadata.

Upload requests accept an optional conflictBehavior (replace | rename | fail). A valid folderName must match one of the predefined subfolders.

Error Handling

  • If a file is deleted in SharePoint outside Newton, download attempts return 404 and purge the stale record.
  • Delete operations ignore missing SharePoint items, ensuring the Newton database stays clean.

Tests

apps/api/src/app/features/documents/documents.service.spec.ts contains unit tests covering folder normalization, upload metadata persistence, and SharePoint-missing-file handling.

Next Steps

  • Extend the document list endpoint to reconcile SharePoint state with Newton periodically.
  • Add front-end drag-and-drop support using the new API routes.
  • Externalize SharePoint drive caching to Redis for multi-instance deployments.