Dynamic Fields

Beside general information 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.

OTOBO supports adding a so-called dynamic field to handle texts, integers, drop-down lists, multi-select fields, date-time, checkboxes and more. OTOBO 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 OTOBO installation contains two 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 type in the left actions 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 dynamic fields list.

  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. The value should be alphabetic and numeric characters only. 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 this field will be shown on the screens where is active.

Validity *

Set the validity of this resource. Each resource can be used in OTOBO 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 has been selected in the left sidebar and can not be changed here anymore. This is a read-only field.

Object type

This type has been selected in the left sidebar 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 a 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.

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.

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 Tickets → Edit 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 Tickets → Edit contacts with data screen from the main navigation bar.

  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 Ticket::Frontend::AgentTicketPhone###DynamicField and do the same for Ticket::Frontend::AgentTicketZoom###DynamicField.

  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. The assigned contact and its attributes will be shown in the Ticket Zoom screen.

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

  12. If it’s 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.

Show link

Here you can specify an optional HTTP link for the field value in overviews and zoom screens. 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 zoom. 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. In case you want to have a tree structure (expandable values), you have to implement the complete tree structure in the key (e.g. Country: Country::Germany and Country::France) and only the lowest item in the value (e.g. Country: Germany and France) of the possible values.

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 in overviews and zoom screens. 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 zoom. 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

Database dynamic fields are used to select and store entries from a table or view of an arbitrary database that can be accessed from within the OTOBO instance. This type is available for object types Ticket, Article, Customers, Customer Users, and FAQs. Agents access this field via the agent interface and customer users via the external interface. In both cases, the field offers autocompletion as well as a detailed search, listing all matches from the referenced database table for the strings entered by the user. The admin configures one or more columns to be considered for the search. The value of the column marked as identifier is stored in the dynamic field.

Possible values

Define the columns of the external table or view that are used by the dynamic field. Clicking on the + button of Add value will add a new card to address a new column with the following settings:

Name *

The exact name of the column in the table or view.

Label *

The label of the column, which is displayed in the search results. You can decide to a add a more descriptive term than just the name of the column.

Datatype *

The data type of the database column. Possible values are Date, Integer and Text.

Filter

Restricts the search results to entries, where this column matches the given ticket attribute (e.g. Queue, State or CustomerID) or the value of another dynamic field (e.g. DynamicField_OtherFieldName). The filter only takes effect, if Searchfield is activated for this column. If the dynamic field is bound to a related ticket, the attributes will be used for the filter mechanism, otherwise the filters will be ignored.

Searchfield

If activated, the search term is matched against this column. Example: Assuming the search field is enabled for both the ID column and the NAME column of the queues table, the search term is matched against the values in both columns and hits are returned.

Listfield

If activated, the column is displayed in the search results. Example: If the list field is enabled only for the Name column of the queues table, the dynamic field shows only the name of the queues among the hits. If the list field is also enabled for the ID column, both values are displayed combined.

Note

You can only address columns from one database table or view per dynamic field database. A combination of columns from multiple tables or views is not possible.

Show link

Here you can specify an optional HTTP link for the field value in overviews and zoom screens. 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 zoom. Please note that for this to work, the regular URL field above needs to be filled in, too.

Type *

Selection of database management system that is used for the database being addressed by the dynamic field. Possible values are MySQL, Oracle, PostgreSQL and SQL Server (ODBC).

SID

The system identifier of the Oracle database. This field is only displayed, if Type is set to Oracle.

Driver

The name of the ODBC driver. This field is only displayed, if Type is set to SQL Server (ODBC).

Server *

The host name or IP address of the database server.

Port

The port of the database server. You can leave it empty if you are using the default ports.

Database *

The name of the database from whose tables or views the dynamic field reads.

Table / View *

The name of the table or view to select the entries from. Only one value can be entered.

User *

The user name to connect to the database.

Password *

The password to connect to the database.

Note

If you setup a dynamic field for your OTOBO database, you may find the database user and password in your Kernel/Config.pm.

Identifier *

The column, whose value is stored in the dynamic field. It must be a unique column of the table or view entered in Table / View.

Note

If the user gets no hits in the dynamic field, please check not only the DatabaseUser’s login credentials, but also the names and settings in the possible values cards.

Multiselect

If activated, multiple entries can be selected and stored in the dynamic field. This option can not be combined with Multiple Values.

CacheTTL

The time (in seconds) the search results are cached. Set to 0 or leave empty to disable the cache.

Searchprefix

A string prepended to the search term (e.g. * to search for entries ending with the search term).

Searchsuffix

A string appended to the search term (e.g. * to search for entries starting with the search term).

Note

The character * is used as wildcard in search terms. For a maximally flexible search, use the wildcard (*) in both fields, so that the system lists all hits. However, this will also make the list of hits longer.

Result Limit

The maximum number of entries returned by a search. If defined, the system truncates the list once the permitted number is reached. In most cases, the system might sort the output alphabetically, but this is not reliable behavior. Leave empty or set to 0 for no limit.

Case Sensitive

If activated, the search is case sensitive. Example: If the agent enters an uppercase ‘R’, the queue ‘Raw’ is displayed; with a lowercase ‘r’, ‘Postmaster’ appears instead.

Multiple Values

Activate this option to allow multiple values for this field. By default, the system allows the dynamic field to be displayed once in the view. If you change the setting to ‘Yes’, the agent can manually add the dynamic field as many times as desired and store multiple values accordingly.

See also

The autocompletion can be configured in the system configuration settings AutoComplete::Agent###DynamicFieldDBSearch and AutoComplete::Customer###DynamicFieldDBSearch.

Additional columns of a selected entry can be stored in other dynamic fields. The mapping between the database dynamic field, the database columns and the target dynamic fields is defined in the DynamicFieldDB::StoreHistoricalData###* settings.

Web Service Dynamic Field

A Web Service dynamic field relies upon a working Web Service, more precisely on a Web Service invoker.

For this purpose, an invoker of type PassThrough can be used.

For the outgoing API call, DynamicFieldID, -Label, -Name and -Value, as well as UserID and Ticket and Form data are passed to the invoker.

For the dynamic field Web Service to work, the response data needs to be mapped into this structure:

PossibleValue => [
    {
        Key => 'abc',
        Value => 'ABC',
    },
    {
        Key => 'bcd',
        Value => 'BCD',
    },
    ...
]

This can be accomplished by implementing an XSLT mapping.

Display Dynamic Fields on Screens

To display a dynamic field on a screen:

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

  2. Open the System Configuration module in the admin interface.

  3. Navigate to Frontend → Agent → View and select a view to add the dynamic field to.

  4. Find the setting ends with ###DynamicField and 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 1 - Enabled or 2 - Enabled and required.

  8. Click on the tick button on the right to save the setting.

  9. Deploy the modified system configuration.

Display Dynamic Fields on Screen

Display Dynamic Fields on Screen

Note

It is possible to add multiple dynamic fields at the same time. To do this, repeat steps 5-7.

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. Open the System Configuration module in the admin interface.

  2. Navigate to Core → Event → Ticket 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. Open the System Configuration module in the admin interface.

  2. Navigate to Core → Ticket → DynamicFieldDefault 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 $OTOBO_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. Open the System Configuration module in the admin interface.

  2. Navigate to Frontend → Agent → View → Preferences 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 Preferences → Miscellaneous 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