Advanced FAQ
Combodo's customers only
- 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
-
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.
-
-
Allow to link FAQs to Tickets (Add a FAQs tab on Ticket). Those FAQs can potentially help for the resolution of that Ticket.
-
Add a
Keywords
field on the Ticket, for the agent to summarize the reported issue in a few words -
Prefill the search of FAQ to match the Ticket entered
keywords
and limit the FAQs to the “published” -
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
-
-
Increase automatically the rate of
useful
associated FAQs on Ticket closure
FAQ edition & rating
-
Allow to manage FAQ status, to publish and obsolete FAQs
-
Allow to flag a published FAQ for rework (FAQs to rework are listed in a
FAQ Overview
Dashlet) -
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.
-
-
Allow to tag FAQs applicable to different
Products
, which you can freely define -
Allow to tag FAQs based on the
Audience
(public, restricted, premium and internal): -
Visibility of FAQs on the Portal is computed based on those audiences and limited to published FAQs:
-
Portal User
seeingpublic
, -
Power Portal user
seeingpublic
+restricted
-
premium
could be used for Partner
-
-
A portal user can note a FAQ to increase its rate
-
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
-
First ensure that you have define at least one FAQ category as it is mandatory to create a FAQ
-
Create or modify your FAQs with additional meta information
-
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 |
Related FAQs
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
-
-
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
andError 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.
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:
-
You have linked FAQs to the Ticket, then those FAQs will be proposed, as long as not flagged as
non applicable
. -
Otherwise, if you have entered Key words on the Ticket, they will be used to filter the FAQs
-
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)
-
Has your administrator configured the parameter compute-related-faqs? Because out of the box, this behavior is not activated.
-
Other possibility if he has, note that in some corner case, you can delete a
manual
relation which should also beauto
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 ), ),