Sidebar

Combodo

iTop Extensions

Advanced FAQ

m( m( m( Combodo's customers only 8-) 8-) 8-)

name:
FAQ advanced
description:
This extension enrich the FAQs with more integration with Tickets
version:
1.0.5
release:
2024-07-22
itop-version-min:
3.0
state:
Stable

This extension add multiple features to the management of FAQs, from controlled publication process, to Copy FAQ to Log, FAQ rating, FAQ segmentation for different audiences, FAQ linkage to Tickets, FAQs in multiple language …

Features

Use cases

If you have one of those needs, this extension is for your:

  • Ease applicable FAQ retrieval while handling a Ticket,
  • Copy FAQ content directly into Ticket Log
  • Control the FAQ publication process,
  • Allow your users to rate the FAQs,
  • Manage FAQs for different audiences (internal, public or premium),
  • Display FAQs in the user language.

Integration with Tickets

  1. Allow a agent to tag a Ticket as candidate for writing a FAQ documenting the issue of the Ticket (User Request, Incident, Change, Problem). The action of creating a FAQ based on a User Request is part of the Problem Management.
    • Add a menu to list the Tickets candidates for a FAQ still to be written. Menu named “FAQ candidate” under menu “Problem Management/FAQ overview”. Also available in the “FAQ overview” new dashboard.
  2. Allow to link FAQs to Tickets (Add a FAQs tab on Ticket). Those FAQs can potentially help for the resolution of that Ticket.
  3. Add a Keywords field on the Ticket, for the agent to summarize the reported issue in a few words
  4. Prefill the search of FAQ to match the Ticket entered keywords and limit the FAQs to the “published”
  5. Ticket resolution may last multiple days, so agent can track on each related FAQ if:
    • it is still to be tested (default value),
    • it was not helpful for this ticket
    • it was useful to this ticket
  6. Increase automatically the rate of useful associated FAQs on Ticket closure
Extension Copy FAQ to Log is included with this one, to allow an agent to copy the description of a selected FAQ on the public log of a User Request.

FAQ edition & rating

  1. Allow to manage FAQ status, to publish and obsolete FAQs
  2. Allow to flag a published FAQ for rework (FAQs to rework are listed in a FAQ Overview Dashlet)
  3. Link FAQs between them, to ease navigation to the FAQs related to the one you are looking at.
    • Link them manually and the symmetrical link is automatically created
    • Reference them within the description using the iTop self-reference syntax ([[FAQ:<id>]] or [[FAQ:<id>|My label]] where <id> is a number: the FAQ identifier in your iTop), this will automatically create the two links.
  4. Allow to tag FAQs applicable to different Products, which you can freely define
  5. Allow to tag FAQs based on the Audience (public, restricted, premium and internal):
  6. Visibility of FAQs on the Portal is computed based on those audiences and limited to published FAQs:
    • Portal User seeing public,
    • Power Portal user seeing public+restricted
    • premium could be used for Partner
  7. A portal user can note a FAQ to increase its rate
  8. Allow to create FAQs in multiple languages, linking the translated FAQs to the original FAQ
    • In case of translation: Audience, Category, Error code and Products are automatically copied from the original
    • The FAQ Overview has Dashlets to count the FAQ per language to track missing translation.

Revision History

Date Version Description
2024-7-22 1.0.5 * N°6984 - Migrate deprecated code from iTop and Symfony
* Fix JS error when importing FAQ to log
* N°7421 - Correctly handle HTML editors in iTop 3.2
* N°7285 - Migrate deprecated code from iTop and Symfony
* N°4942 - Fix issues with iTop 3.1 and Personal Data Anonymizer
2023-07-18 1.0.4 * N°6571 - Fix incompatibility when group FAQ already defined
2023-07-17 1.0.3 * N°6024 - Add label and uniqueness rules on Link classes
2022-12-18 1.0.1 First published version
2021-10-18 0.1.0 First draft

Limitations

User can vote multiple times for the same FAQ in the Portal, as a vote is not recorded as associated to a user.

Requirements

  • FAQ module must be activated at iTop Setup (itop-faq-light)
  • Requires iTop 3.0.0 or above

Installation

Use the Standard installation process for this extension.

Configuration

You should start to define and create in iTop the following objects before creating FAQs:

  • FAQ categories (mandatory)
  • Products which are under Tags configuration menu (optional)
  • Domains also under Tags configuration menu (optional)

Configuration file

The configuration parameters faq-attribute-to-search and combine-keywords are used when searching applicable FAQs from a Ticket
compute-related-faqs parameter allows to automate the FAQ to FAQ relationships handling, based on FAQ references in the description

Configuration
'combodo-faq-advanced' => array (
    'faq-attribute-to-search' => 'key_words', // or description or error_code
    'combine-keywords' => 'yes', // yes="All keywords required", no = "at least one"
    'compute-related-faqs' => 'yes', // default no, parse description to retrieve FAQ pointed in the text and link them explicitly
),
Parameter Meaning Default
faq-attribute-to-search FAQ attribute used for the search criteria, supported values are key_words, description and error_code key_words
combine-keywords if yes all the provided keywords in the Ticket, must be found in the faq-attribute-to-search, otherwise at least one of the keywords must match no
compute-related-faqs if yes parse 'description' field to retrieve FAQ references (made with [[FAQ:xx]] where xx is the remote FAQ id) and link them explicitly to the current FAQ no

The FAQ description can be paste to a single Log of a single Class (which can be abstract)
In the iTop configuration file, you can define on which class the FAQ option will be proposed and in which CaseLog the FAQ description will be copied.

Configuration: Default
      'combodo-faq-to-log' => array (
                'target_class' => 'Ticket',
                'target_caselog' => 'public_log',
        ),

The search criteria prefilled in FAQ search pop-up, can be configured, overwriting the FAQ static method GetRelatedFaq($oObject, $oFilter) to modify the Filter.

  • If you have only installed the “Copy FAQ to log” module, no filtering is applied.
  • Within Advanced FAQ, an automatic filtering is applied, see the Usage part.

Usage

  1. First ensure that you have define at least one FAQ category as it is mandatory to create a FAQ
  2. Create or modify your FAQs with additional meta information
  3. Train you support agents on how to use the FAQs while working on Ticket

New Menus

FAQ Overview A dashboard overview for FAQ management
FAQ Category This existing object was enhanced with an icon and a description for more efficient User Portal navigation
FAQs Many fields and behaviors were added to the FAQ object, see details below
FAQ candidates List the Tickets which have been flagged as candidate for writing a new FAQ related to the Ticket reported issue
My FAQs List the FAQs where the current user is the Author, only available for users allowed to create/modify FAQs

FAQ Overview

FAQ Category

The FAQ Category are a mean to group the FAQs to simplify retrieval of FAQs and related FAQs.

To create a FAQ Category from the console, you can either use the quick edit or

Start from the FAQ edit form or the Administration menu and the result will be
FAQ Category Usage
Name Label of the FAQ Category
Icon Icon of the FAQ Category, which is displayed in the Mosaic mode of the User Portal allowing to navigate within the FAQs
Description Describe when to use this FAQ Category

Managing FAQ

Create a FAQ, accessible under the Problem Management menu, from the list of FAQ or using the Quick create menu at the top.

FAQ fields Usage
Title The Issue that this FAQ is addressing
Strategy A strategy to address the Issue.
When multiple strategies can be used to address the same Issue, multiple FAQs should be created
Status For tracking the publication status.
Possible values: Draft/Published/Obsolete
Category Your own defined FAQ categories to group FAQs by logical packets.
FAQs are presented in the User Portal with a browsing mechanism by FAQ Category
Error code Free text, optional
Key words Free text, optional
Domains Similar to Keywords, but the possible values are restricted to your own defined list
Products Products for which this FAQ applies. The possible values is a typology
Audience To whom this FAQ is targeted: Internal / Premium / Public / Power users
Public: displayed on User Portal to all users
Power users: displayed on User Portal to users with “Power users” profile
Premium: displayed on User Portal to users with “Administrator” profile, can be used for Business Partner Portal users
Internal: never displayed on User Portal
Last update When the “description” was modified for the last time
Publication date When the FAQ was moved to Published status for the last time
Author / Owner Who created it or is in charge of updating it (prefilled at creation with current user, fed on update with current user if empty)
Organization Entering an “Organization” generate a FAQ segmentation, which impact who can see it
To be reworked A flag to identify Published FAQ, which content need to be reworked
Score How many times it was identified as useful, by the Portal users and the agents
Original FAQ To be used for FAQs that are Translation of an Original FAQ
Language Language of the FAQ
Translations This tab contains the FAQs which reference this one in their Original FAQ field
Result in console Result in Portal

In order to help Users navigating between FAQs which can sometimes be related, you can propose directly in the description of a FAQ a direct link to another FAQ, using the iTop wiki syntax:

  • [[FAQ:<id>]] where <id> is a number: the FAQ identifier in your iTop
  • [[FAQ:<id>|<My label>]] where <My label> is a free label which will replace the FAQ friendlyname

Once saved the referenced FAQ(s) are linked, and an hyperlink allow the user to navigate

  • When a relation is manually created between FAQ n°20 (as source) and FAQ n°47 (as related),
    • the Origin is flagged as Manual,
    • a symmetrical relation between FAQ n°47 (as source) and FAQ n°20 (as related), with the same value in Origin

  • When a reference to FAQ n°37 is entered in the description of the FAQ n°2
    • a relation is automatically created between FAQ n°2 (as source) and FAQ n°37 (as related), with Origin = Referenced,
      • if the relation exists already with Origin = Auto, it is changed to Referenced
      • if the relation exists already with Origin = Manual, it is left unchanged
    • a relation is automatically created between FAQ n°37 (as source) and FAQ n°2 (as related), with Origin = Auto
      • if the relation exists already, it is left unchanged

It is recommended to either use only Manual or only Referenced relationships.

User Portal

Your users on the User Portal will see:

  • All FAQs written in the user language
  • All FAQs which are original FAQ and have no translation in the user language (An “Original FAQ” is a FAQ with no value in this field)

FAQ categories are used as a first navigation level, before viewing the FAQs themselves.

Then user get the details of a FAQ:

Unless the referenced FAQ is not published / not visible to the user, in which case the hyperlink is disabled

You see that the Portal User can Mark this FAQ to increase its score.

User can open the FAQ in full screen instead of pop-up, to have a wider display

Languages

If you need to keep FAQs in multiple languages, this extension proposes to link each translated FAQ to an “original” FAQ considered as the reference. When that reference is modified, then all its Translations should be revisited to see if they also need an update.

  • If on a FAQ you set an “original” then the fields Audience, Category, Products and Error code are automatically inherited from the Original FAQ.
  • Then they will be computed and read-only as long as the FAQ has a “source”.
  • If the “original” is modified, the modification of any inherited fields, are cascaded on the Translated FAQs.
  • If a child FAQ has the same language as its Original, you get a warning on child submission.
  • We suggest that all “sources” use the same language, but this is not enforced.
An Original FAQ cannot be itself the translation of another FAQ, just one level of hierarchy is supported

Managing UserRequest

When handling a UserRequest, the support agent can:
1) Enter Key words which are a synthesis of the User Request description

2) Search for pertinent FAQs

  • If key words were entered, the proposed FAQs matches those words (For the matching logic used, see configuration parameters),
    • If all words are required, they appear as separated criteria
    • If at least one word is required, the search criteria is misleading, showing only the last word in the criteria, also the query behind is correct.
  • If no key words were entered, no search criterion are preset, so all FAQs are proposed.
  • The user can modify the preset filter, add some on the language, remove others…

Here the configuration requires every words to be found in the description
Other configurations are possible.

3) Add the FAQs promising to solve the caller request

