How the Dynamics 365 connector works
activeThe 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
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.
| Part | What it does | Runs |
|---|---|---|
| ChangeCapturePlugin | Turns a change on a captured table into Identify and Track calls and sends them | Background step after each save, one step per table and action, registered by Apply |
| SettingsPlugin | Runs Test connection and Apply (registers the capture steps) | Immediately when the admin presses the button |
| HeartbeatPlugin | Sends waiting calls in batches, deletes old outbox rows, resumes a stalled backfill | Every 2 minutes (heartbeat workflow), on Drain now, and when a capture leaves calls waiting |
| BackfillPlugin | Loads existing records as historical events | When a backfill job is started |
bnb_settings | Connection values, on/off switches, service user | One row |
bnb_tableconfig | Captured tables: alias, columns, traits, identity path, actions | One row per table |
bnb_eventrule | Admin-defined named events | One row per rule |
bnb_outbox | Calls waiting to be sent, failures, and a 7-day record of what was sent | One row per call |
bnb_backfilljob, bnb_heartbeat | Backfill progress; the retry loop's clock | |
| Admin page | Set 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 action | Events, in send order | Fires when |
|---|---|---|
| Create a record | identify (Contact and Lead only), then <alias>_created | Always, for a ticked table |
| Update a record | identify (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_changed | Status or status reason changed (this includes Deactivate, Activate, Set State) | |
<alias>_assigned | Owner changed (this includes Assign) | |
<alias>_stage_changed | The business process stage moved | |
<alias>_updated | Any other mapped column changed; one event lists them all in changed_fields | |
| rule events | A rule's column moved from its from value to its to value | |
| Delete a record | <alias>_deleted | Always |
| Merge (Contact, Account, Lead, Case) | identify linking the two people, then <alias>_merged | Always; the Identify is sent for Contacts, and for Leads whose survivor has a contact |
| Qualify a lead | identify (lead linked to the new contact), then lead_qualified | Always |
| Close as won / lost (opportunity) | opportunity_won / opportunity_lost | Always |
| Win / Close / Revise (quote) | quote_won / quote_closed / quote_revised | Always |
| Resolve a case | case_resolved | Always |
| Associate / Disassociate on a chosen N:N relationship | <alias>_linked / <alias>_unlinked | The 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.
| Event | Extra properties |
|---|---|
<alias>_created | Every mapped column that has a value, plus status, status_code, state, state_code |
<alias>_updated | Only the columns that changed, and changed_fields (their names) |
<alias>_status_changed | previous_status, to_status, previous_state, to_state (labels), each with a _code integer |
<alias>_assigned | previous_owner_id, to_owner_id, owner_type (user or team) |
<alias>_stage_changed | previous_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>_merged | surviving_id, merged_id |
<alias>_linked, <alias>_unlinked | relationship, related_id, related_type |
Business events
Fixed names.
| Event | Extra properties |
|---|---|
lead_qualified | created_contact_id, created_account_id, created_opportunity_id |
opportunity_won, opportunity_lost | actual_revenue, currency_code, close_date, close_reason + close_reason_code, competitor_id (lost) |
quote_won, quote_closed | close_reason + close_reason_code, total_amount, currency_code, close_date |
quote_revised | revised_from_quote_id, revision_number |
case_resolved | resolution_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_valueand 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.
| Record | userId | anonymousId | Effect in Binoban |
|---|---|---|---|
| Contact | Contact GUID (or the userId source column) | Contact GUID | The person's profile |
| Lead, not qualified | none | lead:<lead id> | An anonymous profile for the lead |
| Lead with an existing contact (parentcontactid) | That contact's userId | lead:<lead id> | Lead activity lands on the person |
| Lead being qualified | The new contact's userId | lead:<lead id> | One Identify carries both, so Binoban merges the lead's history into the person |
| Account | Its primary contact's userId, if set | account:<account id> | Account events land on the primary contact |
| Contact merge | Survivor's userId | Merged contact's GUID | The two profiles merge |
| Any other record | The person found through its identity path | <alias>:<record id> when no person is found | Event 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:
| Table | Lookups followed |
|---|---|
| Quote, Order, Invoice | Customer |
| Case | Primary contact, then customer |
| Opportunity | Contact, then originating lead, then customer |
| Activities | Regarding, 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:
| Property | Meaning |
|---|---|
record_id, entity | The CRM record and its table |
event_id | Stable ID: the same change always gets the same event_id, so retries can be de-duplicated |
crm_message, crm_org | The CRM action (Create, Update, Win…) and organization |
actor_user_id, actor_type | Who made the change: user, workflow (automation or another plug-in) or system (non-interactive account) |
owner_id, business_unit_id | The record's owner and business unit |
contact_id, lead_id, account_id | The person and account the event was resolved to, where known |
person_unresolved | true when no person could be found |
historical | true on backfilled events |
schema_version | 1; 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 column | Sent as |
|---|---|
| Lookup | <column>_id, <column>_type, and <column>_name when known |
| Option set, status | The label in the org's base language as <column>, the number as <column>_code; optional second language as <column>_label_<lcid> |
| Multi-select | A list of labels and a list of numbers |
| Money | A number, with currency_code (ISO) on the event |
| Date and time | ISO 8601, UTC |
| Yes/No | true / false |
| Text | Up 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.
| Trait | From | Rule |
|---|---|---|
firstName, lastName | First and last name | Dropped if over 32 characters |
email | Lower-cased; dropped if over 64 characters | |
phone | Mobile phone, else business phone | Written as E.164 using the default country code set on Connect, for example +14155550100 |
gender | Gender (Contact) | MALE / FEMALE; other values not sent |
company, jobTitle | Parent account name (Contact) or company name (Lead); job title | Dropped if over 64 characters |
emailOptIn | Not Do not allow emails and not Do not allow bulk emails | See the opt-in rule |
smsOptIn | Not Do not send marketing materials | See the opt-in rule |
| custom traits | Columns ticked as Trait under Review columns | Converted 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
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 response | What the connector does |
|---|---|
| 200 | Marked 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 error | Retried 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>_createdevent (plus an Identify for Contacts and Leads), with its original created on as the timestamp andhistorical: 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_deletedbut 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.