SFTP - 인사 데이터 전송 방법 안내

생성자 Ashish Chaudhary, 수정일 토, 4 10월 시간: 12:52 PM : Ashish Chaudhary

SFTP - 인사(HR) 데이터 연동 가이드

SFTP - 인사(HR) 데이터 연동 가이드

개요

SFTP 관련 일반 안내 및 자세한 정보는 SFTP - 설정 가이드에서 확인하실 수 있습니다.

Spotnana 사용자는(출장자, 예약 담당자, 승인자 등) Spotnana 온라인 예약 시스템(OBT)에 프로필이 등록되어 있어야 여행 예약이 가능합니다. 신규 입사자에게는 접근 권한이 부여되고, 퇴사자의 경우 접근이 해제되도록 프로필 정보를 항상 최신 상태로 유지해주셔야 합니다(신규 생성, 수정, 삭제 등). Spotnana에서는 보고 체계나 소속 법인 등 HR 데이터를 활용해 다양한 정책, 승인, 결제 설정 등을 관리합니다.

정확한 정보 반영을 위해 HR 피드 파일을 CSV 형식으로 Spotnana 서버에 업로드해 주셔야 합니다. 업로드 주기는 원하는 대로 설정하실 수 있으며, 파일이 도착하면 Spotnana에서 즉시 처리합니다.

참고: Spotnana는 Bamboo HR, ADP Workforce Now, Workday 등 여러 HR 시스템과의 직접 연동도 지원합니다.

시스템 구조 및 처리 흐름

아래 다이어그램은 여러 고객사가 SFTP를 통해 HR 데이터를 Spotnana로 업로드하는 상황을 예시로 보여줍니다.

업로드 방법

이 섹션에서는 파일 업로드가 원활하게 진행될 수 있도록 참고하실 만한 정보를 안내합니다.

HR 피드 파일 처리 방식

사용자 식별을 위해 주로 활용되는 필드는 Employee ID입니다.

참고: 특정 상황에서는 Spotnana에서 Business Email 을(를) 직원 식별자로 사용할 수 있습니다. 다만, 이 경우 몇 가지 제한사항이 있습니다. 예를 들어, 사용자의 Business Email이 변경될 경우(이름 변경, 회사 이전 등으로 도메인 변경 등), 기존 계정이 비활성화되고 해당 직원의 새 계정이 생성됩니다.

CSV 파일의 데이터를 처리하는 방식은 다음과 같습니다.

사용자 행의 ACTION 값이 CREATE 이고, Spotnana 데이터베이스에 해당 Employee ID 또는 Business Email 이(가) 없는 경우, Spotnana에 새로운 사용자 프로필이 생성됩니다.
사용자 행의 ACTION 값이 UPDATE 이고, Spotnana 데이터베이스에 Employee ID 또는 Business Email 이(가) 이미 존재하면, 해당 사용자의 Spotnana 프로필이 파일 내 새로운 정보로 업데이트됩니다.
- 참고: 이전 업로드에서 입력했던 선택 항목이 이후 업데이트 파일에 빠져 있다면, 해당 값은 프로필에서 삭제됩니다.
사용자 행의 ACTION 값이 DELETE 이고, Spotnana 데이터베이스에 Employee ID 또는 Business Email 이(가) 일치하는 경우, 해당 사용자 프로필이 비활성화됩니다. 만약 일치하는 정보가 없다면 해당 행은 건너뛰고 별도의 처리는 하지 않습니다. Employee ID 또는 Business Email이(가) 없을 경우, 해당 행은 무시됩니다.

참고: 각 사용자 프로필은 반드시 하나의 법인(Legal Entity)과 연결되어야 합니다. 이 법인은 사용자 프로필을 업로드하기 전에 Spotnana에 미리 등록되어 있어야 하며, 사무실(Office)은 선택 사항입니다. 만약 업로드하는 사용자 중 사무실 정보가 포함되어 있다면, 해당 사무실 정보도 Spotnana에 미리 등록되어 있어야 합니다.

파일 형식 및 명명 규칙

.CSV HR 피드 파일 이름은 다음 형식을 따라야 합니다.

hr_feed.*.csv

*에는 원하는 문자를 자유롭게 넣을 수 있습니다. 단, "feed" 뒤와 "csv" 앞의 점(.)은 반드시 포함되어야 하며, 대소문자는 구분하지 않습니다. 추후 문제 해결을 쉽게 하기 위해 파일 이름에 날짜와 시간을 포함하는 것을 권장합니다. 예시:

hr_feed.spotnana_integration_<DateTime>.csv

또한 .CSV 피드 파일은 정해진 포맷을 따라야 하며, 컬럼명도 반드시 지정된 형식과 일치해야 합니다(자세한 내용은 HR 파일 포맷 섹션에서 확인하실 수 있습니다). 파일 포맷에 대한 추가 정보는 부록 1을 참고하세요.

