Dynamic Fields

Introduction
Configuration
Adding a Dynamic Field
Text Dynamic Field Configuration
Textarea Dynamic Field Configuration
Checkbox Dynamic Field Configuration
Dropdown Dynamic Field Configuration
Multiselect Dynamic Field Configuration
Date Dynamic Field Configuration
Date / Time Dynamic Field Configuration
Editing a Dynamic Field
Showing a Dynamic Field on a Screen
Show Examples
Setting a Default Value by a Ticket Event Module
Set a Default Value by User Preferences

Introduction

A dynamic field is a special kind of field in OTRS, created to extend the information stored on a ticket or article. These fields are not fixed in the system and they can appear only in specific screens, they can be mandatory or not, and their representation in the screens depends on the field type defined at their creation time according to the data to be held by the field. For example, there are fields to hold a text, a date, a selection of items, etc.

Dynamic fields are the evolution of TicketFreeText, TicketFreeKey, TicketFreeTime, ArticleFreeText and ArticleFreeKey fields that where commonly used in OTRS 3.0 and before. The limitation of these "Free Fields" was that they can be defined up to 16 (text or dropdown) fields and 6 time fields for a ticket and 3 (text or dropdown) fields for each article only, not more.

Now with dynamic fields the limitation in the number of fields per ticket or article is removed, you can create as many dynamic fields you like either for ticket or articles. And beyond that, the framework behind the dynamic fields is prepared to handle custom fields for other objects rather than just ticket and articles.

This new framework that handles the dynamic fields is build using a modular approach, where each kind of dynamic field can be seen as a plug-in module for the framework. This means that the variety of dynamic fields can be easily extended by public OTRS modules, OTRS Feature Add-ons, OTRS custom developments, and other custom developments.

The following dynamic field types are included with this release:

  • Text (one line of text)

  • Textarea (multiple lines of text)

  • Checkbox

  • Dropdown (single choice, multiple values)

  • Multiselect (multiple choice, multiple values)

  • Date

  • Date / Time

Configuration

By default, a clean installation of OTRS does not include any dynamic fields. If you plan to use such fields in tickets or articles you need to create dynamic fields.

The configuration of a dynamic field is split in two parts, to add a new dynamic field or manage an existing one you need to navigate into the "Admin" panel in the "Dynamic Fields" link. To show, show as mandatory or hide a dynamic field in one screen you need to change the OTRS settings in the "SysConfig" screen.

Adding a Dynamic Field

Click on the "Admin" button located in the navigation bar, then click on the "Dynamic Fields" link inside "Ticket Settings" box located in the lower center of the screen. The dynamic fields overview will display as follows:

Figure 4.81. Dynamic fields overview screen, empty

Dynamic fields overview screen, empty


Notice that this screen will change as you add more dynamic fields to list all created dynamic fields. This screen might already have some fields if the installation was updated from an older version of OTRS.

The Actions in the side bar at the left of the screen describes two possibilities: Article and Ticket, each one has it's own dropdown selection of dynamic fields.

Note

The installation of an OTRS package could add more objects to the Action side bar.

The general procedure to create a dynamic field is:

  • Click on the desired dynamic field object dropdown in the Actions side bar.

  • Click on the dynamic field type that you want to add from the list.

  • Fill the configuration.

  • Save.

The configuration dialogs for the dynamic fields are split in two parts, the upper section is common among all the fields and the lower part might be different from one type of dynamic field to another.

General dynamic field settings:

  • Name: Mandatory, unique, only letters and numbers are allowed.

    This is the internal name of the field, used for example to show or hide a field in one screen. Any modification of a field name (not recommended) requires a manual update of the "SysConfig" settings where the field is referenciated.

  • Label: Mandatory.

    This is the field name to be displayed on the screens, it supports translations.

    Note

    Label translations have to be added manually to language translations files.

  • Field order: Mandatory.

    Defines the relative order in which the field will be displayed on the screen, by default each new field has the last position, a change in this setting will affect the order of the other created dynamic fields.

  • Validity: Mandatory.

    An invalid dynamic field will not be displayed in any screen, no matter if is configured to displayed.

  • Field type: Mandatory, Read only.

    Shows the current selected field type.

  • Object type: Mandatory, Read only.

    Shows the scope of field.

Note

To illustrate each specific field type settings a few fields will be added in our example. These new fields will be referenciated in later sections.

For the following examples all the dynamic fields will be created for the Ticket object. If you need to create a dynamic field for Article object, just choose the field from the Article dropdown list.

Table 4.6. The following fields will be added into the system:

