Provider Bulk Sync

This page answers common questions about deploying, running, and extending the Provider Bulk Sync connector. For setup steps, see the Setup guide; for field mappings, see the Mappings guide; and for supported changes, see the Extend Connector guide.

Setup and Deployment

Do I need a MuleSoft license to use the connector?
Yes. The connector is built on MuleSoft Direct and requires an active Anypoint Platform license. As long as the fields and data coming from OneKey match the expected format, the connector is pre-built and mapped to the Life Sciences or Health Cloud data model, so a baseline setup is straightforward. Customer-specific needs, such as additional record types or country-specific mappings, require DataWeave changes in the supported mapping layer.

Should I use MuleSoft Direct or deploy to Anypoint Platform?
Use MuleSoft Direct for initial testing and the baseline setup. Once you extend the mapping templates or configuration, deploy and manage the applications through Anypoint Platform. Continuing to deploy through MuleSoft Direct after extending can overwrite your changes.

Can I deploy the applications to a CloudHub 2.0 private space?
Yes. Applications can be deployed to private spaces from MuleSoft Direct. This requires the Enable Integrations: Private space permission to be enabled for the Salesforce org.

Should I disable Salesforce triggers and automations before the initial bulk load?
For a large initial load, this is strongly recommended. The connector writes Account, HealthcareProvider, ProviderAffiliation, and their related records through batched composite calls, with the data and activity queues processed in parallel. Any active trigger, flow, process builder, or validation rule on those objects runs on every inserted record and can cause row-lock contention, transaction timeouts, and rejected records at bulk volume. Some Life Sciences Cloud managed-package handlers can also block the load rather than only slow it.

Temporarily disable automations on the target objects for the duration of the initial load, then re-enable and validate afterward, because some skipped logic may need to be reconciled once automations are back on. Run the load in a controlled maintenance window, and note that disabling a managed-package handler disables it org-wide for all features, not only for the integration. Delta and incremental loads are low-volume and generally tolerate automations being left on.

Sync and Scheduling

What is the recommended way to trigger the Provider Bulk Sync API?
Trigger the bulk load by calling the /sync endpoint of the Provider Bulk Sync application. To run it periodically, schedule a job that calls this endpoint. Common options are:

• A scheduled Apex class with a cron expression.
• An invocable Apex method called from a scheduled Salesforce flow.
• A MuleSoft scheduler in a MuleSoft application that calls the endpoint.

The right option depends on your OneKey data scale and implementation strategy.

Can I trigger the Codes Job manually, and how often should it run?
Yes. Go to Anypoint Platform, open your deployed application, then Schedulers, and select Run Now to trigger it on demand. The Codes Job usually needs to run only once, before the first Bulk Sync. Make sure the codes and code-values mapping is finalized before you deploy the Provider Bulk Sync application.

Why are the picklist values loaded by the Codes Job set to Inactive by default?
The Salesforce Metadata API readMetadata operation does not return inactive values, so the connector cannot see how many inactive values already exist on a field. Because active and inactive values together are subject to the 1,000-value limit, adding new values as active could silently exceed the limit and fail the upsert. To avoid this, the Codes Job inserts new values as inactive. An administrator activates them as needed.

Can I run more than one sync job at the same time?
Run one job at a time. Each sync job is scoped to a single country through the mandatory countryCode on the sync request. A second request for a country that is already being processed is treated as a duplicate and rejected, and jobs for other countries are queued and dispatched one after another.

Do I need to specify a jobId when calling the /sync endpoint, and what format must it use?
No. The jobId is optional for the POST /sync endpoint. If you don't specify a jobId, the connector generates a UUID and returns it in the response. If you provide a jobId, it must be a UUID, such as dd960082-abbf-47c2-8c65-f18eeb35848b. A non-UUID value results in a 400 Bad Request error. Use the returned jobId with the GET /jobs/{jobId} and DELETE /jobs/{jobId} endpoints. UUIDs provide a large identifier space and help reduce the risk of identifier guessing as a defense-in-depth measure. See the Security guide.

Why doesn't the processed-records summary match the total record count from OneKey?
Jobs are independent and stateless. If a job is interrupted and a later job resumes from where it stopped, the second job's IntegrationJobRun summary reflects only the records it processed in its own delivery-ID window, not the full OneKey volume for the country. This is expected when a load is split across more than one job.

In what sequence is data processed from OneKey?
Reference codes are loaded first by the separate Codes Job. During a Bulk Sync, provider records (Workplaces and Individuals) are processed before Activities. The Activity queue is published with a delivery delay so that activity affiliations are written after the provider records they link to already exist in Salesforce.