4) During investigation, flag FAQs which were useful and those which were not

  • If the ticket handling span over days or agents, it can be useful to track what was checked and the results
  • FAQs flagged as useful will have their score automatically increased at the Ticket closure.

5) Paste directly a FAQ description within the log

Within the details of a Ticket (usually a UserRequest), above the log (usually the public log), you will have a button FAQ to select a particular FAQ

Out of the box, all existing FAQs will be proposed, but if you combined this extension with Advanced FAQ then the FAQs will be filtered:

  1. You have linked FAQs to the Ticket, then those FAQs will be proposed, as long as not flagged as non applicable.
  2. Otherwise, if you have entered Key words on the Ticket, they will be used to filter the FAQs
  3. In last resort, all non-obsolete FAQs will be proposed

Once you have selected a FAQ and pressed the “Add” button, the content of the FAQ description is copied within the log.

You can still add / modify the text before submitting your entry

6) Request a FAQ to be reworked

If a FAQ was difficult to read/understand and would need a rework, as a Support Agent you can say it through a Flag for rework transition, even if you have no write access on FAQs.

FAQ datamodel

Questions & Answers

Troubleshooting

Question: I can't see the Ticket fields Key words, FAQ candidate nor the FAQ tab, why?
Answer: If you have customize the Ticket presentation details, those fields must be set again manually in the ITSM Designer.
Check also the lifecycle for when they should be visible or not.