Name Label Type
Field1 My Field 1 Text
Field2 My Field 2 Textarea
Field3 My Field 3 Checkbox
Field4 My Field 4 Dropdown
Field5 My Field 5 Multiselect
Field6 My Field 6 Date
Field7 My Field 7 Date / Time

Text Dynamic Field Configuration

Text dynamic field is used to store a single line string.

Text dynamic field settings:

  • Default value: Optional.

    This is the value to be shown by default on the edit screens (like New Phone Ticket or Ticket Compose).

  • Show link: Optional.

    If set, the field value will be converted into a clickable link for display screens (like ticket zoom or overviews).

    For example, if "Show link" is set to "http://www.otrs.com", clicking on the filled value will make your browser to open the OTRS web page.

    Note

    The use of [% Data.NameX | uri %] in the Set link value, where NameX is the name of the field, will add the field value as part of the link reference.

Figure 4.82. Dynamic field Text configuration dialog

Dynamic field Text configuration dialog


Textarea Dynamic Field Configuration

Textarea dynamic field is used to store a multiple line string.

Textarea dynamic field settings:

  • Number of rows: Optional, integer.

    Used to define the height of the field in the edit screens (like New Phone Ticket or Ticket Compose).

  • Number of cols: Optional, Integer.

    This value is used to define the width of the field in the edit screens.

  • Default value: Optional.

    This is the value to be shown by default in the edit screens (it can be a multiple line text).

Figure 4.83. Dynamic field Textarea configuration dialog

Dynamic field Textarea configuration dialog


Checkbox Dynamic Field Configuration

Checkbox dynamic field is used to store true or false value, represented by a checked or unchecked check box.

Checkbox dynamic field settings:

  • Default value: Mandatory.

    This is the value to be shown by default on the edit screens (like New Phone Ticket or Ticket Compose), the default value for this field is closed selection which can be Checked or Unchecked.

Figure 4.84. Dynamic field Checkbox configuration dialog

Dynamic field Checkbox configuration dialog


Dropdown Dynamic Field Configuration

Dropdown dynamic field is used to store a single value, from a closed list.

Dropdown dynamic field settings:

  • Possible values: Mandatory.

    List of values to choose. If used, a new value is necessary to specify the Key (internal value) and the Value (display value).

  • Default value: Optional.

    This is the value to be shown by default on the edit screens (like New Phone Ticket or Ticket Compose), the default value for this field is closed selection as defined by the Possible values.

  • Add empty value: Mandatory, (Yes / No).

    If this option is activated an extra value is defined to show as a "-" in the list of possible values. This special value is empty internally.

  • Translatable values: Mandatory, (Yes / No).

    This setting is used mark the possible values of this field to be translated. Only the display values are translated, internal values are not affected, the translation of the values needs to be manually added to the language files.

  • Show link: Optional.

    If set, the field value will be converted into a clickable link for display screens (like ticket zoom or overviews).

    For example, if "Show link" is set to "http://www.otrs.com", clicking on the filled value will make your browser to open the OTRS web page.

    Note

    The use of [% Data.NameX | uri %] in the Set link value, where NameX is the name of the field, will add the field value as part of the link reference.

Figure 4.85. Dynamic field Dropdown configuration dialog

Dynamic field Dropdown configuration dialog


Multiselect Dynamic Field Configuration

Multiselect dynamic field is used to store multiple values, from a closed list.

Multiselect dynamic field settings:

  • Possible values: Mandatory.

    List of values to choose from. When adding additional list items, it is necessary to specify the Key (internal value) and the Value (display value).

  • Default value: Optional.

    This is the value to be shown by default on the edit screens (like New Phone Ticket or Ticket Compose), the default value for this field is closed selection as defined by the Possible values.

  • Add empty value: Mandatory, (Yes / No).

    If this option is activated an extra value is defined to show as a "-" in the list of possible values. This special value is empty internally.

  • Translatable values: Mandatory, (Yes / No).

    This setting is used mark the possible values of this field to be translated. Only the display values are translated, internal values are not affected, the translation of the values needs to be manually added to the language files.

Figure 4.86. Dynamic field Multiselect configuration dialog

Dynamic field Multiselect configuration dialog


Date Dynamic Field Configuration

Date dynamic field is used to store a date value (Day, Month and Year).

