ICD: EPC IDCD Photo Fetch

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

Version: 1.1

Date: 20 Oct 2026

Status: Implemented

Changes in 1.1: The unused POST /members/register was removed (EPC-1295), and it was the trigger this document named. The Trigger section now describes the live path: the photo-fetch-queue consumer, and the flows that queue it.

---

Overview

EPC fetches employee ID card photos from the IDCD system via Snaplogic at member registration, on the back office "Update HRMS data", and on a back office photo refetch. 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 by the fetch-employee-photo consumer of the SQS photo-fetch-queue. These flows queue a fetch:

Flow	Handler
First SSO sign-in	`login-sso-callback`
Retiree registration after the OTP	`verify-registration-otp`
Back office "Update HRMS data"	`resync-hrms-member`
Back office photo refetch	`refetch-id-photo`

The photo fetch is non-blocking: the flows queue it and return, and registration proceeds without the photo if the fetch fails.

---

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/fetch-employee-photo/handler.ts`	Trigger: `photo-fetch-queue` consumer

---

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