Question: Useful FAQ score is not increased on UserRequest closure, why?
Answer: If you have customize the UserRequest lifecycle or use an extension which does it such as Global requests management, then in the ITSM Designer on UserRequest ev_close transition, add an action, to call the RateApplicableFAQs() method.

Question: My Support Agents do have Allowed organizations, they don't see FAQs which have no organization, why?
Answer: This is the standard iTop behavior, when a user has Allowed organizations, he can never see objects which do have an organization field and that field is empty.
Workaround: Force the Organization to be mandatory on a FAQ.

Question: I have a referenced FAQ in my description which is clickable, but the corresponding Related FAQ is missing, why?
Answers: There are 2 options: it has never worked (1) or it's a single exception (2)

  1. Has your administrator configured the parameter compute-related-faqs? Because out of the box, this behavior is not activated.
  2. Other possibility if he has, note that in some corner case, you can delete a manual relation which should also be auto and so have an relationship missing. Modify the FAQ description containing the reference to restore the destroyed relationships.

Customization

Question:Can I have a Ref different than the default F-001?
Answer: The Ref field is computed using this logic, only if empty. If your FAQs are created by a CSV import, a Datasynchro or the API REST, you can set whatever value in the Ref it will be left as-loaded.

Question: What is the purpose of the Premium audience for a FAQ?
Answer: This value could be allowed to users having a particular profile or to users of an another Portal such as Portal for Business Partner.

