KoboToolbox 노드를 사용하여 KoboToolbox에서의 작업을 자동화하고, KoboToolbox를 다른 애플리케이션과 통합합니다. n8n은 파일, 폼, 훅 및 제출물 생성, 업데이트, 삭제 및 가져오기를 포함한 광범위한 KoboToolbox 기능을 기본으로 지원합니다.

이 페이지에서 KoboToolbox 노드가 지원하는 작업 목록과 추가 리소스 링크를 확인할 수 있습니다.

작업#

• 파일
  • 생성
  • 삭제
  • 가져오기
  • 여러 개 가져오기
• 폼
  • 가져오기
  • 여러 개 가져오기
    • 재배포
• 훅
  • 가져오기
  • 여러 개 가져오기
  • 로그
  • 모두 재시도
  • 하나 재시도
• 제출물
  • 삭제
  • 가져오기
  • 여러 개 가져오기
  • 유효성 검사 상태 가져오기
  • 유효성 검사 상태 업데이트

템플릿 및 예제#

옵션#

쿼리 옵션#

제출물 쿼리 작업은 쿼리 옵션을 지원합니다:

• 매개변수 패널의 주요 섹션에서:
  • Start는 쿼리를 시작할 인덱스 오프셋을 제어합니다 (API 페이지네이션 로직 사용을 위해).
  • Limit은 반환할 최대 레코드 수를 설정합니다. API는 사용자가 제공하는 값에 관계없이 항상 30,000개의 반환 레코드로 제한됩니다.
• 쿼리 옵션 섹션에서 다음 매개변수를 활성화할 수 있습니다:
  • Query를 사용하면 MongoDB의 JSON 쿼리 형식으로 필터 술어를 지정할 수 있습니다. 예를 들어: {"status": "success", "_submission_time": {"$lt": "2021-11-01T01:02:03"}}는 status 필드에 success 값이 있고 2021년 11월 1일 01:02:03 이전에 제출된 모든 제출물을 쿼리합니다.
  • Fields를 사용하면 응답을 더 가볍게 만들기 위해 가져올 필드 목록을 지정할 수 있습니다.
  • Sort를 사용하면 MongoDB JSON 형식으로 정렬 기준 목록을 제공할 수 있습니다. 예를 들어, {"status": 1, "_submission_time": -1}은 오름차순 상태, 그 다음 내림차순 제출 시간으로 정렬을 지정합니다.

이 옵션에 대한 자세한 내용은 Formhub API 문서에서 확인할 수 있습니다.

제출물 옵션#

폼 제출 데이터를 반환하는 모든 작업은 응답을 조정하는 옵션을 제공합니다. 다음이 포함됩니다:

• 다운로드 옵션을 사용하면 사진 및 동영상과 같이 각 폼 제출에 연결된 모든 첨부 파일을 다운로드할 수 있습니다. 이름 패턴과 다운로드할 파일 크기(사용 가능한 경우 - 일반적으로 이미지의 경우)도 선택할 수 있습니다.
• 형식 옵션은 재형식화 정보에 설명된 대로 재형식화를 수행합니다.

재형식화 정보#

KoboToolbox 제출 데이터의 기본 JSON 형식은 스키마를 인식하지 못하고 모든 필드가 문자열로 반환되기 때문에 처리하기 어려울 때가 있습니다.

이 노드는 모든 폼 제출을 반환하는 작업(제출물 쿼리, 가져오기 및 첨부 파일 다운로드 작업)에서 사용 가능한 재형식화? 매개변수로 활성화되는 경량 의견 기반 재형식화 로직을 제공합니다.

활성화되면 재형식화:

• 폼 그룹에 따라 JSON을 다중 레벨 계층으로 재구성합니다. 기본적으로 질문 그룹 계층은 필드 이름에서 / 문자로 표시됩니다 (예: Group1/Question1). 재형식화가 활성화되면 n8n은 이를 중첩된 JSON 객체로 Group1.Question1처럼 재구성합니다.
• 필드 이름에서 _를 제거하도록 이름을 변경합니다 (많은 다운스트림 시스템에서 지원되지 않음).
• 모든 지리 공간 필드(포인트, 라인, 영역 질문 유형)를 표준 GeoJSON 형식으로 파싱합니다.
• 다중 선택 마스크 와일드카드 마스크와 일치하는 모든 필드를 배열로 분할합니다. 다중 선택 필드는 공백으로 구분된 문자열로 표시되어 알고리즘적으로 추측할 수 없으므로 필드 이름 마스크를 제공해야 합니다. 마스크를 쉼표로 구분된 목록으로 형식화합니다. 목록은 * 와일드카드를 지원합니다.
• 숫자 마스크 와일드카드 마스크와 일치하는 모든 필드를 JSON float으로 변환합니다.

