조직도 정보 API 개발

카카오워크에 고객사의 조직도 정보를 동기화하기 위해 Adapter Agent API의 orgUnit Capability를 구현해야 합니다.

카카오워크에 고객사의 조직도 정보를 동기화할 때는 다음과 같이 구성합니다.

안내
조직도 구성 시 워크스페이스명(ex. 디케이테크인)으로 최상위 조직을 만들고, 실제 최상위 조직(ex. 카카오워크, 카카오 아지트)을 그 하위에 배치합니다.

• 가상의 최상위 조직의 name은 워크스페이스명으로 지정하고, parent_code는 #으로 지정
• 실제 최상위 조직(ex. 카카오워크)의 parent_code는 최상위 조직(ex. 디케이테크인)의 code로 지정
• 직위의 level은 직위 간 정렬에 사용될 값으로 중복 금지
• 직책의 level은 직책 간 정렬에 사용될 값으로 중복 금지

주의
가상의 최상위 조직은 두 개 이상 존재할 수 없습니다. 조직도 정보 동기화 진행 시, 상위 조직의 조직 데이터부터 되며 카카오워크에 수동으로 등록한 조직도 데이터는 삭제됩니다.

• 하위 조직의 조직 데이터가 먼저 전달될 경우, 검증이 실패되어 조직도 정보 동기화가 중단되므로 상위 level의 부서부터 전달되어야 합니다.

그림조직도 구성 예시

조직도 정보 동기화

고객사의 조직도 정보를 카카오워크에 동기화하기 위해서는 Adapter Agent 서버에 getValidOrgunits API 또는 getChangedOrgunits API를 구현해야 합니다. 조직도 정보 동기화는 Adapter 서버에서 주기적으로 Adapter Agent API를 호출하는 방식으로 이루어집니다.

안내
조직도 정보 동기화 시, 카카오 i 계정 서버에 고객사의 계정 정보를 단방향으로만 동기화하여 업데이트만 가능합니다.

카카오 i 서비스 시스템이 조직도 정보 동기화 API를 호출하는 시점은 다음과 같습니다.

• getValidOrgunits API: 최초 동기화 실행 시 또는 그 외 특정 시점의 전체 조직도 목록이 필요한 경우
• getChangedOrgunits API: 설정된 동기화 주기에 따라 호출

API 작업 흐름

카카오 i 서비스 시스템에서 조직도 정보 동기화 API를 호출하는 작업 흐름은 다음과 같습니다.

그림조직도 정보 동기화 작업 흐름

1. 카카오워크 서버에서 조직도 동기화가 필요한 시점에 동기화를 실행합니다.

2. 카카오워크 서버에서 getValidOrgunits 또는 getChangedOrgunits 요청을 Adapter 서버로 전송합니다.

3. Adapter 서버가 Adapter Agent 서버에 구현된 getValidOrgunits 또는 getChangedOrgunits API를 호출합니다.

4. Adapter Agent 서버가 연동된 고객사 시스템에 동기화 대상 조직도 목록을 요청합니다.

getValidOrgunits

getValidOrgunits API는 카카오워크에서 사용할 조직도 정보를 카카오워크에 제공하는 API로서 API 요청 시점을 기준으로 유효한 전체 조직도 목록을 전달합니다. 본 API는 카카오워크 서버와 고객사의 Adapter Agent 서버가 연동되어 최초로 조직도 동기화를 수행할 경우 혹은 장애가 생겨 전체를 동기화해야 하는 경우 등 카카오워크에서 고객사의 조직도 전체 목록이 필요할 경우 호출할 수 있습니다.

getValidOrgunits API 요청을 받았을 때 Adapter Agent 서버의 동작 예제는 다음과 같습니다.

1. Adapter Agent 서버가 연동된 고객사 시스템에 유효한 조직도 전체 목록을 요청합니다.

2. 각 조직도의 status 필드를 ACTIVE로 세팅하고 필드별로 필드 스펙에 맞게 포매팅합니다.

3. API 레퍼런스의 응답 포맷에 맞춰 조직도 목록을 반환합니다.

getChangedOrgunits

getChangedOrgunits API는 특정 시점부터 API 호출 시점까지의 추가, 변경, 비활성화가 일어난 조직도 목록을 제공합니다.

