Dynamic Fields

Beside general information that required for all tickets, organizations have individual needs to add specific details to tickets. This needed information takes various formats like texts, integers, date-time and more.

OTRS supports adding a so-called dynamic field to handle texts, integers, drop-down lists, multi-select fields, date-time, checkboxes and more. OTRS administrators can define where those fields should be visible or editable, and of course, the dynamic fields are also available in statistics and reports.

Use this screen to manage dynamic fields in the system. A fresh OTRS installation contains three dynamic fields by default. The dynamic field management screen is available in the Dynamic Fields module of the Processes & Automation group.

Dynamic Field Management Screen

Dynamic Field Management Screen

Manage Dynamic Fields

To create a new dynamic field:

  1. Choose an object in the left sidebar and select a dynamic field type from its drop-down.
  2. Fill in the required fields.
  3. Click on the Save button.
Create New Dynamic Field Screen

Create New Dynamic Field Screen

To edit a dynamic field:

  1. Click on a dynamic field in the list of dynamic fields.
  2. Modify the fields.
  3. Click on the Save or Save and finish button.
Edit Dynamic Field Screen

Edit Dynamic Field Screen

To delete a dynamic field:

  1. Click on the trash icon in the last column of the overview table.
  2. Click on the Confirm button.
Delete Dynamic Field Screen

Delete Dynamic Field Screen

Note

If several dynamic fields are added to the system, use the filter box to find a particular dynamic field by just typing the name to filter.

Dynamic Field Settings

The following settings are available when adding or editing this resource. The fields marked with an asterisk are mandatory.

General Dynamic Field Settings

These settings are the same for all types of dynamic fields.

Dynamic Field General Screen

Dynamic Field General Screen

Name *
The name of this resource. Any type of characters can be entered to this field including uppercase letters and spaces. The name will be displayed in the overview table.
Label *

This is the name to be shown on the screens where the field is active.

See also

It is possible to add translations for a dynamic field label. Label translations have to be added manually to language translation files.

Field order *

This is the order in which the field is displayed on the screens where it is active.

Note

The configured value for the field order is considered in the following screens:

  • all screens in the administrator interface
  • all screens in the external interface

In other screens the order can be configured in other ways, e.g. via a specific order of fields in the form configuration.

Validity *
Set the validity of this resource. Each resource can be used in OTRS only, if this field is set to valid. Setting this field to invalid or invalid-temporarily will disable the use of the resource.
Field type
This type have been selected in the previous page and can not be changed here anymore. This is a read-only field.
Object type

This type have been selected in the previous page and can not be changed here anymore. This is a read-only field.

Note

The object type determines where the dynamic field can be used. For example dynamic field with object type Ticket can be used only in tickets, and can not be used in articles.

The following settings are relevant only for the particular type of dynamic fields.

Checkbox Dynamic Field Settings

Checkbox dynamic field is used to store true or false value.

Checkbox Dynamic Field Settings

Checkbox Dynamic Field Settings

Default value *

The default value for the checkbox.

Checked
The checkbox is checked by default.
Unchecked
The checkbox is unchecked by default.

Contact With Data Dynamic Field Settings

This dynamic field allows to add contacts with data to tickets.

Contact With Data Dynamic Field Settings

Contact With Data Dynamic Field Settings

Name Field *
The attribute Name is always mandatory and it is not automatically added, so for each new data source this attribute must be added manually. Within the data source definition (or dynamic field configuration) this must be represented by the key Name and the value could be Name for example.
ValidID Field *
The attribute ValidID is always mandatory and it is not automatically added, so for each new data source this attribute must be added manually. Within the data source definition (or dynamic field configuration) this must be represented by the key ValidID and the value could be Validity for example.
Other Fields

These are the possible data attributes for contacts. Clicking on the button of the Add Fields will add two new fields, where a Key (internal value) and a Value (displayed value) can be set. With the button you can add multiple key-value pairs.

Warning

The keys Name and ValidID are already used by Name Field and ValidID Field. Do not use these keys again!

Add Fields
Use this button to add more fields to dynamic field.
Mandatory fields

Comma separated list of mandatory keys.

Note

Keys Name and ValidID are always mandatory and doesn’t have to be listed here.

Sorted fields
Comma separated list of keys in sort order. Keys listed here come first, all remaining fields afterwards and sorted alphabetically.
Searchable fields

Comma separated list of searchable keys.

Note

Key Name is always searchable and doesn’t have to be listed here.