다음은 JSON의 자세한 예입니다:

{
  "_id": 471987,
  "formhub/uuid": "189436bb09a54957bfcc798e338b54d6",
  "start": "2021-12-05T16:13:38.527+02:00",
  "end": "2021-12-05T16:15:33.407+02:00",
  "Field_Details/Field_Name": "Test Fields",
  "Field_Details/Field_Location": "-1.932914 30.078211 1421 165",
  "Field_Details/Field_Shape": "-1.932914 30.078211 1421 165;-1.933011 30.078085 0 0;-1.933257 30.078004 0 0;-1.933338 30.078197 0 0;-1.933107 30.078299 0 0;-1.932914 30.078211 1421 165",
  "Field_Details/Crops_Grown": "maize beans avocado",
  "Field_Details/Field_Size_sqm": "2300",
  "__version__": "veGcULpqP6JNFKRJbbMvMs",
  "meta/instanceID": "uuid:2356cbbe-c1fd-414d-85c8-84f33e92618a",
  "_xform_id_string": "ajXVJpBkTD5tB4Nu9QXpgm",
  "_uuid": "2356cbbe-c1fd-414d-85c8-84f33e92618a",
  "_attachments": [],
  "_status": "submitted_via_web",
  "_geolocation": [
    -1.932914,
    30.078211
  ],
  "_submission_time": "2021-12-05T14:15:44",
  "_tags": [],
  "_notes": [],
  "_validation_status": {},
  "_submitted_by": null
}

재형식화가 활성화되고 다중 선택 및 숫자 형식화를 위한 적절한 마스크(예: 각각 Crops_* 및 *_sqm)가 제공되면 n8n이 이를 다음과 같이 파싱합니다:

{
  "id": 471987,
  "formhub": {
    "uuid": "189436bb09a54957bfcc798e338b54d6"
  },
  "start": "2021-12-05T16:13:38.527+02:00",
  "end": "2021-12-05T16:15:33.407+02:00",
  "Field_Details": {
    "Field_Name": "Test Fields",
    "Field_Location": {
      "lat": -1.932914,
      "lon": 30.078211
    },
    "Field_Shape": {
      "type": "polygon",
      "coordinates": [
        {
          "lat": -1.932914,
          "lon": 30.078211
        },
        {
          "lat": -1.933011,
          "lon": 30.078085
        },
        {
          "lat": -1.933257,
          "lon": 30.078004
        },
        {
          "lat": -1.933338,
          "lon": 30.078197
        },
        {
          "lat": -1.933107,
          "lon": 30.078299
        },
        {
          "lat": -1.932914,
          "lon": 30.078211
        }
      ]
    },
    "Crops_Grown": [
      "maize",
      "beans",
      "avocado"
    ],
    "Field_Size_sqm": 2300
  },
  "version": "veGcULpqP6JNFKRJbbMvMs",
  "meta": {
    "instanceID": "uuid:2356cbbe-c1fd-414d-85c8-84f33e92618a"
  },
  "xform_id_string": "ajXVJpBkTD5tB4Nu9QXpgm",
  "uuid": "2356cbbe-c1fd-414d-85c8-84f33e92618a",
  "attachments": [],
  "status": "submitted_via_web",
  "geolocation": {
    "lat": -1.932914,
    "lon": 30.078211
  },
  "submission_time": "2021-12-05T14:15:44",
  "tags": [],
  "notes": [],
  "validation_status": {},
  "submitted_by": null
}

지원하지 않는 작업에 대한 처리 방법#

이 노드가 원하는 작업을 지원하지 않는 경우, HTTP Request 노드를 사용하여 서비스의 API를 호출할 수 있습니다.

HTTP Request 노드에서 이 서비스용으로 생성한 자격 증명을 사용할 수 있습니다:

1. HTTP Request 노드에서 Authentication > Predefined Credential Type을 선택합니다.
2. 연결하려는 서비스를 선택합니다.
3. 자격 증명을 선택합니다.

자세한 내용은 커스텀 API 작업을 참조하세요.