ICD: EPC HRMS Member Confirmation (SIT)

Direction: EPC --> HRMS (Outbound Push)

Version: 1.0

Date: 11 Feb 2026

Status: Implemented

---

Overview

When an admin activates an HRMS-validated member, EPC pushes a SIT (Special Information Type) confirmation record to HRMS. This records the Employee ID Card issuance in the Oracle HR system.

The confirmation is sent asynchronously via SQS to avoid blocking the admin activation flow.

---

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

POST {baseUrl}/platinum/erp/webservices/rest/xxSITService/process_sit/v1.0
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "PROCESS_SIT": {
    "RESTHeader": {},
    "InputParameters": {
      "P_REQUEST": {
        "P_MODE": "CREATE",
        "P_SIT_NAME": "Employee ID Card",
        "P_EMPLOYEE_ID": "EK123456",
        "P_BUSINESS_GROUP_ID": "61",
        "P_EFFECTIVE_DATE": "11-FEB-2026",
        "P_DATE_FROM": "11-FEB-2026",
        "P_SEGMENT_1": "EPC",
        "P_SEGMENT_3": "11-FEB-2026",
        "P_SEGMENT_4": "31-DEC-4712",
        "P_SEGMENT_6": "Open"
      }
    }
  }
}

Field Descriptions

Field Value Description
P_MODE "CREATE" Always CREATE for new SIT records
P_SIT_NAME "Employee ID Card" Static -- identifies the SIT type
P_EMPLOYEE_ID Dynamic Employee number from HRMS
P_BUSINESS_GROUP_ID SSM config From SSM: /platinum-api/{stage}/hrms-sit-business-group-id (default: "61")
P_EFFECTIVE_DATE Dynamic Approval date in DD-MMM-YYYY format
P_DATE_FROM Dynamic Same as effective date
P_SEGMENT_1 "EPC" Static -- identifies the source system
P_SEGMENT_3 Dynamic Same as effective date
P_SEGMENT_4 "31-DEC-4712" Static -- far-future end date (Oracle convention)
P_SEGMENT_6 "Open" Static -- status

Date Format

All dates use the format DD-MMM-YYYY where month is a 3-letter uppercase abbreviation:

---

Async Flow

Admin activates member (activate-member handler)
  --> Checks member.staffId && member.hrmsValidated
  --> Sends SQS message to notification queue:
      {
        "type": "sit_confirmation",
        "memberId": "...",
        "staffId": "...",
        "approvalDate": "2026-02-11T10:30:00.000Z"
      }
  --> notify-hr-registration handler picks up message
  --> Calls confirmMemberRegistration()
  --> Logs result to HrSyncLog (DynamoDB)
  --> Creates audit log entry

SQS Message Schema

{
  "type": "sit_confirmation",
  "memberId": "550e8400-e29b-41d4-a716-446655440000",
  "staffId": "EK123456",
  "approvalDate": "2026-02-11T10:30:00.000Z"
}

---

Error Handling

Scenario Behavior
API unavailable (503, timeout, HTML) Retry up to 3 times
401 Unauthorized Clear token cache, retry once
500 Internal Error Do NOT retry (POST is not idempotent)
Any failure after retries Log to HrSyncLog as failure, rethrow for SQS retry/DLQ

Non-Idempotent Safety

The SIT API is a POST that creates records. A 500 response may mean the record was partially created. To avoid duplicates, 500 errors are not retried at the application level. SQS retry/DLQ handles persistent failures.

---

Retry Strategy

Parameter Value
Max Retries 3 (application-level)
Retry Delay 5 seconds
Request Timeout 10 seconds
401 Handling Clear token cache, retry once
503 Handling Retry with backoff
500 Handling No retry -- rethrow immediately
SQS Retry Standard SQS visibility timeout + DLQ after max receives

---

Audit Trail

HrSyncLog Entry

On success:

{
  "operation": "update_member_id",
  "staffId": "EK123456",
  "memberId": "550e8400-...",
  "status": "success",
  "responseData": { "approvalDate": "2026-02-11T10:30:00.000Z" }
}

On failure:

{
  "operation": "update_member_id",
  "staffId": "EK123456",
  "memberId": "550e8400-...",
  "status": "failure",
  "errorMessage": "SIT API internal error (500): ...",
  "requestData": { "approvalDate": "2026-02-11T10:30:00.000Z" }
}

Audit Log Entry

{
  "entityType": "member",
  "entityId": "550e8400-...",
  "action": "sit-confirmation-sent",
  "actor": { "id": "hr-system", "email": "hr-integration@system", "type": "system" },
  "additionalData": { "event": "sit-confirmation-sent", "staffId": "EK123456", "approvalDate": "..." }
}

---

Source Files

File Purpose
src/lib/services/hrms-sit.service.ts SIT confirmation POST with retry logic
src/modules/member/notify-hr-registration/handler.ts SQS consumer (routes sit_confirmation messages)
src/modules/member/activate-member/handler.ts SQS producer (queues SIT message on activation)
src/lib/entities/hr-integration.ts Type definitions (HrmsSitRequest)

---

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
/platinum-api/{stage}/hrms-sit-business-group-id String Business group ID for SIT records (default: "61")