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
Updating from OTRS 3.0

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

An updated installation from OTRS 3.0.x will have all the old "free fields" created as dynamic fields for compatibility and data preservation. The following is the list of dynamic fields that are created during the migration from OTRS 3.0.x to 3.1.x.

Anmerkung

During the migration procedure from OTRS 3.0.x to OTRS 3.1.x all the old "free fields" data and configuration are migrated to the new dynamic fields architecture. Any custom development around the old "free fields" has to be updated to use the new dynamic field framework.

The migration of the configuration include the field itself and the screen configurations to hide, show or show field as mandatory for each screen.

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 in the "Admin" button located in the navigation bar, then click on the "Dynamic Field" link inside "Ticket Settings" box located in the lower center of the screen. The dynamic fields overview will display as follows:

Figure: 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.

Anmerkung

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 Action 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 on field name (not recommended) will need manual a update on the "SysConfig" settings where the field is referenciated.

  • Label: Mandatory.

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

    Anmerkung

    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 in the screen, by default each new field has the last position, a change in this setting will affect the other 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.

Anmerkung

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 chose the field from the Article dropdown list.

Tabelle 22.1. 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 5 Date
Field7 My Field 6 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 in 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.

    Anmerkung

    The use of $LQData{"NameX"} 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: 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 is 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: 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 in the edit screens (like New Phone Ticket or Ticket Compose), the default value for this field is closed selection that can be Checked or Unchecked.

Figure: 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. when add 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 show by default in the edit screens (like New Phone Ticket or Ticket Compose), the default value for this field is closed selection defined by the Possible values.

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

    If this option is activated an extra value is defined to show 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 HTP link for display screens (like 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.

    Anmerkung

    The use of $LQData{"NameX"} 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: Dynamic field Dropdown configuration dialog.

Multiselect Dynamic Field Configuration

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

Multiselect dynamic field settings:

  • Possible values: Mandatory.

    List of values to choose. when add 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 show by default in the edit screens (like New Phone Ticket or Ticket Compose), the default value for this field is closed selection defined by the Possible values.

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

    If this option is activated an extra value is defined to show 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: 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 show 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 past and future from current date in the year select of this field, If set to Yes the following options are available:

    • Years in the past: Optional, Positive integer.

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

    • Years in the future: Optional, Positive integer.

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

  • Show link: Optional.

    If set, the field value will be converted into a clickable HTP link for display screens (like 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.

    Anmerkung

    The use of $LQData{"NameX"} 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: 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 show 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 past and future from current date in the year select of this field, If set to Yes the following options are available:

    • Years in the past: Optional, Positive integer.

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

    • Years in the future: Optional, Positive integer.

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

  • Show link: Optional.

    If set, the field value will be converted into a clickable HTP link for display screens (like 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.

    Anmerkung

    The use of $LQData{"NameX"} 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: Dynamic field Date / Time configuration dialog.

Editing a Dynamic Field

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

Figure: 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 it's settings.

Anmerkung

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 has 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 this 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.

    Anmerkung

    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 in the "Update" button and 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.

Beispiel 22.1. 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: Field1 in New Phone Ticket Screen.


Beispiel 22.2. 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: Field1 in New Phone Ticket Screen as mandatory.


Beispiel 22.3. 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: Several fields in New Phone Ticket Screen as mandatory.


Beispiel 22.4. 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: Some deactivated fields in New Phone Ticket Screen as mandatory.


Beispiel 22.5. 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: Field1 in Ticket Zoom Screen.


Beispiel 22.6. 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: Field1 in Ticket Overview Small Screen.

This setting affects: Escalation View, Locked View, Queue View, Responsible View, Status 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.

Anmerkung

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 is necessary to enable the following setting: "Ticket::EventModulePost###TicketDynamicFieldDefault".

Beispiel 22.7. Activate Field1 in TicketCreate event.

  • Group: Ticket

  • Sub-group: Core::TicketDynamicFieldDefault

  • Setting: Ticket::TicketDynamicFieldDefault###Element1

    Anmerkung

    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 admits one dynamic field. if two or more fields will use this feature is necessary to create a custom XML configuration file to add more settings similar to this one.

Anmerkung

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.

Beispiel 22.8. 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 Andere Einstellungen
    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: Field1 in User preferences screen.


Updating from OTRS 3.0

During the update from OTRS 3.0 there is an special step that is very important and must not be skipped, there is an script file named "DBUpdate-to-3.1.pl" under the "$OTRS_HOME/scripts" that must be called at the precise time in the update procedure (please refer to UPGRADING file for more details).

The script mentioned above is in charge to get all the "Free fields" configurations and creates their dynamic field substitute, it also gathers each "Free field" data from every ticket and article and move it to the dynamic fields format. It also read the screen configuration for "Free fields" and port it to the dynamic fields format.

Anmerkung

All the "Free fields" configurations are keep in the system but they are not used anymore, they are placed under the group "Z_Deprecated", and the might be removed in further versions of OTRS.

While the updating script tries to be very precise migrating the screen configurations it is always good to do a manual fine tuning. Please note that "Free fields" TicketFreeKey[1-16] and TicketFreeText[1-16] came always in pair in OTRS 3.0 systems (and before). This is not longer necessary it could be that the TicketFreeKey field is not necessary anymore for a particular TicketFreeText field.

The dynamic fields overview screen from clean OTRS 3.0.x updated to 3.1.x should look like:

Figure: Updated dynamic field overview screen page2.

Figure: Updated dynamic field overview screen page2.

Please note that the new dynamic field named "TicketFreeText2" has the label "Product", this is because the default configuration from this "Free field" in OTRS 3.0.x specifies that "TicketFreeKey2" has a fixed value of "Product". in this case the dynamic field "TicketFreeKey2" is not needed anymore and it can be manually set to invalid.

It might me also a very good idea to set the label value of each valid migrated field to a text that describes better the use of the field in the system.