ICD: EPC HRMS Dependant Details Fetch

Direction: EPC --> HRMS (Outbound)

Version: 1.1

Date: 14 Jun 2026

Status: Implemented

---

Overview

EPC fetches dependant details from HRMS during member registration when the employee record indicates IS_DEP_EXISTS = "Y". The dependant list is returned in the registration response for the front-end to display.

---

Authentication

Same as Employee Details Fetch -- PING OAuth2.0 Client Credentials with credential type hrms.

Parameter	Value
Token URL	SSM: /platinum-api/{stage}/hrms-ping-token-url
Grant Type	client_credentials
Auth Header	Basic {base64} from SSM: /platinum-api/{stage}/hrms-ping-auth-basic

---

Endpoint

Request

GET {baseUrl}/platinum/erp/webservices/rest/DependantDetails/getDependantDetails/?employeeNumber={employeeNumber}&fields={fields}
Authorization: Bearer {access_token}
Accept: application/json

Parameter	Source	Description
baseUrl	SSM: /platinum-api/{stage}/hrms-api-base-url	e.g. https://stgservices.emirates.dev
employeeNumber	From Employee Details response	URL-encoded employee number
fields	Static	See Fields Requested below

Fields Requested

DEP_PERSON_ID,DEP_CONTACT_TYPE,DEP_FIRST_NAME,DEP_LAST_NAME,DEP_CONTACT_EMAIL_ADDR,DEP_DATE_OF_BIRTH,DEP_MOBILE,STATUS,DEP_CONTACT_STATUS

STATUS is the preferred contact-status column; DEP_CONTACT_STATUS is requested as a fallback for HRMS responses that do not yet populate STATUS (see Field Mapping).

Response (Success)

{
  "getDependantDetails_Output": {
    "OutputParameters": {
      "Output": {
        "dependantResponse": [
          {
            "DEP_PERSON_ID": "12345",
            "DEP_CONTACT_TYPE": "Wife",
            "DEP_FIRST_NAME": "Jane",
            "DEP_LAST_NAME": "Doe",
            "DEP_CONTACT_EMAIL_ADDR": "jane.doe@example.com",
            "DEP_DATE_OF_BIRTH": "1995-05-15",
            "DEP_MOBILE": "+971501234567",
            "STATUS": "Active",
            "DEP_CONTACT_STATUS": "Active"
          },
          {
            "DEP_PERSON_ID": "12346",
            "DEP_CONTACT_TYPE": "Son",
            "DEP_FIRST_NAME": "Adam",
            "DEP_LAST_NAME": "Doe",
            "DEP_CONTACT_EMAIL_ADDR": "adam.doe@example.com",
            "DEP_DATE_OF_BIRTH": "2010-03-20",
            "DEP_MOBILE": "",
            "STATUS": "Active",
            "DEP_CONTACT_STATUS": "Active"
          }
        ]
      }
    }
  }
}

Response (No Dependants)

Returns empty dependantResponse array or null. EPC returns an empty array [].

---

Field Mapping

HRMS Field	EPC Field	Notes
DEP_PERSON_ID	id	Dependant person ID (unique)
DEP_CONTACT_TYPE	type	Relationship type (Wife, Son, Daughter, etc.)
DEP_FIRST_NAME	name	First name
DEP_LAST_NAME	surname	Last name
DEP_CONTACT_EMAIL_ADDR	email	Email address. Empty/whitespace normalized to null.
DEP_DATE_OF_BIRTH	birthdate	Date of birth (ISO 8601)
DEP_MOBILE	phone	Mobile number. Empty/whitespace normalized to null.
STATUS / DEP_CONTACT_STATUS	contactStatus	Contact status. STATUS is preferred; falls back to DEP_CONTACT_STATUS when STATUS is missing or an empty string.

---

Error Handling

Scenario	HTTP Status	Behavior
No dependants found	N/A	Return empty array (not an error)
HRMS unavailable (503, timeout)	503	Retry up to 3 times, then throw
401 Unauthorized	401	Clear token cache, retry once
HTML response (Weblogic)	N/A	Treat as 503, retry

---

Retry Strategy

Parameter	Value
Max Retries	3
Retry Delay	5 seconds
Request Timeout	10 seconds
401 Handling	Clear token cache, retry once
503 Handling	Retry with backoff

---

Trigger

Called during member registration (register-member handler) when:

• The registrant's email domain matches emirates.com or danat.com
• The employee record from HRMS has IS_DEP_EXISTS = "Y"

The dependant list is returned in the hrmsDependants field of the registration response. Dependants are not auto-created as member records -- the front-end displays them for the user to add individually.

---

Source Files

File	Purpose
src/lib/services/hrms-dependant.service.ts	Dependant fetch with retry logic
src/lib/mappers/hrms-dependant.mapper.ts	Raw response to domain model mapping
src/lib/entities/hr-integration.ts	Type definitions (HrmsDependantRaw, HrmsDependant)
src/modules/member/register-member/handler.ts	Integration trigger point

---

SSM Parameters

Parameter	Type	Description
/platinum-api/{stage}/hrms-ping-token-url	String	PING OAuth2.0 token endpoint
/platinum-api/{stage}/hrms-api-base-url	String	HRMS API base URL
/platinum-api/{stage}/hrms-ping-auth-basic	SecureString	Base64 client credentials for HRMS APIs