Provider Services API

Provider Services Mappings

SBC and DCR use separate mapping paths because data moves in opposite directions. SBC maps OneKey data into Salesforce, while DCR maps Salesforce changes into OneKey.

Data Change Request (DCR)

DCR pushes changes out to OneKey, so the Salesforce field is the source and the OneKey field is the target. This direction is the reverse of Provider Bulk Sync.

Everything below is the out-of-the-box mapping that ships with the connector. The mapping is metadata-driven and also includes explicit DataWeave logic for entity selection and field transformations: the field list lives in mapping.json, the in-scope entities live in objects.json, the mandatory-field rules live in schema.json, and the transformation logic lives in mapper.dwl, all under onekey-sys-impl/src/main/resources/mappingTemplates/validation/. To change what is mapped, add code-value translations, or apply per-country rules, see the Extend Connector guide; make those changes in the OneKey System API mapping layer, not in the application flows.

How the Mapping Works

A DCR is submitted as a request that carries an operation (create or update), an entityType (activity or workplace), and an entityData object holding the changed Salesforce entities. The System API resolves the mapping in three stages:

1. Physical entity allow-list (objects.json). Six physical Salesforce entities are accepted out of the box. A request that includes any other entity is rejected with "Your request includes unsupported entities: {0}...".

1. Field mapping (mapping.json via mapper.dwl). Each Salesforce field is matched (case-insensitively) to its OneKey target field and internal mapping field. Account fields resolve to either Individual (HCP) or Workplace (HCO) targets depending on whether the record has a LastName (Individual) or only a Name (Workplace). mapper.dwl then applies field-specific transformations (code-value translations, birth-date splitting, date reformatting) and appends OPERATION and ENTITY_TYPE.

2. Schema validation (schema.json). Before the request is sent to OneKey, the mapped payload is validated against a JSON Schema (draft-07). Missing mandatory fields fail with "Missing required fields: {0}...". The mandatory set depends on the operation, the entity type, and the country (see Mandatory Fields).

DCR Entity Type Resolution

A DCR request must carry one of two entity types. The value controls the mapping branch and mandatory-field rules:

• activity: required for every HCP-related DCR. The Provider Services API sets this value when the Account is a person account (IsPersonType).
• workplace: required for every HCO-related DCR.

These are the only values allowed by the DCR schema.json. Use workplace, not workspace; workspace fails schema validation.

Affiliation eligibility is a separate check. An affiliation is submitted only when its AffiliationType is Hard (dcr.activityAffiliationType). DCRs for non-activity (non-Hard) affiliations are not supported by the MDM system; the connector fails them locally with "DCRs for non-activity type affiliations are not supported by the MDM system" without calling OneKey.

In the mapping tables that follow, the Mandatory column shows whether a field is required for an HCP (activity), an HCO (workplace), or both, and for which operation.

Null and Empty Value Handling

The DCR mapping pipeline uses the DataWeave output directive skipNullOn = "everywhere" (sometimes described as skipNull = "everywhere"). By default, null values are omitted from objects and arrays instead of being serialized into the OneKey request. Selected empty values are also omitted when mapper logic uses isEmpty or converts an unresolved value to null.

Examples:

• If ContactPointAddress.Street resolves to null, the request omits ADD_STREET; it doesn't send "ADD_STREET": null.
• If ProfessionalTitle has no matching code translation, mapper.dwl converts the unresolved result to null, so IND_HCP_TITLE is omitted.
• If a DCR comment is empty after trimming, setVrSubmitRequestPayload.dwl doesn't add validation.requestComment.

skipNullOn doesn't remove every empty string by itself. Empty values are omitted only when the surrounding mapper explicitly tests isEmpty or normalizes the value to null.

If a OneKey contract requires an explicit null or empty value, update the mapping pipeline in this order:

