Create and manage Form pages for any template. All the forms available to the current user are listed here.

The "Filter" field allows to narrow down the information displayed by applying specific criteria. The search is applied to all the data columns. For example, typing "Ticket" would display all forms with the target template "Ticket" and also all the forms with the word "Ticket" in their name.

The forms have their information displayed in the following columns:

Creating New Forms

1. To start the creation of a new form, click on the "New Form" button:
   
2. This will open up the "New Form" window:
   
3. To start the creation process, select the target template from the list below. The Find-field can be used to narrow down the list of templates.
4. Once the template has been selected, click on the Done-button to continue. This will open up the form creation menu:
   
5. The following fields are available:
   • Icon - The default icon can be changed by clicking the icon and selecting a new one from the selection menu.
   • Name (required) - Name of the form. Limit is 60 characters.
   • Reporter (required) - Name of the person or the entity who reported the issue handled by the form. In majority of the cases, this is end user who logged into the portal.
   • File attachment - Whether file attachment to the form is possible or not. This requires the FileUpload-handler to be activated on the selected template.
   • Discussion - Whether two way discussion via comments is possible or not. This requires the Comment-handler to be activated on the selected template.
   • Publish - When the form is published, it becomes available to be inserted to panels, lists and panel groups.
6. To add fields to the Form, click on the New field button. 
7. To add elements to the Form, click on the New Element button. Admins can include section titles and text blocks on a form, to provide more guidance to an end-user completing a form. Admin can arrange the order of the section title and text block. Section title and text block are only visible when creating an ticket, not on detailed view of existing issue.
   1. When clicking the New Element button, a drop-down menu appears below it, with Section title and Text block as options. This is similar to adding a new field. 
      1. Section title - This adds a section title with the max length of 450 characters
      2. Text block - This adds a text block with a max length of 2000 characters. Content on the text block can be rich edited text including URLs . Note: Images are not supported in rich text edited text block.
8. On all fields, the field creation process has two steps: 
   1. Select the attribute on the first Target-step from the "Target Attribute" field.
   2. Finalize the field on the second Appearance-screen where the Display name can be selected (by default, it displays the Target Attribute name, selected previously). 
9. The field can be one of the following:
   • Checkbox - The target attribute needs to be a multi-value static string. Note that if new values are added to the attribute, this field is not automatically updated with those values.
     • Has "Limit selections" which limits the maximum number of possible selections and "Required" (minimum number of checkbox selections) options on the Appearance-screen.
   • Date - This includes attributes with date-datatypes.
   • Date & Time - This includes attributes with date and date&time -datatypes.  
     • Has the Required (is this field required) on the Appearance-screen.
   • Drop-down- The target attribute is a single value static string  or a Reference attribute from a target template:
     • Has the "Required" and the “Use Tool-tip ” options on the Appearance-screen.
       • "Required" option: if activated, the user has to fill in this field. 
       • “Use Tool-tip” option: if activated, a tooltip becomes visible to the end user while they are hovering over a menu value. The tooltip displays the same data as shown in the ESM UI for a reference value (selected attributes of the template), provided that the user associated with the reference fields (defined in General Settings → ‘Reference Permissions User’) has the necessary access rights to view this data.
     • When reference attribute is selected, a preview of the first 25 data cards can be displayed by pressing the “Preview Data” button.
       • If the reference attribute has an EQL filter defined, then it is notified under the dropdown menu with the warning “Note: Attribute has EQL filter defined. Please check the exact filter on Template Editor”.
   • Multi-select drop-down - The target attribute needs to be a multi-value static string or a Reference attribute from a target template: . Note that if new values are added to the attribute, this field is not automatically updated with those values. 
     • Has "Limit selections" which limits the maximum number of possible selections, "Required" and “Use Tool-tip” options on the Appearance-screen.
       • "Required" option: if activated, the user has to fill in this field. 
       • “Use Tool-tip” option: if activated, a tooltip becomes visible to the end user while they are hovering over a menu value. The tooltip displays the same data as shown in the ESM UI for a reference value (selected attributes of the template), provided that the user associated with the reference fields (defined in General Settings → ‘Reference Permissions User’) has the necessary access rights to view this data.
       • Note that for references, the maximum amount of selections is 25 values. 
     • When reference attribute is selected, a preview of the first 25 data cards can be displayed by pressing the “Preview Data” button.
       • If the reference attribute has an EQL filter defined, then it is notified under the dropdown menu with the warning “Note: Attribute has EQL filter defined. Please check the exact filter on Template Editor”.
   • Short text - A string a single-line input for short alphanumeric data, such as names or email addresses.
     • Has the Required (is this field required) on the Appearance-screen.
     • Data validation via regular expression can be added, if “Data Validation” is enabled.
       • Enter the regular expression in the RegEx-field (limit 1000 chars).
         • Supported Regex format is a subset of both JS and re2.
       • Enter validation failure expression under the “Validation Fail Message”. This message is shown to the user if the data validation fails.  
   • Text area - Allows users to enter multiple lines of text or longer paragraphs. Can be used to capture comments, messages, or other free-form text input.
     • Has the Required (is this field required) on the Appearance-screen.
