Overview of Contact Ingest Service
- Search Duplicate service
Before creating a Contact, the user will be searched to find such similar record exist in the systems or not. If any such similar record found, the system will display to the user to use. If no record found or user want to still create another record he can continue doing it.
- Create/Update Customer Fields
Contact Audit Data
· User: xyz@gmail.com
· Source System: PRTL
Contact Entity
· Customer Code: IN03811814
· Contact Code: IN03811822
· First Name: Harshita
· Last Name: Saraswat
· Is Master Contact: Yes
· International First Name: Joey
· International Last Name: Tribbiani
· Primary Email ID: tom.cruise@maersk.com
· Secondary Email ID: dwayne.johnson@maersk.com
· Status Code: A
· International Salutation Code: 부인
· Primary Salutation Code: Mr.
· Is Team Contact: No
· Job Title: Data Steward
· Department: Export
· Role: CUST_CONT
· ISO Language Code Preference: EN
Communication Numbers
· Type: MOB
· ISO Country Code: IN
· International Dialing Code: +91
· Extension Number: 237
· Number: 8465888845
Contact Brands
· Brand Code: HSUD
· Brand Name: Hamburg Sud
· Is Deleted Flag: Yes
Contact Types
· Type Code: PORTAL
· Type Name: PORTAL
· Is Deleted Flag: Yes
Contact External System Identifiers
· External System Name: BPMA
· External System Reference: BPMAXXXXXX
· Is Deleted Flag: Yes
Document Preferences
· Customer Code: IN03811814
· Brand Code: MAEU
· Document Type: ARRVL_NTC
· Communication Preferences:
o Preference Media Type: OTH_EMAIL
o Preference Value: additional.email@maersk.com
o Is Deleted Flag: Yes
Complete Snapshot of Contact payload coming from elastic when user searches for a contact on the portal
{
"contactCode": "IN03812149",
"customerCode": "IN03812122",
"customerTradingName": "HIGHLIGHTER COMPANY",
"customerExternalSystemIdentifiers": \[
{
"externalSystemName": "MODS",
"externalSystemReference": "rpqs"
},
{
"externalSystemName": "SCV",
"externalSystemReference": "41003812122"
}
\],
"contactAuditData": \[
{
"creationUser": "[shreya.shree.s@maersk.com](mailto:shreya.shree.s@maersk.com)",
"creationDate": "2025-02-03T06:09:53.294Z",
"lastUpdateUser": "[shreya.shree.s@maersk.com](mailto:shreya.shree.s@maersk.com)",
"lastUpdateDate": "2025-02-03T06:09:53.294Z",
"sourceSystem": "PRTL"
}
\],
"firstName": "HARSHITA",
"lastName": "SARASWAT",
"primaryEmailId": "[admhsa191@crb.apmoller.net](mailto:admhsa191@crb.apmoller.net)",
"statusCode": "A",
"primarySalutationCode": "Miss",
"jobTitle": "INTERN",
"department": "SMDS",
"role": "CUST\_CONT",
"isoLanguageCodePreference": "EN",
"isMasterContact": true,
"isTeamContact": false,
"communicationNumbers": \[
{
"communicationNumberType": "MOB",
"isoCountryCode": "IN",
"internationalDialingCode": "91",
"number": "9378374484"
}
\],
"contactExternalSystemIdentifiers": \[
{
"externalSystemName": "SCV",
"externalSystemReference": "41003812149",
"isDeletedFlag": false
}
\]
}
| S No. | Attribute/Field | Mandatory | Data Type | Validation Details |
|---|---|---|---|---|
| 1 | Customercode | Y | Regex | ^[A-Z0-9*-]{3,11}$ |
| 2 | Contactcode | Regex | ^[A-Z0-9*-]{3,11}$ | |
| 3 | firstName | Regex | ^[a-zA-Z0-9 '-]{1,128}$ | |
| 4 | lastName | Y | Regex | ^[a-zA-Z0-9 '-]{1,128}$ |
| 5 | internationalFirstName | Characters | [1..128] characters | |
| 6 | internationalLastName | Characters | [1..128] characters | |
| 7 | primaryEmailId | Y | Characters | [0..300] characters, validated with Informatica service |
| 8 | secondaryEmailId | Characters | [0..300] characters, validate with Informatica service | |
| 9 | statusCode | Y | Enum | ["A", "I"] - must be A during creation |
| 10 | internationalSalutationCode | Regex | ^[^0-9]{1,50}$ | |
| 11 | primarySalutationCode | Regex | ^[a-zA-Z]{1,50}[\.]?$ | |
| 12 | isTeamContact | Boolean | ["true", "false"] - defaults to false | |
| 13 | jobTitle | Regex | ^[A-Za-z0-9 ]{0,50}$ | |
| 14 | department | Regex | ^[A-Za-z0-9 ]{0,128}$ | |
| 15 | role | Enum | ["CUST_CONT", "ON_BEHALF_OF"] | |
| 16 | isoLanguageCodePreference | Regex | ^[A-Z]{0,2}$ - Mandatory for contacts with type FINANCE | |
| 17 | communicationNumbers | Y | Array | Includes types "MOB", "TEL", "FAX" with validations for each subtype |
| 18 | contactBrands | Array | Contains brandCode (Regex ^[A-Z]{4}$), brandName optional | |
| 19 | contactTypes | Array | Contains typeCode (Regex ^[A-Za-z_ ]{2,20}$), typeName optional | |
| 20 | documentPreferences | Array | Links document types and brands; validated against CMD references |
- Creating a Customer Contact
Input Parameters:
- Customer Code (String): The code of the customer.
- Contact Request (ContactRequest): The payload containing the contact data.
- API Version (String): The version of the API being used.
Output:
- If Success: Indicates if the Contact creation was successful.
- Process Initialization:
· POST Request to Create Customer Contact:
o A POST request is initiated to create a new customer contact.
o The process begins by initializing the contact state, which sets the context for data validation and handling throughout the process.
- Contact Data Validation:
· Validation of Request:
o This validates the contact data with the predefined criteria.
o This includes the checking of the mandatory fields, correct data formats, and if it adheres to business rules.
o If the data validation fails, an internal server error or other exception is thrown, and the process stops.
- Customer Contact Validation Process Documentation
Validate Contact Service Documentation
Input Parameters:
- Customer Code (String): The code of the customer.
- Contact Request (ContactRequest): The payload containing the contact data.
- API Version (String): The version of the API being used.
Output:
- Validation Success: Indicates if the validation was successful.
- validateIngestRequest: Validates the ingestion request of a contact.
Parameters:
- urlContactCode (String): The contact code from the URL.
- urlCustomerCode (String): The customer code from the URL.
- contactRequest (ContactRequest): The payload containing contact data.
- contactInformation (ContactInformation): Existing type from the database.
- isBulkUpdate (boolean): Flag indicating if it's a bulk upload or not.
Process:
Initialization:
§ A list urlValidationErrors is initialized to store any validation errors related to URL parameters.
§ A boolean isUrlValid is initialized to track the validity of URL parameters.
o URL Validation:
§ Checks if the customer code and contact code in the URL match those in the contact request payload. Logs errors and stores them in urlValidationErrors if mismatches are found.
§ If any mismatches are detected and it's not a bulk update, a BadRequestException is thrown with the collected errors.
o Contact Validation:
§ If the contact code is provided in the request, it fetches the corresponding ContactInformation from the database.
- Calls validateContactAttribute method from contactValidationService to perform detailed validation of the contact attributes.
§ If validation errors are found, a BadRequestException is thrown with these errors.
| Validation Attribute | Description |
|---|---|
| Source System | This checks the origin of the contact data and ensures that it comes from an authorized source. |
| Custom Rules | This checks business rules and validations to ensure that data used is correct like Customer Code validation, Contact Code validation etc. |
| Communication | Verifies that communication details like phone numbers, dialling code and email addresses are valid and meet required formats and standards. |
| Emails | Confirms that email addresses are correctly formatted and checks their adherence to standard email configuration rules. |
| Contact Classifications | Ensures contact labels such as customer type or segmentation are correctly applied according to predefined classifications. |
| Primary International Salutations | Checks salutations and makes sure that they are appropriate and aligned with the regional settings. |
| Document Preferences | Ensures that the document preferences like language, format, and delivery methods are suitable for the contact. |
| Master Contact | For updates, this validation checks if the contact designated for update is a master contact. This prevents unintended alterations by non-primary updates. |
| ExternalSystem Identifiers | Ensures that identifiers used for linking the contact to external systems are not only present but also valid and unique. |
- Error Handling and Response
· Depending on the validation output, it responds with an error or validation of success.
· Responses:
o If there are validation errors, an exception is thrown, and it blocks the process.
o If no errors are found, a successful response is generated, showing that no errors occurred in the system, leading to an update as a result.
- Duplicate Contact Handling:
· Checking for Duplicates:
o This checks the duplicate contacts based on specified attributes like contact codes or other fields.
Like:
A contact is identified as a duplicate based on:
·Email Uniqueness: The contact is not considered a duplicate if the email differs, checked against both primary and alternative emails.
Exceptions
· Mobile Number Check: If the first name, last name, and mobile number match but emails differ, it's a duplicate.
· Telephone Check: If the first name, last name, and telephone match but emails differ, it's not a duplicate.
· Email Absence: If phone details match and one contact lacks an email while the other has one, mark as duplicate.
o If a duplicate is found, an exception is thrown, and the process stops.
o If no duplicates are found, the process moves to enrich the request payload.
- Contact Data Processing:
· Upsert Contact Data:
o Based on the validation and duplication checks, the contact data is either updated or inserted (upserted) into the database.
o This with the help of the upsert contact service process the contact data and commits it to the database.
UpsertContact Service
Methods
- Upsert Contact: This initiates the whole process of creation or update.
Process:
- Initializes a customer and upsert response to track the start of process:
- It extracts from the source system and the user information and sets the contact state.
- For create scenario: Calls preValidateCreateRequest.
- For update scenario: Calls preValidateUpdateRequest, this method also checks the status of the contact.
- Evaluation of Contact Upsert:
- Determining the action based upon the contact entity: It updates or creates based upon the presence of contact code and prevalidation results.
- Create Action: If it is a create scenario, it generates a unique contact code and inserts the contact.
- Update Action: It directly retrieves and sets the existing contact code from the contact entity to the contact state. It uses the existing information for the modification.
Helper Methods
PreValidate Update Request:
- Used when updating an existing contact.
- Addresses various scenarios for update:
- Master Contact Validation: If it is marked as a master contact, it validates it through the database to ensure that no conflicts occur.
- Status Change: Checks if the status has changed from (e.g., Inactive to Active), handles these transitions involving activation or inactivation status.
PreValidate Create Request:
- This method is called when a new contact is to be created.
- Status and Role Initialization: If the contact's status code or role is not specified, it sets them to active and default respectively.
- Master Contact Check: It checks if the customers have a master contact. If yes, avoids setting it as a master contact; if no, sets the contact as master.
- Language Preference: If no language preference is specified, it sets the preference according to the country code.
Validate Doc Pref Deletion:
· This mainly checks if any document or communication preference is to be deleted based on the update.
· Performance Deletion Logic: Compares existing preferences with the new request and identifies the preferences that are no longer required and deletes them.
· Communication Preference: Checks if the communication channels like telephone, mobile, fax are still available if required by existing preferences.
Validate Master Contact Switch:
·Master Contact Demotion: If a master contact is demoted, it updates the master status with all related records to ensure consistency.
Validate Contact Movement:
· Manages the logic when one contact is moved from one customer to another.
· Master Contact Movement: A master contact cannot be moved from one customer to another.
Synchronization and Publishing:
Sync and Publish Contact:
o Once the upsert is successful, the contact data is synchronized with external systems for consistency.
o The contact is then published and updates the information.
- Finalization:
Successful Contact Creation:
o If all steps are completed successfully without errors, the contact creation becomes successful.