Fxiaoke 데이터 소스 구성
Fxiaoke 데이터 소스는 오프라인 동기화를 통해 CRM 객체의 데이터를 읽어 플랫폼의 기본 스토리지에 쓰는 데 사용됩니다. 이 문서에서는 Fxiaoke의 앱 권한 부여, 데이터 소스 구성, 동기화 계획 생성, 작업 플로우 연결 방법을 소개합니다.
사용 제한 및 사전 준비
구성을 시작하기 전에 다음 제한 사항과 사전 조건을 확인하십시오.
- Fxiaoke는 데이터 소스로만 사용할 수 있으며, 데이터 목적지로는 사용할 수 없고 Fxiaoke에 데이터를 다시 쓰지도 않습니다.
- 앱 관리 권한이 있는 기업 관리자가 자체 개발 앱을 생성하고 관리해야 하며, CRM 관리자는 접근에 사용할 직원의 객체, 필드, 레코드 권한을 설정해야 합니다.
- 접근에 사용할 직원 계정은 정상적으로 활성화되어 있고 장기간 관리할 수 있어야 합니다. 계정 담당자와 권한 관리 담당자도 명확히 지정하십시오.
- 동기화할 객체, 필드, 레코드 범위와 플랫폼 실행 환경에서 기업이 속한 클라우드의 Fxiaoke 오픈 플랫폼에 접근할 수 있는지 확인하십시오.
| 환경 설정 방식 | 활용 상황 | 설정 요구 사항 |
|---|---|---|
| 환경 구분 없음 | 개발 환경과 운영 환경이 연결 설정을 공유 | 앱 자격 증명과 Employee ID 한 세트를 준비하고 필요한 접근 권한이 있는지 확인 |
| 독립 환경 설정 | 개발 환경과 운영 환경의 연결 설정을 별도로 관리 | 각 환경의 유효한 자격 증명과 Employee ID를 준비하고, 두 환경의 객체 및 필드 권한을 확인한 후 각각 연결 테스트 수행 |
Fxiaoke에서 앱 권한 부여 완료
기업 자체 개발 앱 생성 및 활성화
- 기업 관리자 계정으로 Fxiaoke 웹 버전에 로그인하고 관리 콘솔로 이동합니다.
- 앱 목록을 열고 기업 자체 개발 앱 생성을 선택한 후 앱 이름, 설명 등의 정보를 입력하고 저장합니다.
- 앱 설정 페이지에서 개발자 모드를 활성화하고, 페이지 안내에 따라 로그인 권한 부여 시작 페이지의 도메인과 IP 허용 목록을 설정합니다.
- 현재 기업에서 앱이 활성화되어 있는지 확인하고 App ID, App Secret, Permanent Code(영구 권한 부여 코드) 값을 확보합니다.
IP 허용 목록에는 플랫폼 배포 및 유지 관리 담당자가 제공한 실제로 API 요청을 보내는 서버의 외부 통신용 공인 IP를 입력해야 합니다. 외부 통신 경로가 여러 개이면 모든 IP를 등록하십시오. 브라우저가 실행되는 컴퓨터의 IP를 서버의 외부 통신용 IP로 전달하지 마십시오.
구체적인 메뉴 위치와 설정 방법은 Fxiaoke 공식 빠른 시작을 참조하십시오.
앱 쿼리 권한 및 직원 데이터 권한 설정
자체 개발 앱의 CRM API 쿼리 권한 설정에서 읽을 객체 범위에 따라 다음 쿼리 권한을 부여합니다.
| 권한 용도 | API 경로 |
|---|---|
| 객체 목록 조회 | /cgi/crm/v2/object/list |
| 객체 설명 및 필드 정보 조회 | /cgi/crm/v2/object/describe |
| 기본 제공 객체 데이터 조회 | /cgi/crm/v2/data/query |
| 커스텀 객체 데이터 조회 | /cgi/crm/custom/v2/data/query |
앱 API 권한과 직원 데이터 권한은 각각 설정해야 합니다. CRM 관리자는 접근에 사용할 직원에 대해 다음 사항도 확인해야 합니다.
| 권한 계층 | 확인 내용 |
|---|---|
| 객체 권한 | 동기화할 비즈니스 객체를 볼 수 있음 |
| 필드 권한 | 동기화할 필드를 읽을 수 있음 |
| 레코드 범위 | 해당 부서, 담당자 또는 공유 범위의 데이터를 포함하여 업무상 필요한 범위의 레코드를 볼 수 있음 |
예를 들어 특정 부서의 고객 레코드를 읽으려면 직원의 데이터 범위가 해당 부서를 포함해야 합니다. 본인 레코드만 볼 수 있는 직원을 해당 부서의 모든 레코드에 대한 권한을 가진 것으로 간주하여 검증해서는 안 됩니다. 자세한 내용은 공식 데이터 권한 설명을 참조하십시오.
Employee ID 확인 및 권한 설정 결과 검증
관리자에게 대상 직원의 openUserId 값을 조회하여 데이터 소스의 Employee ID로 사용하도록 요청하십시오. 공식 부서 내 구성원 기본 정보 조회 등의 관리자 절차로 직원을 확인하고 반환된 openUserId를 기록할 수 있습니다. 휴대폰 번호, 로그인 계정, 사번 또는 기업 ID를 입력하지 마십시오.
관리자에게 기업이 속한 클라우드의 API 도메인을 확인하도록 요청하십시오. 기본값은 open.fxiaoke.com입니다. 다른 클라우드의 도메인은 공식 기업 클라우드 도메인 설명을 참조하고 현재 플랫폼이 해당 설정을 허용하는지 확인하십시오. 공식 클라우드 도메인 목록이 현재 플랫폼에서 모든 도메인을 지원한다는 의미는 아닙니다.
권한 설정을 마치면 API 도메인, App ID, App Secret, Permanent Code, Employee ID, 권한이 부여된 데이터 범위, 등록된 외부 통신용 IP, 유지 관리 담당자 정보를 플랫폼 설정 담당자에게 전달합니다. App Secret과 Permanent Code는 기업이 승인한 안전한 채널로 전달하고 일반 문서, 로그 또는 티켓에 기록하지 마십시오.
동일한 앱, 동일한 Employee ID, 실제 서버 외부 통신 경로를 사용하여 자격 증명, API, 객체, 필드 및 레코드 범위를 확인하십시오. 앱이 활성화되어 있거나 액세스 토큰을 받을 수 있다는 사실만으로 직원에게 필요한 모든 데이터 권한이 부여되었다고 볼 수는 없습니다.
Fxiaoke 데이터 소스 생성
- 데이터 개발 플랫폼 > 통합 > 데이터 소스로 이동하여 + 데이터 소스를 클릭합니다.
- Fxiaoke를 선택하고 다음을 클릭한 후 데이터 소스 이름과 비고를 입력합니다.
- 환경 구분 없음 또는 독립 환경 설정을 선택합니다. 독립 환경 설정에서는 개발 환경과 운영 환경을 각각 설정해야 합니다.
- API Domain, App ID, App Secret, Permanent Code, Employee ID를 입력합니다.
- 연결 테스트에서 테스트를 클릭합니다. 연결 가능이 표시되면 완료를 클릭합니다.
연결 매개변수를 입력하고 환경 설정 방식을 확인합니다.
| 구성 항목 | 설명 |
|---|---|
| 데이터 소스 이름 | 현재 공간의 데이터 소스 이름으로, 페이지의 이름 및 고유성 검증을 통과해야 함 |
| 비고 | 용도 또는 유지 관리 정보를 설명하는 선택 항목 |
| API Domain | Fxiaoke 오픈 플랫폼의 API 도메인. 기본값은 open.fxiaoke.com이며 기업이 속한 클라우드와 플랫폼 지원 범위에 따라 설정 |
| App ID | 기업 자체 개발 앱의 앱 ID. 필수 |
| App Secret | 위 앱에 해당하는 앱 시크릿. 필수 |
| Permanent Code | 위 앱에 해당하는 영구 권한 부여 코드. 필수 |
| Employee ID | 데이터를 읽는 직원의 openUserId. 필수이며 해당 직원에게 필요한 데이터 권한이 있어야 함 |
저장된 데이터 소스를 편집할 때 App Secret과 Permanent Code는 마스킹된 값으로 표시됩니다. 마스킹된 값을 유지하면 기존 자격 증명을 계속 사용합니다. 교체하려면 새 값을 입력하고 연결 테스트를 다시 수행하십시오.
연결 테스트를 통과한 후에도 오프라인 동기화 계획에서 대상 객체, 필드 및 레코드 범위를 확인해야 합니다. 독립 환경 설정에서는 개발 환경과 운영 환경의 접근 권한을 각각 확인하십시오.
오프라인 동기화 계획 생성
- 데이터 개발 플랫폼 > 통합 > 오프라인 동기화로 이동하여 + 통합 방안을 클릭합니다.
- 데이터 소스에서 Fxiaoke와 생성한 데이터 소스를 선택합니다.
- 객체 유형으로 기본 제공 객체 또는 커스텀 객체를 선택합니다.
- 출처 객체에서 객체 이름 또는 API 이름으로 검색하고 동기화할 객체를 선택합니다.
- 데이터 미리보기를 클릭하여 소스 객체와 읽을 수 있는 데이터 내용이 예상과 일치하는지 확인합니다.
객체 유형과 소스 객체를 선택한 후 데이터를 미리 봅니다.
객체 유형을 변경하면 기존에 선택한 객체와 필드 매핑이 초기화됩니다. 소스 객체를 다시 선택하고 필드 매핑을 다시 확인하십시오. 소스 객체를 선택하지 않으면 데이터 미리보기를 사용할 수 없습니다.
필드 매핑 및 동기화 검증
지원 필드 타입
| 필드 분류 | 지원하는 Fxiaoke 필드 타입 |
|---|---|
| 텍스트 및 단일 값 참조 | text, long_text, html_rich_text, phone_number, email, url, auto_number, select_one, master_detail, object_reference |
| 지역 및 위치 | country, province, city, district, location |
| 다중 값 필드 | select_many, department, department_many, employee, employee_many, object_reference_many, tag, array |
| 숫자 | number, currency, percentile |
| 불리언 | true_or_false |
| 날짜 및 시간 | date, date_time, time |
| 계산 및 참조 결과 | count, formula, quote. 이미지, 첨부 파일 또는 서명 결과 제외 |
위 필드를 읽을 때 다음 요구 사항도 충족해야 합니다.
- 텍스트 및 단일 값 참조 필드와 지역 및 위치 필드의 값은 문자열이어야 합니다. 다중 값 필드는 문자열 배열이어야 하며 배열에 NULL 값이 포함될 수 있습니다.
- 숫자 필드의 소수 자릿수는 0~38로 명확하게 지정되어야 합니다. 실제 값의 총 정밀도는 38자리를 초과할 수 없으며 유효 소수 자릿수는 필드에 선언된 범위 이내여야 합니다.
- 불리언 필드의 값은 불리언이어야 합니다. 날짜 및 날짜/시간 필드는 정수형 밀리초 타임스탬프를, 시간 필드는 정수 값을 제공해야 합니다.
- 계산 및 참조 필드는 기존 결과를 읽습니다. 결과는 텍스트, 숫자, 불리언 또는 유효한 배열이나 객체 내용이어야 합니다. 기타 필드 타입은 먼저 데이터 미리보기와 수동 실행을 통해 읽기 결과를 확인하십시오.
지원하지 않는 필드 및 제한
- 이미지(
image), 첨부 파일(file_attachment), 서명(signature) 및quote(image)처럼 이러한 내용을 반환하는 참조 결과는 읽기를 지원하지 않습니다. 기타 필드 결과에 첨부 파일이나 이미지 등의 미디어 내용이 포함된 경우에도 일반 필드 내용으로 동기화할 수 없습니다. - 타입 선언이 없거나 숫자 필드에 유효한 소수 자릿수 선언이 없으면 해당 필드를 사용할 수 없습니다. 화면에서 읽기를 지원하지 않는 소스 필드는 회색으로 표시됩니다. 안내된 이유를 확인하십시오.
- 활성화되지 않은 필드는 읽기에 포함되지 않습니다. 필드 그룹(
group) 자체는 독립된 필드로 읽지 않으며 하위 필드는 각 타입에 따라 선택할 수 있습니다.
설정 및 검증
데이터 소스 설정을 완료한 후 데이터 목적지에서 플랫폼 기본 스토리지의 타겟 테이블을 선택하거나 생성하고 필드 매핑을 설정합니다.
독립 환경 설정에서는 수동 실행 시 운영 환경의 데이터 소스 설정을 사용합니다. 실행 전에 운영 환경 자격 증명, 객체 및 필드 권한과 타겟 테이블이 모두 예상과 일치하는지 확인하십시오.
- 비즈니스 요구에 따라 타겟 테이블과 쓰기 방식을 설정합니다.
- 필드 매핑에서 읽을 소스 필드를 타겟 필드에 매핑합니다.
- 회색으로 표시된 필드를 사용 가능한 필드로 설정하지 마십시오. 안내에 따라 동기화할 필드를 조정하십시오.
- 계획 이름, 담당자, 비고를 입력한 후 저장합니다.
- 수동 실행을 클릭하고 실행 기록에서 작업이 성공했는지 확인한 후 타겟 테이블에서 행 수, 필드 및 데이터 내용을 확인합니다.
소스 필드의 이름으로 비즈니스 의미를 파악하고 API 이름으로 해당 필드를 구분할 수 있습니다. 설정을 완료한 후 각 매핑을 확인하여 표시 이름이 비슷한 필드를 잘못 연결하지 않도록 하십시오.
다음은 필드 매핑 화면의 예시입니다. 실제 업무에 맞게 필드 대응 관계를 확인하십시오.
| 증상 | 확인 항목 |
|---|---|
| 연결 테스트 실패 | API Domain, 네 가지 자격 증명 및 이들 간의 대응 관계를 확인하고 앱과 직원 계정이 비활성화되지 않았는지 확인 |
| IP가 허용되지 않거나 접근이 거부되었다는 메시지가 표시됨 | 배포 및 유지 관리 담당자에게 실제 서버 외부 통신용 IP를 확인하고 앱 IP 허용 목록에 모두 등록되었는지 확인하도록 요청 |
| 객체 목록이 비어 있거나 대상 객체를 찾을 수 없음 | 객체 유형이 올바른지, 앱에 객체 목록 및 쿼리 권한이 부여되었는지, 접근에 사용하는 직원에게 해당 객체 권한이 있는지 확인 |
| 필드가 없거나 읽을 수 없음 | 앱의 객체 설명 조회 권한과 직원의 필드 읽기 권한을 확인하고 객체 구조가 변경되었는지 확인 |
| 미리보기 또는 동기화의 레코드 수가 예상보다 적음 | 동일한 Employee ID로 직원의 부서, 담당자 및 공유 범위를 확인하고 읽을 수 있는 레코드가 업무 요구 사항에 맞는지 확인 |
| 소스 필드가 회색으로 표시되거나 읽을 수 없음 | 필드 안내를 확인하고 필드 타입과 실제 내용이 지원 범위에 포함되는지 확인 |
| 개발 환경은 정상이지만 운영 작업이 실패함 | 운영 환경 자격 증명, 외부 통신용 IP, 앱 권한, 직원 데이터 범위와 선택한 객체 및 필드의 접근 가능 여부를 확인 |
작업 플로우에 연결
수동 검증에 성공하면 오프라인 동기화 계획을 작업 플로우에 연결하여 스케줄링 주기에 따라 자동으로 실행할 수 있습니다.
- 저장된 오프라인 동기화 계획을 열고 작업 플로우에 연결을 클릭합니다.
- 대상 작업 플로우를 선택합니다.
- 노드 이름을 입력하고 실행 모드를 선택한 후, 필요에 따라 담당자와 비고를 설정합니다. 노드 타입과 통합 계획은 자동으로 채워집니다.
- 노드 생성 및 연결을 클릭합니다. 연결에 성공하면 작업 플로우로 이동을 클릭하여 노드 위치와 상하위 의존 관계를 확인할 수 있습니다.
- 작업 플로우를 저장하고 배포를 완료합니다. 운영 스케줄링에는 운영 환경의 데이터 소스 설정이 사용됩니다.
배포 전에 운영 환경의 앱, Employee ID, 외부 통신용 IP와 객체, 필드 및 레코드 권한이 모두 준비되었는지 확인하십시오. 동기화 계획이나 데이터 소스를 교체하려면 기존 작업 플로우 의존 관계에 미치는 영향을 먼저 검토하고 변경 후 다시 실행하여 검증하십시오.

