Skip to main content
platform

How the Dynamics 365 connector works

active
Audience: developerUpdated 2026-10-26

The connector runs entirely inside Dynamics 365 CE on-premises (9.0/9.1). After a change to a captured table is saved, a background plug-in turns it into Identify and Track calls and sends them to the Tracking API. If Binoban can't be reached, the calls wait in CRM and are retried. Saving a record is never slowed or blocked. To install it, see Deploy the Dynamics 365 connector.

At a glance​

How a CRM change reaches BinobanStep 1: a record is saved in a ticked Dynamics 365 table. Step 2: the connector's capture step builds Identify and Track calls in the background. Step 3: the calls are sent to the Binoban Tracking API. If Binoban can't be reached, the calls wait in the outbox inside CRM, and the heartbeat retries them every 2 minutes.INSIDE DYNAMICS 365A record is savedin a ticked CRM table1Capture stepbuilds Identify + Trackin the background2Binobanreceives the eventsTracking API3Outboxwaits in CRM, in ordersent nowBinoban unreachableretried every 2 min
In Dynamics 365ConnectorWaiting, retriedBinoban

The capture step sends each event straight to Binoban when it can. When it can't (Binoban is down, sending is paused, or the record already has calls waiting), the call waits in the outbox and the heartbeat sends it later. The admin page decides which tables, columns and actions are captured.

The parts​

Everything is installed in CRM: one plug-in assembly, six connector tables and an admin page. Nothing runs outside CRM and nothing changes in Binoban.

PartWhat it doesRuns
ChangeCapturePluginTurns a change on a captured table into Identify and Track calls and sends themBackground step after each save, one step per table and action, registered by Apply
SettingsPluginRuns Test connection and Apply (registers the capture steps)Immediately when the admin presses the button
HeartbeatPluginSends waiting calls in batches, deletes old outbox rows, resumes a stalled backfillEvery 2 minutes (heartbeat workflow), on Drain now, and when a capture leaves calls waiting
BackfillPluginLoads existing records as historical eventsWhen a backfill job is started
bnb_settingsConnection values, on/off switches, service userOne row
bnb_tableconfigCaptured tables: alias, columns, traits, identity path, actionsOne row per table
bnb_eventruleAdmin-defined named eventsOne row per rule
bnb_outboxCalls waiting to be sent, failures, and a 7-day record of what was sentOne row per call
bnb_backfilljob, bnb_heartbeatBackfill progress; the retry loop's clock
Admin pageSet up, Connect, Tables, Event rules, Backfill, Health (with Diagnose), Outbox/WebResources/bnb_/admin/index.html

Capture steps run asynchronously after the save commits (PostOperation, background), so a user's save takes no longer with the connector on. They run as the service user; changes made by that user are never captured, which prevents loops.

When events fire​

An event fires when a user, a workflow or an integration saves a change on a ticked table, for an action ticked on that table, after the save has committed. It usually reaches Binoban within seconds, or as soon as Binoban is reachable again.

<alias> is the table's event alias (Tables tab): the logical name without its publisher prefix by default, so new_contract becomes contract, incident becomes case and phonecall becomes phone_call.

CRM actionEvents, in send orderFires when
Create a recordidentify (Contact and Lead only), then <alias>_createdAlways, for a ticked table
Update a recordidentify (Contact/Lead)A column that feeds a trait changed: name, email, phone, job title, company, opt-out flags, or a column ticked as a trait
<alias>_status_changedStatus or status reason changed (this includes Deactivate, Activate, Set State)
<alias>_assignedOwner changed (this includes Assign)
<alias>_stage_changedThe business process stage moved
<alias>_updatedAny other mapped column changed; one event lists them all in changed_fields
rule eventsA rule's column moved from its from value to its to value
Delete a record<alias>_deletedAlways
Merge (Contact, Account, Lead, Case)identify linking the two people, then <alias>_mergedAlways; the Identify is sent for Contacts, and for Leads whose survivor has a contact
Qualify a leadidentify (lead linked to the new contact), then lead_qualifiedAlways
Close as won / lost (opportunity)opportunity_won / opportunity_lostAlways
Win / Close / Revise (quote)quote_won / quote_closed / quote_revisedAlways
Resolve a casecase_resolvedAlways
Associate / Disassociate on a chosen N:N relationship<alias>_linked / <alias>_unlinkedThe relationship is ticked on the table

