ICD: EPC HRMS Dependant Details Fetch

Direction: EPC --> HRMS (Outbound)

Version: 1.3

Date: 20 Oct 2026

Status: Implemented

Changes in 1.3: The unused POST /members/register was removed (EPC-1295), and it was the trigger this document named. The Trigger section now names the live callers: the first SSO sign-in, retiree registration after the OTP, the back office "Update HRMS data" and the HR dependant push.

---

Overview

EPC fetches dependant details from HRMS at member registration and on the back office "Update HRMS data", when the employee record indicates IS_DEP_EXISTS = "Y". The dependants are stored on the member as family[] entries, which the app displays. The HR dependant push also looks them up, to fill fields the push left empty.

---

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,DEP_MIDDLE_NAMES,DEP_SEX,DEP_ADDR_LINE_1,DEP_ADDR_LINE_2,DEP_ADDR_LINE_3,DEP_ADDR_TYPE,DEP_TOWN_OR_CITY,DEP_POSTAL_CODE,DEP_COUNTRY

The columns from DEP_MIDDLE_NAMES onward were added in version 1.2 (EPC-1289). HRMS returns a requested column only when it has a value and omits it when empty; columns that are not requested come back as empty placeholders. So a column must be requested to carry data, and a missing or empty value never clears a value EPC already holds.

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_MIDDLE_NAMES": "Marie",
            "DEP_SEX": "Female",
            "DEP_ADDR_LINE_1": "Villa 12",
            "DEP_ADDR_LINE_2": "Al Wasl Road",
            "DEP_ADDR_TYPE": "CRD",
            "DEP_TOWN_OR_CITY": "Dubai",
            "DEP_COUNTRY": "AE"
          },
          {
            "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.
`DEP_MIDDLE_NAMES`	`middleName`	Middle name. Empty normalized to `null`. (1.2)
`DEP_SEX`	`gender`	`Male` / `Female` (also `M` / `F`) normalized to `male` / `female`; anything else is `null`. Required for a family member to be added as a dependant. (1.2)
`DEP_ADDR_LINE_1`, `DEP_ADDR_LINE_2`, `DEP_ADDR_LINE_3`, `DEP_TOWN_OR_CITY`, `DEP_POSTAL_CODE`	`address.address`	Joined in that order with ", ", empty parts skipped. (1.2)
`DEP_COUNTRY`	`address.country`	ISO alpha-2 code. A 2-3 character value that is not a known code or abbreviation is not stored (the HRMS UAT masking value `AN` is ignored). (1.2)
`DEP_ADDR_TYPE`	—	Requested for diagnostics. HRMS returns one `CRD` row per person; no type selection is applied. (1.2)

---

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 by four flows:

Flow	Handler	When
First SSO sign-in	`login-sso-callback`	The employee record has `IS_DEP_EXISTS = "Y"`
Retiree registration after the OTP	`verify-registration-otp`	The retiree record has `IS_DEP_EXISTS = "Y"`
Back office "Update HRMS data"	`resync-hrms-member`	The employee record has `IS_DEP_EXISTS = "Y"`
HR dependant push	`hr-update-dependant`	Only when the push leaves gender, middle name, address or phone empty, to fill those from the matching HRMS dependant. Best-effort: a failed lookup does not fail the push

At registration the dependants are stored as family[] entries on the new member. They are not auto-created as member records; the member adds each one from the app.

---

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/login-sso-callback/handler.ts`	Trigger: first SSO sign-in
`src/modules/member/verify-registration-otp/handler.ts`	Trigger: retiree registration
`src/modules/admin/resync-hrms-member/handler.ts`	Trigger: back office "Update HRMS data"
`src/modules/member/hr-update-dependant/handler.ts`	Trigger: HR dependant push

---

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