Jump to: navigation, search

Knowledge Agent

Overview

Knowledge agent is an AMD-based module that can be used with RequireJS. It exports the _gka variable into the local context where it is accessed.

Configuration

_gka.initialize(options) Examples
Description: Configure the Knowledge agent.
  • options
    Type: PlainObject
    A set of key/value pairs that configure the Agent.
    • host
    Type: String
    A network host where Knowledge API is stored.
    • kbId
    Type: String
    Knowledgebase default identifier to be used.
    • knowledgebases
    Type: String[]
    Knowledgebases identifiers to be used
    • lang
    Type: String
    Default language to be used.
    • agentId
    Type: String
    Agent ID
    • auth
    Type: String
    Agent ID
    • customerId
    Type: String
    Customer ID
    • authorization
    Type: String
    Basic authorization token
    • media (default: 'chat')
    Type: String
    Default search filter by media channel type
    • apiClientId (default: 'web')
    Type: String
    A web client identifier
    • apiClientMediaType (default: 'selfservice')
    Type: String
    A web client media type
_gka.initialize({
    host: 'http://localhost:8080',
    knowledgebases: ['knowledgefaq', 'knowledgearticles']
})

Knowledge Agent API

Once configuration is complete, the Agent can receive data from the Knowledge API. The _gka variable contains the following interfaces:

Method Description
Knowledge Base Operations
.getKnowledgeBases() Retrieves list of knowledge bases supported
.getKnowledgeBaseInfo() Retrieves information about the particular knowledge base
.getCategories() Retrieves list of categories
.getFullContent() Retrieves full content of particular document
FAQ retrival
.search() Executes search for the answer for the given query
.getDocumentsByCategory() Retrieves documents associated to a specific category
.getTrending() Retrieves trending documents
.suggestions() Provides autocomplete functionality
Feedback
.noAnswer() Marks query as the one that do not have valid answer in knowledge base
.vote() Records user rating for the document within query
.advancedVote() Advanced version of .vote()
.visit() Registers viewing the document
.rating() Registers 5-star rating for the document
.addRating() Adds rating feedback to an existing vote

Knowledge Base Operations

Important
For additional information, please refer to the Knowledge API page.
_gka.getKnowledgeBases(): Promise Example
Description: Retrieves information about the particular knowledge base.
 _gkn.getKnowledgeBases().done(function(response, status) {
    console.log(response)
}).fail(function(error, status) {
    console.log(error)
});
Response
  • knowledgebases

    Type: PlainObject[]
    List of supported knowledgebases

    • name
      Type: String
      Name of knowledgebase
    • languages
      Type: String[]
      List of supported languages
{
    "knowledgebases": [{
        "name": "knowledgefaq",
        "languages": [
            "en"
        ]
    }, {
        "name": "the_bank",
        "languages": [
            "en"
        ]
    }]
}
_gka.getKnowledgeBaseInfo([options]): Promise Example
Description: Retrieves information about the knowledge base.
  • options
    Type: PlainObject
    A set of key/value pairs that contains arguments for the RESTful API.
    • kbId (default: stored _gka.kbId)
      Type: String
      Particular knowledge base identifier.
_gkn.getKnowledgeBaseInfo().done(function(response, status) {
    console.log(response)
}).fail(function(error, status) {
    console.log(error)
});
Response
  • languages

    Type: String[]
    List of supported languages for given knowledgebase