Only real changes count. An update compares the new values with the record as it was. If nothing that is sent actually changed, as with an autosave or a save that rewrites the same values, no event fires. One save can produce several events: a status change, an owner change and two edited fields give _status_changed, _assigned and one _updated.

Nothing fires when: the connector is off; the change was made by the connector's service user; the table or action isn't ticked; only unmapped or excluded columns changed; the change came from another plug-in more than 8 levels deep; or the record is in one of the connector's own bnb_ tables.

Event catalogue​

Every Track event also carries the common properties listed under What an event carries. The tables below list what each event adds.

Generic events​

Fired for every ticked table.

EventExtra properties
<alias>_createdEvery mapped column that has a value, plus status, status_code, state, state_code
<alias>_updatedOnly the columns that changed, and changed_fields (their names)
<alias>_status_changedprevious_status, to_status, previous_state, to_state (labels), each with a _code integer
<alias>_assignedprevious_owner_id, to_owner_id, owner_type (user or team)
<alias>_stage_changedprevious_stage, to_stage, process_name, traversed_path (stage names)
<alias>_deleted<lookup>_id and <lookup>_type for each lookup the record had; no other values
<alias>_mergedsurviving_id, merged_id
<alias>_linked, <alias>_unlinkedrelationship, related_id, related_type

Business events​

Fixed names.

EventExtra properties
lead_qualifiedcreated_contact_id, created_account_id, created_opportunity_id
opportunity_won, opportunity_lostactual_revenue, currency_code, close_date, close_reason + close_reason_code, competitor_id (lost)
quote_won, quote_closedclose_reason + close_reason_code, total_amount, currency_code, close_date
quote_revisedrevised_from_quote_id, revision_number
case_resolvedresolution_type + resolution_type_code, time_spent_minutes

Rule events​

Defined on the Event rules tab: a table, a column, an optional from value, a to value and an event name, for example invoice · contract status · any → Signed = agreement_signed.

  • A rule fires in addition to the generic event, so nothing is lost if a rule is wrong.
  • It carries rule_attribute, from_value, to_value and the column's own value.
  • On a Create, a rule fires only when its from is "any" and the new value matches to.
  • Option values match by number or label; yes/no columns by true/false/yes/no/1/0.

Identify​

Identify calls (Contact and Lead) update the person's profile traits. In Binoban they appear as bb_identify events on the profile.

Who an event belongs to​

One person in CRM is one profile in Binoban, and the Contact is the person. By default the Contact's GUID is the userId. On the Connect tab, userId source can name a Contact column instead (for example a customer code), so CRM profiles match the IDs your website and apps already send. See Identity strategy.

RecorduserIdanonymousIdEffect in Binoban
ContactContact GUID (or the userId source column)Contact GUIDThe person's profile
Lead, not qualifiednonelead:<lead id>An anonymous profile for the lead
Lead with an existing contact (parentcontactid)That contact's userIdlead:<lead id>Lead activity lands on the person
Lead being qualifiedThe new contact's userIdlead:<lead id>One Identify carries both, so Binoban merges the lead's history into the person
AccountIts primary contact's userId, if setaccount:<account id>Account events land on the primary contact
Contact mergeSurvivor's userIdMerged contact's GUIDThe two profiles merge
Any other recordThe person found through its identity path<alias>:<record id> when no person is foundEvent lands on the person, or on a record-scoped profile marked person_unresolved: true

Identity path​

