Provider Bulk Sync
Troubleshooting
This guide explains how the connector reports errors and how to use those errors to troubleshoot a run. The connector includes two applications, the Provider Bulk Sync API and the OneKey System API, which handle error logging differently. Errors are written in two places: data and job failures go back to Salesforce so they can be reviewed with the job, and both applications write runtime logs to Anypoint Platform for tracing the run.
Where Errors Are Logged
- Salesforce (Error Log Management). Records that fail to load, and job-level failures, are written back to Salesforce through the LSC log service and linked to the job's Integration Job Run record. All Salesforce error-log entries are written by the Provider Bulk Sync API, which owns the Salesforce connection. This is the primary place to see which records failed and why.
- Anypoint Platform logs. Both applications write runtime logs (
INFO,WARN, andDEBUG) to Anypoint Platform. Use these to trace the run itself, including connectivity, retries, and processing flow.
Use the Salesforce error log to answer "which records failed and why," and the Anypoint Platform logs to answer "what happened during the run."
How the Two Applications Log Errors
The two applications divide error logging along the same lines as the rest of their work: the System API owns the OneKey side, the Process API owns the Salesforce side.
- Provider Bulk Sync API (Process API). Owns all Salesforce error logging. It writes per-record
Errorentries when Salesforce rejects a record, and job-levelExceptionentries when a job fails. It also writes its own runtime logs to Anypoint Platform. - OneKey System API (System API). Does not write to Salesforce. When it hits a failure such as a OneKey connectivity error or a failure in the mapping layer, it logs the detail to Anypoint Platform at
ERRORlevel, publishes a failure status message to the status queue, and records the failure in its abort object store so in-flight processing can stop. The Process API consumes that status message and writes the correspondingExceptionentry to Salesforce Error Log Management on the System API's behalf.
Because of this, a failure that originates in the System API still appears in Salesforce Error Log Management under the same job, but the full technical detail (for example, the OneKey response or the mapping error) is in the System API's Anypoint Platform logs. When a job fails and the Salesforce entry doesn't have enough detail, check the System API logs in Anypoint Platform for the same job.
Reviewing Errors in Salesforce
Open Error Log Management in Salesforce from Admin Console > Error Log Management. To review the errors from a sync, filter by:
- View:
ErrorandException. AnErrorentry is a per-record data failure that the job records before moving on. AnExceptionentry is a fatal error that stops the job. - Error Source:
Provider Syncfor the bulk data sync, andProvider Codes Syncfor the Codes Job.
Error Log Fields
Each error entry captures the following fields.
| Field | Description |
|---|---|
errorType | Error for a per-record data failure, or Exception for a fatal, job-level failure. |
errorDateTime | When the error was recorded. |
jobRunReferenceRecord | The Salesforce record identifier of the job's Integration Job Run, which links the error to its job. |
errorMessage | A user-facing description of the failure. |
errorCode | The error code, described in the next section. |
callStack | The detailed error, including the delivery identifier and the entity type (for example, HealthcareProvider or ProviderAffiliation) the record maps to. |
relatedTransactionIdentifier | The identifier of the source-system record that failed, so it can be traced back to OneKey. |
sourceSystemName | The source MDM system, such as OneKey. |
errorSource | Provider Sync or Provider Codes Sync. |
logType | Always Subscriber. |
Error Codes
The errorCode tells you what went wrong.
| Error code | What it means |
|---|---|
DATA_ERROR | A record was rejected by Salesforce, or the data-error threshold was crossed. |
NOT_FOUND | A relation couldn't be created because the related record does not exist yet. |
BAD_CONNECTION | A Salesforce connection error after retries were exhausted. |
INVALID_CREDENTIALS | An authentication or security error. |
INTERNAL_SERVER_ERROR | A generic or unexpected system error. |
BATCH_MANAGEMENT_TRIGGERING_FAILED | The HCP address batch job didn't start or Invocation failed. |
RECORDS_NOT_PRESENT | The job found no records to sync. |
Data Errors and Fatal Errors
Data errors (errorType = Error) are per-record failures. When a record is rejected by Salesforce, the connector records the failure and continues with the rest of the load, so a single bad record does not stop the job. To fix one, review its call stack, correct the underlying data, and reload that record through a delivery-based sync.
The connector stops a load when data failures cross a configurable threshold, so a systemic problem doesn't fail every record in the delivery. By default the threshold trips only when both conditions are met: more than 10 records have failed, and failures are at least 50% of the records processed so far. Both the count (dataErrorThresholdCount) and the percentage (dataErrorThresholdPercentage) are configurable. When the threshold is crossed, the job records a DATA_ERROR and ends; review the error logs, fix the underlying cause, and retry the job from the last successful page.
Fatal errors (errorType = Exception) stop the job. These include a duplicate job submission, a persistent connection failure after retries are exhausted, or an unexpected processing error. The call stack carries the underlying error detail. Fatal errors from the Codes Job are recorded with the Provider Codes Sync source.
Using Anypoint Platform Logs
Both applications write runtime logs to Anypoint Platform at INFO, WARN, and DEBUG levels. When investigating a failure:
- Search the application logs for keywords such as
error,retry, andfailto locate the relevant entries. - Enable
DEBUGlogging when you need more detail, such as tracing a specific request end to end.