Synchronization Engine

• Bidirectional sync between Odoo Documents and SharePoint libraries
• 5 conflict policies: Manual Resolution, Newest Wins, Odoo Always Wins, SharePoint Always Wins, Keep Both Copies
• Quiet period: Skip files modified within a configurable window (default 30 seconds) to avoid syncing in-progress edits
• Auto-sync: Configurable intervals (5-240 minutes) via scheduled action
• Real-time sync: Microsoft Graph webhook notifications for instant updates
• Background processing: Queue-based async syncing via praetorx_base
• Folder structure preservation: Maintains Odoo folder hierarchy in SharePoint
• Excluded extensions filter: Comma-separated list (e.g. .tmp,.ds_store,.bak)

Conflict Resolution

• Workspace-level policies — configure per workspace how conflicts are handled:

  Policy	Behavior
  Manual Resolution	Surface in conflict queue for user decision
  Newest Wins	Compare timestamps, keep the newer version
  Odoo Always Wins	Always push the Odoo version to SharePoint
  SP Always Wins	Always pull the SharePoint version to Odoo
  Keep Both Copies	Fork both versions (Dropbox-style)

• Conflict Resolution Wizard — bulk-resolve conflicts from the document list with strategy selection and preview of both versions

• Form-level buttons — resolve individual conflicts with "Keep Local", "Keep Remote", or "Keep Both" directly on the document form

• State machine — validated sync status transitions prevent invalid state changes

Sync Audit Log

Every sync event is recorded in sharepoint.sync.log:

• Uploads, downloads, conflict detections, resolutions, deletions, errors
• Metadata snapshot at event time (checksums, ETags, file sizes)
• Trigger source (cron, webhook, manual)
• User who triggered the action
• Daily retention cleanup (90 days standard, 180 days for conflict entries)

Deletion Handling

• Remote deletion policy — when a file is deleted in SharePoint:

  Policy	Behavior
  Quarantine	Move to quarantine folder (default)
  Archive	Archive the Odoo document
  Delete	Delete from Odoo
  Ignore	Keep in Odoo unchanged

• Local deletion policy — when a file is deleted in Odoo:

  Policy	Behavior
  Ignore	Keep in SharePoint (default)
  Delete Remote	Delete from SharePoint

• Un-quarantine flow — restore quarantined documents back to pending sync

• Recycle bin restore — restore from SharePoint's recycle bin if still available

• Deletion log — complete audit trail with user, timestamp, and type

Workspace Dashboard

• Stat buttons on workspace config: synced, pending, conflict, failed, quarantined counts
• Click any stat button to open a filtered document list with the SharePoint sync form
• Reset stale conflicts button — bulk-reset all conflicts in the workspace
• All actions use dedicated SharePoint views (not the default Documents/Vault views)

Security & Authentication

• OAuth2 via Microsoft Graph API with Azure AD application
• Encrypted storage for client secrets and access tokens (Fernet/AES-128-CBC)
• Automatic token refresh before expiration
• Webhook HMAC-SHA256 signature validation (optional — requires webhook_secret)
• Rate limiting: 100 requests/minute per auth record (in-process; does not persist across restarts or workers)
• IP whitelist: CIDR support for webhook sources
• File size validation: Configurable upload limit (default 250 MB)

Python Dependencies

pip install msal requests cryptography

Azure AD Permissions

Your Azure AD application needs these Microsoft Graph Application permissions:

• Files.ReadWrite.All
• Sites.ReadWrite.All
• User.Read

Step 1: Azure AD Application

1. Go to Azure Portal > Azure Active Directory > App registrations
2. Click New registration
3. Set name "Odoo SharePoint Sync", single tenant, no redirect URI needed for client credentials
4. Record your Tenant ID and Client ID
5. Under Certificates & secrets, create a new client secret
6. Under API permissions, add Microsoft Graph Application permissions and grant admin consent

Step 2: SharePoint Authentication in Odoo

1. Navigate to SharePoint Sync > Configuration > OAuth2 Authentication
2. Create a record with your Tenant ID, Client ID, Client Secret, and SharePoint Site URL
3. Click Test Connection to verify

Step 3: Workspace Configuration

1. Navigate to SharePoint Sync > Configuration > Workspace Configuration
2. Create a workspace mapping:
   • Enter your SharePoint Site URL
   • Click Discover Libraries to auto-detect available document libraries
   • Select a library and optionally a subfolder
   • Select the Odoo Documents workspace to map
   • Choose sync direction (Bidirectional recommended)
   • Set the conflict policy (default: Manual Resolution)
   • Configure deletion policies as needed
   • Enable sync and set the interval
3. Click Test Connection, then Sync Now for the initial sync

Step 4: Monitor

• Check the Sync Dashboard for document status overview
• Use the stat buttons on the workspace form for quick filtered views
• Review the Sync-Protokoll (Sync Log) menu for detailed event history

Authentication

• "Invalid client secret" — verify secret value (not ID), check expiration
• "Insufficient privileges" — verify API permissions and admin consent
• Token refresh failing — recreate client secret in Azure AD

Sync Issues

• Files not syncing — check workspace is enabled, document has sp_enabled = True, file type not filtered
• Wrong library — verify workspace drive ID matches the intended library
• Conflicts on every sync — reset stale conflicts via workspace button, check sp_last_sync timestamps

Connection

• "Site not found" — URL must include /sites/[name], verify user access
• "Library not found" — use Discover Libraries, check library name matches

Models

• sharepoint.auth — OAuth2 credentials and token management
• sharepoint.workspace.config — Workspace mappings, policies, sync orchestration
• sharepoint.sync.log — Sync audit log (uploads, downloads, conflicts, errors)
• sharepoint.conflict.resolver — Per-conflict resolution records
• sharepoint.resolve.conflict.wizard — Transient model for bulk conflict resolution
• sharepoint.connector — Microsoft Graph API client
• sharepoint.library — Discovered SharePoint document libraries
• sharepoint.folder — SharePoint folder hierarchy
• sharepoint.sync.deletion.log — Deletion tracking (legacy, superseded by sync log)
• documents.document (extended) — SP sync fields, state machine, audit logging

Key Methods

# Sync a document to SharePoint
document.sync_to_sharepoint()

# Check which version is newer (ETag + timestamp comparison)
result = document._check_newer_version()  # 'odoo', 'sharepoint', 'conflict', 'deleted'

# Validated state transition
document._set_sync_status('pending')

# Log a sync event
document._log_sync_event('sync_up', trigger='manual')

# Resolve conflicts via form buttons
document.action_resolve_keep_local()
document.action_resolve_keep_remote()
document.action_resolve_keep_both()

# Workspace-level sync
workspace.action_sync_now()
workspace._perform_bidirectional_sync()

# Reset stale conflicts
workspace.action_reset_stale_conflicts()