10. Once a field is added, it is displayed on the field listing below.
    • Displayed fields can be filtered by typing in the Filter-field.
    • By using the checkboxes on the field rows, several fields can be selected for deletion or moving  simultaneously.
11. If there are multiple fields, they can be rearranged by using the drag and drop handle, located on the left side of the checkbox:
    

Managing Fields

In the form menu, the form can be deleted or duplicated by clicking the three dots and selecting the appropriate option:

Under the Manage-field, the following actions are available:

Field can be removed by clicking on the Remove-button:

Field can be edited by clicking on the Edit-icon:

Conditions

Field can have conditions, which are managed by clicking the Condition-icon:

The admin can set conditions for when a field is visible to the end user, based on selections in other form fields. On the ESS2 form, the conditional field is only visible when input matches the condition exactly. Maximum amount of conditions per field is 10. Available conditions are:

• is equal to (default condition)
• is not equal to
  • If either “is equal to” or “is not equal to” operators is selected, admin also has to provide a value for the condition. 
  • The condition can’t be saved if the Value is missing.
  • White space only (blank value) is not allowed. 
  • Save becomes enabled when non-space character is entered. 
  • Max length of the value is 450 characters. 
  • If the operator is switched to exists or not exists, the value field disappears. The input is not preserved.
• Exist
• Not exists

The Source field for the condition can be a short text, drop-down, multi-select drop-down or a checkbox. When the Source is a reference, the value is selected from a drop-down, when applicable. The drop-down presents the reference values of the selected Source field. When clicking the Value field, the list of values associated with that drop-down is displayed. Users can search for values by typing a string of printable letters. If all reference attributes are not loaded when opening the drop-down, more values are loaded when scrolled to the bottom/down.

By clicking the add icon, the admin can configure multiple conditions:

When there are more than one conditions on a field/fields, a condition connector is shown. It is telling if all of the conditions need to be true (AND) or only one of them (OR). It is either AND or OR, for the whole set of conditions. By default the connector is AND. It can be changed to the other by clicking it.

If the a condition is not invalid, a warning text is displayed, the condition is highlighted and marked with an icon:

To remove the new condition, click on the remove-icon:

Multimapping Attributes

Normally, the Target Attribute defaults to the same Target Attribute as the Source attribute is. When both are same, a reference between these two attributes is created. If they are different, multimapping is created. 

Administrators often want to define more questions than the target template has available attributes. In this case, the admin maps many input form fields to one "Additional information" text attribute. 

When multimapping is used, no reference between the attributes is created and the string values of the selected options are written as lines of text to the value of the targeted text attribute. 

The target datatype will always be “Text” and it is formatted as: 

Multiple selections:<field name>:<selected value 1> <selected value 2>,... Single selections:<field name>:<selected value 1>

When adding any form field, the admin can select an attribute with datatype “Text” to be the target of for them. 

Source can be from:

• Any static string from whatever template that is accessible.
• Date (in the form: dd.mm.yyyy).
• Date and Time (in the form dd.mm.yyyy hh:mm).
• Reference attribute from a target template:
  
  • When reference attribute is selected, a preview of the first 25 data cards can be displayed by pressing the “Preview Data” button.

Example of Multimapping

 An example of a multimapped field creation:

1. Click on “New field”.
2. Select "Multi-select Drop-down".
3. Under Attribute, select Template “Ticket”.
   1. When selecting template, the Source attribute will only show valid attributes (some templates have none!).
4. Select Source Attribute “Tasks” and click “Next”.
5. Under “Target Attribute” select “Details”. 
   1. Since the Target and Source attribute are different, multimapping is created and the text format is displayed below:
      
6. Set display name, choose if “Limit selections” and/or “Required” are turned on.
7. Once everything is ready, press “Done” to create the field. 

Source can also have Custom values which are always pure text data (defined at the form-field):

Filtering Reference Values for Forms with EQL Filters

The feature enables a dropdown on a Form in the portal to display different options to different users or narrow down results based on certain data card value.

An admin can configure ESS2 specific EQL filters to any reference attribute of any template and they will be located in the reference attribute's Other properties -area. Below is example how ESS2 filter shall be added to the Other properties area.

On the left-hand side, EQL filter should be prefixed with "ess2_filter_" to set them apart from ESM EQLs, and admin can type any EQL in the metadata field. After prefix, there will be info of from which source template code is referred to what target template code, for example: “ticket->service”. On the right-hand side, paste the EQL statement as is. The ESS2 EQL impact to all reference Form fields that are using this template attribute as source attribute.

The EQL filter is available on the drop-down and multi-select drop-down fields.

