# Portal Import

## About Portals

Portals allow users to publish selected content of the knowledge base as portals on the intranet, extranet, or website. A portal is created and customized with the help of topics, a template, and various properties. It has two editions: an agent portal and a customer portal.

[Learn more about Portals](https://help.egain.com/help/knowledge/portals_about.htm)

## Organizing the Portal Structure

1. **Review Existing Topics**: Assess the created topics and understand how they are structured.
2. **Determine Portal Categories**: Decide on the categories or sections the portal should have based on the topics.
3. **Map Topics to Portal Sections**: Organize the topics into the appropriate sections within the portal and ensure a logical and user-friendly structure that aligns with the content strategy.


## Creating Portals

To import topics into portals, a specific JSON format is required. This section explains the parameters used in the JSON structure.

### Understanding the JSON Format

The JSON structure for importing topics into portals consists of a `"portals"` array, with each portal represented by an object containing various properties.

### Parameters

#### 1. Portals Array

The `portals` array contains all the portals to be created.

```json
{
  "portals": []
}
```

#### 2. Portal Object

| Parameter | Description | Type | Required |
|  --- | --- | --- | --- |
| `name` | The name of the portal | String | Yes |
| `description` | Optional description of the portal | String | Optional |


```json
{
  "portals": [
    {
      "name": "Name of portal",
      "description": "Description of portal"
    }
  ]
}
```

#### 3. fromTopics Array

* Specify the exact path to the topic to be added to the portal. This ensures that the intended topics are successfully associated with the portal.
* Continue adding each path to the `"fromTopics"` array, ensuring each entry follows the same format.


```json
{
  "fromTopics": [
    {
      "path": "Path of the Topic"
    },
    {
      "path": "Path of the Topic/Sub Topic"
    }
  ]
}
```

#### 4. Resource Identifiers

The optional `id` and `externalId` fields provide precise control over how a portal is matched during import. These fields are especially useful for content synchronization, where relying on the portal name alone can create duplicate portals if the name changes in the source system.

Provide **only one** identifier per portal — 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 portal. When provided, the import updates the specific portal matching this ID, overriding name matching. Readable IDs are not supported. | String | Optional |
| `externalId` | A reference ID used to map the portal to an external source portal identifier. When provided, the import updates the portal previously mapped to this ID. If no portal is mapped to the `externalId` yet, you must also provide the portal `name` so a new portal can be created and linked to it. | String | Optional |


**Matching Behavior:**

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


```json
{
  "portals": [
    {
      "externalId": "sharepoint-portal-3",
      "name": "Name of portal",
      "description": "Description of portal"
    }
  ]
}
```