Salesforce setup guide

Set up your org in eight steps; the last proves the sync works. The Salesforce integration page covers what the connector does and how to register it in Oclavex; this page covers the org itself.

Set aside about an hour. You need the System Administrator profile (or equivalent) and an edition with API access — Enterprise, Unlimited, Developer, or a sandbox of one. Professional Edition needs the API add-on.

Ask Oclavex for the package first

Everything on this page can be deployed as metadata rather than clicked. If you’d rather not build it by hand, ask Oclavex for the unmanaged package: it carries the custom object, all its fields, the Change Data Capture channel members and two permission sets. Deploying it replaces steps 2, 3 and 5. The clicked route is documented here because it’s what most admins use, and because a few of the clicks are easy to get wrong.

What you are building

Oclavex reads four objects from your org and writes back to one:

Object	Direction	Purpose
Account	read	becomes an organization in Oclavex
Contact	read	becomes a user under that organization
Order	read	its activation is what releases a license
License Grant (custom)	read and write	the license itself; Oclavex writes status back onto it

The one object you have to create is License Grant. The other three are standard.

Step 1 — Enable Orders

Setup → Order Settings → enable Orders.

Orders are the gate: Oclavex will not create a license until the order carrying it is Activated. That is deliberate — it means a quote or a draft order never provisions anything.

Salesforce refuses to activate an order that has no product on it:

FAILED_ACTIVATION: An order must have at least one product.

So you also need a product and a price book entry before you can activate anything. If your org already sells through Orders you have these. If it doesn’t, step 6 walks through creating them for the test.

Step 2 — Create the License Grant object

Setup → Object Manager → Create → Custom Object.

• Label: License Grant
• Object Name: LicenseGrant
• Allow Reports and Activities as you prefer — Oclavex doesn’t care
• Tick “Allow Change Data Capture” if the checkbox is offered

Then add the fields. Create each field with exactly the type shown.

Fields Oclavex reads — your team fills these in:

Field label	API name	Type	Required	Notes
Order	OrderId__c	Master-Detail(Order)	Yes	The parent order whose activation releases the license
Product Code	ProductCode__c	Text(64)	One of these two	Must exactly equal the Oclavex offer name — see the warning below
Product Id	ProductId__c	Text(64)	One of these two	Only read when Product Code is blank
Quantity	Quantity__c	Number(18, 0)	Yes	Seats. Rounded down, minimum 1
Start Date	StartDate__c	Date/Time	No	Falls back to the order’s effective date. A plain Date field loses the time
End Date	EndDate__c	Date/Time	No	Empty means perpetual
Subscription Id	SubscriptionId__c	Text(64)	No	For CPQ subscriptions
Usage Plan	UsagePlan__c	Picklist, unrestricted	No	The tier this grant buys — see step 4

Fields Oclavex writes — leave these to the connector:

Field label	API name	Type	Notes
Status	Status__c	Picklist	Values exactly: Pending, Trialing, Active, Paused, Expired, Canceled, PastDue. Default Pending
Oclavex Entitlement Id	MonetizeItEntitlementId__c	Text(36 or more)	A GUID. Set once, then left alone

Two spellings that break the write-back

Canceled has one l, and PastDue is one word, no space. Salesforce picklist values are matched literally — Cancelled or Past Due means the write-back silently fails to match and the status never updates.

ProductCode__c is a join key, not a label

Its value has to match the name of the Oclavex entitlement offer you want instantiated, character for character. If it doesn’t, the license is never created and the event is rejected with Offer '<value>' not found. Agree the exact strings with whoever administers your Oclavex catalog before sales starts entering orders.

Step 3 — Add two Contact fields

These look optional. They are not.

Setup → Object Manager → Contact → Fields & Relationships → New:

Field label	API name	Type	Values
Tenduke Organization Role	TendukeOrganizationRole__c	Picklist	License manager, Member
Tenduke Contact Language	TendukeContactLanguage__c	Text(10)	e.g. en, nl

License manager becomes an organization administrator in Oclavex; Member becomes an ordinary member.

Create these even if you never populate them

Oclavex looks up the buying contact with a SOQL query that selects these fields by name. If they don’t exist, that query fails with INVALID_FIELD and every license fails — not only the ones that would have used a role. Two empty fields cost nothing; their absence blocks every license.

Step 4 — Decide how the tier is chosen

Skip this step if all your customers get the same entitlement.

Salesforce has no native concept of a usage tier, so there are two ways to tell Oclavex which one a grant buys.

Option A — pick it on the grant. Populate the UsagePlan__c picklist you created in step 2 with your Oclavex plan names (basic, professional, enterprise, or whatever yours are called) and set it per grant. Leave the picklist unrestricted: plan names belong to your Oclavex catalog, and a restricted picklist means every new tier needs a schema change.

Option B — derive it from the SKU. If you already sell one product per tier, give Oclavex your product-code-to-plan mapping instead and leave UsagePlan__c off the object entirely.

If you do both, the picklist wins — a value an admin chose beats a convention configured once. If neither yields a plan, the license is still created and keeps the offer’s own feature values; a typo never blocks a license.

Oclavex owns the tier after creation

UsagePlan__c is read only when the license is first created. Editing it later moves nothing. That’s deliberate: an upgrade applied in Oclavex, or a promotional override, must not be quietly undone by an unrelated edit in Salesforce. Change tiers in Oclavex, or cancel and re-issue.