For other tables the connector follows the lookups set on the table, in order, at most two lookups deep, until it reaches a Contact, Lead or Account. The defaults are:

TableLookups followed
Quote, Order, InvoiceCustomer
CasePrimary contact, then customer
OpportunityContact, then originating lead, then customer
ActivitiesRegarding, then the To / Customer / Required attendee parties

An invoice whose customer is a contact lands on that contact's profile. A custom table pointing at an opportunity reaches the opportunity's contact in two steps.

What an event carries​

Common properties​

On every Track event:

PropertyMeaning
record_id, entityThe CRM record and its table
event_idStable ID: the same change always gets the same event_id, so retries can be de-duplicated
crm_message, crm_orgThe CRM action (Create, Update, Win…) and organization
actor_user_id, actor_typeWho made the change: user, workflow (automation or another plug-in) or system (non-interactive account)
owner_id, business_unit_idThe record's owner and business unit
contact_id, lead_id, account_idThe person and account the event was resolved to, where known
person_unresolvedtrue when no person could be found
historicaltrue on backfilled events
schema_version1; it changes only with breaking changes

The event's timestamp is the CRM time of the change: the record's modified on (created on for a create), or the time of the action for deletes and links. It is never the send time, so events delayed by an outage keep their real time and order in Binoban.

Column values​

CRM columnSent as
Lookup<column>_id, <column>_type, and <column>_name when known
Option set, statusThe label in the org's base language as <column>, the number as <column>_code; optional second language as <column>_label_<lcid>
Multi-selectA list of labels and a list of numbers
MoneyA number, with currency_code (ISO) on the event
Date and timeISO 8601, UTC
Yes/Notrue / false
TextUp to 2,048 characters

Property names are the column's logical name. Names over 64 characters are shortened with a short hash suffix so Binoban accepts them; see Limits & validation.

Traits​

Sent on Identify for Contacts and Leads.

TraitFromRule
firstName, lastNameFirst and last nameDropped if over 32 characters
emailEmailLower-cased; dropped if over 64 characters
phoneMobile phone, else business phoneWritten as E.164 using the default country code set on Connect, for example +14155550100
genderGender (Contact)MALE / FEMALE; other values not sent
company, jobTitleParent account name (Contact) or company name (Lead); job titleDropped if over 64 characters
emailOptInNot Do not allow emails and not Do not allow bulk emailsSee the opt-in rule
smsOptInNot Do not send marketing materialsSee the opt-in rule
custom traitsColumns ticked as Trait under Review columnsConverted like properties; Birthday becomes birthday

Opt-in rule: the connector never opts a person in by itself. On create it sends an opt-in only when it is false, since Binoban treats unset as opted in. On update it sends one only when the CRM flag itself changed.

Size guard​

Binoban accepts at most 8,000 bytes per call. A larger event drops properties in this order: long texts, _name duplicates of lookups, lists, then the largest remaining non-core values. It then gets truncated: true and dropped_fields. If it still can't fit with its identity and core properties, it goes to the outbox as a dead-letter instead of being lost silently.

Delivery​

What happens to each callEach call is checked against Binoban's rules. A call that fails becomes a dead-letter. A call that passes is sent to Binoban unless sending is paused or the record already has calls waiting, in which case it waits in the outbox. HTTP 200 marks it sent; another 4xx makes it a dead-letter; a 5xx, timeout, 401 or 404 puts it in the outbox, and the heartbeat sends it again every 2 minutes.Dead-letterkept 30 daysRetry re-sends itCheck the callnames · IDs · values8,000 bytes at mostSend to Binobanone call30-second timeoutSentHTTP 200kept 7 daysOutbox · pendingwaits in record orderfails a ruleother 4xxpasses2005xx · timeout · 401 / 404heartbeat · 2 minpaused, or calls waiting
SentWaiting, retriedDead-letterBinoban