1. Confirm that the target OneKey field accepts the explicit value. Sending null where the contract doesn't allow it causes downstream validation failures.
2. Update the output directive or field-specific condition in provider-services-impl/src/main/resources/dwl/dcr/submitSAPIRequest.dwl so the Process API preserves the value sent to the System API.
3. Update onekey-sys-impl/src/main/resources/mappingTemplates/validation/mapper.dwl so the field mapping doesn't normalize or drop the value.
4. Update onekey-sys-impl/src/main/resources/dwl/vr/setVrSubmitRequestPayload.dwl so the final OneKey payload includes the field.
5. Test the Process-to-System request and the final System-to-OneKey payload for the affected country, operation, and entity type.

This behavior isn't controlled by a runtime property; changing it requires mapper-script changes at every stage that currently omits the value.

Account Mapping

Account fields map to OneKey Workplace (HCO) or Individual (HCP) targets. The SourceSystemIdentifier is the OneKey entity ID and is mandatory only on update (on create, OneKey generates it).

A dedicated branch in mapper.dwl splits one PersonBirthdate value into two OneKey fields: IND_BIRTH_DATE_YEAR and IND_BIRTH_DATE_DAY.

HealthcareProvider Mapping

HealthcareProvider fields describe the provider's type, class, status, title, and bed count. Several are code-value translated per country.

CareSpecialty Mapping

CareSpecialty carries the specialty code, sent as IND_SP_CODE (HCP) or WKP_SP_CODE (HCO). For an HCP create, IND_SP_CODE is mandatory. A configurable per-request specialty limit exists (dataChange.submit.specialty.limit, default 3).

Specialty data for DCR is carried by CareSpecialty.SpecialtyCode. HealthcareProviderSpecialty has no mapped fields. It exists in objects.json so the entity allow-list check passes because the connector reaches CareSpecialty through it.

ContactPointAddress Mapping

Address fields locate the provider. City and CountryCode are always mandatory, because OneKey uses the country to select the region and validate the request.

ProviderAffiliation Mapping

ProviderAffiliation maps to the OneKey activity (the HCP-to-HCO link). No affiliation field is individually mandatory, but only Hard affiliations are eligible for DCR (see DCR Entity Type Resolution).

Request Envelope Fields

Beyond the entity fields, the System API adds the request envelope from setVrSubmitRequestPayload.dwl:

Mandatory Fields

The System API validates mandatory fields against schema.json before calling OneKey. ADD_CITY and ADD_COUNTRY are always required. The rest depend on operation × entity type × country (US vs. non-US):

Expressed in Salesforce terms:

Managed Fields

For External DCR to fire correctly, these Salesforce fields must be configured as External Managed Fields in alignment with OneKey. A DCR is only generated when a managed field changes.

Picklist Values for Testing

To exercise the shipped mapping end-to-end, use Salesforce source values that appear in the base mapping.json and codeValues.json files. Confirm that each value is valid for the customer's country and OneKey contract before testing against OneKey.

CareSpecialty.SpecialtyCode is passed through directly rather than translated by the shipped mapping. Use a specialty code supported by the customer's OneKey contract.

Search Before Create (SBC)

SBC maps in the opposite direction: OneKey Individual, Workplace, and Activity data into the Life Sciences Cloud data model. It reuses the transformation approach used by Provider Bulk Sync.

For SBC request and response schemas, examples, errors, and field constraints, see the Provider Services API specification. For mapping changes, see Extend Connector.

To locate and extend the SBC mappings:

1. Use mappingTemplates/search in the OneKey System API for fields returned by provider search. This controls the synchronous search result shape.
2. Use mappingTemplates/download for the selected provider and related records written to Salesforce. This controls the data imported after selection.
3. Keep SBC changes separate from mappingTemplates/validation, which is used only by DCR. This prevents an inbound mapping change from affecting outbound validation requests.
4. Review the full OneKey-to-Salesforce field tables before changing either mapping path.

For the full OneKey → Salesforce field tables (Individual, Workplace, and Activity, including transformations, filters, and code-value translations), see the Data Mappings page in the OneKey System API documentation. The Provider Bulk Sync connector shares the same download mapping layer.