# Folder Import

## About Folders

Folders organize knowledge articles efficiently, making them easily accessible to Knowledge Console users. They categorize articles based on common parameters such as content type and target audience.

When a new department is created, several standard folders are automatically generated in the Knowledge Console. Authors with the appropriate permissions can create custom folders to better manage content. These user-created folders have configurable permissions, allowing other authors to view, create, edit, or delete articles and subfolders within them.

## Organizing Folder Structure

- **Organize Folders Sequentially**: Arrange folders in a sequential order to ensure a clear and intuitive structure.
- **Add Subfolders as Needed**: Within each folder, create multiple subfolders to further organize the content. Ensure that subfolders follow the same logical sequence.


**Example Structure in `knowledgehub.json`:**

```json
"folders": [
    {
        "name": "Catalogs",
        "description": ""
    },
    {
        "name": "Credit Cards and Payments",
        "description": ""
    },
    {
        "name": "Macros",
        "description": "",
        "folders": [
            {
                "name": "Company Information",
                "description": ""
            },
            {
                "name": "Contact Information",
                "description": ""
            }
        ]
    }
]
```

### Creating Folders

1. **Access the Knowledge System:** Log into the Knowledge Console.
2. **Review the Folder Hierarchy:** Note the existing folder structure to understand how new folders will fit.
3. **Set Up the Folder Array:** In knowledgehub.json, map the folder structure. Begin with a root element named "folders" that contains an array.


```
{
    "folders": []
}
```

1. **Add Each Folder:** Add an object within the "folders" array for each top-level folder.


| Parameter | Description | Type | Required |
|  --- | --- | --- | --- |
| Name | Name of the folder. **Reserved characters `{`, `}`, and `/` are not allowed.** | String | Yes |
| Description | Description of the folder | String | Optional |


```json
{
  "folders": [
    {
        "name": "Name of folder",
        "description": "Description of folder"
    }
  ]
}
```

1. **Repeat for Additional Folders:** Continue adding folder objects to the "folders" array.


### Creating Subfolders

1. **Locate the parent folder:** In your JSON structure, find the parent folder object where you want to add a subfolder.
2. **Set Up the Subfolder Array:** Add a "folders" array within the parent folder object.


```
{
    "folders": [
    {
        "name": "Name of folder",
        "description": "Description of folder",
        "folders": []
    }
    ]
}
```

1. **Add Each Subfolder:** Add a folder object within the nested "folders" array for each subfolder.


| Parameter | Description | Type | Required |
|  --- | --- | --- | --- |
| Name | Name of the folder. **Reserved characters `{`, `}`, and `/` are not allowed.** | String | Yes |
| Description | Description of the folder | String | Optional |


```json
{
  "folders": [
    {
        "name": "Name of folder",
        "description": "Description of folder",
        "folders": [
          {
            "name": "Name of subfolder",
            "description": "Description of subfolder"
          }
        ]
    }
  ]
}
```

### Resource Identifiers

The optional `id` and `externalId` fields provide precise control over how a folder is matched during import. These fields are especially useful for content synchronization, where relying on the folder name and path alone can create duplicate folders if the name or path changes in the source system (e.g., SharePoint, Confluence).

Provide **only one** identifier per folder — either `id` or `externalId`, but not both. If both are supplied, the import validation aborts.

| Parameter | Description | Type | Required |
|  --- | --- | --- | --- |
| `id` | The internal eGain system ID of the folder. When provided, the import updates the specific folder matching this ID, overriding name/path matching. Readable IDs are not supported. | String | Optional |
| `externalId` | A reference ID that ties the folder to an external source structure, used for tracking and synchronization. When provided, the import updates the folder previously mapped to this ID. If no folder is mapped to the `externalId` yet, you must also provide the folder `name` (in its intended position in the hierarchy) so a new folder can be created and linked to it. | String | Optional |


**Matching Behavior:**

| Identifier | Match | Action Taken |
|  --- | --- | --- |
| `id` provided | N/A | Updates the folder matching the provided `id`. |
| `externalId` provided | Mapped folder exists | Updates the folder mapped to the provided `externalId`. |
| `externalId` provided | No mapped folder | Creates a new folder (requires `name`) and links it to the `externalId`. |
| Neither provided | Name/path match found | Updates the existing folder matching the name/path (existing behavior). |
| Neither provided | No name/path match | Creates a new folder (existing behavior). |


```json
{
  "folders": [
    {
        "externalId": "sharepoint-folder-42",
        "name": "Name of folder",
        "description": "Description of folder"
    }
  ]
}
```

### Sync Operations

The optional `operation` field controls whether a folder is created/updated or deleted during import. This helps keep eGain content in sync with a source system where folders may be removed at the source.

| Parameter | Description | Type | Enum |
|  --- | --- | --- | --- |
| `operation` | The action to perform on the folder. Defaults to `upsert` when omitted. | String [enum] | • upsert• delete |


* **`upsert`** (default): Updates the folder if a match is found (by `id`, `externalId`, or name/path), otherwise creates a new folder. This is the same as the behavior when `operation` is omitted.
* **`delete`**: Deletes the target folder. Identify it by `id` or `externalId` — when either is provided, `name` and path are not required. If you provide `name` and path instead, the import validates those values before deleting.


```json
{
  "folders": [
    {
        "id": "10005678904567",
        "operation": "delete"
    }
  ]
}
```