Each call is checked against Binoban's rules first (names, IDs, values, 8,000 bytes); a call that can't pass goes straight to dead-letter. It is sent at once unless sending is paused or the same record already has calls waiting, in which case it waits in the outbox. Delivery is at least once: no change is dropped while Binoban is down, and a retry after a timeout can arrive twice, with the same event_id.

Binoban responseWhat the connector does
200Marked Sent. The outbox row is kept 7 days as a record of exactly what was sent
401 or 404 (wrong key, unknown source)Pauses sending and shows a banner with the reason. Changes keep queuing. A passing Test connection lifts the pause
413 (too large)Shrinks the event further and resends; if it still doesn't fit, dead-letter
Other 4xx (Binoban rejected the content)Dead-letter with Binoban's error code; never retried. In a batch, the batch is split until the bad call is alone, and the rest are sent
5xx, 429, timeout, DNS or certificate errorRetried after 1, 2, 5, 15, 30 and 60 minutes, then hourly; Binoban's Retry-After is honoured. After 24 hours it becomes a dead-letter

Direct sends use a 30-second timeout.

Order​

Calls for one record go out in the order the changes happened: once a record has a call waiting, its later calls queue behind it rather than overtaking. In each batch, Identify calls go before Track calls so the profile exists first. Different records don't hold each other up.

When waiting calls are sent​

  • The heartbeat every 2 minutes, in batches of up to 100 calls and 800,000 bytes.
  • After any successful direct send, up to 50 due calls.
  • Drain now on the Health tab.
  • Automatically, when a capture leaves calls waiting and the heartbeat has been quiet for 10 minutes. This also restarts the heartbeat.

Housekeeping​

Sent rows are deleted after 7 days and dead-letters after 30. A dead-letter can be sent again with Retry on the Outbox tab once its cause is fixed.

Backfill​

A backfill loads records that existed before the connector, once per table. Start it on the Backfill tab, optionally from a date.

  • Each record becomes one <alias>_created event (plus an Identify for Contacts and Leads), with its original created on as the timestamp and historical: true, so journeys in Binoban can tell it apart from live activity.
  • Records load 500 at a time in creation order, into the same outbox, so they share retries and ordering with live events.
  • Contacts run first, then Leads, then the other tables, so profiles exist before their activity arrives.
  • A job resumes where it stopped. If it stalls, the heartbeat picks it up again after 3 minutes.

Backfilled events describe each record as it is now, under a historical create date. Changes between its creation and today are not replayed.

What is never sent​

The connector sends the least data by default. These columns start excluded, and an admin can opt one in only by ticking it under Review columns:

  • multi-line text (descriptions, notes), files and images;
  • columns under field-level security;
  • columns whose names suggest personal or secret data: passwords and tokens, national ID and passport numbers, bank and card fields, birth dates;
  • system columns (modified by, version number, time-zone codes and similar).

Other rules:

  • Email addresses and phone numbers travel only as Identify traits, never as Track properties.
  • Deletes carry only IDs, never the deleted record's values.
  • The API key is stored under field-level security, readable only by the connector and its administrators. It is never written to the outbox, trace log or error messages.
  • Erasing a person in Binoban is a Binoban-side action. Deleting a Contact sends contact_deleted but doesn't erase the profile.

Limits and known gaps​

  • Versions: Dynamics 365 CE on-premises 9.0 and 9.1 only. Dynamics 365 online (Dataverse) and CRM 2016 are not supported.
  • No time-based events: "overdue", "expiring" or "no activity for 30 days" need a scheduler and are not in this version.
  • One direction: nothing is written back from Binoban into CRM.
  • Accounts have no group call in Binoban; their events land on the primary contact, or on account:<id>.
  • Duplicates are possible after a timeout, because Binoban doesn't yet de-duplicate by event_id.
  • Settings take up to 5 minutes to reach the plug-in, because it caches them.
  • The heartbeat workflow is created by hand. If Dynamics stops it, retries still go out with the next CRM change or Drain now.
  • Throughput: each call is one CRM write into the outbox, so large backfills take time.