일부 데이터는 반드시 유효성 검증 기준을 따라야 합니다(자세한 내용은 HR 파일 포맷 섹션을 참고해주세요).

업로드 주기 및 스케줄 관리

업로드 주기 및 스케줄 관련 자세한 정보는 업로드 주기 및 스케줄 관리 섹션에서 SFTP - 설정 가이드를 참고하세요.

최소한 하루에 한 번 업로드하실 것을 권장합니다. 이렇게 하면 신규/수정/삭제된 인사 정보를 Spotnana에 신속히 반영할 수 있습니다. 이 기준을 지키면:

신규 입사자는 근무 시작일에 Spotnana 프로필이 생성되어 바로 출장 예약이 가능합니다(파일에 해당 직원이 포함되어 있을 경우).
퇴사자는 마지막 근무일에 접근 권한이 해제됩니다(파일에서 해당 직원을 삭제하신 경우).

HR 파일 포맷

아래 정보를 참고하셔서 HR 피드 업로드 시 데이터가 올바른 형식으로 준비되었는지 확인해 주세요.

참고: Spotnana에서 파일을 처리하기 전에 반드시 귀사의 공개 SSH 키를 전달해주시고, SFTP 폴더가 사전에 설정되어 있어야 합니다.

컬럼명	필수 / 선택	비고
Action	필수	각 행마다 “CREATE”, “UPDATE”, “DELETE” 중 하나로 지정해야 하며, 이 값에 따라 해당 행의 정보가 어떻게 처리될지 결정됩니다.
Employee ID	선택	Employee ID 사용을 권장합니다. 만약 Employee ID가 없다면 Business Email이 사용됩니다. Employee ID는 한 명의 사용자에게만 부여되어야 하며, 중복될 수 없습니다.
First Name	필수
Middle Name	선택
Family Name 1	필수
Family Name 2	선택
Business Email	필수
Business Phone ISO Country Code	조건부	ISO 2자리 국가 코드("US", "IN" 등)
Business Phone Country Code	조건부	숫자 형태의 국가 코드이며, 특수문자('+')는 포함하지 않습니다. 예시: “91”
Business Phone Extension	선택
Business Phone Number	조건부	필수 항목은 아니지만, 입력할 경우 ISO 국가 코드와 국가 코드도 함께 입력해야 합니다(위의 조건부 항목 참고). 숫자만 입력 가능하며, 4~10자리여야 하고, 하이픈 등 특수문자는 사용할 수 없습니다.
Office Name	선택	HR 피드의 Office Name 값은 Spotnana 온라인 예약 시스템 UI에 등록된 사무실 이름과(마침표, 쉼표, 공백 등 특수문자 포함) 정확히 일치해야 합니다. 예를 들어, 사무실 이름이 “Paris, France (main office)”로 등록되어 있다면, HR 피드의 Office Name값도 반드시 동일해야 합니다. 만약 “Paris, France” 또는 “Paris (main office)”로 입력하면 오류가 발생합니다. 참고: 모든 사무실 정보는 HR 피드 업로드 전에 Spotnana 온라인 예약 시스템에 미리 등록되어 있어야 합니다. 자세한 내용은 사무실 정보 업로드를 참고하세요.
Manager's Employee ID	선택	Manager's Email Address 는 필수 항목입니다. 만약 매니저도 Employee ID (귀사에서 Employee ID를 사용하는 경우) Manager's Email Address 와 Manager's Employee ID 모두 입력해야 합니다.
Manager's Email Address	필수	Manager's Email Address 는 필수 항목입니다. 만약 매니저도 Employee ID (귀사에서 Employee ID를 사용하는 경우) Manager's Email Address 와 Manager's Employee ID 모두 입력해야 합니다.
Department	선택
Position Title / Designation	선택	예시 값: “VP”, “CEO”, “CFO” 등
Cost Center	선택
Legal Entity Name	필수	HR 피드의 Legal Entity Name 값은 Spotnana 온라인 예약 시스템 UI에 등록된 법인명과(마침표, 쉼표, 공백 등 특수문자 포함) 정확히 일치해야 합니다. 예를 들어, 법인명이 “Spotnana Technology, LLC”로 등록되어 있다면, HR 피드의 Legal Entity Name값도 반드시 동일해야 합니다. 만약 “Spotnana Technology LLC” 또는 “Spotnana Technology”로 입력하면 오류가 발생합니다. 참고: 모든 법인 정보는 HR 피드 업로드 전에 Spotnana 온라인 예약 시스템에 미리 등록되어 있어야 합니다. 자세한 내용은 법인 정보 업로드를 참고하세요.
Grade	선택
Country Code	선택	ISO 2자리 또는 3자리 국가 코드("US" 또는 "USA" 등)
Worker Type	선택	예시 값: “Employee”, “Contingent”, “Intern”, “Seasonal” 등
Accounting Code	선택