Who triggers the HCP contact point address batch job, and should I run it manually?
The connector triggers it automatically, so you should not run it manually under normal operation. As part of setup you create the Salesforce Batch Management job and flows for HCP address processing (see the Setup guide). When a sync job completes, the Provider Bulk Sync API invokes that job (Process_HCP_Contact_Point_Addresses) through its Salesforce invocable action, which creates the contact point address records for the providers and affiliations loaded during the run. The connector passes the sync job's own start and end time as the processing window, so the batch job processes exactly the records that the run loaded.

Avoid triggering the job manually. Because the connector supplies the precise time window for each run, a manual run with the wrong window can reprocess or miss records. The one exception is recovery: if the automatic trigger fails, the connector logs an Error entry with code BATCH_MANAGEMENT_TRIGGERING_FAILED to Salesforce Error Log Management, and you can then start the job in Salesforce using that run's start and end time.

For how the batch job and its flows are created, see Create Flows to Process HCP Addresses. For the related guidance on disabling trigger handlers during a bulk load, see Data Migration Trigger Handler Guidelines.

Mapping

Why are the NPI Type and Account NPI Type hardcoded for HCP and HCO?
On the HealthcareProviderNpi record, NpiType is a fixed picklist of Individual or Organization, so HCP records use Individual and HCO records use Organization to match the data model. AccountNpiType is Type1 or Type2: for Type1 the NPI value must be unique, and for Type2 the combination of account and NPI value must be unique. OneKey sends the same NPI for multiple workplaces but a unique NPI for individuals, so workplaces use Type2 and individuals use Type1.

Why is the Primary Provider field set to true by default?
OneKey creates a one-to-one relationship between the Account and the HealthcareProvider record, so the created HealthcareProvider is the primary provider for that account.

Why is the Provider Affiliation Influence Type hardcoded?
InfluenceType on ProviderAffiliation controls the direction of an affiliation and can be Unidirectional, Bidirectional, or Neutral. Records loaded from OneKey are set to Unidirectional to reflect their unidirectional nature.

Why is the Person Language rank defaulted to 1?
OneKey sends a single preferred-language value per individual, so PersonLanguage.Rank is defaulted to 1.

Can I filter out specific affiliation codes?
Not out of the box. To include or exclude specific affiliation codes, add filtering logic in the DataWeave transformation files in the OneKey System API. This is a supported extension within the mapping layer.

My specialties aren't mapping and OneKey is sending codes like SP.WES.88 instead of 88. What should I check?
This is a OneKey data issue rather than a connector issue. The connector expects specialties in OneKey's direct-value format, where the specialty list is identified by the listCode SP and the value is the bare code, such as 88 or OBG. It reads that code directly as the specialty's external key; it does not parse a fully-qualified, prefixed code such as SP.WES.88. If your OneKey delivery returns specialty codes in the fully-qualified format, they won't map as expected.

Raise this with your OneKey team and ask them to return specialty codes in the direct-value format rather than the fully-qualified format. This kind of source-data formatting is corrected on the OneKey side, not through a connector change. Once OneKey delivers the bare codes, the connector maps them without any modification.

Some ProviderAffiliation records fail to load with a missing Role. Why, and what should I do?
Role is mandatory on ProviderAffiliation in Life Sciences Cloud, and the connector maps it directly from the OneKey relation's linkCode with no fallback. When OneKey sends a relation with an empty linkCode, no Role is written and Salesforce rejects that affiliation. The failure isn't silent: the rejected record is captured as a per-record data error in the error log, so you can find it under the job's failures; see the Troubleshooting guide for where these are recorded.

This is a data gap on the OneKey side. The connector faithfully passes through what OneKey provides. You have two options:

• Work with your OneKey team so that relations are always sent with a Role value.
• Set a default Role in the mapping layer so affiliations without one still load. This is a supported extension; see "Set a Default Role When Role Is Empty" in the Extend Connector guide for the steps, which can also be scoped per country.

Multi-Country

When you onboard a country that isn't already validated for this connector, budget for a data-format validation pass against that country's OneKey delivery before go-live, because OneKey's data format can vary by country.

Do we need a separate connector instance for each country?
No. A single instance serves multiple countries. Each sync job is scoped to one country, and country-specific behavior is handled through configuration and the mapping layer rather than separate deployments. A per-country or per-region instance is an option, not a requirement, and is worth considering only for very large per-country datasets that must load in parallel, for data-residency or compliance boundaries, or for divergent release and configuration life cycles.

Troubleshooting

