ICD: EPC HRMS Employee Details Fetch

Direction: EPC --> HRMS (Outbound)

Version: 1.0

Date: 11 Feb 2026

Status: Implemented

---

Overview

EPC fetches employee details from HRMS during member registration to validate and pre-populate member data. Two endpoints are used:

• Active Employee -- lookup by employee number (staff ID)
• Retiree -- fallback lookup by email address

Authentication

All requests are authenticated via PING OAuth2.0 Client Credentials flow.

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
Token TTL	2 hours (refreshed 10 min before expiry)
Token Cache	In-memory (per Lambda instance)

Token Request

POST {tokenUrl}
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {hrms-ping-auth-basic}
Cache-Control: no-cache

grant_type=client_credentials

Token Response

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 7200
}

---

Endpoint 1: Active Employee Details

Request

GET {baseUrl}/platinum/erp/webservices/rest/EmployeeDetails/getEmployeeDetails/{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	User input (staffId)	URL-encoded employee number
fields	Static	See Fields Requested below

Fields Requested

STAFFNR,EMAIL,MOBILE,EMP_NAME,LAST_NAME,GRADE,PERSON_TYPE,STATUS,WORK_LOCAITON,BG_NAME,CRA,TERM_DATE,DOB,PREV_EMP_NUM,CORE_GRADE,DEP_EXITS,LEAV_RES

Response (Success)

{
  "getEmployeeDetails_Output": {
    "OutputParameters": {
      "Output": {
        "employeeResponse": [
          {
            "EMPLOYEE_NUMBER": "EK123456",
            "EMAIL_ID": "john.doe@emirates.com",
            "MOBILE": "+971501234567",
            "NAME": "John",
            "LAST_NAME": "Doe",
            "GRADE_CODE": "EK.07",
            "EMPLOYEE_TYPE": "EMP",
            "ACTIVE_STATUS": "Active Assignment",
            "WORKLOCATION": "Dubai Airport Free Zone",
            "BG_COUNTRY": "Emirates Group - UAE",
            "CURRENT_RES_ADDRESS": "Dubai, UAE",
            "ACTUAL_TERMINATION_DATE": "",
            "DATE_OF_BIRTH": "1990-01-15",
            "PREV_EMP__ID": "",
            "IS_DEP_EXISTS": "Y",
            "CORE_GRADE": "EK.07",
            "LEAVING_REASON": ""
          }
        ]
      }
    }
  }
}

---

Endpoint 2: Retiree Details (by Email)

Used as fallback when the active employee endpoint returns no results.

Request

GET {baseUrl}/platinum/erp/webservices/rest/EmpDetailsByEmail/getEmpDetailsbyEmail/?emailID={email}&fields={fields}
Authorization: Bearer {access_token}
Accept: application/json

Response (Success)

{
  "getEmpDetailsbyEmail_Output": {
    "OutputParameters": {
      "Output": {
        "employeeResponse": [
          {
            "EMPLOYEE_NUMBER": "EK123456",
            "ACTIVE_STATUS": "Terminate - Process",
            "LEAVING_REASON": "Retirement",
            "ACTUAL_TERMINATION_DATE": "2025-12-31",
            ...
          }
        ]
      }
    }
  }
}

---

Field Mapping

HRMS Field	EPC Field	Notes
EMPLOYEE_NUMBER	employeeId / staffId	Primary identifier
EMAIL_ID	email
MOBILE	phone
NAME	name
LAST_NAME	surname
GRADE_CODE	grade
EMPLOYEE_TYPE	employmentType / memberType
ACTIVE_STATUS	status	See Status Mapping below
WORKLOCATION	addressOptional
BG_COUNTRY	country / address.country
CURRENT_RES_ADDRESS	address
ACTUAL_TERMINATION_DATE	lastDayOfService	Null if empty
DATE_OF_BIRTH	birthdate
PREV_EMP__ID	oldStaffId / previousStaffIds	Null if empty
IS_DEP_EXISTS	dependantsExists	"Y" or "N"
CORE_GRADE	coreGrade
LEAVING_REASON	leavingReason	Null if empty

Status Mapping

HRMS `ACTIVE_STATUS`	Allowed for Registration
Active Assignment	Yes
Terminate - Process with LEAVING_REASON = "Retirement"	Yes (retiree)
Any other terminated/inactive status	No -- rejected with HR_EMPLOYEE_NOT_ACTIVE

---

Error Handling

Scenario	HTTP Status	Behavior
Employee not found (active + retiree)	N/A	Return HR_EMPLOYEE_NOT_FOUND_IN_HRMS (10080)
Employee not active	N/A	Return HR_EMPLOYEE_NOT_ACTIVE (10081)
HRMS unavailable (503, timeout, HTML)	503	Return HR_HRMS_UNAVAILABLE (10079)
ISGServiceFault	Varies	Retry up to 3 times, then fail
401 Unauthorized	401	Clear token cache, retry once

ISGServiceFault Response

{
  "ISGServiceFault": {
    "Code": "500",
    "Message": "Internal Server Error"
  }
}

HTML 503 Response

HRMS may return HTML (Weblogic bridge failure) instead of JSON on 503. Detected via Content-Type: text/html.

---

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 synchronously during member registration (register-member handler) when the registrant's email domain matches emirates.com or danat.com.

Flow

• Try getEmployeeByNumber(staffId) (active endpoint)
• If null, try getEmployeeByEmail(email) (retiree endpoint)
• If found, validate status (active or retired with valid reason)
• Pre-populate member fields from HRMS data
• Set hrmsValidated: true on the member record

---

Source Files

File	Purpose
src/lib/services/hrms-auth.service.ts	PING OAuth2.0 token management
src/lib/services/hrms-employee.service.ts	Employee fetch with retry logic
src/lib/mappers/hrms-employee.mapper.ts	Raw response to domain model mapping
src/lib/entities/hr-integration.ts	Type definitions (HrmsEmployeeRaw, HrmsEmployee)
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