ICD: EPC IDCD Photo Fetch

Direction: EPC --> IDCD/Snaplogic (Outbound)

Version: 1.0

Date: 11 Feb 2026

Status: Implemented

---

Overview

EPC fetches employee ID card photos from the IDCD system via Snaplogic during member registration. The photo is decoded from base64 and uploaded to S3. This integration uses a separate set of PING credentials from the HRMS Employee/Dependant APIs.

---

Authentication

PING OAuth2.0 Client Credentials flow with Photo-specific credentials.

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-photo-ping-auth-basic
Credential Type photo (separate from hrms credentials)

---

Endpoint

Request

POST {baseUrl}/snaplogic/retter/stg/photo/api/1/rest/slsched/feed/ekg-stg/PLATINUMCARD/HR/photo_idcard_platinumcard_rts_TrigTask/v1.0
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "PHOTO_ID": "EK123456",
  "PHOTO_TYPE": "EMP"
}
Field Type Description
PHOTO_ID string Employee number (for EMP) or dependant serial number (for DEP)
PHOTO_TYPE string "EMP" for employee photo, "DEP" for dependant photo

Response (Success)

[
  {
    "membersphotoResponse": {
      "photodetails": {
        "authentication": "Success",
        "Picture": "/9j/4AAQSkZJRg...",
        "Remarks": "SUCCESS"
      }
    }
  }
]
Field Description
authentication "Success" if photo found
Picture Base64-encoded JPEG image
Remarks "SUCCESS" on success, error message on failure

Response (No Photo Available)

[
  {
    "membersphotoResponse": {
      "photodetails": {
        "authentication": "Failure",
        "Picture": "",
        "Remarks": "NO_PHOTO_FOUND"
      }
    }
  }
]

---

S3 Upload

After successful fetch, the base64 photo is decoded and uploaded to S3.

Parameter Value
Bucket Core stack files bucket
S3 Key members/{memberId}/hr-photo.jpg
Content-Type image/jpeg
Metadata source: hrms-idcd, photoId, photoType

The S3 key is stored in the member's idPhoto field, and idPhotoStatus is set to Approved.

---

Error Handling

Scenario Behavior
Photo not found (Remarks != SUCCESS) Return null (non-blocking)
Empty Picture field Return null (non-blocking)
API unavailable (503, timeout) Retry up to 3 times, then return null
401 Unauthorized Clear token cache, retry once
S3 upload failure Log error, return null

Photo fetch is non-blocking -- registration continues even if the photo cannot be retrieved.

---

Retry Strategy

Parameter Value
Max Retries 3
Retry Delay 5 seconds
Request Timeout 15 seconds (longer than other HRMS APIs due to photo payload size)
401 Handling Clear token cache, retry once
503 Handling Retry with backoff

---

Trigger

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

The photo fetch runs as a non-blocking operation -- if it fails, registration proceeds without the photo.

---

Source Files

File Purpose
src/lib/services/hrms-photo.service.ts Photo fetch, decode, and S3 upload
src/lib/services/hrms-auth.service.ts PING OAuth2.0 token (credential type: photo)
src/lib/entities/hr-integration.ts Type definitions (HrmsPhotoResponse)
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 (shared)
/platinum-api/{stage}/hrms-api-base-url String API base URL (shared)
/platinum-api/{stage}/hrms-photo-ping-auth-basic SecureString Base64 client credentials specific to Photo/Snaplogic API