Salesforce

Depends on your plan

The Salesforce connector is included in Enterprise plans (the connector credentials capability). Registering a connector on a plan without it returns 403 connector.not_licensed. See what depends on your plan.

The connector bridges both directions: changes to accounts, contacts and orders in your org become organizations, users and entitlements in Oclavex automatically — and when an entitlement’s lifecycle changes in Oclavex, its status appears on the matching record in your org, so an account owner sees whether a customer is live, paused or lapsed without leaving the CRM.

Inbound — Salesforce drives Oclavex

The connector subscribes to your org’s change events over the Salesforce Pub/Sub API — Oclavex opens the connection to Salesforce, so there is no inbound endpoint for you to expose, and nothing in your org calls Oclavex.

You change in Salesforce	Oclavex creates or updates
Account	Organization
Contact	User (linked to the account’s organization)
Order + LicenseGrant__c	Entitlement

Two behaviours to know when you design your order process around it:

• Order activation releases the entitlement. A LicenseGrant__c on a Draft order does nothing yet; the entitlement materializes when the order is Activated. The two can arrive in either order — a grant that shows up before its order is activated waits.
• The product code selects the offer. ProductCode__c on the license grant decides which Oclavex entitlement offer is instantiated. Codes are agreed when the connector is set up; an unknown code is parked for an operator to resolve rather than silently guessed.

Deleting a license grant record cancels the entitlement it created. Changes made while the connection is down are caught up automatically when it resumes — delivery is at-least-once and replays are harmless.

Outbound — Oclavex writes license state back

When an entitlement changes — activated, suspended, resumed, renewed, cancelled, expired — Oclavex writes to the LicenseGrant__c record it is anchored to:

Oclavex	Salesforce LicenseGrant__c
Entitlement id	MonetizeItEntitlementId__c
Lifecycle status	Status__c

The status is the entitlement’s current lifecycle state, re-evaluated against the clock on every write — a license past its end date shows as expired even if nothing else about it changed. Every status write carries MonetizeItEntitlementId__c with the same value — idempotent rather than write-once — so the entitlement and the Salesforce record stay tied together.

A few guardrails keep the write-back safe to leave running:

• No surprise records. The connector only updates records that already carry the anchor; it never creates new Salesforce records. Entitlements that did not originate from your org are skipped.
• No writing to the wrong record. If a record is later reassigned so its anchor no longer matches, Oclavex refuses to overwrite it and flags it instead.
• Idempotent. Every write targets a specific record, so retries never leave duplicates behind.

Updates are batched and sent through Salesforce’s Composite API, so a burst of activations turns into a small number of requests rather than one call each.

Prepare your Salesforce org

Doing this yourself?

The Salesforce setup guide walks a Salesforce administrator through every step in order — objects, fields, Change Data Capture, the External Client App, the permission set — and ends with an end-to-end test. The rest of this section is the reference contract behind it.

A Salesforce admin sets the org up once — the schema, the change-event feeds, and a server-to-server app for Oclavex to authenticate as.

The LicenseGrant__c object

Salesforce owns the order details on it; Oclavex owns the write-back fields.

Write-back fields (Oclavex-owned — leave these to the connector):

Field	Type	Written	Notes
Status__c	Picklist	now	The entitlement’s current lifecycle status. Default Pending.
MonetizeItEntitlementId__c	Text(64)	now	The link back to the entitlement; the same value on every write.
ActivatedAt__c	DateTime	later	Reserved for the usage release.
LastUsageAt__c	DateTime	later	Reserved for the usage release.
SeatsUsed__c	Number(8,0)	later	Reserved for the usage release.
UsageJson__c	Long Text Area	later	Reserved for the usage release.

Order fields (Salesforce-owned — your team maintains these):

The setup guide’s step 2 is the authoritative schema — it is what a Salesforce admin builds the object from. This table summarises it.

Field	Type	Required	Notes
Name	Auto Number / Text	Yes	Display name.
OrderId__c	Master-Detail(Order)	Yes	The parent order — its activation gates the entitlement.
StartDate__c	Date/Time	No	Validated TODAY()-1 ≤ StartDate__c. If empty, the order’s effective date is used. A plain Date field loses the time.
EndDate__c	Date/Time	No	Validated EndDate__c ≥ StartDate__c. Empty means perpetual.
Quantity__c	Number(18,0)	Yes	Seats. Rounded down, minimum 1.
ProductId__c / ProductCode__c	Text(64)	One required	Product reference; ProductCode__c wins if both are set.
UsagePlan__c	Picklist	No	Names the Oclavex usage plan (tier) this grant buys — see Choosing the tier below.
SubscriptionId__c	Text(64)	No	Salesforce CPQ subscriptions only.

