Directory API의 개요
조직연동
조직 연동이란 고객사의 조직 정보를 NAVER WORKS의 조직 정보와 동기화시키는 작업을 의미한다. Directory API를 이용하면, 고객사의 조직정보를 NAVER WORKS의 조직 정보와 동기화 할 수 있다.
조직 연동을 사용하려면 아래와 같은 준비가 필요하다. 자세한 내용은 API 2.0의 Using APIs을 참고한다.
- Directory scope를 포함하는 클라이언트 앱
- 서비스 계정
- Developer Console의 조직연동 설정 (선택)
조직연동 메뉴
Developer Console 조직연동 설정메뉴에서 아래와 같은 설정을 할 수 있습니다.
조직 연동 사용 설정
연동하고자 하는 항목(조직/구성원, 직급/직책, 그룹, 고용형태, 사용언어, 상태)을 On으로 설정할 수 있다. 구성원의 회사 겸직을 설정하려면 겸직 도메인도 조직 연동 사용 설정을 On으로 설정해야 한다. 조직 연동 설정 시 서비스에서 다음과 같은 기능이 제한된다.
조직 연동 항목 설정에 따른 Admin의 동작
- 조직연동 설정 On으로 적용하면, ‘승인대기’ 중인 구성원은 모두 삭제되고 Admin > 구성원초대기능도 [사용 안함]으로 자동 설정된다.
- 조직/구성원을 On으로 설정하면 NAVER WORKS Admin에서 구성원과 조직을 조회만 할 수 있다. 팀 사용 기능을 허용하도록 선택하면 NAVER WORKS Admin에서 팀 사용 기능의 사용 여부를 설정할 수 있다.
- 직급/직책을 On으로 설정하면 NAVER WORKS Admin에 구성원 > 직급/직책이 노출되지 않는다.
- 그룹을 On으로 설정하면 NAVER WORKS Admin에서 그룹 기본 정보를 수정할 수 없다. 그룹 사용 기능을 허용하도록 선택하면 NAVER WORKS Admin에서 그룹 사용 기능의 사용 여부를 설정할 수 있다.
- 고용 형태를 On으로 설정하면 NAVER WORKS Admin에 구성원 > 고용형태가 노출되지 않는다.
조직 연동 항목 설정에 따른 구성원의 NAVER WORKS의 동작
- 조직/구성원을 On으로 설정하면 구성원이 프로필 사진을 직접 편집할 수 있도록 허용하거나 허용하지 않을 수 있다.
- 사용언어를 On으로 설정하면 구성원이 언어·시간대항목을 설정할 수 없다.
- 상태 연동을 On으로 설정하면 구성원이 상태항목을 설정할 수 없다.
조직 연동 항목 접근
조직, 구성원, 그룹, 고용형태, 직급, 직책, 상태을 구성하는 각각의 항목은 아래와 같은 방법으로 식별하거나 접근할 수 있다.
리소스 ID를 사용 (권장)
조직, 구성원, 그룹, 고용형태, 직급, 직책, 상태의 각 항목 생성시 자동으로 발급되는 리소스 ID를 통해 접근할 수 있다.External Key 를 Mapping하여 사용
조직, 구성원, 그룹, 고용형태, 직급, 직책, 상태의 각 항목을 연동할수 있는 ID를 추가로 지정하여 사용중인 그룹웨어 정보와 연결할 수 있다. External Key는 특수문자 %와 \는 허용하지 않으며 항목 별로 중복조건이 다르다.조직, 구성원, 그룹, 고용형태 : 테넌트내에 유일해야한다.
- 직급, 직책 : 도메인내에서 유일해야 한다.
Directory API는 리소스 ID 또는 External Key Mapping 를 사용하여 접근할 수 있다.
주의
API 1.0은 External Key를 통한 접근만을 지원하며, 사용전 반드시 각 리소스에 External Key Mapping을 마친 후 사용하여야 한다.
External Key Mapping 방법
항목별 전체 정보를 다운로드 받아 수정한 후 다시 등록하여 Mapping할 수 있습니다.
- Developer Console 조직연동을 선택합니다.
- 각 External Key Mapping 항목의 ’다운로드’를 클릭합니다.
- 다운로드 받은 .csv파일에 External Key 항목을 입력한 후 저장합니다.
- ’파일첨부’를 클릭하여 파일을 등록합니다.
- 파일을 등록하면 미리보기 화면에서 확인하고 중복된 External Key를수정할수 있습니다.
- 하단의 ‘저장’을 클릭합니다.
Custom URL 설정
조직도 팝업, 메일 주소록, 개인정보 팝업에서 지정된 URL에 해당하는 화면을 표시한다. 팝업으로 표시할 경우 구성원 이름을 #SEARCHTEXT# 파라미터에 포함하여 제공한다.
참고
Custom URL 은 조직연동 및 API 설정과 관계없이 설정할 수 있다.
조직 정보 배치작업시 주의사항
조직연동 사용 준비를 마쳤으면, Directory API를 사용할 수 있다.
- Directory API를 사용한 조직연동 배치작업은 아래와 같이 직책/직급/고용형태 → 조직 → 구성원 → 그룹 순서로 진행할 것을 권장한다.
그림 1 조직 연동 배치
- 조직 연동은 일(day) 단위 배치로 실행할 것을 권장한다.
- 각 단계에서 실패 시 롤백 프로세스는 자사의 정책에 맞게 적용한다. 단, 한 단계 안에서 일부가 실패했을 때(조직 중 일부가 실패)는 계속 진행하고, 한 단계 전체가 실패하면(조직 전체가 실패) 배치를 중단할 것을 권장한다. (예를 들어, 구성원을 추가하기 전에 소속될 조직을 세팅하여야 한다)
- API를 동시에 5회 이상 호출하지 않도록 관리하며 특히, 조직관련 API는 단일 스레드로 호출해야 한다.
- 구성원 수정과 그룹 수정 등 수정 API 호출 시 업데이트가 발생한 정보만 연동하여 데이터 변경이 없는 항목을 연동하여 불필요한 비용을 높이는 것을 방지할 수 있다. (예: 부분 조직 개편으로 일부 조직 이름이 변경되었지만 전체 조직을 연동함)
- 호출에 실패한 API요청은 반드시 방어 로직을 구현해야 한다.
- API 요청 실패를 감지할수 있도록 로그관리 혹은 모니터링 시스템을 함께 구축할 필요가 있다.