Provider Services API

This page answers common questions about deploying, running, and extending the Search Before Create (SBC) and Data Change Request (DCR) features. For procedures, use the Setup, Mappings, Extend Connector, and Troubleshooting guides.

Search Before Create (SBC)

Overview

Which MuleSoft applications do SBC and DCR require?
Both features use two applications in the same API-led framework:

• Process App: provider-services-impl.
• System App: onekey-sys-impl.

The OneKey System API is a prerequisite and is deployed automatically if Provider Bulk Sync is already deployed. See the Setup guide for the deployment order and manual steps.

Can this connector be used with an MDM system other than OneKey?
No. This connector is built exclusively for the OneKey MDM system. If you use a different MDM system, design your own integration.

How is SBC invoked?
SBC uses synchronous POST /provider/search and POST /provider/download operations under the provider-services/v1 base path. Search returns matching providers; download writes the selected provider and then starts asynchronous related-record processing.

Where can I find endpoint details or create test request models?
See the Provider Services API specification for endpoint schemas, sample requests and responses, errors, and request-field constraints. Use these schemas and examples to create models in your testing tool. The connector doesn't include a mock implementation.

What is supported out of the box, and what can I extend?
SBC searches OneKey, downloads an Individual, Workplace, or Activity, writes the main provider synchronously, and processes related records asynchronously with the provided mappings. You can change search and download mappings, add country-specific overrides, and adjust documented properties. Don't change the API contracts or orchestration order. See Extend Connector.

Search-related Behavior

How many search results does SBC return?
The default is 20, controlled by onekey.search.resultSize in the OneKey System API. The Mule application caps the value at 100. Check IQVIA's documentation for any additional OneKey service limits.

Where are search mappings maintained?
Search response mappings are under mappingTemplates/search in the OneKey System API. See Extend Connector for customization steps.

Download Behavior

How many levels of related records does SBC download?
Related child-record traversal defaults to two levels through sbc.relations.levels. Workplace hierarchy traversal defaults to five levels through sbc.workplaceHierarchy.levels. You can increase either value, but deeper traversal increases OneKey and Salesforce API consumption.

Where are download mappings maintained?
Download mappings are under mappingTemplates/download in the OneKey System API. See Mappings for details and Extend Connector for customization steps.

Where do I troubleshoot an SBC failure?
Start with the synchronous API response. Then use the request or correlation ID in the Provider Services API logs for Salesforce processing and in the OneKey System API logs for OneKey and mapping details. See the SBC section of the Troubleshooting guide.

Data Change Request (DCR)

Setup and Jobs

Do I need a MuleSoft license to use DCR?
Yes. The DCR Submission and Monitoring jobs require an active Anypoint Platform license. Without MuleSoft, Life Sciences Cloud stores the DCR records, but custom middleware must query, transform, submit, monitor, and update them.

How do I enable or disable the DCR jobs after deployment?
In Anypoint Platform, open Runtime Manager, select the correct environment, open Provider Services API, go to Schedules, and enable or disable the DCR Submission and Monitoring jobs. See the Setup guide.

Behavior

Which physical entities are supported out of the box?

DCR supports six physical Salesforce entities:

Customers can add an entity only when their OneKey contract and Optimized JSON specification support it. Update the entity allow-list, field mapping, and mandatory-field schema without changing the API contracts or execution order. Follow the governed extension steps in the Extend Connector guide.

Which entity type must a DCR use?

Every HCP-related DCR must use activity. Every HCO-related DCR must use workplace. The DCR schema accepts only these two values; workspace isn't valid.

Which fields are mandatory to successfully submit a DCR?
It depends on the operation, entity type, and country. Always required: City and CountryCode on ContactPointAddress. See the full matrix in the Mappings guide. In brief:

Does DCR support delete operations?
No. DCR supports create and update only.

What is the required Field Update Type for External DCR?
Use Apply Changes Immediately. The connector enriches data during the update. If a rep updates two entities under the same Account (DCR record 1 and record 2), Don't apply changes immediately means record 1's updated data isn't available when record 2 is processed, which can cause discrepancies. MuleSoft supports only Apply Changes Immediately.