getChangedOrgunits API 요청을 받았을 때 Adapter Agent 서버의 동작 예제는 다음과 같습니다.

1. Adapter Agent 서버가 연동된 고객사 시스템에 특정 시간 이후에 변경이 일어난 조직도 정보를 요청합니다.

2. 각 조직도의 상태에 맞춰서 status 필드를 {REGISTERED | UPDATED | DELETED}에서 선택하고, 다른 필드는 필드 스펙에 맞게 포매팅합니다.

3. API 레퍼런스의 응답 포맷에 맞춰 사용자 목록을 반환합니다.

직책 정보 동기화

고객사의 직책 정보를 카카오워크에 동기화하기 위해 Adapter Agent에 getResponsibilities API를 구현해야 합니다. 직책 정보 동기화는 Adapter 서버에서 주기적으로 Adapter Agent API를 호출하는 방식으로 이루어집니다.

안내
카카오 i 계정 서버에 고객사의 계정 정보를 단방향으로만 동기화하여 업데이트 가능합니다.

API 작업 흐름

그림직책 정보 동기화 작업 흐름

1. 카카오워크 서버에서 직책 동기화가 필요한 시점에 동기화를 실행합니다.

2. 카카오워크 서버에서 getResponsibilities 요청을 Adapter 서버로 전송합니다.

3. Adapter 서버가 Adapter Agent 서버에 구현된 getResponsibilities API를 호출합니다.

4. Adapter Agent 서버가 연동된 고객사 시스템에 동기화 대상 직책 목록을 요청합니다.

getResponsibilities

getResponsibilities API는 카카오워크에서 사용할 직책 정보를 카카오워크에 제공하는 API로, 직책 정보를 최신 상태로 유지하기 위해 해당 API를 정해진 주기에 따라 호출합니다.
이 API는 고객사의 전체 직책 정보를 전달하여 동기화하며, 특정 사용자의 직책 정보는 사용자 정보 동기화 시점에 동기화됩니다.

getResponsibilities API 요청을 받았을 때 Adapter Agent 서버의 내부 예제는 다음과 같습니다.

1. Adapter Agent 서버가 고객사 시스템에서 사용 중인 직책 정보를 요청합니다.

2. API 레퍼런스의 응답 포맷에 맞춰 사용자 목록을 반환합니다.

직위 정보 동기화

고객사의 직위 정보를 카카오워크에 동기화하기 위해 Adapter Agent에 getPositions API를 구현해야 합니다. 직위 정보 동기화는 Adapter 서버에서 주기적으로 Adapter Agent API를 호출하는 방식으로 이루어집니다.

안내
카카오 i 계정 서버에 고객사의 계정 정보를 단방향으로만 동기화하여 업데이트 가능합니다.

API 작업 흐름

그림직위 정보 동기화 작업 흐름

1. 카카오워크 서버는 직위 동기화가 필요한 시점에 동기화를 실행합니다.

2. 카카오워크 서버에서 getPositions 요청을 Adapter 서버로 전송합니다.

3. Adapter 서버가 Adapter Agent 서버에 구현된 getPositions API를 호출합니다.

4. Adapter Agent 서버가 연동된 고객사 시스템에 동기화 대상 직위 목록을 요청합니다.

getPositions

getPositions API는 고객사의 전체 직위 정보를 전달하여 동기화하며, 카카오워크에서 사용할 고객사의 직위 정보를 카카오워크에 제공하는 API입니다. 특정 사용자의 직위 정보는 사용자 정보 동기화 시점에 동기화되며, 직위 정보를 최신 상태로 유지하기 위해 본 API를 정해진 주기에 따라 호출합니다.

getPositions API 요청을 받았을 때 Adapter Agent 서버의 동작 예제는 다음과 같습니다.

1. Adapter Agent 서버가 연동된 고객사 시스템에서 사용 중인 직위 정보를 요청합니다.

2. API 레퍼런스의 응답 포맷에 맞춰 사용자 목록을 반환합니다.

안내
API별 상세 레퍼런스는 카카오 i 계정 API 레퍼런스 문서를 참고하시기 바랍니다.