Allow people without iTop accounts to update objects through tailored forms

Get structured feedbacks from users without ​giving them credentials to your iTop.

• At a given state of your Ticket lifecycle you may want additional information from a caller who has no iTop user account.
• With this extension, you can send him a special email notification with a single-answer question.
• He can answer directly with a single click on his choice.
• Some choices may lead him to provide more details on a web form.
• His first answer will automatically update the Ticket field(s).

• The extension is localized in English and French only.
• The forms use iTop default language as the user is not authenticated
• In the form configuration (see dedicated section), only the following attribute types are supported:
• AttributeString & derivated,
  • AttributeDateTime & derivated,
  • AttributeCaseLog,
  • AttributeEnum,
  • AttributeText,
  • AttributeHTML.

iTop 2.4+ (tested with iTop 2.4.2 and above)

Use the Standard installation process for this extension.

The extension has two main parameters that can be set in the module settings part of the configuration file:

• custom_theme_url: An URL to load a custom stylesheet, allowing to put branding on the forms.
• forms: An array of form definitions that can be used in the ActionUnauthenticatedFormEmail actions
• For each form, you will define the behavior of the form.
• Each form defines 2 placeholders that can be used in the ActionUnauthenticatedFormEmail actions

The parameters should be structured like the following:

'combodo-unauthenticated-forms' => array (
  'custom_theme_url' => 'https://itop/path-to-css/theme.css',
  'forms' => array (
    // <FORM_ID> is the unique identifier of the form, will be used in the action placeholders.
    <FORM_ID> => array (
 
      // Optional. Allow you to disable the form without loosing its configuration.
      // Value can be true|false, default is true.
      'enabled' => true,
 
      // Optional. Description will be shown to the user configuring the action, next to the placeholders.
      'description' => 'Prompts the user with satisfaction and comment so he/she can provide a feedback on how its request has been handled.',
 
      // Optional. Defines if the form will prompt to the end-user when he/she clicks on the hyperlink
      // within the email.
      // If not prompt, the form will be filled with values from the 'fields' part of the 
      // form configuration.
      // Value can be true|false, default is true.
      'prompt_form' => true,
 
      // Fields of the form, must be valid attributes of the object (see Limitations section 
      // for supported attribute types)
      // If a value is specified for an attribute, the field will be pre-filled in the form
      // (can also be used for setting values directly when not prompting the form)
      'fields' => array (
        'user_satisfaction' => 4,
        'user_comment' => null,
      ),
 
      // Optional. The stimulus code to apply on the object after the form submission.
      // Note that if the stimulus can't be applied (not available in current state for example), 
      // it will be skipped so the end-user doesn't get an error message.
      'stimulus' => 'ev_close',
 
      // Optional. Labels of the form and its various feedbacks.
      'labels' => array (
        // Optional. Label of the button in the generated email.
        // If not present, the <FORM_ID> will be used.
        'mail_button' => NULL,
 
        // Optional. Title displayed in the header of the form.
        'form_title' => 'UnauthenticatedForms:Form:DefaultLabel:Form:Title',
 
        // Optional. Short text displayed above the form fields, should be used to guide the end-users through the form filling.
        'form_description' => 'UnauthenticatedForms:Form:DefaultLabel:Form:Description',
 
        // Optional. Message shown when form submission is successful.
        'feedback_success' => 'UnauthenticatedForms:Form:DefaultLabel:Feedback:Success',
 
        // Optional. Message shown to an end-user accessing the form with an expired token.
        'feedback_expired' => 'UnauthenticatedForms:Form:DefaultLabel:Feedback:Expired',
 
        // Optional. Message shown to an end-user accessing the form with a token that
        // has already been used by him/herself or someone else.
        'feedback_already_used' => 'UnauthenticatedForms:Form:DefaultLabel:Feedback:AlreadyUsed',
 
        // Optional. Message shown when an error occurs.
        'feedback_error' => 'UnauthenticatedForms:Form:DefaultLabel:Feedback:Error',
      ),
    ),
  ),
  <FORM_ID_2> => array(
    ...
  ),
)

First you need to design the forms you want the end-users to access in the configuration file (see section above).

Then go to the “Admin tools > Notifications” menu and create a new “Action” object of the class “Unauthenticated email action”. Fill all attributes and associate the desired trigger(s) like on a regular email action.

For the body attribute, you can use placeholders to insert links to the previously configured forms. Those placeholders are of the form:

• $unauth_form_<FORM_ID>_url$ for a raw url
• $unauth_form_<FORM_ID>_button$ for a hyperlink with the mail_button label from the configuration.

Check the “Help” tab of the object to have an overview of the available forms and their placeholders.

When the corresponding trigger is called, emails will be send to the recipients. In our example, they will look like this:

When the user click on one of the link he will get either the form to fill in, or directly the message below if there is no additional information to provide.

Each actions is identified by a unique token, that can be used once. When the action is submitted, the url cannot be used any more. The token is unique for all the recipients of this email. So only one person can answer.

Forms can stylized easily through a CSS file for some color changes or to match your company branding. You can do so by creating your own stylesheet and customize the default theme, but you can also apply any Bootstrap 3 theme you like.

• Create a new .css file and put your style in it. (eg. my-theme.css)
• Copy you CSS somewhere on your webserver (eg. /data/my-theme.css)
• Set the cutom_theme_url module parameter in the configuration file (see section above). It must be the absolute URL to this file (eg. https://myitop/data/my-theme.css)

For this example we are making a theme that will round the form & button corners. It will also change the header color to something darker. Here is the content of the my-theme.css file:

.panel{
    border-radius: 8px;
}
.panel-heading{
    border-top-right-radius: 8px;
    border-top-left-radius: 8px;
}
.panel-default > .panel-heading{
    color: #fff;
    background-color: #5b5959;
}
.btn{
    border-radius: 8px;
}

Before the theme

After the theme

• Copy the Bootstrap theme to your webserver (eg. /data/bootstrap-theme.css)
• Set the custom_theme_url module parameter in the configuration file (see section above). It must be the absolute URL to this file (eg. https://myitop/data/bootstrap-theme.css)

Before the theme

After the theme