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할 수 있습니다.

    1. Developer Console 조직연동을 선택합니다.
    2. 각 External Key Mapping 항목의 ’다운로드’를 클릭합니다.
    3. 다운로드 받은 .csv파일에 External Key 항목을 입력한 후 저장합니다.
    4. ’파일첨부’를 클릭하여 파일을 등록합니다.
    5. 파일을 등록하면 미리보기 화면에서 확인하고 중복된 External Key를수정할수 있습니다.
    6. 하단의 ‘저장’을 클릭합니다.

    Custom URL 설정

    조직도 팝업, 메일 주소록, 개인정보 팝업에서 지정된 URL에 해당하는 화면을 표시한다. 팝업으로 표시할 경우 구성원 이름을 #SEARCHTEXT# 파라미터에 포함하여 제공한다.

    참고

    Custom URL 은 조직연동 및 API 설정과 관계없이 설정할 수 있다.

    조직 정보 배치작업시 주의사항

    조직연동 사용 준비를 마쳤으면, Directory API를 사용할 수 있다.

    • Directory API를 사용한 조직연동 배치작업은 아래와 같이 직책/직급/고용형태 → 조직 → 구성원 → 그룹 순서로 진행할 것을 권장한다.

    ALT

    그림 1 조직 연동 배치

    • 조직 연동은 일(day) 단위 배치로 실행할 것을 권장한다.
    • 각 단계에서 실패 시 롤백 프로세스는 자사의 정책에 맞게 적용한다. 단, 한 단계 안에서 일부가 실패했을 때(조직 중 일부가 실패)는 계속 진행하고, 한 단계 전체가 실패하면(조직 전체가 실패) 배치를 중단할 것을 권장한다. (예를 들어, 구성원을 추가하기 전에 소속될 조직을 세팅하여야 한다)
    • API를 동시에 5회 이상 호출하지 않도록 관리하며 특히, 조직관련 API는 단일 스레드로 호출해야 한다.
    • 구성원 수정과 그룹 수정 등 수정 API 호출 시 업데이트가 발생한 정보만 연동하여 데이터 변경이 없는 항목을 연동하여 불필요한 비용을 높이는 것을 방지할 수 있다. (예: 부분 조직 개편으로 일부 조직 이름이 변경되었지만 전체 조직을 연동함)
    • 호출에 실패한 API요청은 반드시 방어 로직을 구현해야 한다.
    • API 요청 실패를 감지할수 있도록 로그관리 혹은 모니터링 시스템을 함께 구축할 필요가 있다.