Article Import

About Articles

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

Creating 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 article.json .
  3. Start with the Root Element : Begin the JSON file with a root element named "articles" that contains an array.
    Copy
    Copied
    {
  "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.
    • Folder Path : Specify the folder path where the article will be stored.
    • Content : Include the path of the article content, which should reside under the /content folder.
      Copy
      Copied
      {
"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.

Adding Additional Parameters

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

Availability Date

The Availability Date is the specific date and time when the article is available for use in the portal, Advisor Desktop, workflows, and so on. By default, the availability date is set as the date the article is created.

Parameter Description Type
availabilityDate Enter date in the following format:
[ 20 .. 25 ] characters ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$		 String
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "availabilityDate": "2025-01-28T19:53:58Z"
    } 
  ]
}

Expiration Date

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. For example, if an article is created about a special offer for one month, give the article an expiration date.

Parameter Description Type
expirationDate Enter date in the following format:
[ 20 .. 25 ] characters ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$		 String
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "expirationDate": "2025-01-28T19:53:58Z"
    } 
  ]
}

Macros

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

Parameter Description Type
name Name of the macro. Must not contain any spaces or the following characters: < , . ? : ; & " ' ! String
defaultValue Default Value of the Macro. Only used when the article macro does not have any content. String
description A brief description of the Macro. String
Copy
Copied
{
  "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

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

Learn more about Metadata

Parameter Description Type
description The description of the article offers information and context to the article. String
summary The summary of the article can be a one-line review of the content of the article. String
keywords Keywords are unique words to help identify article content. String
additionalInfo This is additional information for the article. String
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "description": "Description of the article",
      "summary": "Summary of the article",
      "keywords": "Article keywords",
      "additionalInfo": "Additional information for the article"
    } 
  ]
}

Article Category

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’.

Parameter Description Type Enum
articleCategory Provide a category for the article. String [enum] • General
• Guided Help
• Data Link
• Topic Home
• Suggestion
• Virtual Assistant Action
• Rich Message
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "articleCategory": "General"
    } 
  ]
}

Article Image

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.

Parameter Description Type
imageURL Provide an external link for the image. String
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "imageURL": "https://sampleimage.url.com"
    } 
  ]
}

Notes

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.

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

Questions

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.

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

Personalization

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

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

Parameter Description Type
category Category of the access tag. String
tags Array containing tags associated with the access tag category. Array
tagGroups Array containing tag groups associated with the access tag category. Array
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "personalization": {
        "access_tags": [{
            "category": "roles",
            "tags": [
                "Agents",
                "Supervisors"
            ],
            "tagGroups": [
                "Internal employees"
            ]
        }]
      }
    } 
  ]
}

Filter Tags

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

Parameter Description Type
category Category of the filter tag. String
tags Array containing tags associated with the filter tag category. Array
tagGroups Array containing tag groups associated with the filter tag category. Array
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "personalization": {
        "filter_tags": [{
            "category": "country",
            "tags": [
                "US",
                "CA"
            ],
            "tagGroups": [
                "states"
            ]
        }]
      }
    } 
  ]
}

Attachments

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.
Parameter Description Type
path Attachment source file path. Maximum size: 10 MB. String
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "attachments": [
          {
              "name": "Attachment Name",
              "source": "resources/sample-attachment.pdf"
          }
      ]
      }
    ]
}

Inline Images

  • 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}}

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

content/order-history2.html

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

Article to Article Linking

  • 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.

Sample article to article linking:

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

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

content/order-history3.html

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

Related Articles

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.

Web Articles

Associate articles with external resources by adding links under webArticlesLinks.

Parameter Description Type
title Title of the related web article. String
link URL of the related web article. String
Copy
Copied
"relatedArticles": {
    "webArticlesLinks": [
        {
            "title": "Google",
            "link": "https://google.com"
        },
        {
            "title": "Wikipedia",
            "link": "https://wikipedia.org"
        }
    ]
}

Articles

Associate articles with other internal articles under the articles array.

Parameter Description Type
path Path to the related article within your knowledge base. String
Copy
Copied
"relatedArticles": {
    "articles": [
        {
            "path": "Reasoning Engine/Content/Shared/articleName1"
        },
        {
            "path": "Knowledge Base/Content/Shared/articleName2"
        }
    ]
}

Combining Both

Combine webArticlesLinks and articles within the relatedArticles section.

Copy
Copied
{
  "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

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.

Parameter Description Type
name Name of the custom attribute. String
value Value of the custom attribute. String
Copy
Copied
{  
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "customAttributes": [
          {
              "name": "attribute1",
              "value": "value1"
          },
          {
              "name": "attribute2",
              "value": "true"
          }
      ]
    }
  ]
}

AI

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

Parameter Description Type
articles[].includeInGenAI Allows the article to be used in Instant Answers. Default is false. Boolean
Copy
Copied
{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history.html",
      "includeInGenAI": "true"
    } 
  ]
}

Translations

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

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