§7 — discovery is NOT an authoritative full-gamut enumeration. DiscoverObjects returns the
Declared baseline (engine cache) and GetQueryDefinition only extends per-object fields; neither
enumerates the complete set of objects the credentials expose (customer-installed queries vary).
So absence in a refresh proves nothing → the comprehensive-refresh deactivation path must stay
off. Returning false keeps the Declared metadata safe from wrongful deactivation.
The canonical integration name (e.g., "HubSpot", "Rasa.io"). Used by GetActionGeneratorConfig() and IntegrationActionExecutor to match connectors to action Config.IntegrationName.
Override in subclasses. Defaults to the class name.
Highest SAFE per-layer concurrency the source tolerates (plan.md §7 peak parallelization) — the
ceiling the engine's adaptive controller ramps toward. null → use configured syncConcurrency.
Whether the watermark this connector returns (FetchBatchResult.NewWatermarkValue) is a
RELIABLE, monotonically-increasing global maximum — i.e. the connector fetches in watermark
order so the last batch's value IS the true high-water mark, and an updated record always
re-surfaces at a NEW (higher) watermark. When true, the engine uses that watermark to NARROW
the next incremental (instead of advancing a full sync to wall-clock "now", and instead of the
keyset clear-and-re-scan), so incrementals fetch only what's new.
Default false — the safe, backwards-compatible choice: a connector whose source returns
records out of watermark order (e.g. HubSpot's creation-ordered list API, where the last batch
can carry old modstamps) MUST stay false so the engine keeps advancing to "now" and never saves
a stale watermark. Override to true ONLY when the source guarantees monotonic ordering.
Token-bucket rate-limit policy for this connector's source API (plan.md §7 peak-aware rate
limiting). null → the engine derives a conservative rate from Integration.BatchRequestWaitTime.
Override to push to the source's real limits.
Whether this connector supports batched target writes (plan.md §7 aggressive batching).
Whether this connector supports creating new records in the external system.
Whether this connector supports deleting records from the external system.
Whether this connector supports reading/fetching records. Always true.
Whether this connector supports paginated listing of records.
Whether this connector supports searching/querying records with filters.
Whether this connector supports updating existing records in the external system.
Whether this connector supports idempotent upserts (create-or-update keyed
by a unique business property). Connectors override this AND Upsert to enable it.
ProtectedAppendAppends default query parameters from the IntegrationObject metadata. DefaultQueryParams is stored as a JSON object like {"key": "value"}. Automatically skips params whose key (case-insensitive) already appears in the URL to avoid duplicates with pagination params.
ProtectedapplyRuns TransformRecord, then RE-ADDS any source key the transform dropped (present in
raw, absent from the output) unless declared in ExcludedSourceKeys. This makes the
base-fetch path structurally full-record (§0 forward-compat contract): a TransformRecord
override may reshape/coerce but cannot SILENTLY drop a source key from ExternalRecord.Fields,
so the framework's custom-column capture sees everything the source returned. The default
identity transform returns raw unchanged → fast-path no-op (zero overhead, zero behavior
change for connectors that don't override TransformRecord).
ProtectedAuthenticateStep 1 of the two-step auth: POST a SOAP Authenticate(userName, password) envelope (which
carries NO AuthorizationToken header — it is the bootstrap) and read the token string from
AuthenticateResult. The token is cached and re-used until its TTL elapses or a 401 forces
re-auth. Credentials go in the SOAP body elements — there is no HTTP Basic / Bearer here.
Batch-create. Default loops single-record CreateRecord, so the engine may always call the batch form.
Batch-delete. Default loops single-record DeleteRecord.
Batch-update. Default loops single-record UpdateRecord.
ProtectedBuildBuilds a CRUDResult for a record CREATE, failing LOUDLY when the external system returned no usable record ID. A 2xx response with an empty/undefined ID means the create did not durably produce a record we can track — returning Success:true there silently loses the record and causes duplicate creates on the next sync (the HubSpot-association class of bug, fixed in next commit 9f718a7e). This makes that failure explicit at the connector boundary.
ProtectedBuildThe base-class abstract BuildHeaders — defers to SoapHeaders for the active operation.
ProtectedBuildBuild the operation request body per BodyShape:
ProtectedBuildAppends pagination parameters to a URL based on the object's PaginationType. Override in subclasses to use vendor-specific parameter names.
Optionalcursor: stringOptionaleffectivePageSize: numberWhen provided by FetchPaginatedLoop, caps the requested page size to the remaining batch capacity. Subclasses should honor this to prevent overshoot.
Create via the SOAP operation named in the IO's CreateBodyKey / Configuration.writeOps.createOp (e.g. WEBIndividualInsert, InsertFacadeObject). The attributes are wrapped in a SOAP envelope for that operation; the new key is read from the response and routed through BuildCreatedResult, so a 2xx that carries no record key FAILS loudly (the silent-create-loss invariant).
Overridden (not the generic per-operation REST path) because the body must be a SOAP envelope, not a JSON body — the generic CreateRecord builds a JSON body. We still honor the metadata columns (operation name) and still call BuildCreatedResult.
Delete is not supported. DeleteFacadeObject is not confirmed in any reachable vendor doc and netFORUM prefers soft-delete via status flags. SupportsDelete is false, so this returns a clean error rather than silently claiming success.
Two-stage field discovery. Stage 1 returns the Declared field set (engine cache). Stage 2, when a credential is available, calls the GetQueryDefinition MECHANISM and parses the returned SQL column definition (Object → ListTable → ListFromTables → Column[]) into ExternalFieldSchema — this surfaces customer-added columns the static metadata never saw. With no credential, or on any error, it degrades to the Declared fields (never throws, never bakes a catalog).
Discovery via the connector's READ PATH (FetchChanges), TIME-BOUNDED — the way to gather a statistically-significant sample when a single DiscoverFields sample is too small to PROVE a key. "Discovery is the sync read path with the save removed."
Loops FetchChanges as a read-only FULL fetch (WatermarkValue=null, nothing persisted), threading pagination/keyset cursors across batches, and streams every record through the data-informed field + provable-PK inference. It stops at the discovery TIME BUDGET (default 5 min), or a record cap, or source exhaustion — whichever comes first — so the provable-PK decision is made on as much real data as the budget allows. It NEVER fabricates a key: if even this larger sample yields no provable single/composite PK, the field set comes back PK-less and the object is honestly not added.
Falls back to the single-sample DiscoverFields if the read path can't run for this object (e.g. a connector whose FetchChanges needs an already-persisted IO row that doesn't exist yet).
Optionalopts: { BatchSize?: number; MaxRecords?: number; TimeBudgetMs?: number }ProtectedDiscoverStage-2 field discovery for sources WITHOUT a describe/introspection endpoint (file feeds,
undocumented JSON list endpoints): stream the source's actual records — READ-ONLY, no save,
no ack — and derive the full field set + data-informed PK/uniqueness/nullability from the
gathered statistics. The connector supplies whatever read-only fetch yields the records; this
helper turns that stream into ExternalFieldSchema[].
Why data-informed: streaming the real values lets pickPrimaryKeyFromStats pick the PK from
evidence (uniqueness/non-null statistics) COMBINED with the naming convention, rather than a
name guess alone. The PK is a SOFT key, so the pick is best-available, not strict-significance:
a confident unique+non-null column wins outright; otherwise a near-unique / convention-named
column is taken as a soft key (a PK-less object would stall CodeGen). The scan is time-bounded —
it stops on exhaustion OR opts.Discovery.TimeBudgetMs; more rows simply mean stronger claims.
Provable-only encoding into the standard flags:
IsPrimaryKey — set ONLY on the single statistics-first pick. Multiple equally-ranked unique
columns leave PK unset here (ambiguous → the pipeline's SoftPKClassifier LLM tiebreaker
decides, fed these same stats). Zero unique columns → no PK is fabricated.IsUniqueKey — set when the column was all-distinct over the scan AND uniqueness was provable
(the distinct-cap wasn't hit).AllowsNull — asserted true ONLY when a null/absent value was actually observed; otherwise
left undefined (permissive default). Never fabricates NOT NULL — critical under a time-capped
partial scan where unseen rows could still be null.The PK emitted here is SOFT (it rides additionalSchemaInfo via the persist + DDL path; it is
NEVER a hard DB key), so a wrong inference can never reject a valid row — the engine dedupes via
the record-map. IsReadOnly defaults to true (stream discovery targets read feeds); a writable
source overrides via opts.ReadOnly.
A read-only sync/async iterable of source records (the caller's fetch yields them).
Optionalopts: { Discovery?: StreamDiscoveryOptions; Pk?: PkPickOptions; ReadOnly?: boolean }OptionalDiscovery?: StreamDiscoveryOptionsTime budget / sample caps for the scan (see StreamDiscoveryOptions).
OptionalPk?: PkPickOptionsSignificance threshold + naming-rank tiebreaker (see PkPickOptions).
OptionalReadOnly?: booleanWhether discovered fields are read-only. Default true.
Standard objects = the Declared metadata (engine cache of persisted IntegrationObject rows). NO hardcoded catalog. The base implementation reads exactly the credential-free Declared universe; a live credential only ADDS customer-installed query objects (the Discovered extension), it never supplies the baseline — so this re-yields the standard universe credential-free and the runtime structure self-check passes without a token.
ProtectedDiscoveryDISCOVERY-ONLY: last-resort SAFETY bound on the recursion depth for multi-level template chains (a
parent that is itself a template-var child), so a malformed metadata cycle cannot loop unboundedly.
This is only the fallback when the consumer sets no discoverySampleMaxDepth in Configuration and
no env override is present — the consumer decides the real value. A recursion cap MUST have some
bound, so a conservative default remains here; override the getter to change the fallback.
ProtectedDiscoveryREST override (§sample-discover): a SINGLE-template-var CHILD is sampled with the recursive, record-constrained StreamRecordsForDiscovery. Flat objects fall back to the generic FetchChanges loop; MULTI-var (composition) children are deferred — StreamRecordsForDiscovery adjourns them (declared-only until first sync) rather than fire malformed URLs.
ProtectedExcludedSource keys a connector DELIBERATELY removes in its TransformRecord override (vendor noise, a flattened parent blob, a nested child collection emitted as its own object). These are the only sanctioned drops — excluded from the applyTransformPreservingKeys re-add. Default: none. Override per-object to declare intentional removals.
ProtectedExtractBest-effort error message extraction from a vendor response. Override for vendor-specific shapes.
ProtectedExtractExtract the new record's external ID from a create response per IDLocation.
ProtectedExtractExtract pagination state from the vendor-specific response.
The parsed response body
The pagination strategy for this object
Current page number (1-based)
Current record offset
Page size used in the request
Pagination state indicating whether more data is available
Parse a Retry-After / rate-limit signal out of a failed response or thrown error into
milliseconds so the engine can back off precisely. Return undefined when the error is not a
throttle (or carries no hint).
Fetches a batch via the GetQuery door. Walks the IO's access path from Configuration: the door
(GetQuery), the query object name, and any top modifier (@TOP -1 to bypass the DataGrid row
cap). Incremental sync uses the IO's per-facade IncrementalWatermarkField in the
szWhereClause — there is NO canonical LastModifiedDate; the field is metadata-driven.
Full-record pass-through: every parsed row becomes ExternalRecord.Fields verbatim — never a filtered/narrow literal — so the framework's custom-column capture sees every column the query returned, including customer-added ones.
Returns the ActionGeneratorConfig for this connector, combining the integration name, category, icon, and objects into a ready-to-use configuration for ActionMetadataGenerator.Generate().
Override in subclasses to customize the config (e.g., icon, category). Returns null by default if GetIntegrationObjects() returns empty.
ProtectedGetGet the base URL for API requests (e.g., "https://api.example.com/v1"). Combined with the object's APIPath to form the full request URL.
ProtectedGetGets IntegrationObjectField records from the engine's cache for a given object ID. Returns only active fields sorted by Sequence.
ProtectedGetGets an IntegrationObject from the engine's cache by integration ID and object name. Throws if not found.
Returns a proposed default configuration for quick setup. Override in subclasses to provide connector-specific defaults including schema name, objects to sync, and field mappings. Returns null by default (no quick setup available).
Returns suggested default field mappings for an external object to MJ entity. Override in subclasses to provide intelligent defaults.
Name of the external object
Name of the target MJ entity
Array of default field mappings (empty by default)
Returns the integration objects and their fields that this connector supports, for use by the ActionMetadataGenerator. This is static metadata that does NOT require a live connection — it describes the connector's known object model.
Override in subclasses to provide connector-specific objects/fields. Returns an empty array by default (no action generation available).
Generic get-one: hits APIPath/{ID} via GET. Override if API uses non-standard get shape.
Builds SourceSchemaInfo from IntegrationEngineBase cached metadata. Provides richer metadata than the base class implementation, including FK relationships derived from RelatedIntegrationObjectID.
Lists records with cursor-based pagination.
Override in subclasses that support paginated listing.
Check SupportsListing before calling.
ProtectedMakeThe base-class abstract MakeHTTPRequest — routes through the raw transport.
Optionalbody: unknownProtectedMakeRaw SOAP transport: POSTs the XML envelope, retries on 401 (re-auth)/429/5xx, and returns the response body as text (SOAP is text/xml). Never logs credentials, the token, or PII.
protected so a unit-test subclass can override this single transport seam to feed canned
SOAP responses (no live network, no credentials) — the only seam tests need to mock.
Optionalbody: stringProtectedNormalizeStrips the SOAP envelope and the GetQueryResult wrapper, returning each flattened row as a plain object of column→value. netFORUM GetQuery returns a DataSet of repeated row elements (the row element name is the query's "Result"/"
Type-driven post-processing hook (plan.md §10): a connector may normalize/enforce a record's
values to the resolved column formats AFTER transform/normalize and BEFORE write. Default
returns the record unchanged. (Named for this system — NOT MCP, not take.) The engine ALSO
applies target-type constraint enforcement; this is the connector-side complement.
Searches for records matching the given filters.
Override in subclasses that support search/query operations.
Check SupportsSearch before calling.
Returns the IO's stable, monotonic ordering column (the PK / Configuration.stableOrderingKey) so the engine can keyset-resume objects that have no incremental watermark. Null when the IO is unknown or has no stable key — keyset resume is simply unavailable then, not an error.
ProtectedSubstituteSubstitute the ExternalID into a URL path template at runtime. Path templates may use {ID}, {id}, or {ExternalID} as the placeholder; for symmetry with FetchChanges template-var handling, any unsubstituted {var} in the template is left in place (caller's responsibility to ensure consistency).
For IDLocation='body' or 'header' the ID is not substituted into the path (caller must handle separately); we just return the raw path.
ProtectedTemplatePer-call cap on how many PARENTS a parent-iterated object processes before yielding a resumable batch (the engine loops on HasMore). Kept conservative so a single FetchChanges call fits the engine's op-timeout even at a slow initial adaptive rate; the AIMD bucket ramps up over batches. Override in a concrete connector if a vendor tolerates larger per-call parent runs.
Tests connectivity to the external system.
The company integration entity with connection credentials
User context for authorization
Connection test result with success/failure and message
ProtectedTransformOptional per-record CUSTOMIZATION hook called between NormalizeResponse (vendor envelope-stripping) and ToExternalRecord (composite-PK assembly).
Distinct from NormalizeResponse — that strips the vendor's response envelope to expose individual records. This hook is for vendor-specific record-level customization the standard pipeline shouldn't carry: nested-field flattening, empty-string→null coercion for date columns, computed fields, removing vendor metadata blobs (e.g. Salesforce 'attributes'), etc.
Default is identity (no transform). Override only when a concrete connector needs vendor-specific shape changes.
Update via the SOAP operation named in UpdateBodyKey / Configuration.writeOps.updateOp. netFORUM exposes no ETag / If-Match — updates are last-write-wins.
Upserts a record — a single idempotent create-or-update keyed by a unique
business property (e.g. email), eliminating the search-then-create race window.
Override in subclasses whose external system exposes a keyed upsert primitive.
Check SupportsUpsert before calling.
Abstract base class for REST API integration connectors.
Implements the generic REST sync pattern: reads IntegrationObject/Field metadata from the MJ database, handles pagination, template variable resolution (per-parent iteration), and converts raw API responses to ExternalRecord format.
Concrete connectors (YourMembership, Salesforce, HubSpot, etc.) extend this class and implement only auth, HTTP transport, and response normalization.