Date dynamic field settings:

  • Default date difference: Optional, Integer.

    Number of seconds (positive or negative) between the current date and the selected date to be shown by default in the edit screens (like New Phone Ticket or Ticket Compose).

  • Define years period: Mandatory, (Yes / No).

    Used to set a defined number of years in the past and the future based on the current date of the year select for this field. If set to Yes the following options are available:

    • Years in the past: Optional, Positive integer.

      Define the number of years in the past from the current day to display in the year selection for this dynamic field in edit screens.

    • Years in the future: Optional, Positive integer.

      Define the number of years in the future from the current day to display in the year selection for this dynamic field in edit screens.

  • Show link: Optional.

    If set, the field value will be converted into a clickable link for display screens (like ticket zoom or overviews).

    For example, if "Show link" is set to "http://www.otrs.com", clicking on the filed value will make your browser to open the OTRS web page.

    Note

    The use of [% Data.NameX | uri %] in the Set link value, where NameX is the name of the field will add the field value as part of the link reference.

Figure 4.87. Dynamic field Date configuration dialog

Dynamic field Date configuration dialog


Date / Time Dynamic Field Configuration

Date / Time dynamic field is used to store a date time value (Minute, Hour, Day, Month and Year).

Date / Time dynamic field settings:

  • Default date difference: Optional, Integer.

    Number of seconds (positive or negative) between the current date and the selected date to be shown by default in the edit screens (like New Phone Ticket or Ticket Compose).

  • Define years period: Mandatory, (Yes / No).

    Used to set a defined number of years in the past and the future based on the current date of the year select for this field. If set to Yes the following options are available:

    • Years in the past: Optional, Positive integer.

      Define the number of years in the past from the current day to display in the year selection for this dynamic field in edit screens.

    • Years in the future: Optional, Positive integer.

      Define the number of years in the future from the current day to display in the year selection for this dynamic field in edit screens.

  • Show link: Optional.

    If set, the field value will be converted into a clickable link for display screens (like ticket zoom or overviews).

    For example, if "Show link" is set to "http://www.otrs.com", clicking on the filed value will make your browser to open the OTRS web page.

    Note

    The use of [% Data.NameX | uri %] in the Set link value, where NameX is the name of the field will add the field value as part of the link reference.

Figure 4.88. Dynamic field Date / Time configuration dialog

Dynamic field Date / Time configuration dialog


Editing a Dynamic Field

A filled dynamic field overview screen (with the previous examples) should look like:

Figure 4.89. Dynamic field overview screen filled with sample data

Dynamic field overview screen filled with sample data


To change or edit a dynamic field you must have at least one field defined, select an already added field from the dynamic fields overview screen and update its settings.

Note

Not all the dynamic field settings can be changed, the Field type and Object type are fixed from the selection of the field and they can't be changed.

It is not recommended to change the field internal name, but the label can be changed at any time. If internal name is changed all "SysConfig" settings that have a reference to that particular field needs to be updated as well as user preferences (if defined).

Showing a Dynamic Field on a Screen

To display a dynamic field on a particular screen there are two mandatory conditions:

  1. The dynamic field must be valid.

  2. The dynamic field must be set to 1 or 2 in the configuration of the screen.

Follow these steps to show a dynamic field in a screen

  • Be sure that the dynamic field is set to valid, you can see the validity of the field from the dynamic field overview screen. Set to valid by editing the field if necessary.

  • Open the "sysconfig" and select "Ticket" from the dropdown list in the Actions side bar located in the left part of the screen.

    Note

    You can also search for "DynamicField" in the search box above or the "sysconfig" key directly if you already know it.

  • Locate the setting sub-group for the screen that you are looking for and click on it. For example "Frontend::Agent::Ticket::ViewPhoneNew".

  • Search for the setting that ends with "###DynamicField". For example "Ticket::Frontend::AgentTicketPhone###DynamicField".

  • If the setting is empty or does not have the required dynamic field name, click on the "+" button to add a new entry. For example Key: Field1, Content: 1.

    If the setting already has the dynamic field name listed be sure that is set to "1" to display the field or to "2" to display it as mandatory.

  • Save the configuration by clicking on the "Update" button at the bottom of the screen and navigate to the screen where you want the field to be displayed.

Show Examples

The following are "sysconfig" configurations examples to show or hide dynamic fields on different screens.

Example 4.22. Activate Field1 in New Phone Ticket Screen.

  • Group: Ticket

  • Sub-group: Frontend::Agent::Ticket::ViewPhoneNew

  • Setting: Ticket::Frontend::AgentTicketPhone###DynamicField

  • Value:

    Key Content
    Field1 1

Figure 4.90. Field1 in New Phone Ticket Screen

Field1 in New Phone Ticket Screen



Example 4.23. Activate Field1 in New Phone Ticket Screen as mandatory.

  • Group: Ticket

  • Sub-group: Frontend::Agent::Ticket::ViewPhoneNew

  • Setting: Ticket::Frontend::AgentTicketPhone###DynamicField

  • Value:

    Key Content
    Field1 2