When the dynamic field was saved, click on the name of the newly created dynamic field in the overview table. The Edit Dynamic Field screen will open. There is a button Add or edit contacts, that points to TicketsEdit contacts with data to add some data.

Contact With Data Management Screen

Contact With Data Management Screen

To add a new contact with data:

  1. Select a dynamic field from the drop-down list in Actions widget of the left sidebar.
  2. Click on the Add contact with data button in the left sidebar.
  3. Fill in the required fields.
  4. Click on the Save button.
Add Contact With Data Screen

Add Contact With Data Screen

To edit a contact with data:

  1. Click on a contact with data in the list of contact with data entries.
  2. Modify the fields.
  3. Click on the Save or Save and finish button.
Edit Contact With Data Screen

Edit Contact With Data Screen

The usage of this type of dynamic field is more complex then the others. An exemplary usage of contacts with data is as follows:

  1. Create a new dynamic field of type contact with data.

  2. Set the possible contact attributes (possible values).

    • Type Name into Name Field.
    • Type Validity into ValidID Field.
    • Add any other attribute with Add Fields button such as Telephone attribute (key: Telephone, value: Phone).
  3. Add the list of mandatory attribute keys comma separated (Name and ValidID are not needed).

  4. Set the attribute key order list comma separated as: Name,Telephone,ValidID.

  5. Add the list of searchable attribute keys comma separated (Name is not needed).

  6. Populate the data source by adding at least one contact in the newly created data source by using Manage Contacts with Data screen from the main menu of the agent interface.

  7. Add the new dynamic field to the screen’s configuration where it should be shown. For example in New Phone Ticket screen by updating the system configuration setting Forms###AgentFrontend::TicketCreate::Phone::CreateProperties and do the same for AgentFrontend::TicketDetailView::WidgetType###Properties.

    See also

    See Display Dynamic Fields on Screens for more information.

  8. Go to New Phone Ticket screen, and notice that the new field is there. Add all needed information to the ticket.

  9. Select an existing contact using autocomplete and choosing a contact.

  10. Click on the Create button to create the ticket and go to the ticket detail view.

  11. Open the widget configuration of the Properties widget in the ticket detail view, and enable the dynamic field in the Hide/Show Properties list.

  12. The assigned contact and its attributes will be shown in the ticket detail view.

  13. It is possible to update the attributes of the contact by clicking the Edit contact button that appears in the right side of dynamic field property card (if the current user is a member of the groups defined in system configuration setting Frontend::Module###AdminDynamicFieldContactWithData).

  14. If is necessary to change the contact for this ticket, it can be done via any other ticket action where the dynamic field is configured for display.

Date Dynamic Field Settings

Date dynamic field is used to store a date value.

Date Dynamic Field Settings

Date Dynamic Field Settings

Default date difference
The difference from now (in seconds) to calculate the field default value (e.g. 3600 or -60).
Define years period

Activate this feature to define a fixed range of years (in the future and in the past) to be displayed on the year part of the field. If set to Yes the following options will be available:

Years in the past
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
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.

Note

If no years period is specified, the system uses the default value for the period: 10 years (5 years in the past and 5 years in the future).

Show link

Here you can specify an optional HTTP link for the field value displayed in overviews and detail views. Example:

http://some.example.com/handle?query=[% Data.Field1 | uri %]
Link for preview
If filled in, this URL will be used for a preview which is shown when this link is hovered in ticket detail view. Please note that for this to work, the regular URL field above needs to be filled in, too.
Restrict entering of dates

Here you can restrict the entering of dates of tickets.

Prevent entry of dates in the future
Selecting this option will prevent entering a date that is after the current date.
Prevent entry of dates in the past
Selecting this option will prevent entering a date that is before the current date.

Date / Time Dynamic Field Settings

Date / time dynamic field is used to store a date time value.

Date / Time Dynamic Field Settings

Date / Time Dynamic Field Settings

The settings for this type of dynamic field is the same as for date dynamic field.

Multiselect Dynamic Field Settings

Multiselect Dynamic Field Settings

Multiselect Dynamic Field Settings

Possible values
These are the possible data attributes for contacts. Clicking on the button will add two new fields, where a key (internal value) and a value (displayed value) can be set. With the button you can add multiple key-value pairs.
Default value
This is the default value for this field and this will be shown on the edit screens.
Add empty value
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.
Tree View
Activate this option to display values as a tree.
Translatable values

If you activate this option the values will be translated to the user defined language.

Note

You need to add the translations manually into the language translation files.

Text Dynamic Field Settings

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

Text Dynamic Field Settings

Text Dynamic Field Settings

Default value
This is the default value for this field and this will be shown on the edit screens.
Show link

Here you can specify an optional HTTP link for the field value displayed in overviews and detail views. Example:

http://some.example.com/handle?query=[% Data.Field1 | uri %]
Link for preview
If filled in, this URL will be used for a preview which is shown when this link is hovered in ticket detail view. Please note that for this to work, the regular URL field above needs to be filled in, too.
Check RegEx

Here you can specify a regular expression to check the value. The regex will be executed with the modifiers xms. Example:

^[0-9]$
Add RegEx
Clicking on the button will add two new fields, where a regular expression and an error message can be added.

Textarea Dynamic Field Settings

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

Textarea Dynamic Field Settings

Textarea Dynamic Field Settings

Number of rows
The height (in lines) for this field in the edit mode.
Number of cols
The width (in characters) for this field in the edit mode.
Default value
This is the default value for this field and this will be shown on the edit screens.
Check RegEx

Here you can specify a regular expression to check the value. The regex will be executed with the modifiers xms. Example:

^[0-9]$
Add RegEx
Clicking on the button will add two new fields, where a regular expression and an error message can be added.

Database Dynamic Field

Note

To use this type of dynamic field, an OTRS service package is needed. Please contact at sales@otrs.com for an upgrade.

Web Service Dynamic Field

Note

To use this type of dynamic field, an OTRS service package is needed. Please contact at sales@otrs.com for an upgrade.

Display Dynamic Fields on Screens

The following sections describe how to add a dynamic field to certain screens. The following examples use a dynamic field named Test1. Please make sure that you replace it with the actual name of your dynamic field.

Note

Make sure that the Validity of the dynamic field is set to valid.

Dynamic Field in Business Object Detail View

Dynamic fields can be added to any widget of the business object detail view. The following examples show the possibilities.

To add a ticket dynamic field to the Properties widget:

  1. Go to the System Configuration screen.

  2. Search for the setting AgentFrontend::TicketDetailView::WidgetType###Properties.

  3. Add the ticket dynamic field to the Properties section of the YAML configuration.

    Properties:
    - Name: DynamicField_Test1
      IsVisible: 1
    
    Add Dynamic Field to Properties Widget Configuration

    Add Dynamic Field to Properties Widget Configuration

    See also

    Detailed information about the configuration of the property card and possible keys can be found under the reference.

  4. Deploy the modified system configuration.

  5. Go to the ticket detail view screen in the agent interface.

  6. Find the Properties widget and open its configuration via the gear icon. Identify the Test1 dynamic field property in the Hide/Show Properties list. Activate it by clicking on the checkbox. Click on the Save button to apply the change and close the widget configuration.

    Enable Dynamic Field Property Card in Properties Widget

    Enable Dynamic Field Property Card in Properties Widget

If defined, the ticket dynamic field value will then be displayed as a separate property card.

Display Dynamic Field Property Card in Properties Widget

Display Dynamic Field Property Card in Properties Widget

To add an article dynamic field to the Communication Stream widget:

  1. Go to the System Configuration screen.

  2. Search for the setting AgentFrontend::TicketDetailView::WidgetType###CommunicationStream.

  3. Add the article dynamic field name to the ArticleDynamicFields array of the YAML configuration.

    ArticleDynamicFields:
    - Test1
    
    Add Dynamic Field to Communication Stream Widget Configuration

    Add Dynamic Field to Communication Stream Widget Configuration

  4. Deploy the modified system configuration.

If defined, the article dynamic field value will then be displayed as a separate line in the article header in the Communication Stream widget. If not visible, make sure the header is expanded by clicking on it.

Display Dynamic Field Value in Communication Stream Widget

Display Dynamic Field Value in Communication Stream Widget

To add a ticket dynamic field to the Business Process Information widget:

  1. Go to the System Configuration screen.

  2. Search for the setting AgentFrontend::TicketDetailView::Widget::BusinessProcessInformation###DynamicField.

  3. Add the dynamic field to the list and enabled it.

    Add Dynamic Field to Business Process Information Widget Configuration

    Add Dynamic Field to Business Process Information Widget Configuration

  4. Deploy the modified system configuration.

If defined, the ticket dynamic field value will then be displayed as a separate property card in the Business Process Information widget of a process ticket.

Display Dynamic Field Property Card in Business Process Information Widget

Display Dynamic Field Property Card in Business Process Information Widget

See also

If you want to group the dynamic fields into groups, please check the setting AgentFrontend::TicketDetailView::Widget::BusinessProcessInformation###DynamicFieldGroup.

Dynamic Field in Ticket and Article Action

The following example shows how to add a dynamic field to the Close Ticket action. The steps are identical for other actions, only the system configuration keys are different for each form.

See also

For the names and explanations of other forms, please consult the Form Fields chapter.

To add a ticket or an article dynamic field to the Close Ticket form:

  1. Go to the System Configuration screen.

  2. Search for the setting Forms###AgentFrontend::Ticket::Action::Close.

  3. Add the dynamic field to the Fields section of the YAML configuration.

    Fields:
    - Name: DynamicField_Test1
    
    Add Dynamic Field to Close Ticket Form Configuration

    Add Dynamic Field to Close Ticket Form Configuration

  4. Deploy the modified system configuration.

The ticket dynamic field will be displayed in the relevant ticket or article action as a form field.

Display Dynamic Field in Close Ticket Action

Display Dynamic Field in Close Ticket Action

Note

Article dynamic fields are only displayed if article related fields such as Subject and Body are present. If these fields do not exist, no article is created and no value is set for the dynamic field when the action is executed.

Dynamic Field in Business Object List

The following examples show how to add a dynamic field as a column or as a filter to the organizer item type Ticket List. This affects all organizer items of the type Ticket List. If only a specific organizer item needs to be affected, then please modify the system configuration key of the relevant organizer item.

See also

For the names and explanations for other organizer items please read the chapter Business Object Lists.

To add a ticket dynamic field as a list column:

  1. Go to the System Configuration screen.

  2. Search for the setting Agent::Organizer::ItemType###TicketList.

  3. Add the ticket dynamic field to the Columns section of the YAML configuration.

    Columns:
      DynamicField_Test1:
        IsVisible: 2
    
    Add Dynamic Field to Ticket List Configuration

    Add Dynamic Field to Ticket List Configuration

    See also

    For detailed information about the column configuration and possible keys, please check the reference.

  4. Deploy the modified system configuration.

If defined, the ticket dynamic field value will then be displayed in a column cell, for any of the organizer items of the ticket list type.

Display Dynamic Field Value in Ticket List

Display Dynamic Field Value in Ticket List

To add a ticket dynamic field as a list filter:

  1. Go to the System Configuration screen.

  2. Search for the setting Agent::Organizer::ItemType###TicketList.

  3. Add the ticket dynamic field name to the AvailableDynamicFieldFilters array of the YAML configuration.

    AvailableDynamicFieldFilters:
    - Test1
    
    Add Dynamic Field Filter to Ticket List Configuration

    Add Dynamic Field Filter to Ticket List Configuration

  4. Deploy the modified system configuration.

The ticket dynamic field can now be used as a filter in the business object list.

Use Dynamic Field as Filter in Ticket List

Use Dynamic Field as Filter in Ticket List

Dynamic Field in Ticket Create Screen

To add a ticket or an article dynamic field to New Email Ticket screen:

  1. Go to the System Configuration screen.

  2. Search for the setting Forms###AgentFrontend::TicketCreate::Email::CreateProperties.

  3. Add the ticket dynamic field to the Fields section of the YAML configuration.

    Fields:
    - Name: DynamicField_Test1
    
    Add Dynamic Field to New Email Ticket Configuration

    Add Dynamic Field to New Email Ticket Configuration

    See also

    For more information about form fields and groups, please consult the Forms chapter.

  4. Deploy the modified system configuration.

The ticket or article dynamic field can now be used as part of the New Email Ticket screen.

Display Dynamic Field in New Email Ticket Screen

Display Dynamic Field in New Email Ticket Screen

Dynamic Field in Ticket Bulk Action

To add a ticket or an article dynamic field to a ticket bulk action:

  1. Go to the System Configuration screen.

  2. Search for the setting AgentFrontend::Ticket::BulkFeature::Attributes###DynamicField.

  3. Add the dynamic field to the list and enabled it.

    Add Dynamic Field to Ticket Bulk Configuration

    Add Dynamic Field to Ticket Bulk Configuration

  4. Deploy the modified system configuration.

The ticket or article dynamic field is now displayed in the Properties section in the action form of the bulk action.

Display Dynamic Field in Ticket Bulk Action

Display Dynamic Field in Ticket Bulk Action

Dynamic Field in the Print Output

To add a ticket or an article dynamic field to the print output:

  1. Go to the System Configuration screen.

  2. Search for the setting AgentFrontend::Ticket::Print###DynamicField.

  3. Add the dynamic field to the list and enabled it.

    Add Dynamic Field to Print Ticket Configuration

    Add Dynamic Field to Print Ticket Configuration

  4. Deploy the modified system configuration.

The ticket or article dynamic field is now displayed in the printed output of the ticket.

Display Dynamic Field in Printed Output

Display Dynamic Field in Printed Output

Dynamic Field in External Interface

To add a dynamic field to the external interface:

  1. Go to System Configuration screen.

  2. Navigate to Frontend → External → View in the navigation tree.

  3. Select the screen where the dynamic field should be displayed.

  4. Search for the dynamic field setting of the screen and click on the Edit this setting button.

    The following settings are relevant to adding dynamic fields:

    - ExternalFrontend::KnowledgeBaseDetailView###DynamicField
    - ExternalFrontend::TicketCreate###DynamicField
    - ExternalFrontend::TicketDetailView###DynamicField
    - ExternalFrontend::TicketDetailView###FollowUpDynamicField
    - ExternalFrontend::TicketOverview###DynamicField
    
  5. Click on the + button to add the dynamic field. The key is the name of the dynamic field, the value is 1 - Enabled. This setting is used to display the content of dynamic field in the selcted screen.

  6. Search for setting ExternalFrontend::TicketDetailView###FollowUpDynamicField and click on the Edit this setting button.

  7. Click on the + button to add the dynamic field. The key is the name of the dynamic field, the value is 1 - Enabled. This setting is used to configure dynamic fields in the answer part of customers detail view.

  8. Repeat the steps for other views, if needed.

  9. Deploy the modified settings.

Add Dynamic Fields to Search Engine

By default, the content of the dynamic fields cannot be searched using the document search functionality. Each dynamic field has to be added manually.

To add a dynamic field to the document search functionality:

  1. Go to System Configuration screen.
  2. Navigate to Frontend → Agent → DocumentSearch and Frontend → External → DocumentSearch in the navigation tree.
  3. Search for the setting DocumentSearch::Agent::DynamicField and DocumentSearch::External::DynamicField respectively.
  4. Click on the Edit this setting button.
  5. Click on the + button to add the dynamic field.
  6. Enter the name of the dynamic field to the text box and click on the tick button.
  7. Select 0 - Disabled or 1 - Enabled.
  8. Click on the tick button on the right to save the setting.
  9. Deploy the modified system configuration.

Set Default Value via 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.

  1. Go to the System Configuration screen.
  2. Navigate to CoreEventTicket and search for the setting Ticket::EventModulePost###9600-TicketDynamicFieldDefault.
  3. Click on the Edit this setting button to activate the setting.
  4. Click on the tick button on the right to save the setting.
  5. Deploy the modified system configuration.
Activate Ticket Event Module

Activate Ticket Event Module

Example: activate Field1 in TicketCreate event:

  1. Go to the System Configuration screen.
  2. Navigate to CoreTicketDynamicFieldDefault and search for the setting Ticket::TicketDynamicFieldDefault###Element1.
  3. Click on the Edit this setting button to activate the setting.
  4. Click on the tick button on the right to save the setting.
  5. Deploy the modified system configuration.
Activate Dynamic Field in Ticket Create Event

Activate Dynamic Field in Ticket Create Event

Note

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

See also

If more than 16 fields needs to be set up, a custom XML file must be placed in $OTRS_HOME/Kernel/Config/Files/XML directory to extend this feature.

Set Default Value via User Preferences

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

  1. Go to the System Configuration screen.
  2. Navigate to FrontendAgentViewPreferences and search for the setting PreferencesGroups###DynamicField.
  3. Click on the Edit this setting button to activate the setting.
  4. Click on the tick button on the right to save the setting.
  5. Deploy the modified system configuration.
Activate Dynamic Field in Personal Preferences

Activate Dynamic Field in Personal Preferences

Click on your avatar on the top left corner, and select Personal PreferencesMiscellaneous to add a default value for the dynamic field.

Dynamic Field in Personal Preferences

Dynamic Field in Personal Preferences

This setting is an example of how to create an entry in the user preferences screen to set an exclusive dynamic field Name_X 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

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