Bridging NetSuite and SharePoint: Architectural Options

Document management is one of the most common integration requirements we encounter. The business has standardised on SharePoint Online for file storage, but transaction-related documents (purchase orders, invoices, contracts) need to be linked to NetSuite records. The question is not whether to connect them, but how. The decision has more technical depth than most vendors admit.

Option A: iPaaS middleware (Celigo, Workato, Power Automate)

Use an integration platform to synchronise documents between the two systems. When a file is uploaded to a designated SharePoint folder, the platform creates a reference record in NetSuite. When a NetSuite transaction reaches a certain status, the platform generates a PDF and files it in SharePoint.

This works well for unidirectional flows with predictable folder structures. It struggles with three things: bidirectional synchronisation with conflict resolution (what happens when the same document is edited in both places?), large-file handling (Power Automate has a 100MB limit per action; Celigo charges per-transaction costs that scale poorly with document volume) and dynamic folder logic that depends on record data not exposed in the standard connector.

The primary advantage is speed of delivery. If your organisation already has Celigo or Power Automate licensed, a basic document flow can be configured in days rather than weeks. The hidden cost is long-term vendor lock-in: your document logic now lives inside a third-party platform whose pricing can change and whose debugging tools are limited compared to native SuiteScript.

Option B: Custom SuiteApp with Security Provider Interface

For organisations that need full programmatic control over the document lifecycle, we build a custom SuiteApp that communicates with the SharePoint Graph API directly from SuiteScript. The architecture uses a RESTlet or Scheduled Script as the communication layer, a custom record for configuration (SharePoint tenant URL, document library path, folder naming convention) and a Security Provider Interface that abstracts the authentication mechanism.

Four technical decisions make or break this implementation.

Decision 1: Application permissions vs delegated permissions

Application permissions (client credentials flow) let the SuiteApp act as itself with admin-granted consent over the whole tenant. Delegated permissions require a user context and are scoped to what that user can access. Most integration guides default to application permissions because they are easier. The right answer depends on your compliance posture.

If your compliance team requires that document access be traceable to a specific user (for example, if SharePoint audit logs must show which user uploaded a document), delegated permissions with an OAuth refresh token flow are mandatory. This is harder to implement and requires a mechanism to refresh tokens before they expire, typically a Scheduled Script running every 60 minutes. Application permissions, by contrast, show all uploads as coming from the app identity, which may violate audit requirements.

Decision 2: Chunked upload for files over 4MB

The Graph API's simple upload endpoint only accepts files under 4MB. For anything larger (and many PO packages with attachments exceed this), you must use the upload session pattern: create an upload session, then PUT byte ranges in chunks of 320KB to 60MB, then finalise the upload. This is not optional. Many teams discover it only after their integration starts silently failing on larger documents.

In SuiteScript, this requires careful handling of binary data across https.request calls and attention to governance units. A chunked upload of a 50MB file will consume multiple HTTP call units, so budget accordingly in your deployment configuration.

Decision 3: Throttling and retry strategy

SharePoint Online throttles aggressively. A burst of 100 document uploads in 60 seconds will see later requests return 429 responses with Retry-After headers. Your integration must respect these headers and implement exponential backoff. A production-grade implementation also queues uploads through a Map/Reduce script rather than attempting them synchronously from User Events, which means users do not see throttling errors on record save.

Decision 4: The Security Provider Interface

Different organisations have different security postures. One client may use Azure AD app registrations with client certificates stored in Azure Key Vault. Another may require tokens to be obtained through an on-premises gateway for data residency reasons. A third may use Privileged Identity Management with just-in-time elevation.

Without a configurable security layer, you build three different versions of the SuiteApp. With one, you build one SuiteApp and three security providers that all implement the same interface: getAccessToken(), refreshToken(), and validateScope(requiredScopes). The SuiteApp calls the interface; the provider handles the specifics. This transforms the integration from a bespoke project into reusable intellectual property.

Choosing between the two

Option A suits organisations with existing middleware investment, low-to-moderate document volumes, straightforward folder structures and no strict audit requirements around user attribution. Option B suits organisations with high document volumes, complex routing logic, compliance requirements around data residency or user-level audit, or multiple subsidiaries where the integration must be standardised.

The decision should be documented in the options assessment before any build work begins. Most importantly, it should be a conscious decision based on your specific constraints, not a default to whichever option your current vendor happens to specialise in.