Skip to content
Ingestion/
/
Article Import
Last updated

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.
    {
  "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.
    {
  "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.

ParameterDescriptionType
availabilityDateEnter 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
{
  "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.

ParameterDescriptionType
expirationDateEnter 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
{
  "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

ParameterDescriptionType
nameName of the macro. Must not contain any spaces or the following characters: < , . ? : ; & " ' !String
defaultValueDefault Value of the Macro. Only used when the article macro does not have any content.String
descriptionA brief description of the Macro.String
{
  "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

ParameterDescriptionType
descriptionThe description of the article offers information and context to the article.String
summaryThe summary of the article can be a one-line review of the content of the article.String
keywordsKeywords are unique words to help identify article content.String
additionalInfoThis is additional information for the article.String
{
  "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’.

ParameterDescriptionTypeEnum
articleCategoryProvide a category for the article.String [enum]• General
• Guided Help
• Data Link
• Topic Home
• Suggestion
• Virtual Assistant Action
• Rich Message
{
  "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.

ParameterDescriptionType
imageURLProvide an external link for the image.String
{
  "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.

ParameterDescriptionType
noteContent of the note.String
{
  "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.

ParameterDescriptionType
questionContent of the question.String
{
  "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.

ParameterDescriptionType
categoryCategory of the access tag.String
tagsArray containing tags associated with the access tag category.Array
tagGroupsArray containing tag groups associated with the access tag category.Array
{
  "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.

ParameterDescriptionType
categoryCategory of the filter tag.String
tagsArray containing tags associated with the filter tag category.Array
tagGroupsArray containing tag groups associated with the filter tag category.Array
{
  "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"
            ]
        }]
      }
    } 
  ]
}

Publish Views

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.

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

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.
ParameterDescriptionType
pathAttachment source file path. Maximum size: 10 MB.String
{
  "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}}

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history2.html",
      "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>

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

{
  "articles": [
    {
      "name": "Sample Article Name",
      "folder": {
          "path": "Parent Folder/Subfolder"
      },
      "content": "content/order-history3.html",
      "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.

Web Articles

Associate articles with external resources by adding links under webArticlesLinks.

ParameterDescriptionType
titleTitle of the related web article.String
linkURL of the related web article.String
"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.

ParameterDescriptionType
pathPath to the related article within your knowledge base.String
"relatedArticles": {
    "articles": [
        {
            "path": "Reasoning Engine/Content/Shared/articleName1"
        },
        {
            "path": "Knowledge Base/Content/Shared/articleName2"
        }
    ]
}

Combining Both

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

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.

ParameterDescriptionType
nameName of the custom attribute.String
valueValue of the custom attribute.String
{  
  "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

ParameterDescriptionType
articles[].includeInGenAIAllows the article to be used in Instant Answers. Default is false.Boolean
{
  "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.

{
    "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"
                }
            ]
        }
    ]
}
Previous page
Next page