Combodo's customers only
- FAQ advanced
- This extension enrich the FAQs with more integration with Tickets
- PHP 8.1
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 …
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.
Keywordsfield 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
keywordsand 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
usefulassociated 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
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:
Power Portal userseeing
premiumcould 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
FAQ Overviewhas Dashlets to count the FAQ per language to track missing translation.
|1.0.1||2022-12-18||First published version|
User can vote multiple times for the same FAQ in the Portal, as a vote is not recorded as associated to a user.
FAQ module must be activated at iTop Setup (itop-faq-light)
Requires iTop 3.0.0 or above
Use the Standard installation process for this extension.
You should start to define and create in iTop the following objects before creating FAQs:
FAQ categories (mandatory)
Products which are under
Tags configurationmenu (optional)
Domains also under
Tags configurationmenu (optional)
The configuration parameters
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
'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 ),
|faq-attribute-to-search||FAQ attribute used for the
search criteria, supported values are
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
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.
|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
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|
|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|
Create a FAQ,
accessible under the
Problem Management menu, from the
list of FAQ or
using the Quick create menu at the top.
|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
FAQs are presented in the User Portal with a browsing mechanism by
|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
|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
|Language||Language of the FAQ|
|Translations||This tab contains the FAQs which reference this
one in their
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
[[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),
Originis flagged as Manual,
a symmetrical relation between FAQ n°47 (as source) and FAQ n°20 (as related), with the same value in
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
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
if the relation exists already, it is left unchanged
Your users on the User Portal will see:
All FAQs written in the user language
All FAQs which are
original FAQand 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
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
Error codeare 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.
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
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.
Questions & Answers
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
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
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
manualrelation which should also be
autoand so have an relationship missing. Modify the FAQ description containing the reference to restore the destroyed relationships.
Question:Can I have a Ref
different than the default F-001?
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
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
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)|
'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 ), ),