Advanced FAQ

Combodo's customers only

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.

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

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.

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 configuration menu (optional)
• Domains also under Tags configuration menu (optional)

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
),

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

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

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

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

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

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.

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

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.

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.

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:

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
                    ),
                  ),