Article Import

Articles serve as the repository of an organization’s information. They are stored and organized within the Knowledge Console, allowing users to easily access them and respond to customer queries through various communication channels.

Learn more about Articles

1. Access Knowledge Articles: Gather the existing articles for import into eGain and ensure all the necessary details for each article are included, including its name, folder path, and content.
2. Create a New JSON File: In a text editor or JSON editor, create a new file and save it as articles.json.
3. Start with the Root Element: Begin the JSON file with a root element named "articles" that contains an array.
   {
     "articles": []
   }

4. Add Each Article: Add an object within the "articles" array containing the required components: name, folder, and content for each knowledge article.
5. Populate the Article Details:
   • Name: Provide the title of the article. Note: The characters {, }, and / are reserved and cannot be used in article names. Using them will cause the import validation to fail.
   • Folder Path: Specify the folder path. Individual folder names within the path must not contain { or }. The / character is reserved strictly as a path separator.
   • Content: Include the path of the article content, which should reside under the /content folder.
   {
     "articles": [
       {
         "name": "Sample Article Name",
         "folder": {
             "path": "Parent Folder/Subfolder"
         },
         "content": "content/order-history.html"
       } 
     ]
   }

6. Repeat for Additional Articles: Continue adding each article to the "articles" array, ensuring each entry follows the same format.

Add the additional/optional parameters in the object within the "article" array.

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

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

Matching Behavior:

Update an existing article by id:

{
  "articles": [
    {
      "id": "10000678901234",
      "content": "content/order-history.html"
    } 
  ]
}

Create/link a new article by externalId (name and path required):

{
  "articles": [
    {
      "externalId": "sharepoint-item-9f8c7b6a",
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html"
    } 
  ]
}

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

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

{
  "articles": [
    {
      "id": "12345678901234",
      "operation": "delete"
    } 
  ]
}

The Availability Date is the specific date and time when the article becomes visible and available for use. This field can be used independently or in conjunction with the expirationDate and timeZone fields to define a specific visibility window.

Validation Rules:

• Future Date: Must be set in the future compared to the current time.
• 1-Year Limit: Cannot be set more than 1 year from the current date (based on the resolved time zone).
• Window Logic: If expirationDate is also provided, availabilityDate must occur before it.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "availabilityDate": "01-28-2025, 7:53:58 PM",
      "expirationDate": "01-28-2026, 7:53:58 PM"
    } 
  ]
}

Set the expiration date if the article is to become unavailable to users on a particular date. The article is automatically withdrawn on the given date. This field can be used independently or in conjunction with the availabilityDate and timeZone fields.

Validation Rules:

• Future Date: Must be set in the future compared to the current time.
• 5-Year Limit: The date is capped at 5 years from the availabilityDate window.
• Window Logic: Must occur after the availabilityDate (if provided).

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "expirationDate": "12-31-2025, 11:59:59 PM"
    } 
  ]
}

The timeZone field defines the time zone for the availabilityDate and/or expirationDate.

• Optional: If not provided, the system defaults to UTC.
• Independence: Can accompany availabilityDate alone, expirationDate alone, or both when defining a window.
• Validation: The system does not accept UTC-offset strings (e.g., Z, +00:00, -05:00). Using these will result in an invalid_timeZone error.

Supported Time Zones:

• US Abbreviations: PST, PT, PDT, EST, ET, EDT, CST, CT, CDT, MST, MT, MDT
• IANA IDs: America/Los_Angeles, America/New_York, America/Chicago, America/Denver, Africa/Abidjan

Example (Visibility Window with Time Zone):

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "availabilityDate": "06-01-2025, 12:00:00 AM",
      "expirationDate": "06-01-2026, 12:00:00 AM",
      "timeZone": "America/New_York"
    } 
  ]
}

Shortcuts known as macros are assigned to specific articles. These macros enable authors to efficiently reuse commonly used content by embedding an article macro within another article. This streamlined process enables agents to promptly incorporate articles into their responses.

Learn more about Macros

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "articleMacro": {
        "name": "Sample Macro Name",
        "defaultValue": "Default Macro Value",
        "description": "Description of the Macro"
      }
    } 
  ]
}

Metadata can be added to articles to make the search for articles more efficient.

Learn more about Metadata

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "metadata": {
          "description": "Description of the article",
          "summary": "Summary of the article",
          "keywords": "Article keywords",
          "additionalInfo": "Additional information for the article"
      }
    } 
  ]
}

Giving an article a category better categorizes the article’s uses. If an article category is not given, then it will be default given ‘General’.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "articleType": "General"
    } 
  ]
}

Incorporating images into articles enhances the visual appeal and provides readers with a richer, more engaging experience. To add an image to an article, provide the URL of the image inside articleImage object.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "articleImage": {
          "imageURL": "https://sampleimage.url.com"
      }
    } 
  ]
}

Notes are annotations added to articles for internal communication among authors and editors. Multiple notes can be included within an article. To add multiple notes, add the "note" object within the "notes" array.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "notes": [
        {
          "note": "content of the note"
        }
      ]
    } 
  ]
}

Incorporating associated questions into an article helps to address common inquiries and provide additional context. To add multiple questions, add the "question" object within the "questions" array.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "questions": [
        {
          "question": "content of the question"
        }
      ]
    } 
  ]
}

Personalization is a key feature crafted to customize content for different segments of the audience. This functionality enables prioritizing access to internal content for specific users, offering more detailed information to newcomers, and establishing distinct boundaries between information accessible to various teams.

