Provider Services API

This guide separates troubleshooting by feature because Search Before Create (SBC) is request-driven and Data Change Request (DCR) is job-driven. In both paths, the Provider Services API owns Salesforce processing and the OneKey System API owns OneKey connectivity and mapping.

The messages on this page are illustrative examples, not an exhaustive error catalog. Exact text can vary by operation, country-specific contract, OneKey response, and downstream Salesforce validation. Use each example to identify the failing layer, then confirm the specific cause in the corresponding record fields or application logs.

Search Before Create (SBC)

SBC search and download requests return a synchronous response, while related-record and affiliation processing continues asynchronously after the main provider is downloaded.

For endpoint schemas, examples, errors, and field constraints, see the Provider Services API specification.

Where SBC Errors Are Logged

• Life Sciences Cloud toast notifications. The Provider Services LWC displays synchronous search and main-provider download errors in toast notifications. Start here for request validation, authentication, System API, and synchronous Salesforce write failures.
• Salesforce Error Log Management. Asynchronous related-record, affiliation, and post-processing failures are written through the Life Sciences Cloud log service. In Salesforce, go to Admin Console > Error Log Management, and filter Error Source by Provider Search. A synchronous main-provider failure is returned to the LWC instead of being written here.
• Anypoint Platform logs. At the application deployment level, use the Provider Services API logs for request handling and Salesforce processing. Use the OneKey System API logs for OneKey calls, mapping, and transformation details. Enable DEBUG logging when the standard runtime logs don't contain enough detail.

Common Debugging Scenarios

A search request fails or returns an unexpected result. Trace the request in this order to isolate whether the failure is in request handling, OneKey retrieval, or response mapping:

1. Inspect the synchronous API response and confirm the request fields and country code.
2. In the Provider Services API logs, find the search request and the call to the System API.
3. In the OneKey System API logs, confirm the OneKey response and the mappingTemplates/search transformation.

The main provider downloads, but related records or affiliations are missing. The main entity is written synchronously, but relation processing is asynchronous. Check each phase separately:

1. Confirm that the download response contains the Salesforce ID or IDs for the downloaded main record or records.
2. Check the Provider Services API logs for asynchronous post-processing and Salesforce write failures.
3. Check the OneKey System API logs for /addToContract, relation downloads, and mappingTemplates/download transformation issues.
4. In Salesforce Error Log Management, filter Error Source by Provider Search and review the records that failed to load.

Using Anypoint Platform Logs for SBC

1. Search the Provider Services API logs with the request or correlation ID to trace Salesforce-side validation and writes.
2. Use the same ID in the OneKey System API logs to trace the OneKey request and response.
3. Compare the response with the relevant search or download mapping only after confirming that OneKey returned the expected source data.

Data Change Request (DCR)

DCR processing is asynchronous. The Submission and Monitoring jobs write a status and response back to each LifeSciDataChangeRequest record. Provider Services API and OneKey System API logs retain the technical detail.

Where DCR Errors Are Logged

• Salesforce DCR record. Use the record fields for the business outcome and the request-specific response. This is the first place to determine whether a request is pending, approved, rejected, or failed.
• Provider Services API logs in Anypoint Platform. Use these logs for scheduler execution, Salesforce enrichment, System API calls, per-record error isolation, and status write-back.
• OneKey System API logs in Anypoint Platform. Use these logs for OneKey request-and-response details, mapping or schema failures, contract-coverage responses, and connectivity errors.

The DCR record fields have distinct purposes:

Start with these Salesforce fields for "what happened to this request," then use Anypoint Platform logs for "what happened during processing." For the established Salesforce Error Log Management fields and the general Process API/System API logging model, open the Troubleshooting page in the Provider Bulk Sync documentation.

Illustrative DCR Error Examples

These examples show how to interpret common failure patterns. Other messages can occur; use the origin and record correlation fields to choose the next log to inspect.

DCR Status Outcomes

• Approved: OneKey returned VAS_FOUND.
• Rejected: OneKey returned a decision that is neither approved nor pending; its response comment is written to the record.
• Processed: OneKey hasn't decided; the Monitoring Job selects the record again on its next run.
• Failed: Submission failed or no matching OneKey result was found.

Common Debugging Scenarios

A DCR stays in Qualified and is never submitted. Check the selection criteria in order:

1. Confirm status = 'Qualified', externalvalidationsysname = 'OneKey', and validationtype = 'External'.
2. Confirm parentdatachangerequestid = null and extlvalidationreqidentifier = null on the parent request.
3. Confirm the Field Update Type is Apply Changes Immediately.
4. Confirm the DCR Submission schedule is enabled in Anypoint Runtime Manager.

Requests for one country fail with an access or non-retryable OneKey response. Treat this as a contract-specific regional coverage limitation, not a connector defect. The connector can submit a country only when that region is in the customer's OneKey agreement and credentials. Confirm coverage with the customer's OneKey contract. Remove non-contracted countries from the configuration, and set affected DCR records to Failed before retrying other records. If the business needs the region, arrange coverage with IQVIA before enabling it.

An Individual HCP DCR fails with missing IND_HCP_TYPE_CODE or IND_SP_CODE. Fix the missing data in one of these ways:

1. Populate the source field in Salesforce as part of the create experience or through Salesforce automation.
2. If a contractually valid default exists, add it in mapper.dwl or a country-specific mapping so the required field is present only where appropriate.
3. Keep the change in the mapping or configuration layer rather than the application flows.

A country field is dropped from the request. DCR mapping applies skipNullOn = "everywhere", so null values and selected empty values normalized by the mapper are omitted. Confirm the source field is populated, then verify that Source_Field in mapping_<COUNTRY>.json uses the casing expected by mapper.dwl. See Null and Empty Value Handling in the Mappings guide before changing the mapper scripts.

Using Anypoint Platform Logs for DCR

1. Search the Provider Services API logs for the DCR record ID and validation job failed with error.
2. Enable DEBUG on the submit flow when you need the exact System API request and response.
3. Use the same request context in the OneKey System API logs to find the mapping or OneKey error.
4. Compare the technical error with the status and response written to the DCR record.

Illustrative HTTP-Level Error Examples

These examples show how the Process API classifies common transport-level failures from the System API and Salesforce. They aren't an exhaustive list. SBC returns these errors through the synchronous request path. DCR captures APP:BADREQUEST_ERROR per record, while other failures surface in the job logs.