10 KiB
10 KiB
The /dcr API serves as a canonical interface for initiating data change requests. The JSON payload sent to this endpoint contains a standardized representation of the desired changes. The MDM HUB is then responsible for validating this request and mapping its attributes to the distinct models of the target systems.
/dcr API to Target System Attribute Mapping
The following sections break down the mapping from the attributes in the /dcr request payload to their corresponding fields in OneKey and Veeva.
1. Request-Level Attributes
These attributes are defined at the top level of each object within the DCRRequests array in the JSON payload.
| HUB /dcr Attribute | OneKey Mapping | Veeva OpenData (VOD) Mapping | Notes / Description |
|---|---|---|---|
extDCRRequestId |
Used to populate the DCRID in the Reltio DCR tracking entity. OneKey's validation.clientRequestId is typically a HUB-generated internal ID, but extDCRRequestId is the primary key for client-side tracking. |
dcr_key (in all CSV files: change_request.csv, change_request_hco.csv, etc.) |
This is the primary external identifier for the entire DCR. It is crucial for clients like PforceRx to track the request's status and is used as the main correlation ID across all systems and files. |
extDCRComment |
validation.requestComment |
description (in change_request.csv) |
A free-text field for the requester to provide context or justification for the DCR. For OneKey, it has a special function: due to API limitations, requests to remove an attribute are specified in this comment field (e.g., "Please remove attributes: [Address: ...]"). |
country |
isoCod2 |
primary_country__v (in change_request_hcp.csv and change_request_hco.csv) and country__v (in change_request_address.csv) |
The mandatory two-letter ISO country code. This is a critical routing attribute that determines which validator instance to use and, for Veeva, which S3/SFTP directory the DCR files are placed in. |
action (within HCP/HCO object) |
This determines the logic. update and insert map to a submitVR call. An update requires a valid individual.individualEid or workplace.workplaceEid. delete is handled by updating the entity's end date in Reltio. |
change_request_type (in change_request.csv). Mapped to ADD_REQUEST for an insert action, and CHANGE_REQUEST for an update action. |
This defines the fundamental operation being performed on the entity. |
refId (within HCP/HCO object) |
Used to query Reltio to find the OneKey crosswalk (individual.individualEid or workplace.workplaceEid) which is mandatory for update operations. |
Used to query Reltio to find the Veeva crosswalk (vid__v), which is mandatory for update operations. The Reltio URI from the refId is also used to populate the entity_key field in the VOD CSVs. |
This object contains the necessary identifiers (CrosswalkTargetObjectId, EntityURITargetObjectId, etc.) to locate the target entity in Reltio for an update or delete operation. |
2. Healthcare Professional (HCP) Attributes
These attributes are provided within the HCP object of a DCR request.
| HUB /dcr Attribute | OneKey Mapping | Veeva OpenData (VOD) Mapping | Notes / Description |
|---|---|---|---|
firstName |
individual.firstName |
first_name__v |
HCP's first name. |
lastName |
individual.lastName |
last_name__v |
HCP's last name. Mandatory for creating a new HCP in OneKey. |
middleName |
individual.middleName |
middle_name__v |
HCP's middle name. |
prefix |
individual.prefixNameCode |
prefix__v |
Name prefix (e.g., Mr., Dr.). Requires a lookup from the canonical code (HCPPrefix) to the target system's specific code. |
title |
individual.titleCode |
professional_title__v |
Professional title. Requires a lookup from the canonical code (HCPTitle or HCPProfessionalTitle) to the target system's specific code. |
gender |
individual.genderCode |
gender__v |
HCP's gender. Requires a lookup to map the canonical value (e.g., M, F) to the target system's code. |
subTypeCode |
individual.typeCode |
hcp_type__v |
The professional subtype of the HCP (e.g., Physician, Nurse). Requires a lookup from the canonical code (HCPSubTypeCode or HCPType). |
specialties (List) |
individual.speciality1, individual.speciality2, individual.speciality3 |
specialty_1__v through specialty_10__v |
The list of specialties is flattened. OneKey accepts up to 3 ranked specialties. Veeva accepts up to 10. A lookup is required to map the canonical HCPSpecialty code to the target system's value. |
emails (List) |
individual.email |
email_1__v, email_2__v |
The list of emails is flattened. OneKey typically takes the highest-ranked email. Veeva takes the top two. |
phones (List) |
individual.mobilePhone |
phone_1__v to phone_3__v (for office), fax_1__v to fax_2__v (for fax) |
The list is filtered by type and ranked. OneKey maps the highest-ranked to mobilePhone. Veeva separates numbers into distinct phone and fax columns based on the Reltio phone type. |
3. Healthcare Organization (HCO) Attributes
These attributes are provided within the HCO object of a DCR request.
| HUB /dcr Attribute | OneKey Mapping | Veeva OpenData (VOD) Mapping | Notes / Description |
|---|---|---|---|
name |
workplace.usualName / workplace.officialName |
corporate_name__v |
The primary, official name of the organization. |
otherNames (List) |
workplace.usualName2 |
alternate_name_1__v |
The list of alternative names is flattened. Both systems typically take the first or highest-ranked alternative name. |
subTypeCode |
workplace.typeCode |
major_class_of_trade__v |
The HCO's subtype, often representing facility type. Requires a lookup from the canonical code (COTFacilityType). |
typeCode |
Not Mapped | hco_type__v |
Maps to the HCO Type. Requires a lookup (HCOType). The OneKey mapping document indicates this is not used for their system. |
websiteURL |
workplace.website |
URL_1__v |
The official website of the organization. |
specialties (List) |
workplace.speciality1 to speciality3 |
specialty_1__v to specialty_10__v |
Similar to HCPs, the list of specialties is flattened and ranked. A lookup from the canonical COTSpecialty code is required. |
emails (List) |
workplace.email |
email_1__v, email_2__v |
List of emails is flattened, with the highest-ranked ones being used. |
phones (List) |
workplace.telephone, workplace.fax |
phone_1__v to phone_3__v, fax_1__v to fax_2__v |
Similar to HCPs, the list is filtered by type (TEL.OFFICE vs. TEL.FAX) and ranked before mapping. |
4. Nested Object Mapping: Addresses
Address information is provided as a list of objects within the HCP or HCO DCR payload.
HUB /dcr addresses Attribute |
OneKey Mapping | Veeva OpenData (VOD) Mapping | Notes / Description |
|---|---|---|---|
| (Address Object) | Mapped to a single address complex object in the JSON request. Only the primary address is sent. |
Each address object is mapped to a separate row in the change_request_address.csv file. |
OneKey's API takes a single address per DCR, while Veeva's file-based approach can handle multiple address changes in one DCR. |
refId |
Used to match and update an existing address. | address_key |
This is the PfizerAddressID, a unique identifier for the address record in Reltio. |
addressLine1 |
address.longLabel or address.addressLine1 |
address_line_1__v |
The first line of the street address. |
addressLine2 |
address.longLabel2 or address.addressLine2 |
address_line_2__v |
The second line of the street address. |
city |
address.city |
locality__v |
The city name. |
stateProvince |
address.countyCode |
administrative_area__v |
The state or province. Requires a lookup from the canonical value to the target system's code. |
zip |
address.longPostalCode or address.Zip5 |
postal_code__v |
The postal or ZIP code. |
addressType |
Not explicitly mapped in submitVR request, but used in logic. |
address_type__v |
The type of address (e.g., Office, Home). Requires a lookup (AddressType). |
5. Nested Object Mapping: Affiliations
Affiliations are provided as a list of objects (contactAffiliations for HCP, otherHCOAffiliations for HCO) in the DCR payload.
HUB /dcr affiliations Attribute |
OneKey Mapping | Veeva OpenData (VOD) Mapping | Notes / Description |
|---|---|---|---|
| (Affiliation Object) | The refId of the target HCO is used to find its workplace.workplaceEid, which is then sent as part of the HCP or parent HCO record. |
Each affiliation object is mapped to a separate row in the change_request_parenthco.csv file. |
The mapping for affiliations is fundamentally different. OneKey handles it as an attribute of the child entity, while Veeva treats it as a distinct relationship record. |
Relation refId |
The workplace.workplaceEid of the target (parent) HCO is populated in the request. |
parenthco_key (populated with the Reltio relationUri) |
Veeva requires a unique key for the relationship itself. |
| Start/Child Object | The main body of the request contains the child's details (e.g., the HCP). | child_entity_key |
This field is populated with the entity_key of the child entity (e.g., the HCP). |
| End/Parent Object | The workplace.workplaceEid of the parent HCO is sent. |
parent_entity_key |
This field is populated with the entity_key of the parent entity (e.g., the HCO). |
type |
activity.role (requires lookup, e.g., TIH.W.*) |
relationship_type__v (requires lookup from RelationType) |
The type or role of the affiliation (e.g., Employed, Manages). |
primary |
Not explicitly mapped. | is_primary_relationship__v |
A boolean flag (Y/N) indicating if this is the primary affiliation. |