Step 5 — Turn on Change Data Capture

Setup → Change Data Capture. Move these four into Selected Entities:

• Account
• Contact
• Order
• License Grant

An entity you don’t select never syncs. Nothing errors — so re-read this list before you finish. Oclavex’s connector health view shows each feed separately, so a missing one shows up as degraded rather than as silence.

Change events expire after 72 hours

Salesforce keeps them for three days. If the connector is disconnected for longer than that, the events in the gap are gone and the affected records need touching again to re-emit. Relevant if you disable a connector over a long holiday.

Step 6 — Create the External Client App

This is what lets Oclavex authenticate as a service, with no browser and no user session.

Setup → External Client Apps → New. (Salesforce’s older object is called a Connected App; Setup search surfaces both. Use External Client App.)

1. Name it something recognisable — “Oclavex Integration”.
2. Enable OAuth, and enable the Client Credentials flow.
3. Scopes: api is sufficient. refresh_token is not needed for this flow.
4. Set a Run-As user. This is the user Oclavex acts as, so it needs API Enabled and the permission set from step 7.
5. Save, then copy the Consumer Key and Consumer Secret.

Three traps in this one form

• The Run-As field wants a username, even though the placeholder text asks for an email address. They’re often the same string; when they differ, the save fails without explaining why.
• The UI has been observed to silently not persist the client-credentials policy. Re-open the app after saving and confirm it’s still enabled before moving on.
• Give the Run-As user a license and profile that won’t be deactivated when someone leaves. A named individual’s account is a poor choice; an integration user is the right one.

Send the Consumer Key, the Consumer Secret and your My Domain URL (https://yourcompany.my.salesforce.com) to whoever registers the connector in Oclavex. The secret is stored encrypted and never echoed back.

Step 7 — Create and assign a permission set

Setup → Permission Sets → New — “Oclavex Integration”. Grant:

On	Permission
Account, Contact, Order	Read
License Grant	Read, Edit
Every field in step 2’s tables	Field-level Read
Status__c, MonetizeItEntitlementId__c	Field-level Edit as well

Also confirm the Run-As user’s sharing reaches the records you expect. Oclavex resolves a buying contact by querying the order’s account, so a Run-As user who cannot see that account sees no contact either.

Assign the permission set to the Run-As user.

Deployed fields arrive invisible

If you deploy the fields as metadata instead of clicking them, they are created with field-level security off. A deployment that reports complete success can still leave most fields unreadable until this permission set is assigned. If the sync starts and fields look empty, check field-level security before anything else.

Step 8 — Prove it works

Register the connector in Oclavex (how), then run one license through end to end. Do this in a sandbox first if you have one.

1. Create an Account. Within a few seconds it should appear as an organization in Oclavex. This alone proves authentication, Change Data Capture and the network path all work — if it fails, nothing later will succeed.
2. Create a Contact on that account, with TendukeOrganizationRole__c set to License manager. It should appear as a user under the organization, as an administrator.
3. Create a draft Order for the account. Set its Price Book, add an Order Product, then set the status to Activated. (Activation fails without a product — see step 1.)
4. Create a License Grant on that order: ProductCode__c matching an Oclavex offer, Quantity__c set, and UsagePlan__c if you’re using option A.
5. Check both sides. Oclavex should show a new entitlement for the account, on the tier you named. Back in Salesforce, the grant’s Status__c should have become Active and MonetizeItEntitlementId__c should now hold a GUID — that’s Oclavex writing back, which confirms the loop closes in both directions.

Steps 3 and 4 work in either sequence: a grant created first waits and is released on activation, so sales can build the order in whatever sequence suits them.

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 in Oclavex.

Salesforce change events for a delete carry no field values at all, only the record’s identity, so the sync acts on identity alone. A deleted record also cannot be written back to, so Oclavex stops trying rather than retrying forever.

When something doesn’t sync

Work down this list in order — it’s roughly most to least common.

What you see	Almost always
Nothing syncs at all, for any object	The entity isn’t selected in Change Data Capture (step 5), or the permission set isn’t assigned to the Run-As user (step 7)
Every license fails, accounts and contacts are fine	The two Contact fields from step 3 are missing
One license fails with an offer error	ProductCode__c doesn’t match an Oclavex offer name exactly
Licenses never appear, orders look fine	The order isn’t Activated — a draft holds its grants deliberately
Fields sync as empty	Field-level security on deployed fields (step 7)
Status__c never updates	The picklist values don’t match exactly — check Canceled and PastDue
Authentication fails immediately	The client-credentials policy didn’t persist, or the Run-As user lacks API Enabled (step 6)
Everything worked, then stopped for a few days’ worth of records	Change events expired after 72 hours (step 5)

Oclavex keeps a dead-letter queue of events it couldn’t process, with the reason for each. Ask Oclavex for the dead-letter entry when a record hasn’t arrived — it usually names the cause directly.

What Oclavex never does to your org

• It never writes to Account, Contact or Order — read-only, always.
• On License Grant it writes only Status__c and MonetizeItEntitlementId__c. Every other field is yours.
• It never deletes anything.
• It acts only as the Run-As user, so your sharing rules and field-level security apply to it exactly as they do to a person.

See Data & privacy for what’s stored on the Oclavex side and for how long.