Which entities does OneKey assign a SourceSystemIdentifier to on create?
Account, ContactPointAddress, and ProviderAffiliation.

For an HCO or HCP create, how many requests go to OneKey?
At least one. For each parent DCR, the connector creates one primary request containing its linked child records, including the first ContactPointAddress and first ProviderAffiliation. Each additional address or affiliation becomes a separate request. HealthcareProviderSpecialty records are included in the primary request and appended to each additional request.

If the same field on one entity is updated repeatedly, how many requests go to OneKey?
One per update. For example, changing an Account's FirstName first to "John" then to "Johnson" generates two DCR records and two separate calls to OneKey.

When attributes across multiple entities are updated, how many requests go to OneKey?
It depends on how the DCR records are related. Child records linked to the same parent are placed in the primary request, except that each address or affiliation after the first is submitted separately. Updates represented by separate parent DCR records are processed as separate submissions.

In what order are DCR records processed?
Oldest first, for both the Submission and Monitoring jobs (ordered by CreatedDate).

Why do only Hard affiliations get submitted?
An affiliation qualifies as an activity only when its AffiliationType is Hard (dcr.activityAffiliationType). DCRs for non-activity affiliations are not supported by the MDM system and are failed locally without calling OneKey.

Does OneKey approve or reject individual fields, or the whole request?
The whole request. OneKey returns one overall outcome per submitted Data Change Request (Approved, Rejected, still pending, or Failed); there is no field-level or partial approval. A request either validates as a unit or it does not. When OneKey approves changes, the corrected values return to Life Sciences Cloud through the Delta Job rather than on the DCR response.

Are there pending steps after OneKey approval and the Monitoring job completes?
Yes. A Delta Job brings the approved updates back into Life Sciences Cloud. Delta updates are not immediately available because OneKey processing time varies. The provider-bulk-sync-api-impl application handles the delta procedure.

Mapping and Customization

Does the connector send DCR comments to OneKey?
Yes, when LifeSciDataChangeRequest.Comments is populated. Provider Services combines nonempty comments from the parent and child DCR records, and the System API sends the result as validation.requestComment. If the Salesforce process that creates the DCR doesn't populate Comments from entity-specific comment fields, customize the Salesforce DCR Handler to populate it. See the Extend Connector guide, section 1.1.

OneKey sends specialty codes. How do I store them in Salesforce?
DCR sends CareSpecialty.SpecialtyCode directly, so the value stored in Salesforce must be the code OneKey expects. Present a readable name in a Salesforce picklist while storing the OneKey code, or add a country-specific translation in mapping_<COUNTRY>.json. See the Extend Connector guide, section 1.4.

A functional concept, such as "Cardiologist," maps to different OneKey codes per country. How do I handle that?
Define the translation per country using the region-specific override files (mapping_<COUNTRY>.json, codeValues_<COUNTRY>.json), which fall back to the base files. Avoid hardcoding a single mapping across countries. See the Extend Connector guide, section 1.3.

How should I handle a region that isn't covered by my OneKey contract?
Treat this as a contract-specific coverage limitation, not a connector defect. Configure only the countries included in the customer's OneKey agreement. A request for a non-contracted country can receive an access or non-retryable OneKey response and block later DCR processing. Set affected records to Failed, confirm the configured country list, and arrange coverage with IQVIA before enabling that region.

Multi-Country

Do I need a separate connector instance per country?
No. A single instance serves multiple countries. Each request carries a countryCode, and country-specific behavior is handled through the region-specific mapping files rather than separate deployments. A per-region instance is an option for large or divergent regions, not a requirement.

When onboarding a new country, what should I budget for?
A data-format validation pass against that country's OneKey data contract before go-live, because OneKey's data format and required codes vary by country.

Additional References

• DCR: Data Change Request and External Validation Requirements
• SBC API contract: Provider Services API specification