System Design: Order-to-Cash Sync
Examine the architecture of Harborline Software's Salesforce–NetSuite order-to-cash integration. Select interfaces and authentication mechanisms for each integration path, allocate API capacity between live processing and historical backfills, and coordinate both workloads without duplicate or conflicting updates. Define the validation evidence required to verify the integration architecture before processing production orders.
We'll cover the following...
Proposed integration: "Salesforce change events → integration worker → NetSuite SOAP, using OAuth 2.0 client credentials for authentication." Does NetSuite support this endpoint and authentication combination? The business handoff is agreed, but the proposed NetSuite SOAP endpoint does not support the selected OAuth 2.0 client credentials grant. Before processing OPP-410 as an accepted order, verify the supported record operations, authentication identity, access permissions, API limits, and recovery behaviour.
What evidence makes OPP-410’s connections implementable
The proposed NetSuite SOAP connection does not support the selected OAuth 2.0 client credentials grant:
Oracle documents OAuth 2.0 and token-based authentication for REST web services and RESTlets. SOAP web services have separate authentication requirements.
Oracle's OAuth 2.0 configuration guidance covers RESTlets and REST web services. The integration must use a supported grant type and the required scopes. The proposed SOAP endpoint cannot use the OAuth 2.0 machine-to-machine configuration supported by NetSuite REST interfaces.
Consider NetSuite REST web services, subject to verifying the required functionality. Verify the required order operations in Harborline's NetSuite account. Oracle's documented API capabilities do not guarantee support for every customised record or workflow.
Oracle has announced plans to retire SOAP web services and token-based authentication. Check the applicable release timelines, Harborline's account configuration, and migration requirements before considering a legacy integration.
An interface decision record documents the selected endpoint, authentication method, required capabilities, and supporting validation evidence. Evaluate the endpoint, authentication identity, permissions, and API capacity together. An adapter cannot compensate for operations the target system does not support.
Review Harborline's proposed interface decision record. Resolve all outstanding requirements before approving deployment or committing to a launch date.
Harborline’s Proposed Interface Decision Record
Path and System Instance | Actual Representation and Operation | API Family and Version | Identity, Grant, and Permission Boundary | Quota, Freshness, and Recovery | Unresolved Checks |
Change trigger · sf-prod | Notify changes to the actual handoff object and approval fields; representation pending discovery. | Salesforce event API: selection and version pending. | Dedicated subscriber identity; accepted grant pending first-party verification. Object and channel access pending. | Event allocations, delivery behavior, and replay limits pending. Advance capture checkpoint only after durable storage; REST gap recovery required. | Verify event coverage and subscriber authentication separately from REST token issuance. |
Authoritative approved-handoff reads · sf-prod | Read the approved handoff, including approved customer and item references; actual representation pending discovery. | Salesforce REST query/read; select an org-supported version. | Dedicated integration Run As identity. Client credentials conditional on verified interface compatibility and org policy; narrow object, field, and record read access. | Salesforce request allocation and read latency pending. Bounded incremental reads provide recovery. | Confirm schema, reference coverage, permissions, compatible grant, supported version, and incremental query boundaries. |
Approved-order submission and result verification · ns-prod | Actual order representation and required fields pending account-specific REST metadata and representative operation tests. | NetSuite REST web services; record deployed API version/release after verification. | OAuth 2.0 M2M: application/entity/role/public-certificate mapping with REST web services scope. Only required order operations and reference reads. | One live slot shared with projection reads; two-minute projection target pending validation. Durable intent and verified destination reference required. | Verify account-specific order coverage, mapping, permissions, and version/release. Define ambiguous submission outcome policy. |
Fulfillment and financial projection reads · ns-prod | Read order lines, shipment, return receipt, invoice, applied payment, and posted linked credit; actual representations pending coverage verification. | NetSuite REST query and record reads; version/release pending. | NetSuite M2M identity with read permissions for the required records. | Shares the live slot with order operations; two-minute target pending validation. Independent read and application checkpoints; source comparison recovery. | Verify coverage, linked records, read permissions, query boundaries, and latency under shared live load. |
Projection writes and verification reads · sf-prod | Update integration-owned projection fields and read back results; actual fields pending schema review. | Salesforce REST update/read; org-supported version pending. | Dedicated Salesforce integration identity with compatible client credentials. Write only projection fields; read verification fields. No authority over NetSuite finance or fulfillment transitions. | Salesforce quotas and two-minute target pending. Require verified write result and separate projection application progress. | Verify field ownership, update/read permissions, grant compatibility, supported version, quotas, and end-to-end latency. |
Historical inventory · sf-prod and ns-prod | Read actual handoff and accepted-order/projection representations; inventory pending. Populate approved links and projections, never new order commands. | Supported REST read/query families; versions and query boundaries pending. | Provider-specific read identities, or narrowly authorized read permissions under existing identities. | Salesforce quotas and one NetSuite backfill slot. Independent checkpoints, overlap, revision deduplication, and source comparison. | Verify inventory, snapshot or query boundaries, permissions, versions, overlap strategy, and live-priority scheduling. |
OPP-410 → SO-920 represents the relationship between a Salesforce opportunity and a NetSuite sales order. These business identifiers do not determine the API resources or endpoints used. The Salesforce handoff initiates a NetSuite sales order request, subject to the agreed approval process. Fulfilment and financial data synchronised back to Salesforce remain read-only projections of ...