EQL is saved on source attribute of the reference field. It is also possible to add multiple ESS2 filters to one attribute that refer to different templates in the case the reference field has EQL filter. For more information about the EQL logic and usage, see the article EQL Editor. Note that the user macros used in ESS2 / Pro Self-Service are identical to the ones used in the EQL examples, they just have the "ess2" prefix in at the start (#Username# vs #ess2Username#, etc.)

For using user macro's, note that the format is different in ESS2 use case. In ESS2 the supported user macros are:

• #ess2UserName#
• #ess2UserId#
• #ess2User#

Use case examples of user macro's below

Override Defaults

An ESS2 admin can define override default values which will be set to data card when it is created through the ESS2.

The administrator can set "Override values" to each Form by:

1. Navigating to its configuration tab on self-service admin page.
2. Pressing "New override" on the table configuration area.
3. Adding a new override value.

 Supported data types are:

• String
• Static string
• Text fields
• Reference fields

When values are set in the configurator, all data cards that are created, will use given override values of used form. If the admin defines a form field, and override value to same target attribute, the user input to form field overrides form specific override value. 

This feature extends the functionality of the override values to include support for Reference attribute types.

As an administrator can define a Reference value also to the Override values, so that the admin can define e.g. default support groups to each Form.

To override defaults, the admin can select a single value reference attribute type. Note that in the override defaults config area, the admin can select any data card they have access, without a restriction of the permission user.

Admin:

• Admin can select a reference attribute type (not multi-value)
• After selection, admin can open a drop-down to see the list of available datacard names (or primary attribute)
  • the admin can select any data card they have access, without a restriction of the permission user
  • datacards are paginated
• Admin can select from one of the options in the drop-down
• After the form has been submitted in the Portal UI, the generated datacard will contain the stored value in the associated attribute.

End-user:

• The end user should see only the values where the permission user has an access. 
  • In a case where: 1.) the admin has configured an override value to which the "Reference permission user" has no access, and 2.) the attribute has been configured to be visible in request details (either through Form or Presentation View) →  The end user will not see the value in the request details.
• If the referred datacard is deleted, created datacards shall receive empty value to the targeted attribute

Override Values for Reference Fields

To override defaults, the admin can select a single value reference attribute type. Note that in the override defaults config area, the admin can select any data card they have access, without a restriction of the permission user.

Admin:

• Admin can select a reference attribute type (not multi-value)
• After selection, admin can open a drop-down to see the list of available datacard names (or primary attribute)
  • the admin can select any data card they have access, without a restriction of the permission user
  • datacards are paginated
• Admin can select from one of the options in the drop-down
• After the form has been submitted in the Portal UI, the generated datacard will contain the stored value in the associated attribute.

End-user:

• The end user should see only the values where the permission user has an access. 
  • In a case where: 1.) the admin has configured an override value to which the "Reference permission user" has no access, and 2.) the attribute has been configured to be visible in request details (either through Form or Presentation View) →  The end user will not see the value in the request details.
• If the referred datacard is deleted, created datacards shall receive empty value to the targeted attribute

How Add New Override Values for Reference Fields

Open up a “General Forms → Form → Override Defaults”:

Click on the +New override button. This opens the New override creation wizard.

1. Select the attribute target attribute.
2.  Once selected, the Value field displays the current default value for the template.
   
3. Now, in the Value field, choose the new value to override the default one:
   
4. Click Save to save all the changes.
5. The new override value will now be displayed under the Value column in the Override Defaults view:
   

Comment Handler Details

The comment handler is a new handler which UI is based on the Worklog handler. Every time when the ESM or the ESS2 user adds a comment, the comment will be added as child data card to the parent data card (the main data card to which the comments / child cards are linked). The comment template is located under the System templates but the template is locked and editing is disabled for the ESM admins. If parent data card is removed, also all related comment data cards will be deleted. In addition, the comment is seen as part of the main data card and therefore also global search returns the parent data card if the search string value is found in the comment.

Also the comment handler keeps track on new comments, that haven't been marked as read. The ESS2 automatically handles new comments and marks them automatically read. On ESM side the ESM user shall mark new comments read manually.

Unread comments will get a "New" marking on the ESS2 and ESM user interfaces. On the ESM user interface, the agent shall manually update comments read on the data card. If ESM users want to find issues with unread comments, they can use Matrix42's reporting tool to help narrow down results.

A new comment is added when the user adds a file or files to the issue. The comment includes the file name with extension. A comment is not added if the ESM agent adds a new file to the issue through the ESM user interface.

For more information how to handle comments through the Python API, see this article.

Attribute Tags

When selecting an attribute, the list of attributes shows the attribute's type as a tag next to it:

These lists and tags are shown when:

• Selecting the Source Attribute for a form field.
• Selecting the Target attribute for a form field.
• Selecting an override attributes for a form.
• Selecting the attributes to be displayed on Details of case presentation.
• Selecting the attributes to be displayed on Overview of case presentation.