Using it requires to customize those Portals either with the ITSM Designer for Combodo's customers, or by writing an extension

Question: I have a User Request which is a good candidate to be transformed into a FAQ. Can this step be simplified?
Answer: Assuming you have installed User actions configurator, you can create a rule to create a FAQ, prefilling fields:

Ticket field (code) FAQ field (code)
Key words (key_words) Key words (key_words)
Title (title) Title (title)
Solution (solution) or Description (description) Description (description)
Configuration
                'UR-to-FAQ' => array (
                    'source_scope' => 'SELECT UserRequest',
                    'allowed_profiles' => 'Problem Manager,Support Agent,Administrator',
                    'menu_label' => 'Create a FAQ...',
                    'menu_label/FR FR' => 'Créer une FAQ...',
                    'form_label' => 'Create a FAQ from  %1$s',
                    'form_label/FR FR' => 'Créer une FAQ à partir de %1$s',
                    'report_label' => 'Created from %1$s',
                    'report_label/FR FR' => 'Créée depuis %1$s',
                    'dest_class' => 'FAQ',
                    'preset' => array (
                      0 => 'copy(title,title)',
                      1 => 'copy(key_words,key_words)',
                      2 => 'copy(description,description)',
                    ),
                    'retrofit' => array (
                        0 => 'set(faq_candidate,done)',  // Requires Problem Manager to be allowed to update Tickets
                    ),
                  ),
extensions/combodo-faq-advanced.txt · Last modified: 2024/08/14 11:45 (external edit)
Back to top
Contact us