I get a 400 Bad Request when calling the /sync endpoint. What should I check?
Common causes are:

• Incorrect or missing parameters in the MuleSoft configuration.
• A non-standard data format returned by an IQVIA test connector, because test accounts sometimes do not return data in the standard format.
• A wrong value in the runtime properties.

Check the application logs in Anypoint Platform for the specific error detail.

The Provider Bulk Sync API reports a credentials error even though the OneKey System API works with the same credentials. What is happening?
This is usually caused by an incorrect parameter in the Provider Bulk Sync configuration rather than by the credentials themselves. Review the runtime properties for the Provider Bulk Sync application and confirm that all required parameters are set correctly.

A job finished with a CompletedWithError status. Where are the failed records recorded, and how do I fix them?
When an individual record is rejected by Salesforce during a load, the connector doesn't stop the job for that one record; it records the failure and moves on. Each failed record is logged back to Salesforce through the Life Sciences Cloud log service and linked to the job's Integration Job Run record, so you can review the failures in Salesforce rather than only in the MuleSoft application logs. Each error entry captures:

• The error message and call stack, including the delivery identifier and the entity type (for example, HealthcareProvider or ProviderAffiliation) the record maps to.
• The identifier of the source-system record that failed, so you can trace it back to OneKey.
• An error code and type, and the source system name.

To fix a failure, review the logged error and call stack, correct the underlying data, and reload that record through a delivery-based sync. A common cause is source data that doesn't match the expected format for the country.

A job never completes or no data is loaded. Could the Anypoint MQ queues be misconfigured?
Yes. The two applications never call each other directly; they communicate only through the Anypoint MQ queues, so the queue names must match on both sides. If a queue name in one application's anypointMQ configuration does not match the other's, messages are published but never consumed, and the job appears to hang without loading data or reaching a final status. The queue names, along with the prefetch, concurrency, and acknowledgement settings, are part of the connector's architecture and aren't meant to be changed; see "What Isn't Supported" in the Extend Connector guide. If a previous run failed or was aborted and left residual messages behind, clear them using the controlled recovery procedure in the housekeeping question below, but do not purge the queues as a routine step, since that can delete in-flight or delayed work.

Can the same Anypoint MQ message be processed more than once, and will that create duplicate records?
Anypoint MQ guarantees at-least-once delivery, so a message can be redelivered, for example after an acknowledgement timeout or a worker restart. The connector is built to tolerate this, so redelivery does not create duplicate data:

• Salesforce writes are upserts. Records are written through the Composite Graph API with a PATCH against an external-id field, so reprocessing the same record updates it in place instead of inserting a second copy.
• A duplicate sync request for a job or country that is already in progress is rejected rather than started again, as described under "Can I run more than one sync job at the same time?".
• On the relations handshake, a redelivered message is detected through its delivery count and the downstream re-publish is skipped, so relations aren't queued twice.

Because the queued messages are persistent, an application restart or redeployment does not lose in-flight work; unacknowledged messages are redelivered and reprocessed. See the Design Rationale in the Architecture Diagram guide for more on why the connector uses durable queues.

Is there any housekeeping to do before a run?
No routine purging is needed, and purging the queues before each run is not safe. The connector's queues are persistent by design, and the Activity queue delivers its messages on a delay (30 seconds by default) so that activities load after their related provider records. Under normal operation these queued and delayed messages are in-flight work, not leftovers: purging them, or purging while a job is still running, deletes work the connector expects to process, which surfaces later as missing records or a job that never reaches a correct final status. Between jobs the queues drain on their own, so a clean run does not require any manual clearing.

Purge only as a deliberate recovery step, for example after a run has failed or been aborted and left residual messages behind, and only after confirming that no job is active. To do this safely:

1. Confirm no job is active. Call GET /jobs/{jobId} (or check the Status object store) and verify the job is in a terminal status: Completed, CompletedWithError, Failure, or Aborted. If it is still New, InProgress, or AbortInitiated, a job is running or winding down and you must not purge yet.
2. Stop any running job. If a job is still active, abort it by calling DELETE /jobs/{jobId} and wait until its status becomes Aborted. An abort ends the job but does not roll back records already written.
3. Purge the queues. With no job active, in Anypoint Platform go to MQ, select the environment, select each queue, and choose Purge Messages. Clear all of the connector's queues together so no partial handshake state is left behind.
4. Restart cleanly. Trigger a fresh sync through the /sync endpoint. Jobs are stateless and resume from the last successful delivery, so the next run continues from where the interrupted one stopped rather than reprocessing the whole volume.