{
    languages: [
        'en',
        'fr',
        'de'
    ]
}
_gka.getCategories(): Promise Example
Description: Retrieves list of categories.
_gkn.getCategories().done(function(response, status) {
    console.log(response)
}).fail(function(error, status) {
    console.log(error)
});
Response
  • categories

    Type: PlainObject[]
    List of supported categories

    • id
      Type: String
      Category identifier
    • name
      Type: String
      Category name
    • count
      Type: Number
      Total count of documents in category
{
    "categories": [{
        "id": "Home Mortgage",
        "name": "Home Mortgage",
        "count": 78
    }, {
        "id": "Home Equity Basics",
        "name": "Home Equity Basics",
        "count": 78
    }]
}
_gka.getFullContent(options): Promise Example
Description: Retrieves full content of particular document.
  • options
    Type: PlainObject
    A set of key/value pairs that contains arguments for the RESTful API.
    • kbId
      Type: String
      Knowledge base identifier
      • docId
        Type: String
        Particular document identifier.
     _gkn.getFullContent({
        docId: 'knowledge'
    }).done(function(response, status) {
        console.log(response)
    }).fail(function(error, status) {
        console.log(error)
    });
    Response
    • id

      Type: String

    • language
      Type: String
    • typeName
      Type: String
    • kbId
      Type: String
    • categories
      Type: String[]
    • created
      Type: Number
    • modified
      Type: Number
    • snippet
      Type: String
    • fields
      • id
        Type: String
      • created
        Type: Number
      • answer
        Type: String
      • categories
        Type: String[]
      • question
        Type: String
      • modified
        Type: Number
    {
        "id":"knowledge",
        "language":"en",
        "typeName":"qna_document_en",
        "kbId":"knowledge",
        "categories":[
            "Booking trips"
        ],
        "created":1402573911163,
        "modified":1402573911163,
        "snippet":"",
        "fields":{
            "id":"knowledge",
            "created":1402573911163,
            "answer":"Every travel option we offer",
            "categories":[
                "Booking trips"
            ],
            "question":"What’s the difference between",
            "modified":1402573911163
        }
    }

    FAQ retrival

    _gka.search([options]): Promise Example
    Description: Executes search for the answer for the given query.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • from (default: 0)
        Type: Number
        Pagination offset.
      • size (default: 10)
        Type: Number
        Pagination page size
      • query (default: '')
        Type: String
        User typed query string
      • categories (default: [])
        Type: String[]
        List of categories that is used as a context for the current query
      • filters
        Type: String[]
        List of filters
    _gkn.search({
        from: 0,
        size: 10,
        query: '',
        categories: []
    }).done(function(response, status) {
        console.log(response)
    }).fail(function(error, status) {
        console.log(error)
    });
    Response
    • count

      Type: Number

    • page
      Type: PlainObject
      • from
        Type: Number
      • size
        Type: Number
    • documents
      Type: PlainObject[]
      • id
        Type: String
      • language
        Type: String
      • typeName
        Type: String
      • kbId
        Type: String
      • categories
        Type: String[]
      • created
        Type: Number
      • modified
        Type: Number
      • snippet
        Type: String
      • score
        Type: Number
      • fields
        Type: PlainObject
        • question
          Type: String
        • answer
          Type: String
      • morelikethis
        Type: String[]
      • confidence
        Type: Number
    • categories
      Type: PlainObject[]
      • id
        Type: String
      • name
        Type: String
      • count
        Type: String
    {
        "count": 78,
        "page": {
            "from": 0,
            "size": 10
        },
        "documents": [
            {
                "id": "knowledge",
                "language": "en",
                "typeName": "qna_document_en",
                "kbId": "knowledge",
                "categories": [
                    "Home Equity Basics",
                    "Home Mortgage"
                ],
                "created": 1404823845989,
                "modified": 1404823845989,
                "snippet": "What is the difference\n",
                "score": 4.20981,
                "fields": {
                    "question": "What is the difference",
                    "answer": "Locking ensures that you"
                },
                "morelikethis": [
     
                ],
                "confidence": 1.0
            },
            {
                "id": "knowledge",
                "language": "en",
                "typeName": "qna_document_en",
                "kbId": "knowledge",
                "categories": [
                    "Home Equity Basics",
                    "Home Mortgage"
                ],
                "created": 1404823845989,
                "modified": 1404823845989,
                "snippet": "How long do I have to pay",
                "score": 4.20981,
                "fields": {
                    "question": "How long do I have",
                    "answer": "If you obtained your"
                },
                "morelikethis": [
     
                ],
                "confidence": 1.0
            }
        ],
        "categories": [
            {
                "id": "Home Equity Basics",
                "name": "Home Equity Basics",
                "count": 78
            },
            {
                "id": "Home Equity Rates & Services",
                "name": "Home Equity Rates & Services",
                "count": 2
            }
        ]
    }
    _gka.getDocumentsByCategory(): Promise Example
    Description: Retrieves documents associated to a specific category.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • kbId
        Type: String
        Knowledge base identifier
        • catId
          Type: Number
          Category ID.
        • from (default:0)
          Type: Number
          Pagination offset.
        • size (default: 10)
          Type: Number
          Pagination page size
    _gka.getDocumentsByCategory({
     catId: options.categories[0]
    }).done(function(reponse) {
     console.log(response)
    }).fail(function (error, status) {
     console.warn(error)
    });
    Response
    • count

      Type: Number[]

    • page
      Type: PlainObject
      • from
        Type: Number
      • size
        Type: Number
    • documents
      Type: PlainObject[]
      • id
        Type: String
      • language
        Type: String
      • typeName
        Type: String
      • kbId
        Type: String
      • categories
        Type: String[]
      • created
        Type: Number
      • modified
        Type: Number
      • snippet
        Type: String
      • score
        Type: Number
      • fields
        Type: PlainObject
        • question
          Type: String
        • answer
          Type: String
      • morelikethis
        Type: String[]
      • confidence
        Type: Number
    • categories
      Type: PlainObject[]
      • id
        Type: String
      • name
        Type: String
      • count
        Type: String

    For additional information, please refer to the Knowledge API page.

    {
        "count": 78,
        "page": {
            "from": 0,
            "size": 10
        },
        "documents": [
            {
                "id": "GBank_458",
                "language": "en",
                "typeName": "qna_document_en",
                "kbId": "GBank",
                "categories": [
                    "Home Equity Basics",
                    "Home Mortgage"
                ],
                "created": 1404823845989,
                "modified": 1404823845989,
                "snippet": "What is the difference\n",
                "score": 4.20981,
                "fields": {
                    "question": "What is the difference",
                    "answer": "Locking ensures that you"
                },
                "morelikethis": [
     
                ],
                "confidence": 1.0
            },
            {
                "id": "GBank_477",
                "language": "en",
                "typeName": "qna_document_en",
                "kbId": "GBank",
                "categories": [
                    "Home Equity Basics",
                    "Home Mortgage"
                ],
                "created": 1404823845989,
                "modified": 1404823845989,
                "snippet": "How long do I have to pay",
                "score": 4.20981,
                "fields": {
                    "question": "How long do I have",
                    "answer": "If you obtained your"
                },
                "morelikethis": [
     
                ],
                "confidence": 1.0
            }
        ],
        "categories": [
            {
                "id": "Home Equity Basics",
                "name": "Home Equity Basics",
                "count": 78
            },
            {
                "id": "Home Equity Rates & Services",
                "name": "Home Equity Rates & Services",
                "count": 2
            }
        ]
    }
    _gka.getTrending([options]): Promise Example
    Description: Retrieves trending documents.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • size (default: 10)
        Type: Number
        Pagination page size
     _gka.getTrending().done(function(reponse) {
     console.log(response)
    }).fail(function (error, status) {
     console.warn(error)
    });
    Response
    • count

      Type: Number[]

    • documents
      Type: PlainObject
      • id
        Type: String
      • language
        Type: String
      • typeName
        Type: String
      • kbId
        Type: String
      • categories
        Type: String[]
      • created
        Type: Number
      • modified
        Type: Number
      • snippet
        Type: String
      • score
        Type: Number
      • fields
        Type: PlainObject
        • question
          Type: String
        • answer
          Type: String
      • morelikethis
        Type: String[]
      • confidence
        Type: Number
    • categories
      Type: PlainObject[]
      • id
        Type: String
      • name
        Type: String
      • count
        Type: String

    For additional information, please refer to the Knowledge API page.

    {
        "count": 78,
        "documents": [
            {
                "id": "GBank_458",
                "language": "en",
                "typeName": "qna_document_en",
                "kbId": "GBank",
                "categories": [
                    "Home Equity Basics",
                    "Home Mortgage"
                ],
                "created": 1404823845989,
                "modified": 1404823845989,
                "snippet": "What is the difference\n",
                "score": 4.20981,
                "fields": {
                    "question": "What is the difference",
                    "answer": "Locking ensures that you"
                },
                "morelikethis": [
     
                ],
                "confidence": 1.0
            },
            {
                "id": "GBank_477",
                "language": "en",
                "typeName": "qna_document_en",
                "kbId": "GBank",
                "categories": [
                    "Home Equity Basics",
                    "Home Mortgage"
                ],
                "created": 1404823845989,
                "modified": 1404823845989,
                "snippet": "How long do I have to pay",
                "score": 4.20981,
                "fields": {
                    "question": "How long do I have",
                    "answer": "If you obtained your"
                },
                "morelikethis": [
     
                ],
                "confidence": 1.0
            }
        ],
        "categories": [
            {
                "id": "Home Equity Basics",
                "name": "Home Equity Basics",
                "count": 78
            },
            {
                "id": "Home Equity Rates & Services",
                "name": "Home Equity Rates & Services",
                "count": 2
            }
        ]
    }
    _gka.suggestions(options): Promise Example
    Description: Provides autocomplete functionality.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • query
        Type: String
        User typed query string.
      • categories
        Type: String
        List of categories that are used as context for the query.
     
    _gkn.suggestions({
        query: 'ipad'
    }).done(function(response, status) {
        console.log(response)
    }).fail(function(error, status) {
        console.log(error)
    });
    Response
    • suggestions
      Type: String[]

    For additional information, please refer to the Knowledge API page.

    {
        "suggestions":[
            "What else do I need to know at check-in",
            "What is a Non-Sufficient Funds fee",
            "What’s a 401(k) plan?\n",
        ]
    }

    Feedback

    _gka.noAnswer(options): Promise Example
    Description: Marks query as the one that do not have valid answer in knowledge base.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • from
        Type: Number
        Pagination offset.
      • size
        Type: Number
        Pagination page size
      • query
        Type: String
        User typed query string
      • categories
        Type: String[]
        List of categories that are used as context for the current query

    For additional information, please refer to the Knowledge API page.

     _gkn.noAnswer ({
        from: 0,
        size: 10,
        query: '',
        categories: []
    }).fail(function(error, status) {
        console.log(error)
    })
    _gka.vote(options): Promise Example
    Description: Records user ratings for the document within a query.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • kbId
        Type: String
        Knowledge base identifier
        • docId
          Type: String
          Particular document identifier.
        • relevant (default: true)
          Type: Boolean
          Whether the search result was relevant.
        • query
          Type: String
          User typed query string.
        • categories
          Type: String
          List of categories that are used as context for the query.
        • filters
          Type: String[]
          List of filters.
     
    _gkn.like({
        docId: ''groupon_22'',
        relevant: false
    }).fail(function(error, status) {
        console.log(error)
    });
    Response
    • recordId

      Type: String[]

      Created vote ID
    _gka.advancedVote(options): Promise Example
    Description: Marks queries that do not have a valid answer in knowledge base.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • kbId
        Type: String
        Knowledge base identifier
        • likeDocId
          Type: String
          Particular document identifier.
        • selection
          Type: String[]
          An array of document ID's in search result.
        • request (default: '')
          Type: PlainObject
          Request for the associated search.
          • query
            Type: String
            User typed query string.
          • categories
            Type: String[]
            List of categories that are used as context for the current query
          • filters Type: String[]
            List of filters.

      For additional information, please refer to the Knowledge API page.

     
    _gka.advancedVote({
        likeDocId: 'id2', selection: ['id1', 'id2', id3']
    });
    Response
    • recordId

      Type: String

      Created vote ID
    _gka.visit(options): Promise Example
    Description: Registers document views.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • kbId
        Type: String
        Knowledge base identifier
        • docId
          Type: String
          Particular document identifier.
        • query
          Type: String
          User typed query string.
        • categoreis
          Type: String[]
          List of categories that are used as context for the current query.
        • filter
          Type: String[]
          List of filters.
     _gkn.visit({
        docId: "knowledge",
    }).fail(function(error, status) {
        console.log(error)
    });
    _gka.rating(options):Promise Example
    Description: Registers 5-star rating for the document
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • kbId
        Type: String
        Knowledge base identifier
        • docId
          Type: String
          Particular document identifier.
        • comment
          Type: String
          Text comment
        • rating
          Type: String enum (1, 2, 3, 4, 5)
          Rating for the document
    _gka.rating({
     kbId: 'knowledgefaq',
     docId: '550e8400-e29b-41d4-a716-446655440000',
     comment: 'This document was very helpful',
     rating: 5
    });
    Response
    • recordId

      Type: String

      Created vote ID
    _gka.addRating(options): Promise Example
    Description: Add rating & comment to an existing vote.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • voteId
        Type: String
        Particular vote identifier
      • comment
        Type: String
        Text comment
      • rating
        Type: String enum (1, 2, 3, 4, 5)
        Rating for the document
    _gka.addRating({
     voteId: 'vote_id',
     comment: 'some comment',
     rating: 5 
    });
    Response
    Not Provided
    _gka.addComment(options): Promise Example
    Description: Registers document views.
    • options
      Type: PlainObject
      A set of key/value pairs that contains arguments for the RESTful API.
      • voteId
        Type: String
        Particular vote identifier.
      • comment
        Type: String[]
        Comment body
     
    _gka.addComment({
        voteId: 'vote_id', comment: 'some comment'
    });
    Response
    • recordId

      Type: String

      Created vote ID

    Promise Object

    The object returned by all methods of _gka variable implements the Promise interface, giving them all the properties, methods, and behaviour of a Promise (see jQuery Deferred for more information). It represents a value that may not be available yet.

    promise.done(doneCallbacks [, doneCallbacks ]): Promise Example
    Description: Add handlers to be called when the Deferred object is resolved.
    • doneCallbacks
      Type: Function(response, status)
      A function, or array of functions, that are called when the Deferred is resolved.
    • doneCallbacks
      Type: Function(response, status)
      Optional additional functions, or arrays of functions, that are called when the Deferred is resolved.
     
    promise.done(function(response, status) {
        alert('ajax call succeeded');
        console.log(response);
        console.log(status)
    });
    promise.fail(failCallbacks [, failCallbacks ])): Promise Example
    Description: Add handlers to be called when the Deferred object is rejected.
    • doneCallbacks
      Type: Function(error, status)
      A function, or array of functions, that are called when the Deferred is rejected.
    • doneCallbacks
      Type: Function(error, status)
      Optional additional functions, or arrays of functions, that are called when the Deferred is rejected.
    promise.done(function() {
        alert('ajax call succeeded');
    }).fail(function(error, status) {
        alert('ajax call failed');
        console.log(error);
        console.log(status)
    });
    promise.always(alwaysCallbacks [, alwaysCallbacks ]): Promise Example
    Description: Add handlers to be called when the Deferred object is either resolved or rejected.
    • doneCallbacks
      Type: Function(response|error, status)
      A function, or array of functions, that is called when the Deferred is resolved or rejected.
    • doneCallbacks
      Type: Function(response|error, status)
      Optional additional functions, or arrays of functions, that are called when the Deferred is resolved or rejected.
    promise.always(function(responseOrError, status) {
        alert('ajax call completed with success or error callback arguments');
        console.log(responseOrError);
        console.log(status)
    });
    promise.state(): String
    Description: Determine the current state of a linked Deferred object.

    The .state() method returns a string representing the current state of the Deferred object. The Deferred object can be in one of three states:

    • pending: The Deferred object is not yet in a completed state (neither "rejected" nor "resolved").
    • resolved: The Deferred object is in the resolved state, meaning that the doneCallbacks have been called (or are in the process of being called).
    • rejected: The Deferred object is in the rejected state, meaning that the failCallbacks have been called (or are in the process of being called).

    Feedback

    Comment on this article:

    blog comments powered by Disqus
    This page was last modified on May 29, 2018, at 12:36.