JSON Import

Import documents from JSON files into AGO

Import documents from JSON files into AGO. Use this connector for custom data sources, migrations, or bulk imports from any system that can export JSON.

Overview

Feature	Details
Authentication	None (file upload)
Content Type	Custom JSON data
Hierarchy	Flat (configurable)
Bulk Import	Yes

Prerequisites

• JSON file with your documents
• Understanding of your data structure

Configuration

Required Fields

Field	Description	Example
title_field	Field name for document title	title, name, heading

Optional Fields

Field	Type	Default	Description
content_fields	array	["content"]	Fields to combine as document content
id_field	string	id	Field name for unique identifier

Setup Steps

1. Navigate to Knowledge → Sources
2. Click Create Source
3. Select JSON as the source type
4. Configure field mappings:
   • Set the title field
   • Set content field(s)
   • Set ID field (optional)
5. Click Save
6. Upload your JSON file via the sync interface

JSON Format

Basic Format

Array of objects with consistent structure:

[
  {
    "id": "doc-001",
    "title": "Getting Started",
    "content": "Welcome to our platform..."
  },
  {
    "id": "doc-002",
    "title": "Installation Guide",
    "content": "Follow these steps to install..."
  }
]

Multiple Content Fields

Combine multiple fields into document content:

[
  {
    "id": "faq-001",
    "question": "How do I reset my password?",
    "answer": "Click on the forgot password link...",
    "category": "Account"
  }
]

Configuration:

{
  "title_field": "question",
  "content_fields": ["answer", "category"],
  "id_field": "id"
}

Custom Field Names

Map any field structure:

[
  {
    "article_id": "KB001",
    "headline": "Troubleshooting Connection Issues",
    "body": "If you're experiencing connection problems...",
    "summary": "Quick fixes for common issues"
  }
]

Configuration:

{
  "title_field": "headline",
  "content_fields": ["summary", "body"],
  "id_field": "article_id"
}

Uploading Files

Via Admin Interface

1. Go to the JSON source in Admin > Knowledge > Sources
2. Click Import > Upload File
3. Select your JSON file
4. Monitor import progress

Via API

POST /api/knowledge-management/sync/upload-files
Content-Type: multipart/form-data

source_id: <source-uuid>
files: <your-file.json>

Content Field Combination

When multiple content fields are specified, they are combined in order:

Configuration:

{
  "content_fields": ["summary", "description", "details"]
}

Result:

[summary content]

[description content]

[details content]

Best Practices

Data Preparation

• Ensure all objects have the same structure
• Use consistent field names
• Clean HTML or convert to Markdown before import
• Validate JSON syntax before upload

Field Mapping

• Choose descriptive titles (not IDs or codes)
• Include all relevant content fields
• Use a unique ID field for updates

Large Files

• For large datasets, consider splitting into smaller files
• Upload sequentially to avoid timeouts
• Monitor sync history for errors

Migration Use Cases

From Other Knowledge Bases

1. Export data from source system as JSON
2. Map fields to AGO’s expected structure
3. Upload and verify import

From Spreadsheets

1. Export spreadsheet to CSV
2. Convert CSV to JSON (many tools available)
3. Upload JSON to AGO

From Databases

1. Export database query results as JSON
2. Transform field names if needed
3. Upload to AGO

Troubleshooting

Invalid JSON

• Validate JSON syntax (use online validators)
• Check for trailing commas
• Ensure proper quoting of strings

Missing Content

• Verify content_fields includes all needed fields
• Check field names match exactly (case-sensitive)
• Review for null or empty values

Duplicate Documents

• Use unique values in id_field
• Re-importing updates existing documents by ID
• Clear source before re-importing for fresh start

Encoding Issues

• Use UTF-8 encoding
• Handle special characters properly
• Convert from other encodings if needed

Related Documentation

• Public API v1 Reference - Complete API documentation
• Knowledge Connectors - All available connectors
• Knowledge Source Management - Source configuration
• Knowledge AI Ingestion - AI-powered import