Figure 4.91. Field1 in New Phone Ticket Screen as mandatory

Field1 in New Phone Ticket Screen as mandatory



Example 4.24. Activate several fields in New Phone Ticket Screen.

  • Group: Ticket

  • Sub-group: Frontend::Agent::Ticket::ViewPhoneNew

  • Setting: Ticket::Frontend::AgentTicketPhone###DynamicField

  • Value:

    Key Content
    Field1 1
    Field2 1
    Field3 1
    Field4 1
    Field5 1
    Field6 1
    Field7 1

Figure 4.92. Several fields in New Phone Ticket Screen as mandatory

Several fields in New Phone Ticket Screen as mandatory



Example 4.25. Deactivate some fields in New Phone Ticket Screen.

  • Group: Ticket

  • Sub-group: Frontend::Agent::Ticket::ViewPhoneNew

  • Setting: Ticket::Frontend::AgentTicketPhone###DynamicField

  • Value:

    Key Content
    Field1 1
    Field2 0
    Field3 1
    Field4 0
    Field5 1
    Field6 0
    Field7 1

Figure 4.93. Some deactivated fields in New Phone Ticket Screen as mandatory

Some deactivated fields in New Phone Ticket Screen as mandatory



Example 4.26. Activate Field1 in Ticket Zoom Screen.

  • Group: Ticket

  • Sub-group: Frontend::Agent::Ticket::ViewZoom

  • Setting: Ticket::Frontend::AgentTicketZoom###DynamicField

  • Value:

    Key Content
    Field1 1

Figure 4.94. Field1 in Ticket Zoom Screen

Field1 in Ticket Zoom Screen



Example 4.27. Activate Field1 in Ticket Overview Small Screens.

  • Group: Ticket

  • Sub-group: Frontend::Agent::TicketOverview

  • Setting: Ticket::Frontend::OverviewSmall###DynamicField

  • Value:

    Key Content
    Field1 1

Figure 4.95. Field1 in Ticket Overview Small Screen

Field1 in Ticket Overview Small Screen


This setting affects: Escalation View, Locked View, Queue View, Responsible View, Status View, Service View and Watch View screens.


Setting a Default Value by a Ticket Event Module

A ticket event (e.g. TicketCreate) can trigger a value set for a certain field, if the field does not have a value yet.

Note

By using this method this default value, is not seen in the edit screen (e.g. New Phone Ticket) since the value is set after the creation of the ticket.

To activate this feature it is necessary to enable the following setting: "Ticket::EventModulePost###TicketDynamicFieldDefault".

Example 4.28. Activate Field1 in TicketCreate event.

  • Group: Ticket

  • Sub-group: Core::TicketDynamicFieldDefault

  • Setting: Ticket::TicketDynamicFieldDefault###Element1

    Note

    This configuration can be set in any of the 16 Ticket::TicketDynamicFieldDefault###Element settings.

    If more that 16 fields needs to be set up a custom XML file must be places in $OTRS_HOME/Kernel/Config/files directory to extend this feature.

  • Value:

    Key Content
    Event TicketCreate
    Name Field1
    Value a new value


Set a Default Value by User Preferences

The dynamic field default value can be overwritten with a user defined value stored in the user preferences.

Using this method, the default value of the field will be shown on any screen where the field is activated (if the field does not have already a different value).

The "sysconfig" setting "PreferencesGroups###DynamicField" located in the "Frontend::Agent::Preferences" Sub-group. This setting is an example of how to create an entry in the User Preferences screen to set an exclusive dynamic field default value for the selected user. The limitation of this setting is that it only permits the use of one dynamic field. If two or more fields will use this feature, it is necessary to create a custom XML configuration file to add more settings similar to this one.

Note

Remember, if more settings are added in a new XML each setting name needs to be unique in the system and different than "PreferencesGroups###DynamicField". For example: PreferencesGroups###101-DynamicField-Field1, PreferencesGroups###102-DynamicField-Field2, PreferencesGroups###My-Field1, PreferencesGroups###My-Field2, etc.

Example 4.29. Activate Field1 in the User preferences.

  • Group: Ticket

  • Sub-group: Frontend::Agent::Preferences

  • Setting: PreferencesGroups###101-DynamicField-Field1

  • Value:

    Key Content
    Event TicketCreate
    Active 1
    Block Input
    Column Other Settings
    Data: [% Env("UserDynamicField_Field1") %]
    Key: My Field 1
    Label: Default value for: My Field 1
    Module: Kernel::Output::HTML::PreferencesGeneric
    PrefKey: UserDynamicField_Field1
    Prio: 7000

Figure 4.96. Field1 in User preferences screen

Field1 in User preferences screen