Choosing the tier

Salesforce has no native concept of a usage tier, so there are two ways to say which one a grant buys. Both are supported, and the explicit field wins.

Pick it on the grant. Add a UsagePlan__c picklist to License Grant whose values are your Oclavex plan names, and the entitlement is created on that plan. Leave the picklist unrestricted — plan names are yours, not Oclavex’s.

Or derive it from the SKU. If you sell one product per tier, ask Oclavex to map product codes to plan names instead and leave UsagePlan__c off entirely. There is deliberately no fallback that treats a product code as a plan name: a code absent from the map yields no plan rather than a guessed tier, so nobody is silently placed on a tier no one named.

If neither yields a plan — or the name matches nothing on the product — the entitlement is still created and keeps its offer’s own feature values. A typo in a picklist never blocks a license; it is logged, and you can apply the plan by hand afterwards.

Oclavex owns the tier from then on. UsagePlan__c is read only when the entitlement is first created. Editing it later moves nothing, by design: an upgrade applied in Oclavex, or a promotional override, must not be silently reverted by an unrelated edit in Salesforce.

Deleting records

Deleting a License Grant cancels its entitlement — the license stops working. Deleting an Account or Contact marks the matching organization or user deleted. Salesforce keeps deleted records in the recycle bin, and a delete change event carries no field values, so the sync acts on the record’s identity alone.

Change Data Capture

Inbound sync uses Salesforce Change Data Capture. In Setup → Change Data Capture, enable change events for the four synced entities: Account, Contact, Order and License Grant. An entity that isn’t enabled never syncs — the connector’s health view shows the affected feed as degraded so the gap is visible rather than silent.

The connected app

Oclavex authenticates server-to-server with the OAuth client_credentials flow:

• Create a connected app enabled for the client-credentials flow.
• Assign an Execution User. Its profile and permission sets decide what the integration can do: Read on Account, Contact, Order; Read/Edit on LicenseGrant__c; nothing broader.
• Keep OAuth scopes minimal — api is enough; avoid broad scopes such as full and web.
• Note the authority for the environment — https://login.salesforce.com for a production org, https://test.salesforce.com for a sandbox (or your My Domain URL).

Connect it in Oclavex

Administrator only.

1. Register the connector — its kind (Salesforce), the org’s login authority, and the connected app’s client id and secret. The secret is encrypted at rest on write and is never returned by any API response; what you get back is the connector record with an opaque credential reference.
2. Probe it. The probe performs a live sign-in against your org, records the org’s id, and moves the connector to healthy — which is also what switches the inbound event feeds on. A failed probe leaves the connector degraded with the org’s error code, so a mistyped secret is visible immediately rather than as a silent dead feed.
3. The health status — pending → healthy → revoked, dropping to degraded when checks fail — stays visible in the connector workbench, where you can re-probe, rotate or revoke at any time. A connector can also be disabled: a reversible pause — inbound streams stop and outbound writes wait in a queue — after which re-enabling returns it to pending until the next successful probe marks it healthy again.

Rotating credentials replaces the stored pair and takes effect on the next call — rotate, then probe to confirm the new pair works. Revoking deletes the stored secret and stops both directions of sync.

Data & privacy

• Inbound contact data is personal data. Names and emails from synced contacts become Oclavex users, and they participate fully in data-subject requests — an erasure request suppresses further sync for that person and redacts them from the connector’s own records.
• Outbound carries no personal data. The write-back is only the entitlement’s status and id — no names, emails or usage.
• Secrets are encrypted at rest. The client secret is stored encrypted, never echoed back, and a rotation deletes the old secret immediately.
• One account, one org. A connector binds exactly one Oclavex account to one Salesforce org; a request for another account’s connector returns not found.
• Hardened traffic. Calls to Salesforce use TLS 1.2 or higher, reach only Salesforce domains, and never follow a redirect to another host.
• Audited. Every registration, rotation, revoke and probe is recorded — who, when, what and the result.

Not yet available

• Usage projection onto the Salesforce record (the reserved fields above) — planned for a later release.
• Creating LicenseGrant__c records from Oclavex. Salesforce is the creator today (the grant lives under an Order); entitlements born in Oclavex are not pushed out as new records.

If either of those blocks you, the Zapier and Stripe patterns — webhooks plus the REST API — remain fully supported alongside the connector.