ClearView CRM Connector (Technical Reference)

Overview

The ClearView CRM connector pulls data from the ClearView CRM API into your Bytespree data lake.

Key characteristics:

API base: https://api.clearviewcrm.com/{VERSION}/api/proc
Default API VERSION: pm02prod (overridable via config).
Authentication: HTTP Basic (username & password) tied to a ClearView dsource (data source).
Payloads/Responses: XML via datafile requests; action get_table_pg.
All columns are extracted as strings.
The connector treats TCN as the row uniqueness field.

Setup & Configuration

Provide the following settings:

{ "dsource": "<your ClearView dsource>", "username": "<api username>", "password": "<api password>", "api_version": "pm02prod" }

Sync Behavior

Initial sync start: 01/01/2000 12:00:00 am.
Window size: 7 days per request window.
Pagination:
1. A header call returns REQUESTID and TOTAL_PAGES for a date window.
2. Page calls use that REQUESTID plus a PAGE index (1..TOTAL_PAGES).
Page size: 50 records per page.
Change filtering: Request XML uses <CHANGE_START> and <CHANGE_END> to limit rows by the API's change tracking.
No saved bookmark/state: Each run iterates windows from the initial sync date up to the time of execution. Downstream deduplication should rely on TCN.

Error Handling & Retries

Retries with exponential backoff (up to 5 attempts) for header and page fetches.
XML is validated; any element containing ERROR triggers an exception and retry.
Non-mapped fields in API responses are ignored and logged; see Schema Handling.

Schema Handling

The connector uses a static table map (see below). Any field not listed for a table is not emitted (but a warning is logged).
Field names from XML are normalized by replacing . with _.
All fields are typed as strings in the current implementation.

Known Limitations / Notes

Because there is no incremental bookmark, a full windowed backfill runs on each execution — potentially slow on large datasets.
Page size is fixed at 50; very large tables result in many page calls.
Some tables are wide (e.g., PAYMENT, PROSPECT, APPEALS, GIFT_VIEW), which can increase payload size and processing time.
Only the fields listed below are synced; new fields introduced by ClearView will be dropped until this connector’s schema map is updated.

API Request Shapes (for reference)

Header (window registration) request XML:

<?xml version="1.0" encoding="UTF-8"?> <XMLREQUEST> <RECORD> <TABLE>{TABLE_NAME}</TABLE> <PAGESIZE>{PAGE_SIZE}</PAGESIZE> <CHANGE_START>{MM/DD/YYYY HH:MI:SS am/pm}</CHANGE_START> <!-- optional --> <CHANGE_END>{MM/DD/YYYY HH:MI:SS am/pm}</CHANGE_END> <!-- optional --> </RECORD> </XMLREQUEST>

Page request XML:

<?xml version="1.0" encoding="UTF-8"?> <XMLREQUEST> <RECORD> <TABLE>{TABLE_NAME}</TABLE> <REQUESTID>{REQUEST_ID}</REQUESTID> <PAGE>{PAGE_NUMBER}</PAGE> </RECORD> </XMLREQUEST>

Field-Level Notes

Many tables include common audit fields: TENANT_ID, TCN, TIMESTAMP, UPDATE_DATE, USERID_ADD, USERID_CHANGE.
Address-like tables include standardized address components; event-related tables include start/end date+time split fields.