사용 매뉴얼
개요
대상 사용자: NAVER WORKS를 사용하는 조직의 IT·보안 담당자 또는 소나 관리자
- NAVER WORKS 조직의 부서 구조와 임직원 목록을 소나 쿼리로 실시간 조회
- 조회한 조직도 데이터를 소나 내 임직원 정보와 동기화해 항상 최신 상태 유지
- 예약된 쿼리를 활용한 주기적 자동 동기화로 인사 발령 내용을 소나에 자동 반영
기본 개념·용어
| 용어 | 의미 | 관련 리소스 |
|---|---|---|
| 접속 프로파일 | NAVER WORKS 연결에 필요한 자격증명(Client ID, Private Key 등)을 저장하는 소나 객체 | 설치 매뉴얼 참고 |
naverworks-departments | NAVER WORKS API를 호출해 부서 목록을 조회하는 확장 명령어 | 명령어 문서 |
naverworks-employees | NAVER WORKS API를 호출해 임직원 목록을 조회하는 확장 명령어 | 명령어 문서 |
sonar-sync-departments | 입력 레코드 기준으로 소나 부서 객체를 생성·수정·삭제하는 실험실 앱 명령어 | 실험실 앱 설치 필요 |
sonar-sync-employees | 입력 레코드 기준으로 소나 임직원 객체를 생성·수정·비활성화하는 실험실 앱 명령어 | 실험실 앱 설치 필요 |
sonar-sync-bosses | 입력 레코드 기준으로 소나 부서장을 설정·해제하는 실험실 앱 명령어 | 실험실 앱 설치 필요 |
| dry-run | sonar-sync-* 실행 시 run 파라미터를 생략한 상태. API 호출 없이 변경 계획(action)만 미리 확인 | — |
주요 화면·메뉴 경로
| 기능 | 경로 |
|---|---|
| 앱 관리 | 앱 |
| 접속 프로파일 등록·관리 | 시스템 > 접속 프로파일 |
| 쿼리 실행 | 분석 > 쿼리 |
| 예약된 쿼리 등록·관리 | 분석 > 예약된 쿼리 |
| 인사 정보 (조직·임직원) | 계정 > 임직원 |
작업 시나리오
시나리오 1: NAVER WORKS 조직도 조회
목적: NAVER WORKS에 등록된 부서 목록과 임직원 정보를 소나에서 바로 확인합니다. 동기화 전 데이터 품질을 검토하거나 특정 부서·직원을 빠르게 조회할 때 사용합니다.
사전 조건:
- NAVER WORKS 앱이 설치되어 있고 접속 프로파일(식별자 예: naver_works)이 등록되어 있어야 합니다.
- 소나 관리자 권한이 필요합니다.
수행 절차:
- 분석 > 쿼리에서 아래 쿼리를 실행합니다.
부서 목록 조회:
임직원 목록 조회:
결과 확인:
부서 조회 결과 예시:
| dept_code | dept_name | dept_path | parent_dept_code | ... |
|---|---|---|---|---|
| D001 | 경영지원팀 | 본사 > 경영지원팀 | D000 | ... |
임직원 조회 결과 예시:
| emp_num | first_name | last_name | dept_name | position_name | ... | |
|---|---|---|---|---|---|---|
| A000001 | 길동 | 홍 | 개발팀 | 팀장 | user@example.com | ... |
실패 대응:
| 증상 | 원인 | 해결 |
|---|---|---|
| 결과 0건 | 접속 프로파일 오류 또는 OAuth Scope 미설정 | 시스템 > 접속 프로파일 정보 확인. NAVER WORKS Developer Console에서 directory.read scope 확인 |
| 인증 오류 메시지 | Client Secret 또는 Private Key 불일치 | NAVER WORKS Developer Console에서 재발급 후 접속 프로파일 갱신 |
| 네트워크 오류 | 소나 → NAVER WORKS API 방화벽 차단 | auth.worksmobile.com, www.worksapis.com HTTPS/443 허용 확인 |
시나리오 2: 부서 정보 동기화 (dry-run → 적용)
목적: NAVER WORKS 부서 구조를 소나 조직 정보와 동기화합니다. 신규 부서 추가, 부서명 변경, 폐지된 부서 삭제가 자동으로 처리됩니다.
사전 조건:
- 실험실 앱이 설치되어 있어야 합니다.
- 소나 클러스터 관리자 권한이 필요합니다.
수행 절차:
1. dry-run으로 변경 계획 먼저 확인
naverworks-departments profile=naver_works
| fields dept_code, dept_name, parent_dept_code, description
| sonar-sync-departments
action 값의 의미는 다음과 같습니다.
| action | 의미 |
|---|---|
notify | 처리 불가 항목. error 필드에서 원인 확인 필요 |
create | 소나에 없는 신규 부서 생성 |
update | 부서명 또는 설명(description) 변경 |
delete | 입력 레코드에 없는 기존 부서 삭제 |
set_parent | 상위 부서 신규 설정 또는 변경 |
unset_parent | 상위 부서 해제 |
params 필드에는 action별로 다음 정보가 포함됩니다.
update 시에는 변경 전 부서명이 old_name으로, set_parent 시에는 새 상위 부서의 이름과 GUID가 parent_name/parent_guid로, unset_parent 시에는 해제된 상위 부서 정보가 old_parent_name/old_parent_guid로 표시됩니다.
- `sonar-sync-departments`는 부서장 정보를 동기화하지 않습니다. 부서장 설정은 시나리오 3(임직원 동기화) 완료 후 시나리오 4(부서장 동기화)를 실행하세요.
2. 변경 내용 확인 후 실제 적용
dry-run으로 실행한 결과를 통해 변경 내용을 확인했다면 run=t를 추가한 후 실행해 실제로 적용합니다.
naverworks-departments profile=naver_works
| fields dept_code, dept_name, parent_dept_code, description
| sonar-sync-departments run=t
결과 확인:
status 필드가 success인 레코드만 표시되면 정상입니다. 소나 UI에서 계정 > 임직원 화면 우측 그룹 트리에 동기화된 부서 구조가 반영되었는지 확인합니다.
실패 대응:
| 증상 | 원인 | 해결 |
|---|---|---|
결과 레코드 내 action=notify | 상위 부서 코드(parent_dept_code)가 소나에 없음 | 상위 부서가 먼저 동기화되어야 함. dry-run 결과에서 notify 항목의 error 필드 확인 |
status = failure | 소나 API 오류 | error 필드 내용 확인 후 재시도 |
| 권한 오류 | 소나 클러스터 관리자 권한 없음 | 소나 클러스터 관리자 계정으로 실행 |
시나리오 3: 임직원 정보 동기화 (dry-run → 적용)
목적: NAVER WORKS 임직원 정보를 소나와 동기화합니다. 신규 입사자 등록, 정보 변경 반영, 퇴사자 비활성화가 자동으로 처리됩니다.
사전 조건:
- 시나리오 2(부서 동기화)가 완료되어 있어야 합니다.
- 소나 클러스터 관리자 권한이 필요합니다.
수행 절차:
1. dry-run으로 변경 계획 먼저 확인
naverworks-employees profile=naver_works
| eval emp_name = concat(last_name, first_name)
| rename emp_num as emp_key, level_name as emp_title, hired_date as join_date
| fields emp_key, emp_name, emp_title, dept_code, email, phone, address, join_date, leave_date, locale
| sonar-sync-employees
notify 행은 error 필드에서 원인을 확인합니다. 주요 원인은 필수 필드 누락(emp_key, emp_name, emp_title, locale), dept_code에 해당하는 부서 미존재 등입니다.
action 값의 의미는 다음과 같습니다.
| action | 의미 |
|---|---|
notify | 처리 불가 항목. 필수 필드 누락 또는 부서 코드 미존재. error 필드에서 원인 확인 |
create | 소나에 없는 신규 임직원 등록 예정. params에 등록 데이터 표시 |
update | 임직원 정보 변경 예정. changes에 변경 항목 목록, params에 변경 전·후 값 표시 |
deactivate | 입력 레코드에 없는 기존 임직원 퇴사 처리 예정 |
skip | 변경 사항 없음 |
2. 변경 내용 확인 후 실제 적용
dry-run으로 실행한 결과를 통해 변경 내용을 확인했다면 run=t를 추가한 후 실행해 실제로 적용합니다.
naverworks-employees profile=naver_works
| eval emp_name = concat(last_name, first_name)
| rename emp_num as emp_key, level_name as emp_title, hired_date as join_date
| fields emp_key, emp_name, emp_title, dept_code, email, phone, address, join_date, leave_date, locale
| sonar-sync-employees run=t
결과 확인:
status 필드가 success인 레코드만 표시되면 정상입니다. 소나 UI에서 계정 > 임직원 화면의 임직원 목록 및 우측 그룹 트리에서 각 부서에 임직원이 정상 배치되었는지 확인합니다.
실패 대응:
| 증상 | 원인 | 해결 |
|---|---|---|
notify action — dept 오류 | dept_code에 해당하는 부서가 소나에 없음 | 시나리오 2(부서 동기화) 먼저 실행 |
같은 임직원에 notify가 2건 연속 출력 | dept_code 미존재와 locale 미설정이 동시에 발생 | error 필드 확인 후 두 문제 모두 해결 |
deactivate 예상 외 발생 | NAVER WORKS에서 삭제된 계정이 동기화 대상에서 제외됨 | NAVER WORKS에서 계정 상태 확인 |
locale 필드 오류 | locale 값 누락 또는 형식 불일치 | NAVER WORKS 직원 정보에서 locale 필드 값 확인 |
시나리오 4: 부서장 동기화 (dry-run → 적용)
목적: NAVER WORKS 임직원 정보를 기준으로 소나의 각 부서에 부서장을 할당합니다.
사전 조건:
- 시나리오 2(부서 동기화)와 시나리오 3(임직원 동기화)이 모두 완료되어 있어야 합니다.
- 소나 클러스터 관리자 권한이 필요합니다.
- 부서장으로 지정할 임직원을 식별하는 기준(직위, 별도 데이터 등)이 정해져 있어야 합니다.
수행 절차:
1. dry-run으로 부서장 변경 계획 확인
아래 예시는 position_name이 비어있지 않은 직원을 해당 부서의 부서장으로 설정합니다.
naverworks-employees profile=naver_works
| search position_name != ""
| rename emp_num as boss_key
| fields dept_code, boss_key, position_name
| sonar-sync-bosses
action 값의 의미는 다음과 같습니다.
| action | 의미 |
|---|---|
notify | 처리 불가 항목. 부서 또는 임직원이 소나에 없는 경우 발생 |
set | 부서장 신규 설정 또는 변경 예정 |
unset | 부서장 해제 예정 |
skip | 현재 부서장과 동일. 변경 없음 |
2. 변경 내용 확인 후 실제 적용
dry-run으로 실행한 결과를 통해 변경 내용을 확인했다면 run=t를 추가한 후 실행해 실제로 적용합니다.
naverworks-employees profile=naver_works
| search position_name != ""
| rename emp_num as boss_key
| fields dept_code, boss_key, position_name
| sonar-sync-bosses run=t
결과 확인:
action이 set 또는 skip이고 status가 success이면 정상입니다. 소나 UI에서 계정 > 임직원 화면 우측 그룹 트리의 각 부서에 부서장이 올바르게 표시되는지 확인합니다.
실패 대응:
| 증상 | 원인 | 해결 |
|---|---|---|
notify — 부서 없음 | 해당 dept_code가 소나에 없음 | 시나리오 2(부서 동기화) 먼저 실행 |
notify — 임직원 없음 | 해당 boss_key(사번)가 소나에 없음 | 시나리오 3(임직원 동기화) 먼저 실행 |
| 부서장이 여러 명 조회됨 | position_name 조건에 해당하는 직원이 한 부서에 복수 존재 | 부서장 선별 조건 쿼리 조정 필요 |
시나리오 5: 예약된 쿼리로 주기적 자동 동기화
목적: 소나의 예약된 쿼리 기능으로 NAVER WORKS 인사 정보를 매일 자동으로 동기화해 수동 실행 없이 항상 최신 상태를 유지합니다.
사전 조건:
- 시나리오 2~4를 수동으로 1회 이상 성공적으로 실행해 데이터 기준이 맞춰진 상태여야 합니다.
- 소나 클러스터 관리자 권한이 필요합니다.
수행 절차:
- 분석 > 예약된 쿼리에서 추가를 클릭합니다. (예약된 쿼리 가이드 참고)
- 아래 3개의 예약된 쿼리를 각각 별도로 생성합니다. 각 쿼리마다 쿼리 내용과 실행 시각을 독립적으로 설정하며, 앞 쿼리가 완료된 후 다음 쿼리가 시작되도록 실행 시각에 충분한 간격을 둡니다 (예: 02:00, 02:10, 02:20).
예약 쿼리 1 — 부서 동기화
naverworks-departments profile=naver_works
| fields dept_code, dept_name, parent_dept_code, description
| sonar-sync-departments run=t
예약 쿼리 2 — 임직원 동기화
naverworks-employees profile=naver_works
| eval emp_name = concat(last_name, first_name)
| rename emp_num as emp_key, level_name as emp_title, hired_date as join_date
| fields emp_key, emp_name, emp_title, dept_code, email, phone, address, join_date, leave_date, locale
| sonar-sync-employees run=t
예약 쿼리 3 — 부서장 동기화
naverworks-employees profile=naver_works
| search position_name != ""
| rename emp_num as boss_key
| fields dept_code, boss_key, position_name
| sonar-sync-bosses run=t
결과 확인:
예약 쿼리 실행 후 분석 > 예약된 쿼리 목록에서 각 쿼리의 최근 실행 결과(성공/실패)를 확인합니다.
실패 대응:
| 증상 | 원인 | 해결 |
|---|---|---|
| 예약 쿼리 실패 | NAVER WORKS API 일시 장애 | 다음 날 자동 재실행됨. 즉시 필요 시 수동 실행 |
notify 건수 증가 | 부서·임직원 불일치 누적 | 수동으로 순서대로(부서 → 임직원 → 부서장) 1회 실행해 기준 맞춤 |
| 동기화 후 소나 인사 정보 불일치 | 실행 순서 오류 | 반드시 부서 → 임직원 → 부서장 순으로 실행 확인 |
주의사항
- Private Key 재발행 시 접속 프로파일 갱신 필요: NAVER WORKS에서 Private Key를 재발행하면 기존 키는 즉시 무효화됩니다. 시스템 > 접속 프로파일에서 새 키로 즉시 갱신하지 않으면 예약된 쿼리가 실패합니다.
sonar-sync-*명령어는 실험실 앱 제공:sonar-sync-departments,sonar-sync-employees,sonar-sync-bosses는 소나 실험실 앱에서 제공하는 명령어입니다. 실험실 앱이 설치되지 않은 환경에서는 사용할 수 없습니다.sonar-sync-*클러스터 관리자 권한 필수:sonar-sync-departments,sonar-sync-employees,sonar-sync-bosses명령어는 소나 클러스터 관리자 권한이 없는 계정에서는 실행되지 않습니다.- dry-run 먼저 확인:
run=t적용 전 반드시 dry-run(run파라미터 생략)으로action필드를 검토하세요. 예상치 못한delete또는deactivate항목이 있는지 반드시 확인합니다. - 동기화 실행 순서 필수:
sonar-sync-departments→sonar-sync-employees→sonar-sync-bosses순서를 반드시 지켜야 합니다. 순서가 바뀌면 부서·임직원 미존재로notify오류가 대량 발생합니다. - 쿼리 예시는 참고용: 매뉴얼의 쿼리 예시는 일반적인 NAVER WORKS 조직도 구조를 기준으로 작성되었습니다. 조직의 필드 구성, 부서장 식별 방식, 사번 형식 등이 다를 수 있으므로 실제 환경에 맞게 쿼리를 수정해 사용하세요.
관련 문서
- naverworks-departments — 부서 목록 조회 명령어
- naverworks-employees — 임직원 목록 조회 명령어