Learn more about Personalization

Prerequisites Configure tags in the Administration Console before starting the import process.

Learn more on Creating Tags

Access tags control user access to the article. To add access tags, add the "access tags" array within the "personalization" object.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "personalization": {
        "accessTags": [{
            "category": "roles",
            "tags": [
                "Agents",
                "Supervisors"
            ],
            "tagGroups": [
                "Internal employees"
            ]
        }]
      }
    } 
  ]
}

Filters act as search refiners. To add filter tags to the article, add the "filter tags" array within the "personalization" object.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "personalization": {
        "filterTags": [{
            "category": "country",
            "tags": [
                "US",
                "CA"
            ],
            "tagGroups": [
                "states"
            ]
        }]
      }
    } 
  ]
}

Publish views are a set of access tags that help manage this method of single-sourcing articles by generating a version of the article for each assigned publish view. To add publish views to the article, add the "publish view" array within the "personalization" object.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
        "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "personalization": {
        "publishViews": [
          {
            "name": "Ingestion Service Publish View"
          }
        ]
      }
    }
  ]
}

Attachments are supplementary files that can be added to an article.

To add an attachment:

1. Store Files: Place all attachment files within the /resources folder.
2. Specify Path: In the JSON, define each attachment's name and source path pointing to the /resources folder.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "attachments": [
          {
              "path": "resources/sample-attachment.pdf"
          }
      ]
      }
    ]
}

• Uploading: Upload image files to the /inline_resources folder. A maximum of 60 images can be included per article.
• Requirements:
  • Each image must be under 12 MB.
  • Supported formats: .GIF, .SVG, .BMP, .JPG, .JPEG, .JPE, .PNG, and .TIF.
• Using: Inline images can be inserted using a URL. The maximum is 100 per article.
• Inserting: Add the image path directly to the HTML body content.

Learn more about inline images

Sample article content to add inline images:

{{inline_resources/salesleads.jpg}}

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history2.html",
      "articleImage": {
          "imageURL": "https://sampleimage.url.com"
      }
    } 
  ]
}

content/order-history2.html

<p>This is the body of the sample article in HTML format. \n{{inline_resources/sample.jpg}}</p>

• Linking Internal Articles: To link another internal article, add the path to the article in the body content.
• Requirements: The linked article must already exist.
  To ensure Article to Article linking functions correctly, folder and article names must not contain reserved characters: {, }, or /. If these characters are detected in a name, the import validation will fail.

Sample article to article linking:

{{Mirrored Content/amitv/Product/Marketing/Content Marketing Strategies}}

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history3.html",
      "articleImage": {
          "imageURL": "https://sampleimage.url.com"
      }
    } 
  ]
}

content/order-history3.html

<p>The {{Mirrored Content/amitv/Product/Marketing/Content Marketing Strategies}} article contains many content marketing strategies to utilize.</p>

This feature enhances user experience by providing additional relevant information.

Learn more about related articles

To add related articles, create the relatedArticles section in the JSON structure.

Associate articles with external resources by adding links under webArticlesLinks.

"relatedArticles": {
    "webArticlesLinks": [
        {
            "title": "Google",
            "link": "https://google.com"
        },
        {
            "title": "Wikipedia",
            "link": "https://wikipedia.org"
        }
    ]
}

Associate articles with other internal articles under the articles array.

"relatedArticles": {
    "articles": [
        {
            "path": "Reasoning Engine/Content/Shared/articleName1"
        },
        {
            "path": "Knowledge Base/Content/Shared/articleName2"
        }
    ]
}

Combine webArticlesLinks and articles within the relatedArticles section.

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": 
      "content/order-history.html",
      "relatedArticles": {
          "webArticlesLinks": [
              {
                  "title": "test1",
                  "link": "https://google.com"
              }
          ],
          "articles": [
              {
                  "path": "Reasoning Engine/Content/Shared/articleName"
              }
          ]
      }
    }
  ]
}

Custom attributes allow users to add additional metadata fields.

Prerequisites Configure custom attributes in the Administration Console before importing.

Learn more on Creating Custom Attributes

Create a Custom Attribute in the Administration Console

1. Login to the eGain Administration Console.
2. Go to the partition space from the Partition and Departments dropdown.
3. Navigate to Tools > System Attributes.
4. Select the KB article data business object.
5. Create and save the necessary custom attributes.

Add Custom Attribute Entries Within the customAttributes section, add entries for each attribute.

{  
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "customAttributes": [
          {
              "name": "attribute1",
              "value": "value1"
          },
          {
              "name": "attribute2",
              "value": "true"
          }
      ]
    }
  ]
}

Enable AI services for the article from the Properties pane. This allows Generative AI to use the article in Instant Answers.

Learn more on enabling AI Services on Administration Console

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "ai": true
    } 
  ]
}

The article JSON format can support import in multiple languages. defaultPrimaryLang should be provided; if not, en-US will be the default.

{
    "defaultPrimaryLang": "en-gb",
    "articles": [
        {
            "name": "Chat Links V3",
            "folder": {
                "path": "Reasoning/Content/Shared"
            },
            "skipPrimaryLanguage": false,
            "content": "content/order-history.html",
            "metadata": {
                "description": "Sample Article",
                "summary": "Sample Article",
                "keywords": "Chat",
                "additionalInfo": "NA"
            },
            "ai": true,
            "translations": [
                {
                    "langCode": "es-es",
                    "name": "Chat links V3 spanish",
                    "content": "content/order-history_es.html"
                }
            ]
        }
    ]
}