OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Introduction

This manual is intended for use by OTRS administrators. The chapters describe the administration of the OTRS software. The administrator interface is available in the Admin menu item of the main menu, when you logged in as an administrator. Administrators are users, who are member of the admin group.

Administrator Interface

The administrator interface contains several modules collected into groups. Use the filter box in the left sidebar to find a particular module by just typing the name to filter.

This manual shows you the configuration possibilities needed to solve common problems. The chapters:

Identify a typical use-case for the administrator, to aid in orientation, and explain what OTRS does to provide a solution (warranty).

Direct you how to configure OTRS to fit your use-case (utility).

The chapters are the same as the modules in the administrator interface. The order of the chapters are also the same as they are displayed alphabetically in the (English) administrator interface. However, the steps to do to configure a fresh new OTRS installation is different from this order. We recommend to configure OTRS to do the steps as explained below.

Getting Started

Note

OTRS is installed by the Customer Solution Team. Please contact the Customer Solution Team via support@otrs.com or in the OTRS Portal.

A fresh new OTRS installation contains only the default settings. You need to customize your system to work properly and meet your needs.

First, you need to check some System Configuration and modify the values, if needed. FQDN, SystemID and SendmailModule::Host are the most important. Defining the TimeWorkingHours setting for working hours and the TimeVacationDays setting for public holidays are also needed to calculate the escalation times correctly in OTRS.

Then, open the PostMaster Mail Accounts module to add email addresses used by the system. For sending email, you can add more Email Addresses.

To improve the security, PGP Keys or S/MIME Certificates can be used for encryption of emails.

Let’s continue with users, but you might need to add some Groups and/or Roles to the system first. It is recommended to create new groups for each main queues. There are some groups in your OTRS, but no roles are defined by default. You can add roles, if needed, and you can set the Roles ↔ Groups relations.

The next step is to add Agents to the system and set the Agents ↔ Groups and/or Agents ↔ Roles relations.

Now you can add Customers and Customer Users. Customers are companies and customer users are the employees of the company.

Note

Both agents and customer users can log in using Active Directory or LDAP for authentication. In these cases doesn’t need to add users manually.

Like for agents, customers users can also assign to groups using the Customer Users ↔ Groups management screen. Similarly, Customer Users ↔ Customers relations can also be set.

Your OTRS installation already contains a standard salutation and a standard signature, but you might need to edit them or create new Salutations and Signatures. Queues can not be created without salutations and signatures, and only one salutation and signature can be assigned to a queue.

After system addresses, salutations, signatures, groups are set, you can continue the setup with Queues. Each queue has to assign to a group, and only the group members can see the tickets in the assigned queue.

Now you can add Auto Responses and assign them to queues using the Queues ↔ Auto Responses management screen. Your OTRS installation already contains some automatic responses, you can use or edit them instead of create new ones.

To reduce the time needed for answering the tickets, Templates or SMS Templates can be created.

Normal templates can contain Attachments, and you can assign the uploaded attachments to templates using the Templates ↔ Attachments management screen.

When templates are created, you can set the templates to use in queues in the Templates ↔ Queues or SMS Templates ↔ Queues management screens.

You need to review the default Priorities, States and Types, and add new elements, if needed.

The customer requests can be categorize into services. If you would like to use this possibility, then create some Services and set the Customer Users ↔ Services relations. Furthermore, Service Level Agreements can be assign to the services.

Now you can add some notifications to be received by agents, if particular events occur. You can do this in the Ticket Notifications screen.

To help agents to organize appointments, you can setup the Calendars and the Appointment Notifications.

Tickets, articles and other objects in OTRS can be extended with Dynamic Fields or can be reduced with Access Control Lists (ACL).

Without doing everything manually, the number of failure can be reduced. Automatize some process in OTRS using Generic Agent jobs or creating processes with Process Management. The incoming emails can be pre-processed and dispatched automatically by defining some Postmaster Filters.

If external systems need to integrate with OTRS, Web Services will be very useful for this.

However OTRS has many features by default, you can extend the functionality by installing packages with the Package Manager.

If your system is ready for productive work, don’t forget to register it by using the System Registration procedure.

Finally, you can set the Home Page, the Custom Pages and the Layout of the external interface, as well as you can define a Customer Service Catalogue displayed in the external interface.

Become OTRS Expert

The next chapters of this manual describe the features and configuration settings of OTRS more detailed. There is a separated manual for Configuration Options References, that gives you a good overview of System Configuration, that can be modify the behavior of OTRS.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Ticket Settings

A ticket is similar to a medical report created for a hospital patient. When a patient first visits the hospital, a medical report is created to hold all necessary personal and medical information on him. Over multiple visits, as he is attended to by the same or additional doctors, the attending doctor updates the report by adding new information on the patient’s health and the ongoing treatment. This allows any other doctors or the nursing staff to get a complete picture on the case at hand. When the patient recovers and leaves the hospital, all information from the medical report is archived and the report is closed.

Ticket systems such as OTRS handle tickets like normal emails. The messages are saved in the system. When a customer sends a request, a new ticket is generated by the system which is comparable to a new medical report being created. The response to this new ticket is comparable to a doctor’s entry in the medical report. A ticket is closed if an answer is sent back to the customer, or if the ticket is separately closed by the system. If a customer responds again on an already closed ticket, the ticket is reopened with the new information added.

Every ticket is stored and archived with complete information. Since tickets are handled like normal emails, attachments and contextual annotations will also be stored with each email. In addition, information on relevant dates, employees involved, working time needed for ticket resolution, etc. are also saved. At any later stage, tickets can be sorted, and it is possible to search through and analyze all information using different filtering mechanisms.

Contents

Attachments

Manage Attachments

Attachment Settings

Auto Responses

Manage Auto Responses

Auto Response Settings

Auto Response Variables

Priorities

Manage Priorities

Priority Settings

Queues

Manage Queues

Queue Settings

Queues ↔ Auto Responses

Manage Queues ↔ Auto Responses Relations

Queues ↔ Auto Responses Settings

Salutations

Manage Salutations

Salutation Settings

Salutation Variables

Service Level Agreements

Manage Service Level Agreements

Service Level Agreement Settings

Services

Manage Services

Service Settings

Signatures

Manage Signatures

Signature Settings

Signature Variables

SMS Templates

Manage SMS Templates

SMS Template Settings

SMS Template Variables

SMS Templates ↔ Queues

Manage SMS Templates ↔ Queues Relations

States

Manage States

State Settings

Templates

Manage Templates

Template Settings

Template Variables

Templates ↔ Attachments

Manage Templates ↔ Attachments Relations

Templates ↔ Queues

Manage Templates ↔ Queues Relations

Types

Manage Types

Type Settings

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Attachments

For any size of organization it is often required to send a service agreement, the terms of service or a privacy statement out when a customer signs a contract.

OTRS can handle an infinite number of attachments (PDF, image, etc.) and can bundle them into templates. Your agents don’t need to maintain the attachments on their own, nor don’t they need to upload them again and again - they can just use the predefined templates.

Use this screen to add attachments for use in templates. A fresh OTRS installation doesn’t contain any attachments by default. The attachment management screen is available in the Attachments module of the Ticket Settings group.

Attachment Management Screen

Manage Attachments

To add an attachment:

Click on the Add Attachments button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Attachment Screen

To edit an attachment:

Click on an attachment in the list of attachments.

Modify the fields.

Click on the Save or Save and finish button.

Edit Attachment Screen

To delete an attachment:

Click on the trash icon in the last column of the overview table.

Click on the Confirm button.

Delete Attachment Screen

Note

If several attachments are added to the system, use the filter box to find a particular attachment by just typing the name to filter.

Attachment Settings

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

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.

Attachment *

Open the file dialog to add a file from the file system. This field is mandatory in the attachment add screen, but optional in the attachment edit screen. Adding a new file in the edit screen will overwrite the existing attachment.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Auto Responses

Quick and transparent service is vital to maintaining a good working relationship with your customer. Email, fax, social media and other non-real-time communication are patient, but you want to engage your customer immediately upon receipt of a request.

OTRS allows you to respond to a customer immediately upon receipt of a request giving the customers instantaneous feedback assuring them that their request is in processing, establishing expectation.

Automatic responses can be sent to customers based on the occurrence of certain events, such as the creation of a ticket in a specific queue, the receipt of a follow-up message in regards to a closed or rejected ticket, etc.

Use this screen to add automatic responses for use in queues. A fresh OTRS installation contains some automatic responses by default. The automatic response management screen is available in the Auto Responses module of the Ticket Settings group.

Auto Response Management Screen

Manage Auto Responses

Note

Adding automatic responses requires a valid system address. Create system addresses in the Email Addresses screen.

To add an automatic response:

Click on the Add Auto Response button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Auto Response Screen

Warning

Auto responses can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit an automatic response:

Click on an automatic response in the list of automatic responses.

Modify the fields.

Click on the Save or Save and finish button.

Edit Auto Response Screen

Note

If several automatic responses are added to the system, use the filter box to find a particular automatic response by just typing the name to filter.

Auto Response Settings

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

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.

Subject *

The subject of the email sent to the users.

Response

The body of the email sent to the users.

Type *

The event type that triggers the sending of this automatic response. Only one automatic response can be sent automatically. The following event types are available:

auto follow up

Confirms receipt of the follow-up.

auto reject

The message rejects a customer follow-up.

auto remove

Deletion of a ticket, done by the system.

auto reply

A newly raised ticket will trigger this auto response.

auto reply/new ticket

This message informs the customer of the new ticket number.

Auto response from *

The sender email address, from which the automatic response will be sent.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Auto Response Variables

Using variables in the text makes it possible to personalize messages. Variables, known as OTRS tags, are replaced by OTRS when generating the message. Find a list of available tags stems for this resource at the bottom of both add and edit screens.

Auto Response Variables

For example, the variable <OTRS_TICKET_TicketNumber> expands to the ticket number allowing a template to include something like the following.

Ticket#<OTRS_TICKET_TicketNumber>

This tag expands, for example to:

Ticket#2018101042000012

The values of the following variables are translated based on the chosen language of the customer user.

OTRSTicket_Type
OTRSTicket_State
OTRSTicket_StateType
OTRSTicket_Lock
OTRSTicket_Priority

If the language is not supported the default language is applied.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Priorities

Sometimes tickets are not equally created. One ticket may need more focus than another. A customer may be given a higher priority by the service desk to help raise customer satisfaction in a pinch or to ensure that a long-running request receives special attention. Keeping track of these higher priority requests is important, as well as handling them quickly.

OTRS provides a traffic light system based per default five levels of priorities to handle this task.

Blue: very low

Green: low

Grey: normal

Pink: high

Red: very high

The colors are based on the ID (very low being ID 1) in the database. Changing the names should be done with this in mind. New priorities have the color gray.

Use this screen to add priorities to the system. A fresh OTRS installation contains five default priority levels. The priority management screen is available in the Priorities module of the Ticket Settings group.

Priority Management Screen

Manage Priorities

Note

When creating a customized list of priorities, please keep in mind that they are sorted alphabetically in the priority selection box in the user interface.

To add a priority:

Click on the Add Priority button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Priority Screen

Warning

Priorities can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

Note

It’s recommended to limit your system to 5 priorities or less and reuse the current 5 to keep the use of the traffic light system.

To edit a priority:

Click on a priority in the list of priorities.

Modify the fields.

Click on the Save or Save and finish button.

Edit Priority Screen

Note

If several priorities are added to the system, use the filter box to find a particular priority by just typing the name to filter.

Priority Validation Dialog

If you change the name of a priority which is used in the system configuration, a validation check will warn you and give you the following options:

Save and update automatically

Apply the change and also update the affected settings.

Don’t save, update manually

Apply the change, but don’t update the affected settings. The updates need to be done manually.

Cancel

Cancel the action.

Warning

Changing the name of this object should be done with care, the check only provides verification for certain settings and ignores things where the name can’t be verified. Some examples are dashboard filters, access control lists (ACLs), and processes (sequence flow actions) to name a few. Documentation of your setup is key to surviving a name change.

Priority Settings

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

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.

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.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Queues

Teams need a workspace and the ability to dispatch work based on skill level, security level, department or responsibility just to name a few. Other teams may also need to view or react in these requests as well.

OTRS uses queues to provide your teams with structure. Queues provide a powerful way to divide and disperse the work to the responsible group of people.

Use this screen to add queues to the system. In a fresh OTRS installation there are 4 default queues: Raw, Junk, Misc and Postmaster. All incoming messages will be stored in the Raw queue if no filter rules are defined. The Junk queue can be used to store spam messages. The queue management screen is available in the Queues module of the Ticket Settings group.

Queue Management Screen

Manage Queues

To add a queue:

Click on the Add Queue button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Queue Screen

Warning

Queues can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a queue:

Click on a queue in the list of queues.

Modify the fields.

Click on the Save or Save and finish button.

Edit Queue Screen

Note

If several queues are added to the system, use the filter box to find a particular queue by just typing the name to filter.

Queue Validation Dialog

If you change the name of a queue which is used in the system configuration, a validation check will warn you and give you the following options:

Save and update automatically

Apply the change and also update the affected settings.

Don’t save, update manually

Apply the change, but don’t update the affected settings. The updates need to be done manually.

Cancel

Cancel the action.

Warning

Changing the name of this object should be done with care, the check only provides verification for certain settings and ignores things where the name can’t be verified. Some examples are dashboard filters, access control lists (ACLs), and processes (sequence flow actions) to name a few. Documentation of your setup is key to surviving a name change.

Queue Settings

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

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.

Note

The names of queues cannot be translated, even using a custom language file. Salutations and Signatures have to be assigned to queues, which depend on a specific language, so translating the name makes no sense.

Sub-queue of

It is possible to add the new queue under an existing one as sub-queue. This will be displayed as Parent Queue::Child Queue.

Group *

It is possible to limit access to the selected group. The group creates a permission link between the queue and an agent or a customer user.

Unlock timeout minutes

Any ticket on open, which is locked, in this queue will automatically unlock after the set amount of minutes. The value 0 (default) means tickets in this queue remain locked.

Escalation - first response time (minutes)

The maximum amount of working time allowed before the agent contacts with the customer.

Note

First response time will not trigger for an email ticket or telephone ticket created by an agent.

Escalation - update time (minutes)

The maximum amount of working time allowed between the agent contacts with the customer.

Escalation - solution time (minutes)

The maximum amount of working time allowed until the ticket is marked as solved.

Note

Solution time will not reset if the ticket is reopened.

Follow up Option *

Specify the handling of a follow up on closed tickets. Possible values:

new ticket

The follow up will create a new ticket.

possible

The follow up will reopen the already closed ticket.

reject

The follow up will be rejected.

See also

See Auto Responses chapter for more information.

Ticket lock after a follow up *

Only applicable if the Follow up Option is set to possible. Locks the previously closed ticket, upon reopening, to the last owner. This ensures that a follow up for a ticket is processed by the agent that has previously handled that ticket.

Warning

This does not take out-of-office into account. Use this setting with care to ensure or in combination with Unlock timeout minutes.

System address *

Select one of the Email Addresses as the sender identity for this queue.

Note

This is an ID in the database. Making changes to the Email Addresses can have adverse effects here.

Default sign key

This is only active if PGP Keys or S/MIME Certificates is enabled in the System Configuration. Choose the key to sign emails per default.

Salutation *

Select one of the defined Salutations.

Signature *

Select one of the defined Signatures.

Calendar

Select the calendar which defines working hours for this queue. Calendars are defined in the System 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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Chat Channel

Chat channel that will be used for communication related to the tickets in this queue.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Queues ↔ Auto Responses

Communicating a change in, for example, service times, service levels or other information which would be good for a customer to know when opening a ticket can be a tedious and error-ridden task. Attempting to make sure all departments have the correct information and transmitting this to their customers poses a challenge.

OTRS gives you the power to quickly assign the appropriate automatic responses to any queue, containing pertinent service information, ensuring this information reaches your customers before expectations aren’t reached.

Use this screen to add one or more automatic responses to one or more queues. The management screen is available in the Queues ↔ Auto Responses module of the Ticket Settings group.

Manage Queue-Auto Response Relations

Manage Queues ↔ Auto Responses Relations

To assign an automatic response to a queue:

Click on a queue in the Queues column.

Select the automatic responses you would like to add the queue to.

Click on the Save or Save and finish button.

Change Auto Response Relations for Queue

Note

It is not possible to assign multiple queues to an automatic response by clicking on the automatic response name. A click on the automatic response will open to the Auto Responses screen.

Note

If several automatic responses or queues are added to the system, use the filter box to find a particular automatic response or queue by just typing the name to filter.

Queues ↔ Auto Responses Settings

The following settings are available when assigning some automatic responses to a queue.

auto reply

This automatic response will be sent to users, when they send a message to the queue, and the message is not a follow-up message of a ticket.

auto reject

This automatic response will be sent to users, when they send a message to the queue and reject is set as Follow up Option in the queue settings.

auto follow up

This automatic response will be sent to users, when they send a message to the queue and possible is set as Follow up Option in the queue settings.

auto reply/new ticket

This automatic response will be sent to users, when they send a message to the queue and new ticket is set as Follow up Option in the queue settings.

auto remove

This automatic response will be sent to users, when the remove option is enabled.

Note

Auto reply, auto reject and auto reply/new ticket mutually cancel each other based on the Queues settings. Only one will take effect per queue.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Salutations

Addressing customers must be done in a standardized way. Your customers may not always be external customers requiring a less formal greeting.

OTRS provides you with the tools needed to create a standardized communication form for any one of your queues. As defined in the Queue Settings: Salutations, Templates, and Signatures are combined to ensure a well formed standardized email communication.

Salutations can be linked to one or more Queues. A salutation is used only in email answers to tickets.

Use this screen to add salutations to the system. A fresh OTRS installation already contains a standard salutation. The salutation management screen is available in the Salutations module of the Ticket Settings group.

Salutation Management Screen

Manage Salutations

To add a salutation:

Click on the Add Salutation button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Salutation Screen

Warning

Salutations can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a salutation:

Click on a salutation in the list of salutations.

Modify the fields.

Click on the Save or Save and finish button.

Edit Salutation Screen

Note

If several salutations are added to the system, use the filter box to find a particular salutation by just typing the name to filter.

Warning

Before invalidating this object, please go to the Queues module of the Ticket Settings group and make sure all queues using this setting are using a valid object.

Salutation Settings

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

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.

Salutation

The text that will be placed to the beginning of new emails.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Salutation Variables

Using variables in the text makes it possible to personalize messages. Variables, known as OTRS tags, are replaced by OTRS when generating the message. Find a list of available tags stems for this resource at the bottom of both add and edit screens.

Salutation Variables

For example, the variable <OTRS_CUSTOMER_DATA_UserLastname> expands to the customer’s last name to be included in something like the following.

Dear <OTRS_CUSTOMER_DATA_UserFirstname> <OTRS_CUSTOMER_DATA_UserLastname>,

This tag expands, for example to:

Dear Lisa Wagner,

The values of the following variables are translated based on the chosen language of the customer user.

OTRSTicket_Type
OTRSTicket_State
OTRSTicket_StateType
OTRSTicket_Lock
OTRSTicket_Priority

If the language is not supported the default language is applied.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Service Level Agreements

Your organization must meet the time demands of your customers. Timely service matters. Response to questions, updates on issues, and solutions must be provided in an agreed amount of time. The agent must receive notification of possible breaches, to prevent ticket escalation.

OTRS scales well with your needs and offers management of service level agreements (SLAs). OTRS provides you with the possibility to create numerous service level agreements covering all of your service and customer need. Each SLA can cover multiple services and define the availability of service and escalation periods.

Use this screen to add service level agreements to the system. A fresh OTRS installation doesn’t contain any service level agreements by default. The service level agreement management screen is available in the Service Level Agreements module of the Ticket Settings group.

Service Level Agreement Management Screen

See also

To use this feature, Ticket::Service must be activated in the System Configuration under the Administration group to be selectable in the ticket screens. You may click on the link in the warning message of the notification bar to directly jump to the configuration setting.

Manage Service Level Agreements

Note

Adding service level agreements requires, that at least one service is added to the system. Create services in the Services screen.

To add a service level agreement:

Click on the Add SLA button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Service Level Agreement Screen

Warning

Service level agreements can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a service level agreement:

Click on a service level agreement in the list of service level agreements.

Modify the fields.

Click on the Save or Save and finish button.

Edit Service Level Agreement Screen

Note

If several service level agreements are added to the system, use the filter box to find a particular service level agreement by just typing the name to filter.

Service Level Agreement Settings

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

SLA *

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.

Note

The names of service level agreements cannot be translated, even using a custom language file. Service level agreements can use calendars, that depend on time zones. Because of this, different service level agreements have to be created for each time zone and translating their names makes no sense.

Service

Select one or more of the Services to be assigned to this SLA.

Calendar

Select the calendar which defines working hours for this queue. Calendars are defined in the System Configuration.

Escalation - first response time (minutes)

The maximum amount of working time allowed before the agent contacts with the customer.

Note

First response time will not trigger for an email ticket or telephone ticket created by an agent.

Escalation - update time (minutes)

The maximum amount of working time allowed between the agent contacts with the customer.

Escalation - solution time (minutes)

The maximum amount of working time allowed until the ticket is marked as solved.

Note

Solution time will not reset if the ticket is reopened.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Dialog message

Is being displayed if a customer chooses this SLA on ticket creation (only in the external interface).

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Services

Requests to your service desk should be categorized based on affected service to correctly reach a team of experts to deal with the issue. Because not all your agents can deal with specific problems. Lack of experience or access to resources to fix an issue requires defining the service affected in a ticket helps to categorize the issue and target the correct teams.

OTRS allows adding all services offered to your customers. These services may be later bound to Service Level Agreements to ensure a timely solution based on customer-specific agreements.

Use this screen to add services to the system. A fresh OTRS installation doesn’t contain any services by default. The service management screen is available in the Services module of the Ticket Settings group.

Service Management Screen

See also

To use this feature, Ticket::Service must be activated in the System Configuration under the Administration group to be selectable in the ticket screens. You may click on the link in the warning message of the notification bar to directly jump to the configuration setting.

Manage Services

To add a service:

Click on the Add Service button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Service Screen

Warning

Services can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a service:

Click on a service in the list of services.

Modify the fields.

Click on the Save or Save and finish button.

Edit Service Screen

Note

If several services are added to the system, use the filter box to find a particular service by just typing the name to filter.

Warning

Changing the name of this object should be done with care, the check only provides verification for certain settings and ignores things where the name can’t be verified. Some examples are dashboard filters, access control lists (ACLs), and processes (sequence flow actions) to name a few. Documentation of your setup is key to surviving a name change.

Service Settings

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

Service *

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.

Sub-service of

It is possible to add the new service under an existing one as sub-service. This will be displayed as Parent Service::Child Service.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Note

A service can only be selectable in the ticket screens, if the service is assigned to the customer user of the ticket or it is set as default service for all customer users in the Customer Users ↔ Services screen.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Signatures

Corporate identity and team information are essential in each communication. The name of the employee writing and other vital details like disclaimers are some examples of necessary information to include in the communication with the customer.

OTRS provides you with the same tools here, as with Salutations, to create a standardized communication form for any one of your queues. As defined in the Queue Settings: Salutations, Templates, and Signatures are combined to ensure a well formed standardized email communication.

Signatures can be linked to one or more Queues. A signature is used only in email answers to tickets.

Use this screen to add signatures to the system. A fresh OTRS installation already contains a standard signature. The signature management screen is available in the Signatures module of the Ticket Settings group.

Signature Management Screen

Manage Signatures

To add a signature:

Click on the Add Signature button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Signature Screen

Warning

Signatures can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a signature:

Click on a signature in the list of signatures.

Modify the fields.

Click on the Save or Save and finish button.

Edit Signature Screen

Note

If several signatures are added to the system, use the filter box to find a particular signature by just typing the name to filter.

Warning

Before invalidating this object, please go to the Queues module of the Ticket Settings group and make sure all queues using this setting are using a valid object.

Signature Settings

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

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.

Signature

The text that will be placed to the end of new emails.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Signature Variables

Using variables in the text makes it possible to personalize messages. Variables, known as OTRS tags, are replaced by OTRS when generating the message. Find a list of available tags stems for this resource at the bottom of both add and edit screens.

Signature Variables

For example, the variable <OTRS_CURRENT_UserFirstname> <OTRS_CURRENT_UserLastname> expands to the agent’s first and last name allowing a template to include something like the following.

Best regards,

<OTRS_CURRENT_UserFirstname> <OTRS_CURRENT_UserLastname>

This tag expands, for example to:

Best regards,

Steven Weber

The values of the following variables are translated based on the chosen language of the customer user.

OTRSTicket_Type
OTRSTicket_State
OTRSTicket_StateType
OTRSTicket_Lock
OTRSTicket_Priority

If the language is not supported the default language is applied.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

SMS Templates

An on-call duty should be alarmed about incidents on an email servers, therefore cannot get an email from OTRS. Additionally, in the case where customers have no internet access, it’s imperative to ensure good contact.

OTRS provides SMS as a cloud service and allows, as with email, management of this communication via templates.

An SMS template is a default text which helps your agents to write faster tickets or answers.

Use this screen to add SMS templates for use in communications. A fresh OTRS installation doesn’t contain any SMS templates by default. The SMS template management screen is available in the SMS Templates module of the Ticket Settings group.

SMS Template Management Screen

Manage SMS Templates

Note

To be able to use SMS cloud service in OTRS, you have to activate it first in Cloud Services module.

Activate SMS Cloud Service

To add an SMS template:

Click on the Add SMS Template button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add SMS Template Screen

To edit an SMS template:

Click on an SMS template in the list of SMS templates.

Modify the fields.

Click on the Save or Save and finish button.

Edit SMS Template Screen

To delete an SMS template:

Click on the trash icon in the list of SMS templates.

Click on the Confirm button.

Delete SMS Template Screen

Note

If several SMS templates are added to the system, a filter box is useful to find a particular SMS template by just typing to filter.

SMS Template Settings

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

Type *

There are different kind of SMS templates that are used for different purposes. A template can be:

Answer

To be used as a ticket response with Reply via SMS article action of the ticket detail view.

Create

To be used for a new SMS ticket.

SMSOutbound

To be used for sending a new SMS to a customer user from within the ticket detail view.

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.

Template

The body of the email sent to the users.

Warning

The maximum length of text message that you can send is 918 characters. However, if you send more than 160 characters then your message will be broken down in to chunks of 153 characters before being sent to the recipient’s handset. We recommend keeping the messages to less than 160 characters.

Flash message

Show message directly without user interaction and do not store it automatically (support may vary by device and provider).

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

SMS Template Variables

Using variables in the text makes it possible to personalize messages. Variables, known as OTRS tags, are replaced by OTRS when generating the message. Find a list of available tags stems for this resource at the bottom of both add and edit screens.

SMS Template Variables

For example, the variable <OTRS_TICKET_TicketNumber> expands to the ticket number allowing an SMS template to include something like the following.

Ticket#<OTRS_TICKET_TicketNumber> has been raised in <OTRS_Ticket_Queue>.

This tag expands, for example to:

Ticket#2018101042000012 has been raised in Postmaster.

The values of the following variables are translated based on the chosen language of the customer user.

OTRSTicket_Type
OTRSTicket_State
OTRSTicket_StateType
OTRSTicket_Lock
OTRSTicket_Priority

If the language is not supported the default language is applied.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

SMS Templates ↔ Queues

Communicating a change to a template, or distribution of a new communication requirement, can be tedious and error-ridden because it requires that all teams pull the information and publish it appropriately.

OTRS gives you the power to quickly assign the appropriate SMS templates to any queue, containing pertinent ticket information, ensuring this information reaches your customers and agents.

Use this screen to add one or more SMS templates to one or more queues. The management screen is available in the SMS Templates ↔ Queues module of the Ticket Settings group.

Manage SMS Template-Queue Relations

Manage SMS Templates ↔ Queues Relations

To assign an SMS template to one or more queues:

Click on an SMS template in the SMS Templates column.

Select the queues you would like to add the SMS template to.

Click on the Save or Save and finish button.

Change Queue Relations for SMS Template

To assign a queue to one or more SMS templates:

Click on a queue in the Queues column.

Select the SMS templates you would like to add the queue to.

Click on the Save or Save and finish button.

Change SMS Template Relations for Queue

Note

If several SMS templates or queues are added to the system, use the filter box to find a particular SMS template or queue by just typing the name to filter.

Multiple SMS templates or queues can be assigned in both screens at the same time. Additionally clicking on an SMS template or clicking on a queue in the relations screen will open the Edit SMS Template screen or the Edit Queue screen accordingly.

Warning

Accessing a queue or an SMS template provides no back link to the relations screen.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

States

Active tracking of tickets leads to a better sense of workload and provides metrics as a key performance indicator. Sorting tasks and setting appointments can help to level-off the workload and keep your service desk running.

OTRS uses ticket states to ensure that your agents always know which tickets are being attended to and which not. Additionally, detailed reports on the states of your tickets can be provided by ticket search or reports and personalized sorting is possible using dashboards and queue and service overviews.

Nine states are pre-defined. More states can be added, but the default states are enough to get you going and mostly enough for any situation.

The default states are the following:

closed successful

A ticket is complete. The customer received a solution which worked.

closed unsuccessful

A ticket is complete. The customer received no solution or the solution was not appropriate.

merged

The ticket content is found in a different ticket.

new

The ticket is created by the customer without contact with an agent.

open

The ticket is currently in progress. Customer and agent are in contact with each another.

pending auto close+

The ticket will be set as closed successful upon reaching the pending time.

pending auto close-

The ticket will be set as closed unsuccessful upon reaching the pending time.

pending reminder

The ticket should be worked on again upon reaching the pending time.

removed

The ticket has been removed from the system.

Note

Pending jobs are checked per default every two hours and forty-five minutes. This time is a static time, which means the times are 02:45, 04:45, 06:45 and so on. The job can be run more often or seldom and are configured in the System Configuration module of the Administration group.

Use this screen to add states to the system. A fresh OTRS installation contains several states by default. The state management screen is available in the States module of the Ticket Settings group.

State Management Screen

Manage States

To add a state:

Click on the Add State button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add State Screen

Warning

States can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a state:

Click on a state in the list of states.

Modify the fields.

Click on the Save or Save and finish button.

Edit State Screen

Note

If several states are added to the system, use the filter box to find a particular state by just typing the name to filter.

State Validation Dialog

If you change the name of a state which is used in the system configuration, a validation check will warn you and give you the following options:

Save and update automatically

Apply the change and also update the affected settings.

Don’t save, update manually

Apply the change, but don’t update the affected settings. The updates need to be done manually.

Cancel

Cancel the action.

Warning

Changing the name of this object should be done with care, the check only provides verification for certain settings and ignores things where the name can’t be verified. Some examples are dashboard filters, access control lists (ACLs), and processes (sequence flow actions) to name a few. Documentation of your setup is key to surviving a name change.

State Settings

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

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.

State type *

Every state is linked to a type, which needs to be specified if a new state is created or an existing one is edited. The following types are available:

closed

merged

new

open

pending auto

pending reminder

removed

Note

State types are predefined and cannot be changed in the software due to their special mechanics. When adding new states for pending auto and pending reminder state types you must make further configurations in the System Configuration module of the Administration group.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

See also

The following configuration options are relevant and noteworthy when managing states:

Daemon::SchedulerCronTaskManager::Task###TicketPendingCheck

Ticket::StateAfterPending

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Templates

Providing the correct and consistent answer all the time regardless of employee or knowledge-level is important to maintain a professional appearance to your customers. Additionally, speed in sending standard answers is key to wading through the masses of requests in growing service desks.

OTRS templates offer you a variety of ways to deal with standardizing communications and help to pre-define texts so that the customer always receives the same level and quality of service from all agents.

Use this screen to add templates for use in communications. A fresh OTRS installation already contains a template by default. The template management screen is available in the Templates module of the Ticket Settings group.

Template Management Screen

Manage Templates

Note

To add attachments to a template, it needs to create the attachment first in the Attachments screen.

To add a template:

Click on the Add Template button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Template Screen

To edit a template:

Click on a template in the list of templates.

Modify the fields.

Click on the Save or Save and finish button.

Edit Template Screen

To delete a template:

Click on the trash icon in the list of templates.

Click on the Confirm button.

Delete Template Screen

Note

If several templates are added to the system, a filter box is useful to find a particular template by just typing to filter.

Template Settings

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

Type *

There are different kind of templates that are used for different purposes. A template can be:

Answer

To be used as a ticket response or reply.

Create

To be used for new phone or email ticket.

Email

To be used for writing an email to a customer user or to someone else.

Forward

To be used to forward an article to someone else.

Note

To be used to create notes.

Phone call

To be used for inbound and outbound phone calls.

Process dialog

To be used in process management to pre-fill text of articles in user task activity dialogs.

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.

Subject

The subject of the article added by the template.

Subject method

Specify how the current article subject should be dealt with. The following methods are available:

Combine

The template subject will be added after the current article subject.

Keep

The current article subject will be kept.

Overwrite

The current article subject will be replaced with the template subject.

Template

The body of the article added by the template.

Attachments

It is possible to add one or more attachments to this template. Attachments can be added in the Attachments screen.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Template Variables

Using variables in the text makes it possible to personalize messages. Variables, known as OTRS tags, are replaced by OTRS when generating the message. Find a list of available tags stems for this resource at the bottom of both add and edit screens.

Template Variables

For example, the variable <OTRS_TICKET_TicketNumber> expands to the ticket number allowing a template to include something like the following.

Ticket#<OTRS_TICKET_TicketNumber>

This tag expands, for example to:

Ticket#2018101042000012

The values of the following variables are translated based on the chosen language of the customer user.

OTRSTicket_Type
OTRSTicket_State
OTRSTicket_StateType
OTRSTicket_Lock
OTRSTicket_Priority

If the language is not supported the default language is applied.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Templates ↔ Attachments

Making changes to standard attachments is sometimes overwhelming. The question is, “Where were the attachments used?” or “How to quickly update them across the board?”. It’s also important to know who are using which attachments, before updating them. A new attachment can have multiple uses within your organization.

OTRS empowers you to manage this providing you an overview to manage the 1:n relationships and quickly identify the templates using your attachments.

Use this screen to add one or more attachments to one or more templates. To use this function, at least one attachment and one template need to have been added to the system. The management screen is available in the Templates ↔ Attachments module of the Ticket Settings group.

Manage Template-Attachment Relations

Manage Templates ↔ Attachments Relations

To add some attachments to a template:

Click on a template in the Templates column.

Select the attachments you would like to add to the template.

Click on the Save or Save and finish button.

Change Attachment Relations for Template

To assign an attachment to some templates:

Click on an attachment in the Attachments column.

Select the templates you would like to assign the attachment to.

Click on the Save or Save and finish button.

Change Template Relations for Attachment

Note

If several templates or attachments are added to the system, use the filter box to find a particular template or attachment by just typing the name to filter.

Multiple templates or attachments can be assigned in both screens at the same time. Additionally clicking on a template or clicking on an attachment in the relations screen will open the Edit Template screen or the Edit Attachment screen accordingly.

Warning

Accessing a template or an attachment provides no back link to the relations screen.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Templates ↔ Queues

Sharing, distributing and making changes to standard text modules and information for sharing with customers or communication between teams can be an impossible mission.

OTRS can quickly aid you in ensuring that all of your teams have the correct templates available for use by assignment based on the queue.

Use this screen to add one or more templates to one or more queues. To use this function, at least one template and one queue need to have been added to the system. The management screen is available in the Templates ↔ Queues module of the Ticket Settings group.

Manage Template-Queue Relations Screen

Manage Templates ↔ Queues Relations

To assign a template to a queue:

Click on a template in the Templates column.

Select the queues you would like to add the template to.

Click on the Save or Save and finish button.

Change Queue Relations for Template

To assign a queue to a template:

Click on a queue in the Queues column.

Select the templates you would like to assign the queue to.

Click on the Save or Save and finish button.

Change Template Relations for Queue

Note

If several templates or queues are added to the system, use the filter box to find a particular template or queue by just typing the name to filter.

Multiple templates or queues can be assigned in both screens at the same time. Additionally clicking on a template or clicking on a queue in the relations screen will open the Edit Template screen or the Edit Queue screen accordingly.

Warning

Accessing a queue or a template provides no back link to the relations screen.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Types

Good KPIs require knowing the type of work your organization performs. Not all tasks take the same amount of effort even when performed by the same team. Creating a queue structure for this purpose can be overpowered due to the amount of configuration required to create and manage a queue.

OTRS provisions for KPIs with minimal overhead using ticket types. Typical types used in IT service desks are unclassified, incident and problem. You can quickly define new types with ease.

Use this screen to add types to the system. A fresh OTRS installation contains an unclassified type by default. The type management screen is available in the Types module of the Ticket Settings group.

Type Management Screen

Warning

Services must first be activated via System Configuration under the Administration group to be selectable in the ticket screens. You may click on the link in the warning message to directly jump to the configuration setting.

Type Activation Warning

Manage Types

To add a type:

Click on the Add Ticket Type button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Type Screen

Warning

Types can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a type:

Click on a type in the list of types.

Modify the fields.

Click on the Save or Save and finish button.

Edit Type Screen

Note

If several types are added to the system, use the filter box to find a particular type by just typing the name to filter.

Type Settings

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

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.

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.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Communication & Notifications

Clear, complete, and transparent communication is key to ensuring that your organization offers outstanding service to your customers. Your organization would like to give your customers the most consistent service and ensure that your service is highly recognizable, every time. Your teams want to have an identity which instills a specific sense of security and familiarity.

OTRS provides you with the tools to build teams, trust and security to better and uniformly serve your customer. With system addresses you can assign your inbound mails to certain teams and allow them all to use the same address without causing confusion by using team mailboxes via a mail client. Templates, automatic answers, and attachment management let you leverage central management of the most important communications. Many other tools are also available and covered in the sections below.

Contents

Admin Notification

Administrative Message Settings

Appointment Notifications

Manage Appointment Notifications

Appointment Notification Settings

Basic Appointment Notification Settings

Appointment Events

Appointment Filter

Appointment Notification Recipients

Appointment Notification Methods

Appointment Notification Text

Appointment Notification Variables

Communication Log

Communication Log Overview

Email Addresses

Manage Email Addresses

Email Address Settings

Setting up Outgoing Emails

Sending Mails via Local MTA

Sending Mails via External Email Provider

PGP Keys

Manage PGP Keys

Postmaster Filters

Manage Postmaster Filters

Postmaster Filter Settings

Basic Postmaster Filter Settings

Filter Condition

Set Email Headers

PostMaster Mail Accounts

Manage Mail Accounts

Mail Account Settings

Setting up Incoming Emails

Receiving Mails via Local MDA

Receiving Mails via External Email Provider

S/MIME Certificates

Manage S/MIME Certificates

Social Media Profiles

Manage Facebook Profiles

Manage LinkedIn Profiles

Manage Twitter Profiles

Limit User Access to Profiles

Ticket Notifications

Manage Ticket Notifications

Ticket Notification Settings

Basic Ticket Notification Settings

Events

Ticket Filter

Article Filter

Ticket Notification Recipients

Ticket Notification Methods

Notification Text

Ticket Notification Variables

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Admin Notification

Corporations may need to make general announcements to everyone or publish news to several groups of agents or individuals. Also, OTRS administrator may need to contact with specific agents regarding an event.

OTRS gives the administration the tool Admin Notification making sending announcements and news to the masses of users accurate and timely, to target group of people, simple. Administrators can send notifications based on a specific list of recipients, or a group of users inside OTRS, with powerful text editor enhanced content.

Use this screen to send administrative messages to specific agents, group or role members. The message compose screen is available in the Admin Notification module of the Communication & Notifications group.

Create Administrative Message Screen

Administrative Message Settings

The following settings are available when composing an administrative message. The fields marked with an asterisk are mandatory.

From *

This email address will be added into the From field of the message.

Send message to users

One or more Agents can be selected in this field, to whom the message will be sent.

Send message to group members

One or more Groups can be selected in this field, to whose members the message will be sent.

Group members need to have permission

With these radio buttons can be selected, if a group member need read-only or read-write permissions to receive the message.

Also send to customers in groups

Select this checkbox to send the message also for customers in groups.

Note

This option is available only, if the CustomerGroupSupport setting is enabled.

Subject *

The subject of the messages.

Body *

The body text of the message.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Appointment Notifications

Missing appointments can damage your image with a customer. Once there is an appointment assigned in the calendar, it’s normal to receive notification:

Upon a new or changed event

Upon cancellation of an event

Before the event, as a reminder

Notification relieves the agent the stress of mentally tracking appointments.

OTRS appointment notifications satisfies this need. Here an administrator can easily set notifications with general rules, including trigger events and filters. Afterward, appointments fitting the bill notify the correct users at the correct time.

Use this screen to add appointment notifications to the system. In a fresh OTRS installation an appointment reminder notification is already added by default. The appointment notification management screen is available in the Appointment Notifications module of the Communication & Notifications group.

Appointment Notification Management Screen

Manage Appointment Notifications

To add an appointment notification:

Click on the Add Notification button in the left sidebar.

Fill in the required fields as explained in Appointment Notification Settings.

Click on the Save button.

To edit an appointment notification:

Click on an appointment notification in the list of appointment notifications.

Modify the fields as explained in Appointment Notification Settings.

Click on the Save or Save and finish button.

To delete an appointment notification:

Click on the trash icon in the list of appointment notifications.

Click on the Confirm button.

Delete Appointment Notification Screen

To export all appointment notifications:

Click on the Export Notifications button in the left sidebar.

Choose a location in your computer to save the Export_Notification.yml file.

To import appointment notifications:

Click on the Browse… button in the left sidebar.

Select a previously exported .yml file.

Click on the Overwrite existing notifications? checkbox, if you would like to overwrite the existing notifications.

Click on the Import Notification configuration button.

Appointment Notification Settings

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

See also

For an example, see the default appointment reminder notification which is included in a fresh OTRS installation.

Basic Appointment Notification Settings

Appointment Notification Settings - Basic

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Show in agent preferences

Define how the notification should be displayed in agent preferences. The following options are available:

No

The notification won’t be displayed in agent preferences. The notification is sent to all appropriate agents by the defined method.

Yes

The notification will be displayed in agent preferences for selection. The agents may opt-in or opt-out.

Yes, but require at least one active notification method.

The notification will be displayed in agent preferences, but require at least one active notification method. This is annotated by an asterisk next to the name.

Personal Appointment Notification Settings

Available for agent in groups

The notification will only appear to agents that belong to the selected groups. If no group is selected, it is available for all agents.

Agent preferences tooltip

This message will be shown on the agent preferences screen as a tooltip for this notification.

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.

Appointment Events

Appointment Notification Settings - Events

Event

Here you can choose which events will trigger this notification. An additional appointment filter can be applied below to only send for appointments with certain criteria.

Possible events are:

AppointmentCreate

Executed after an appointment has been created.

AppointmentUpdate

Executed after an appointment has been updated.

AppointmentDelete

Executed after an appointment has been deleted.

AppointmentNotification

This is a special appointment event that will be executed by the OTRS daemon in time. If an appointment contains a date/time value for notifications, as already described in this documentation, and such a notification date is reached, the OTRS daemon will execute this kind of event for every related appointment separately.

CalendarCreate

Executed after a calendar has been created.

CalendarUpdate

Executed after a calendar has been updated.

Appointment Filter

Appointment Notification Settings - Appointment Filter

This widget can optionally be used to narrow the list of appointments by matching configured values:

Calendar

Select which calendar the related appointment needs to be part of.

Title

Filter for a part or complete title of the appointment.

Location

Filter for a part or complete location of the appointment.

Resource

Choose from a list of teams or resources assigned to the appointments.

Appointment Notification Recipients

Appointment Notification Settings - Recipients

Send to

Select which agents should receive the notifications. Possible values are:

Agent (resources), who are selected within the appointment

All agents with (at least) read permission for the appointment (calendar)

All agents with write permission for the appointment (calendar)

Send to these agents

One or more agents can be selected who should receive the notifications.

Send to all group members (agents only)

One or more groups can be selected whom agents should receive the notifications.

Send to all role members

One or more roles can be selected whom agents should receive the notifications.

Send on out of office

If this option is checked, the notification will be sent even if the agent is currently out of office.

Once per day

Notify users just once per day about a single appointment using a selected transport. If this is the first notification about an appointment, then the notification will be sent. If a notification was already sent before and this option is checked, the OTRS daemon will check the time the last notification was sent. If there was no notification sent in the last 24 hours, the notification will be sent again.

Appointment Notification Methods

Appointment Notification Settings - Notification Methods

Enable this notification method

Enable or disable this notification method. A notification method can be email, web view or SMS.

Note

To use the SMS notification method, Cloud Services need to be enabled.

Additional recipient email addresses

Additional recipients can be added here. Use comma or semicolon to separate the email addresses.

Article visible for customer

An article will be created if the notification is sent to the customer or an additional email address.

Email template

Select which email template should be used for the notification.

Note

Additional email templates can be added by placing a .tt file into the folder <OTRS_Home>/Kernel/Output/HTML/Templates/Standard/NotificationEvent/Email/. See the existing email templates for an example.

Enable email security

Checking this option will encrypt the notification email.

Note

To use this feature, PGP Keys or S/MIME Certificates need to be enabled.

Email security level

If Enable email security is checked, then this setting is activated. The following options are available:

PGP sign only

Sign only the notification email with PGP key. If no PGP keys have been added to the system, this option is not visible.

PGP encrypt only

Encrypt only the notification email with PGP key. If no PGP keys have been added to the system, this option is not visible.

PGP sign and encrypt

Sign and encrypt the notification email with PGP key. If no PGP keys have been added to the system, this option is not visible.

SMIME sign only

Sign only the notification email with S/MIME certificate. If no S/MIME certificates have been added to the system, this option is not visible.

SMIME encrypt only

Encrypt only the notification email with S/MIME certificate. If no S/MIME certificates have been added to the system, this option is not visible.

SMIME sign and encrypt

Sign and encrypt the notification email with S/MIME certificate. If no S/MIME certificates have been added to the system, this option is not visible.

Note

To use this feature, PGP Keys or S/MIME Certificates need to be enabled.

If signing key/certificate is missing

Select the method, that should be used if signing key or certificate is missing.

If encryption key/certificate is missing:

Select the method, that should be used if encryption key or certificate is missing.

Appointment Notification Text

Appointment Notification Settings - Notification Text

The main content of a notification can be added for each languages with localized subject and body text. It is also possible to define static text content mixed with OTRS smart tags.

Subject *

The localized subject for a specific language.

Text *

The localized body text for a specific language.

Add new notification language

Select which languages should be added to create localized notifications. The language of the customer or agent will be used as found in the customer and agent preferences. Secondarily, the system default language will be chosen. The fall back will always be English.

Warning

Deleting a language from the DefaultUsedLanguages setting that already has a notification text here will make the notification text unusable. If a language is not present or enabled on the system, the corresponding notification text could be deleted if it is not needed anymore.

Appointment Notification Variables

Using variables in the text makes it possible to personalize messages. Variables, known as OTRS tags, are replaced by OTRS when generating the message. Find a list of available tags stems for this resource at the bottom of both add and edit screens.

Appointment Notification Variables

For example, the variable <OTRS_APPOINTMENT_TITLE[20]> expands to the first 20 characters of the title allowing a template to include something like the following.

Title: <OTRS_APPOINTMENT_TITLE[20]>

This tag expands, for example to:

Title: Daily meeting in the…

The values of the following variables are translated based on the chosen language of the customer user.

OTRSTicket_Type
OTRSTicket_State
OTRSTicket_StateType
OTRSTicket_Lock
OTRSTicket_Priority

If the language is not supported the default language is applied.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Communication Log

Managers, leaders, team leads, and system administrators may need to track past communication to follow up specific messages. In some cases, issues arise, and a target recipient did not receive a message. Without access to the mail server logs, tracking the communication is difficult.

OTRS introduces the Communication Log module. It’s designed to track the communication: building and spooling the mail and the connection between client and server.

Use this screen to inspect the internal logs about communication handling. The communication log overview screen is available in the Communication Log module of the Communication & Notifications group.

Communication Log Overview Screen

Communication Log Overview

The communication log overview page is a dashboard-like screen with several metrics indicating the overall health of the system, depending on filtered communications.

Account Status Screen

Account status

This widget will signal if you have any issues with configured accounts used for fetching or sending messages.

Communication status

This widget will notify you if there are any errors with either account connections or message processing.

Communication state

This widget will display if there are any active communications currently in the system.

Average processing time

This is a cumulative time statistic that is needed to complete a communication.

You can select the time range in the left sidebar in order to filter communications depending on their creation time. In addition to this, you can also dynamically filter for any keywords, state of the communication, and you can sort the overview table by all columns.

If you click on a communication row in any table, you will be presented with a detailed view screen.

Communication Log Detailed View Screen

Every communication can contain one or more logs, which can be of Connection or Message type.

Connection

This type of logs will contain any log messages coming from the modules responsible for connecting to your accounts and fetching/receiving messages.

Message

This type of logs will contain any log messages related to specific message processing. Any module working on message themselves can log their actions in this log, giving you a clear overview of what’s going on.

You can filter log entries based on their priority, by choosing desired priority in the left sidebar. Log level rules apply: by selecting a specific priority, you will get log entries that have that priority set and higher, with Error being the highest.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Email Addresses

The main channel of communication with the customers is often email. An organization consists of multiple department or teams. Email addresses differ for each group which is servicing your customer. You may have the following:

support@example.org

hr@exapmle.org

sales@example.org

These addresses are just some examples, and you may have many more. You use these channels to receive and send messages, and in mail clients, one can often send with the wrong address.

OTRS manages as many email addresses for your teams as needed. All your email addresses, whether for sending or receiving, are kept and configured nicely in one place. In the Queue Settings, the correct address is always chosen preventing that someone working in multiple roles sends an email out with the wrong account.

To enable OTRS to send emails, you need a valid email address to be used by the system. OTRS is capable of working with multiple email addresses, since many support installations need to use more than one. A queue can be linked to many email addresses, and vice versa. The address used for outgoing messages from a queue can be set when the queue is created.

Use this screen to add system email addresses to the system. An email address is already added to the system at installation time of OTRS. The email address management screen is available in the Email Addresses module of the Communication & Notifications group.

Email Address Management Screen

Manage Email Addresses

To add an email address:

Click on the Add System Address button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Email Address Add Screen

Warning

Email addresses can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

Note

Once an email address is added and set to valid, OTRS cannot send an email to this address. This prevents loopbacks which could crash your system. If you need to transfer information between departments please use the split article action. This will allow you to create a new ticket to another team for assigning a task, for example.

To edit an email address:

Click on an email address in the list of email addresses.

Modify the fields.

Click on the Save or Save and finish button.

Email Address Edit Screen

Note

If several email addresses are added to the system, use the filter box to find a particular email address by just typing the name to filter.

Email Address Settings

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

Email address *

The email address to be added.

Display 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 sender information of the article.

Sender Information

Queue *

The queue, to which the email address will be added as default email address.

Note

This setting will apply if the email is distributed via the recipient address. This setting can be overridden by Postmaster Filters or in the Mail Account Settings when Dispatching by selected Queue is chosen.

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.

Note

An email address can only be set to invalid or invalid-temporarily, if it is not assigned to any queue.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Setting up Outgoing Emails

For outgoing emails, OTRS can be configured in a variety of ways. The best option to do this might depend on your specific circumstances.

Sending Mails via Local MTA

Using a local mail transfer agent (MTA) to send mails directly or relay mails to a smart host is the recommended option. It provides local mail queuing in the case of network connectivity issues and provides you with the capability to authenticate against multiple outgoing mail accounts or accounts using other than basic authentication methods.

A default setup could use the Sendmail binary and Postfix.

Sending emails via SMTP (Simple Mail Transfer Protocol) relay via a smart host can be used in case you are using another mail server in your network, or on the internet. Your local MTA must be configured with the credentials for authentication and the target MTA must allow the user to send mails as other users of the domain.

Sending emails in the name of another domain requires either a sender policy framework (SPF) record, allowing the local server to send as the user, or in the case that the local mail server should act as the mail server for a target domain, mail exchange resource record (MX) and domain name service (DNS) C-name records for the local server are required. The MTA must, in both cases, be correctly configured to send as the target domain.

Note

An SPF record is not necessarily required. However, if the sender domain has an SPF record set, the MTA’s IP address must be listed in it, otherwise the SPF check will fail. Alternatively, you can send outbound mails to a relay host, and in that case the relay’s IP address must be listed in the SPF record of the sender domain. If the sender domain has no SPF record, there is nothing wrong with the OTRS MTA delivering outbound mails directly.

Sending Mails via External Email Provider

Alternatively, it is also possible to use an external email provider for outgoing emails.

Note

Only regular password authentication is supported. For advanced OAuth2 support and in case you are an OTRS customer, please raise a support ticket in the OTRS customer portal.

Note

In case you are an OTRS customer, you can change the SMTP configuration by raising a support ticket in the OTRS customer portal.

To setup the system to use Office 365 as email provider:

Read the POP, IMAP, and SMTP settings for Outlook.com and Add your Outlook.com account to another mail app or smart device chapters in the official documentation.

Copy the one-time application password shown in the administrator area of Office 365.

Go to the System Configuration screen of OTRS and add the following settings:

SendmailModule → Kernel::System::Email::SMTPTLS

SendmailModule::AuthPassword → the application password from Office 365

SendmailModule::AuthUser → email-address@company.tld

SendmailModule::Host → SMTP.office365.com

SendmailModule::Port → 587

To setup the system to use Gmail as email provider:

Read the Send email from a printer, scanner, or app chapter in the official Help Center.

Go to the System Configuration screen of OTRS and add the following settings:

SendmailModule → Kernel::System::Email::SMTPTLS

SendmailModule::AuthPassword → your email password

SendmailModule::AuthUser → email-address@company.tld

SendmailModule::Host → smtp-relay.gmail.com

SendmailModule::Port → 587

To setup the system to use another external email provider:

Read the official documentation of the external provider.

Go to the System Configuration screen of OTRS and add the following settings:

SendmailModule → Kernel::System::Email::SMTPTLS

SendmailModule::AuthPassword → your email password

SendmailModule::AuthUser → your email address or username

SendmailModule::Host → the SMTP address of the external provider

SendmailModule::Port → the port for the SMTP server

See also

You can find detailed instructions in the PostMaster Mail Accounts chapter about how to configure incoming emails.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

PGP Keys

Secure communications protect your customers and you. In the GDPR encryption is explicitly mentioned as one of the security and personal data protection measures in a few articles. Although under the GDPR encryption is not mandatory, it is indeed essential in some areas.

OTRS empowers you to encrypt communications where needed by means of S/MIME Certificates or PGP Keys.

Note

Setup of services and software required for encryption are not covered here because of independence to this software.

Use this screen to add PGP keys to the system. The PGP management screen is available in the PGP Keys module of the Communication & Notifications group.

PGP Management Screen

Manage PGP Keys

Note

To be able to use PGP keys in OTRS, you have to activate its setting first.

Enable PGP Support

To add a PGP key:

Click on the Add PGP Key button in the left sidebar.

Click on Browse… button to open the file dialog.

Select a PGP key from the file system.

Click on the Add button.

Add PGP Key Screen

To delete a PGP key:

Click on the trash icon in the list of PGP keys.

Click on the Confirm button.

Delete PGP Key Screen

Note

If several PGP keys are added to the system, use the search box to find a particular PGP key.

To adjust the PGP settings of the system:

Go to System Configuration screen.

Navigate to Core → Crypt → PGP in the navigation tree.

Review the settings.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Postmaster Filters

Pre-sorting standard mail done in a mail room takes care that not every piece of mail sent to the office goes to the same group of people. After a second look at the envelope, rerouting occurs where needed.

OTRS uses so-called postmaster filters to read the email’s envelope and take further action. Depending upon, for example, a subject or sender, an email bound for the service desk could land in a sub-queue or be redirected to a completely different team to create transparency and give your customer the fastest service possible.

Use this screen to add postmaster filters to the system. The postmaster filter management screen is available in the PostMaster Filters module of the Communication & Notifications group.

Postmaster Filter Management Screen

Manage Postmaster Filters

Note

When adding or editing a postmaster filter, please keep in mind that they are evaluated in ASCIIbetical order by name.

To add a postmaster filter:

Click on the Add PostMaster Filter button in the left sidebar.

Fill in the required fields.

Click on the Save button.

To edit a postmaster filter:

Click on a postmaster filter in the list of postmaster filters.

Modify the fields.

Click on the Save or Save and finish button.

To delete a postmaster filter:

Click on the trash icon in the list of postmaster filters.

Click on the Confirm button.

Delete Postmaster Filter Screen

Note

If several postmaster filters are added to the system, a filter box is useful to find a particular postmaster filter by just typing to filter.

Postmaster Filter Settings

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

Postmaster Filter Settings Example

Basic Postmaster Filter Settings

Postmaster Filter Settings - Basic

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.

Note

When adding or editing one of the postmaster filters, remember multiple filters may apply to a single mail. Rules are executed and sorted by the ASCII value of the names. Based on the sorted order in the overview, they are applied from top to bottom. Look at the ASCII table to see how to sort your names based on the ASCIIbetical order.

Stop after match *

Postmaster filters are evaluated in ASCIIbetical order. This setting defines the evaluation of the subsequent postmaster filters.

No

All postmaster filters are executed.

Yes

The current postmaster filter is still evaluated, but evaluation of the remaining filters is canceled.

Filter Condition

Postmaster Filter Settings - Filter Condition

A postmaster filter consists of one or more conditions that must be met in order for the defined actions to be executed on the email. Filter conditions can be defined for specific mail header entries or for strings in the mail body.

Search header field … for value

Select a mail header or an X-OTRS header from the first drop-down list, and enter a value as search term for the selected mail header to the second field. Even regular expressions can be used for extended pattern matching.

A list of mail header entries can be found in RFC5322. It is also possible to define X-OTRS headers as filter condition. The different X-OTRS headers and their meaning are the following:

X-OTRS-AttachmentCount

This contains as value the number of attachments which are contained in the email (e.g. 0 for mails without attachments).

X-OTRS-AttachmentExists

Depending on whether attachments are included in the email this X-OTRS header is set to yes, or it has a no value if no attachments are included.

X-OTRS-BodyDecrypted

If the incoming mail was encrypted, it is possible to add a search term to look for the body of the incoming encrypted mail.

X-OTRS-CustomerNo

Set the customer ID for the ticket.

X-OTRS-CustomerUser

Set the customer user for the ticket.

X-OTRS-DynamicField-<DynamicFieldName>

Saves an additional information value for the ticket on <DynamicFieldName> dynamic field. The possible values depend on dynamic field configuration (e.g. text: Notebook, date: 2010-11-20 00:00:00, integer: 1).

X-OTRS-FollowUp-*

These headers are the same as the ones without the FollowUp prefix, but these headers are applied only for follow-up mails.

X-OTRS-FollowUp-State-Keep

If set to 1, the incoming follow-up message will not change the ticket state. For this purpose the header can be customized in the system configuration using option KeepStateHeader.

X-OTRS-Ignore

If set to Yes or True, the incoming message will completely be ignored and never delivered to the system.

X-OTRS-IsVisibleForCustomer

Controls if the article is shown to customer users. Possible values are 0 or 1.

X-OTRS-Lock

Set the lock state of a ticket. Possible values are lock or unlock.

X-OTRS-Loop

If set to Yes or True, no auto answer is delivered to the sender of the message (mail loop protection).

X-OTRS-Owner

Set the agent as owner for the ticket.

X-OTRS-OwnerID

Set the agent ID as owner for the ticket.

X-OTRS-Priority

Set the priority for the ticket.

X-OTRS-Queue

Defines the queue in which the ticket should be sorted. If a queue is set with this header, this setting has priority over all other filter rules that refer to queues. If you use a sub-queue, specify it as Parent::Sub.

X-OTRS-Responsible

Set the agent as responsible for the ticket.

X-OTRS-ResponsibleID

Set the agent ID as responsible for the ticket.

X-OTRS-SenderType

Set the sender type for the ticket. Possible values are agent, system or customer.

X-OTRS-Service

Set the service for the ticket. If you use a sub-service, specify it as Parent::Sub.

X-OTRS-SLA

Set the service level agreement for the ticket.

X-OTRS-State

Set the state for the ticket.

X-OTRS-State-PendingTime

Set the pending time for the ticket (you should sent a pending state via X-OTRS-State). You can specify absolute dates like 2010-11-20 00:00:00 or relative dates, based on the arrival time of the email. Use the form + $Number $Unit, where $Unit can be s (seconds), m (minutes), h (hours) or d (days). Only one unit can be specified. Examples of valid settings: +50s (pending in 50 seconds), +30m (30 minutes), +12d (12 days).

Note

Settings like +1d 12h are not possible. You can specify +36h instead.

X-OTRS-Title

Set the title for the ticket.

X-OTRS-Type

Set the type for the ticket.

Warning

These headers must be manually injected into the mail by means not provided for by OTRS. OTRS only accepts X-OTRS headers from trusted sources.

See also

The Mail Account Settings defines the trust level.

Negate

If checked, the condition will use the negate search term.

Set Email Headers

Postmaster Filter Settings - Set Email Headers

In this section you can choose the actions that are triggered if the filter rules match.

Set email header … with value

Select an X-OTRS header from the first drop-down list, and add a value to the second field that should be set as value of the selected X-OTRS header.

See also

The X-OTRS headers are already described above.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

PostMaster Mail Accounts

Just as a company doesn’t just have one department which receives traditional mail, your service desk will also serve multiple teams. Each team can have its physical email mailbox.

OTRS eases setup for email mailboxes. OTRS manages polling one or multiple email mailboxes of any internet standard type.

Use this screen to add mail accounts to the system. The mail account management screen is available in the PostMaster Mail Accounts module of the Communication & Notifications group.

Mail Account Management Screen

Warning

When fetching mail, OTRS deletes the mail from the POP or IMAP server. There is no option to also keep a copy on the server. If you want to retain a copy on the server, you should create forwarding rules on your mail server. Please consult your mail server documentation for details.

Note

If you choose IMAP, you can specify a folder for collection. Selective dispatching of mails is then possible.

All data for the mail accounts are saved in the OTRS database. The bin/otrs.Console.pl Maint::PostMaster::MailAccountFetch command uses the settings in the database and fetches the mail. You can execute it manually to check if all your mail settings are working properly.

On a default installation, the mail is fetched every 10 minutes when the OTRS daemon is running.

Manage Mail Accounts

To add a mail account:

Click on the Add Mail Account button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Mail Account Screen

To edit a mail account:

Click on a mail account in the list of mail accounts.

Modify the fields.

Click on the Save or Save and finish button.

Edit Mail Account Screen

To delete a mail account:

Click on the trash icon in the list of mail accounts.

Click on the Confirm button.

Delete Mail Account Screen

Note

If several mail accounts are added to the system, a filter box is useful to find a particular mail account by just typing to filter.

Mail Account Settings

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

Type *

There are different kind of protocols that are used for fetching mail. The following protocols are supported:

IMAP

IMAPS

IMAPTLS

POP3

POP3S

POP3TLS

Username *

The username of the mail account.

Password *

The password of the mail account.

Note

Only regular password authentication is supported. For advanced OAuth2 support and in case you are an OTRS customer, please raise a support ticket in the OTRS customer portal.

Host *

The host name of the mail account. Specify how the current article subject should be dealt with. The following methods are available:

IMAP Folder

The folder in the mail account to be fetched. Other folders remain untouched.

Trusted

If Yes is selected, any X-OTRS headers attached to an incoming message are evaluated and executed. Because the X-OTRS header can execute some actions in the ticket system, you should set this option to Yes only for known senders.

See also

The X-OTRS headers are explained in the filter conditions of Postmaster Filters.

Dispatching

The distribution of incoming messages can be controlled if they need to be sorted by queue or by the content of the To: field.

Dispatching by email To: field

The system checks if a queue is linked with the address in the To: field of the incoming mail. You can link an address to a queue in the Email Addresses screen. If the address in the To: field is linked with a queue, the new message will be sorted into the linked queue. If no link is found between the address in the To: field and any queue, then the message flows into the Raw queue in the system, which is the postmaster default queue after a default installation.

See also

The postmaster default queue can be changed in system configuration setting PostmasterDefaultQueue.

Dispatching by selected Queue

All incoming messages will be sorted into the specified queue. The address where the mail was sent to is disregarded in this case.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Setting up Incoming Emails

For incoming emails, OTRS can be configured in a variety of ways.The best option to do this might depend on your specific circumstances.

Receiving Mails via Local MDA

Using a local mail transfer agent (MTA) to receive mails directly is the recommended option. It provides near to real time mail delivery and the setup is more stable than when you poll your mails via IMAP(S) or POP(S). Authentication is also no longer an issue.

Redirecting mails to another address

Your current mail server must relay the emails to the local MTA.

SMTP Transport

An alternative router is setup on the receiving MTA to deliver mails from specific users to an external SMTP server.

In both cases, the use of Procmail is required as the mail delivery agent (MDA), as well as the proper $HOME setup for the user otrs on your system. An example file .procmailrc.dist can be used directly without modification. Just remove the .dist ending. Mails sent to the local otrs user are then piped to the console command for processing.

Warning

Please note that all “push” mail transferred directly to the otrs user (i.e. via the console command) is always trusted. This means X-OTRS headers in emails can and will affect the distribution of mails and setting of ticket properties. This includes the X-OTRS-FollowUp headers.

For more information, please read the Postmaster Filters chapter.

Note

Errors will send the mail to the directory var/spool/problem-email.

Read the Postfix documentation or the Exim4 documentation for more information on the setup.

Note

In case you are an OTRS customer, you can configure relaying by raising a support ticket in the OTRS customer portal.

Receiving Mails via External Email Provider

Alternatively, it is also possible to use an external email provider for incoming emails.

Note

Only regular password authentication is supported. For advanced OAuth2 support and in case you are an OTRS customer, please raise a support ticket in the OTRS customer portal.

To setup the system to use Office 365 as email provider:

Read the POP and IMAP email settings for Outlook chapter in the official documentation.

Fill the form with the following data:

Type: select the desired protocol

Username: your email address

Password: your email password

Host: outlook.office365.com

Warning

On October 13th, 2020 Microsoft stops supporting and retires basic authentication for POP3 and IMAP. Only OAuth2 can be used for authentication. For more information, please read the original blog post.

To setup the system to use Gmail as email provider:

Read the Check Gmail through other email platforms chapter in the official documentation.

Fill the form with the following data:

Type: select the desired protocol

Username: your email address

Password: your email password

Host: imap.gmail.com

To setup the system to use another external email provider:

Read the official documentation of the external provider.

Fill the form with the following data:

Type: select the desired protocol

Username: your email address

Password: your email password

Host: the POP3 or IMAP address of the external provider

See also

You can find detailed instructions in the Email Addresses chapter about how to configure outgoing emails.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

S/MIME Certificates

Faculty and staff have key roles safeguarding critical information by implementing information security policies, standards, and controls. Safe email communication is a vital part of protecting this communication.

OTRS empowers you to encrypt communications where needed by means of S/MIME Certificates or PGP Keys.

Note

Setup of services and software required for encryption are not covered here because of independence to this software.

Use this screen to add S/MIME certificates to the system. The S/MIME management screen is available in the S/MIME Certificates module of the Communication & Notifications group.

S/MIME Management Screen

Manage S/MIME Certificates

Note

To be able to use S/MIME certificates in OTRS, you have to activate its setting first.

Enable S/MIME Support

To add an S/MIME certificate:

Click on the Add Certificate button in the left sidebar.

Click on Browse… button to open the file dialog.

Select an S/MIME certificate from the file system.

Click on the Add button.

Add S/MIME Certificate Screen

Note

Only non binary keys contain ASCII (Base64) armored data started with a ----- BEGIN CERTIFICATE ----- line can be uploaded which are most commonly key.pem or root.crt. Conversion of other formats like cert.p7b must be done using OpenSSL.

To add a private key:

Click on the Add Private Key button in the left sidebar.

Click on Browse… button to open the file dialog.

Select a private key from the file system.

Click on the Submit button.

Add S/MIME Private Key Screen

To delete an S/MIME certificate:

Click on the trash icon in the list of S/MIME certificates.

Click on the Confirm button.

Delete S/MIME Certificate Screen

Note

If several S/MIME certificates are added to the system, use the filter box to find a particular S/MIME certificate by just typing the name to filter.

To adjust the S/MIME certificate settings of the system:

Go to System Configuration screen.

Navigate to Core → Crypt → SMIME in the navigation tree.

Review the settings.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Social Media Profiles

Note

This feature is available only for managed customers. A special contract is needed to use this feature.

Social media profile integration makes it possible to connect OTRS with social media channels. This allows agents to send and receive messages and communicate with social media users like with customer users. This feature stores the messages in the tickets as articles.

Use this screen to add social media profiles to the system. The social media profile management screen is available in the Social Media Profiles module of the Communication & Notifications group.

Profile Configuration Management Screen

Manage Facebook Profiles

To add a Facebook profile:

Select Facebook from the Actions widget in the left sidebar.

Fill in the required fields in the General widget.

General Widget

Name *

The name of this resource. Must be unique and only accept alphabetic and numeric characters. The name will be displayed in the overview table.

Description

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Click on the Save button and follow the instruction steps. You have to save the entered data between all steps.

Read the instructions and create the necessary Facebook resources.

Step 1: Setup Facebook Developer Account And App

Add the access keys.

Step 2: Access Keys

App ID *

Paste the “App ID”. This is located in basic settings of the Facebook App.

App Secret *

Reveal and paste the “App Secret”. This is located in basic settings of the Facebook App.

Access Token *

Paste the generated token from your Facebook App.

Click on the Check Access button to test the configuration.

Click on the Check Permissions button to test the permissions.

Step 3: Access Permission Check

Setup Facebook webhooks for the app.

Step 4: Setup Webhook

Select the Use production mode checkbox if the Facebook app is ready for use in production.

Click on the Verify webhook setup button to test the configuration.

Step 5: Webhook Verification

Select a target queue and add automatic response for the messages from Facebook.

Step 6: Settings For Inbound Communication

Target Queue *

Select the queue used for incoming entities.

Auto Response

Add an automatic response used for incoming direct messages. Click on the checkbox to enable it.

Click on the Save or Save and Finish button.

Warning

Social media profiles can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a Facebook profile:

Click on a Facebook profile in the list of social media profiles.

Modify the fields. Use the Previous Step and the Next Step buttons to navigate between the steps.

Click on the Save or Save and finish button.

Note

If several social media profiles are added to the system, use the filter box to find a particular social media profile by just typing the name to filter.

Manage LinkedIn Profiles

To add a LinkedIn profile:

Select LinkedIn from the Actions widget in the left sidebar.

Fill in the required fields in the General widget.

General Widget

Name *

The name of this resource. Must be unique and only accept alphabetic and numeric characters. The name will be displayed in the overview table.

Description

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Click on the Save button and follow the instruction steps. You have to save the entered data between all steps.

Read the instructions and create the necessary LinkedIn resources.

Step 1: Setup LinkedIn App

Configure the application.

Step 2: Authentication Setup

Client ID *

Paste the “Client ID”. This is located in auth settings of the LinkedIn App.

Client Secret *

Reveal and paste the “Client Secret”. This is located in auth settings of the LinkedIn App.

Organization ID *

You should go to the assigned LinkedIn organization page (as an administrator) and then you can get the organization ID from the current URL in the browser: “https://www.linkedin.com/company/{OrganizationID}/admin/“.

Click on the Save button to test the configuration.

Click on the Approve Application button to test the permissions.

Once redirected, you will be presented with a LinkedIn’s authentication screen. This identifies your application and outlines the particular member permissions that your application is requesting. By providing valid LinkedIn credentials and clicking “Allow“, you approves the application’s request to access the member data and interact with LinkedIn on their behalf. This approval instructs LinkedIn to redirect you to the callback URL that you defined before.

Step 3: Request an Authorization Code and generate Access Token

The expire date for the refresh token. The refresh token is used to generate a new access token until the expire date is reached. However, LinkedIn reserves the right to revoke Refresh Tokens or Access Tokens at any time due to technical or policy reasons. In both situations you need to do the authentication step again and afterwards you can generate a new access token and refresh token.

Note

For security reasons, the authorization code expires in one year. A notification will be displayed in the administrator interface 1 month before the refresh token will expire with a link to the profile management.

Click on the Check Access button to fetch all needed information from LinkedIn.

Step 4: Access Permission Check

Click on the Save or Save and Finish button.

Warning

Social media profiles can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a LinkedIn profile:

Click on a LinkedIn profile in the list of social media profiles.

Modify the fields. Use the Previous Step and the Next Step buttons to navigate between the steps.

Click on the Save or Save and finish button.

Note

If several social media profiles are added to the system, use the filter box to find a particular social media profile by just typing the name to filter.

Manage Twitter Profiles

To add a Twitter profile:

Select Twitter from the Actions widget in the left sidebar.

Fill in the required fields in the General widget.

General Widget

Name *

The name of this resource. Must be unique and only accept alphabetic and numeric characters. The name will be displayed in the overview table.

Description

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Click on the Save button and follow the instruction steps. You have to save the entered data between all steps.

Read the instructions and create the necessary Twitter resources.

Step 1: Setup Twitter Developer Account

Add the Twitter app name.

Step 2: Twitter App Name

Twitter App Name *

Enter a Twitter app name.

Add the consumer API keys.

Step 3: Access Permissions

Consumer Key *

Copy and paste your consumer key from the consumer API key section of the Twitter app.

Consumer Secret *

Copy and paste your consumer secret from the consumer API key section of the Twitter app.

Add the access token.

Step 4: Access Token

Access Token *

Copy and paste your access token from the Twitter app.

Access Token Secret *

Copy and paste your access token secret from the Twitter app.

Click on the Verify Credentials button to test the configuration.

Step 5: Credentials Verification

Select a target queue and add automatic response for the messages from Twitter.

Step 6: Incoming Settings

Target Queue *

Select the queue used for incoming entities.

Auto Response

Add an automatic response used for incoming direct messages. Click on the checkbox to enable it.

Click on the Save and Finish button.

Warning

Social media profiles can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a Twitter profile:

Click on a Twitter profile in the list of social media profiles.

Modify the fields. Use the Previous Step and the Next Step buttons to navigate between the steps.

Click on the Save or Save and finish button.

Note

If several social media profiles are added to the system, use the filter box to find a particular social media profile by just typing the name to filter.

Limit User Access to Profiles

In case you would like to limit the user access to a certain social media profile, you can use the Access Control Lists (ACL).

In the following example, we restrict the access of members of the group facebook to a Facebook page profile with relevant views. This guide assumes that you have already created this group and assigned users with rw permissions to it.

To identify the profile ID:

Go to the Social Media Profiles module in the administrator interface.

Select the target profile in the list you would like to limit the access to.

Identify the ID of the current profile in the URL of the current page. In our case, the ID is 1.

...;ProfileType=Facebook;ID=1

To create an ACL:

Go to the Access Control Lists (ACL) module in the administrator interface.

Click on the Create New ACL button in the left sidebar.

Fill in the required Name field with a suitable text.

Set Validity to valid.

Click on the Save button.

To edit and deploy the ACL:

Click in the Match settings field in the Edit ACL structure widget, and select Properties.

Click in the field below Properties and select User.

Type in Group_rw in the empty box below User.

Select Negative Exact Match from the drop-down list below Group_rw and enter the name of the group in the empty field next to it. In this example this is facebook.

Click in the field Change settings and select PossibleNot.

Click in the field below PossibleNot and select Ticket.

Type in FacebookProfileID in the empty box below Ticket.

In the empty box below FacebookProfileID type in the identified value of the profile. In our case, this is 1.

ACL Rule to Limit Access to Facebook Profile

Click on the Save and finish button.

Click on the Deploy ACLs button in the left sidebar.

From now on, a user who is not member of the group facebook will no longer have access to the page profile with the ID 1 in the Facebook Page field on the corresponding screens.

In case of a Twitter account, use a different group name (e.g. twitter) and use TwitterProfileID for the field name in step 7 of the ACL creation.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Ticket Notifications

Streamlining communication can save hours of labor and prevent mistakes. Sending certain messages at pre-defined stages of communication not only keeps the customer and agents informed about specific events, but it can also aid your agents by programmatically doing automated updates to the customer.

The flexible OTRS is an industry leader in email communication and offers you complete control of notifications based on any event in your system.

Use this screen to add ticket notifications to the system. In a fresh OTRS installation several ticket notifications are already added by default. The ticket notification management screen is available in the Ticket Notifications module of the Communication & Notifications group.

Ticket Notification Management Screen

Manage Ticket Notifications

To add a ticket notification:

Click on the Add Notification button in the left sidebar.

Fill in the required fields as explained in Ticket Notification Settings.

Click on the Save button.

To edit a ticket notification:

Click on a ticket notification in the list of ticket notifications.

Modify the fields as explained in Ticket Notification Settings.

Click on the Save or Save and finish button.

To delete a ticket notification:

Click on the trash icon in the list of ticket notifications.

Click on the Confirm button.

Delete Ticket Notification Screen

To export all ticket notifications:

Click on the Export Notifications button in the left sidebar.

Choose a location in your computer to save the Export_Notification.yml file.

Warning

Certain settings are exported as numeric IDs and will break when importing to a system where these settings do not appear or reference other named items.

To import ticket notifications:

Click on the Browse… button in the left sidebar.

Select a previously exported .yml file.

Click on the Overwrite existing notifications? checkbox, if you would like to overwrite the existing notifications.

Click on the Import Notification configuration button.

Ticket Notification Settings

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

See also

For an example, see a default ticket notification which is included in a fresh OTRS installation.

Basic Ticket Notification Settings

Ticket Notification Settings - Basic

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Show in agent preferences

Define how the notification should be displayed in agent preferences. The following options are available:

No

The notification won’t be displayed in agent preferences. The notification is sent to all appropriate agents by the defined method.

Yes

The notification will be displayed in agent preferences for selection. The agents may opt-in or opt-out.

Yes, but require at least one active notification method.

The notification will be displayed in agent preferences, but require at least one active notification method. This is annotated by an asterisk next to the name.

Personal Ticket Notification Settings

Available for agent in groups

The notification will only appear to agents that belong to the selected groups. If no group is selected, it is available for all agents.

Agent preferences tooltip

This message will be shown on the agent preferences screen as a tooltip for this notification.

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.

Events

Ticket Notification Settings - Events

Event

Here you can choose which events will trigger this notification. An additional ticket filter can be applied below to only send for tickets with certain criteria.

Ticket Filter 1

Ticket Notification Settings - Ticket Filter

This widget can optionally be used to narrow the list of tickets by matching configured values:

Note

The values in this list can grow as your system grows. The more Dynamic Fields are and features you have in your system, the longer the list will be.

State

Filter for a state of the ticket.

Priority

Filter for a priority of the ticket.

Queue

Filter for a queue in which the ticket is located.

Lock

Filter for a lock state of the ticket.

Customer ID

Filter for a customer ID of the ticket.

Customer User ID

Filter for a customer user ID of the ticket.

Dynamic Fields

Filter for some dynamic fields added to the system. For the complete list of dynamic fields see the Dynamic Fields chapter.

Article Filter 1

Ticket Notification Settings - Article Filter

Note

This widget works only if ArticleCreate or ArticleSend is selected in the Events widget.

Article sender type

Filter for the sender type of the ticket. Possible values are agent, system or customer.

Customer visibility

Filter for the customer visibility. Possible values are Invisible to customer or Visible to customer.

Communication channel

Filter for the communication channel. Possible values are Chat, Email, OTRS, Phone or SMS.

Include attachments to notification

If Yes is selected, attachments will be included to notification. Selecting No will not use this feature.

Attachment Name

Filter for attachment name.

Bcc

Filter for blind carbon copy field.

Body

Filter for body text.

Cc

Filter for carbon copy field.

From

Filter for the sender field.

Subject

Filter for the subject field.

To

Filter for the main recipients field.

SMS phone number

Filter for an SMS phone number.

SMS text

Filter for the SMS text.

SMS transaction number

Filter for an SMS transaction number.

Ticket Notification Recipients

Ticket Notification Settings - Recipients

Send to

Select which agents should receive the notifications. Possible values are:

Agent who created the ticket

Agent who is responsible for the ticket

Agent who owns the ticket

All agents subscribed to both the ticket’s queue and service

All agents subscribed to the ticket’s queue

All agents subscribed to the ticket’s service

All agents watching the ticket

All agents with write permission for the ticket

All recipients of the first article

All recipients of the last article

Customer user of the ticket

Send to these agents

One or more agents can be selected who should receive the notifications.

Send to all group members (agents only)

One or more groups can be selected whom agents should receive the notifications.

Send to all role members

One or more roles can be selected whom agents should receive the notifications.

Send on out of office

If this option is checked, the notification will be sent even if the agent is currently out of office.

Once per day

Notify users just once per day about a single ticket using a selected transport. If this is the first notification about a ticket, then the notification will be sent. If a notification was already sent before and this option is checked, the OTRS daemon will check the time the last notification was sent. If there was no notification sent in the last 24 hours, the notification will be sent again.

Ticket Notification Methods

Ticket Notification Settings - Notification Methods

Enable this notification method

Enable or disable this notification method. A notification method can be email, web view or SMS.

Note

To use the SMS notification method, Cloud Services need to be enabled.

Additional recipient email addresses

Additional recipients can be added here. Use comma or semicolon to separate the email addresses.

Article visible for customer

An article will be created if the notification is sent to the customer or an additional email address.

Email template

Select which email template should be used for the notification.

Note

Additional email templates can be added by placing a .tt file into the folder <OTRS_Home>/Kernel/Output/HTML/Templates/Standard/NotificationEvent/Email/. See the existing email templates for an example.

Enable email security

Checking this option will encrypt the notification email.

Note

To use this feature, PGP Keys or S/MIME Certificates need to be enabled.

Email security level

If Enable email security is checked, then this setting is activated. The following options are available:

PGP sign only

Sign only the notification email with PGP key. If no PGP keys have been added to the system, this option is not visible.

PGP encrypt only

Encrypt only the notification email with PGP key. If no PGP keys have been added to the system, this option is not visible.

PGP sign and encrypt

Sign and encrypt the notification email with PGP key. If no PGP keys have been added to the system, this option is not visible.

SMIME sign only

Sign only the notification email with S/MIME certificate. If no S/MIME certificates have been added to the system, this option is not visible.

SMIME encrypt only

Encrypt only the notification email with S/MIME certificate. If no S/MIME certificates have been added to the system, this option is not visible.

SMIME sign and encrypt

Sign and encrypt the notification email with S/MIME certificate. If no S/MIME certificates have been added to the system, this option is not visible.

Note

To use this feature, PGP Keys or S/MIME Certificates need to be enabled.

If signing key/certificate is missing

Select the method, that should be used if signing key or certificate is missing.

If encryption key/certificate is missing:

Select the method, that should be used if encryption key or certificate is missing.

Notification Text

Ticket Notification Settings - Notification Text

The main content of a notification can be added for each languages with localized subject and body text. It is also possible to define static text content mixed with OTRS smart tags.

Subject *

The localized subject for a specific language.

Text *

The localized body text for a specific language.

Add new notification language

Select which languages should be added to create localized notifications. The language of the customer or agent will be used as found in the customer and agent preferences. Secondarily, the system default language will be chosen. The fall back will always be English.

Warning

Deleting a language from the DefaultUsedLanguages setting that already has a notification text here will make the notification text unusable. If a language is not present or enabled on the system, the corresponding notification text could be deleted if it is not needed anymore.

Ticket Notification Variables

Using variables in the text makes it possible to personalize messages. Variables, known as OTRS tags, are replaced by OTRS when generating the message. Find a list of available tags stems for this resource at the bottom of both add and edit screens.

Ticket Notification Variables

For example, the variable <OTRS_TICKET_TicketNumber> expands to the ticket number allowing a template to include something like the following.

Ticket#<OTRS_TICKET_TicketNumber>

This tag expands, for example to:

Ticket#2018101042000012

The values of the following variables are translated based on the chosen language of the customer user.

OTRSTicket_Type
OTRSTicket_State
OTRSTicket_StateType
OTRSTicket_Lock
OTRSTicket_Priority

If the language is not supported the default language is applied.

1(1,2)

Use of regular expressions as a filter do not work here.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Users, Groups & Roles

Simple and complex organizations need a flexible way to control access to their service desk. Access, resources, and permissions must be orchestrated so that, the users and customers have access to the resources they need and their data is protected as needed by the system.

OTRS provides powerful tools for this purpose and their use is described in the following chapter.

Contents

Agents

Manage Agents

Agent Settings

Agent Back End Sources

Agent Authentication Back End

Agent Synchronization Back End

Agent Configuration Options

Agents ↔ Groups

Manage Agents ↔ Groups Relations

Agents ↔ Groups Relations Reference

Agents ↔ Roles

Manage Agents ↔ Roles Relations

Customers

Manage Customers

Customer Settings

Customers ↔ Groups

Manage Customers ↔ Groups Relations

Customers ↔ Groups Relations Reference

Customer Users

Manage Customer Users

Customer User Settings

Customer User Back Ends

Database

LDAP

Multiple Customer User Back Ends

Customer User Data in Dynamic Fields

Customer Users ↔ Customers

Manage Customer Users ↔ Customers Relations

Customer Users ↔ Groups

Manage Customer Users ↔ Groups Relations

Customer Users ↔ Groups Relations Reference

Customer Users ↔ Services

Manage Customers Users ↔ Services Relations

Manage Default Services

Groups

Manage Groups

Group Settings

Default Groups

Roles

Manage Roles

Role Settings

Roles ↔ Groups

Manage Roles ↔ Groups Relations

Roles ↔ Groups Relations Reference

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Agents

Agent and access management for your service desk should be easy. Flexibility in adding, editing, invalidating access and a quick overview of which permissions a user has will help you maintain a clean permissions system and record of your setup in OTRS.

OTRS aids you giving you the power to manage agents within OTRS across multiple back ends. OTRS can use up-to ten back end sources, even marking some as read-only. Managing user settings centrally, an administrator can quickly invalidate a compromised account or set an account to out-of-office in case of an unexpected illness.

Use this screen to add agents to the system. A fresh OTRS installation contains an agent with administrator privileges by default. The agent management screen is available in the Agents module of the Users, Groups & Roles group.

Agent Management Screen

Warning

The superuser account username is root@localhost. Don’t use the superuser account to work with OTRS! Create new agents and work with these accounts instead. One of the adverse effects is that Access Control Lists (ACL) will not have an effect on this user.

Manage Agents

Note

Adding or editing an agent is possible only by using database back end. Using explicitly external directory services like LDAP and, based on configuration, some databases are read-only. Personal preferences like out-of-office can still be set.

To add an agent:

Click on the Add Agent button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Agent Screen

Warning

Agents can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit an agent:

Click on an agent in the list of agents.

Modify the fields.

Click on the Save or Save and finish button.

Edit Agent Screen

It is also possible to edit the agent personal preferences. To do this, click on the Edit personal preferences for this agent button in the left sidebar of the Edit Agent screen.

To find an agent:

Enter a search term to the search box in the left sidebar.

Click on the magnifying glass icon in the right part of the field or hit an Enter.

Note

If several agents are added to the system, use the search box to find a particular agent. Only the first 1000 agents are listed by default.

The agent permissions can be controlled by adding an agent to Groups or Roles. This can result a complex matrix of permissions. The effective permissions for an agent can be checked in the bottom of the Edit Agent screen. If roles (recommended) are used, this screen will reflect the combined permissions as dictated by the roles.

Effective Permissions for Agent Widget

Agent Settings

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

Note

These are the default fields available for the internal database table.

Title or salutation

Some name prefix can be added here like Mr., Dr., Jr., etc.

Firstname *

The first name of the agent.

Lastname *

The last name of the agent.

See also

The agent display name can be set via the system configuration setting FirstnameLastnameOrder.

Username *

The username of the agent to login to the system.

Password

The password of the agent. This will be auto-generated if left empty.

Email *

The email address of the agent.

Note

The email syntax and validity of an available MX record could prevent you from submitting this form. For some systems it may be acceptable to turn off these checks. See the Agent Configuration Options.

Mobile

The mobile phone number of the agent.

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.

Agent Back End Sources

Agents can be read and synchronized from an Active Directory® or LDAP server.

In case of using On-Premise system or ((OTRS)) Community Edition, you may use the following section to configure your system.

Note

The following configurations are taken care of by the Customer Solution Team in OTRS. Please contact the Customer Solution Team via support@otrs.com or in the OTRS Portal.

Agent Authentication Back End

The users table houses your agent data per default. You may attach a directory server (LDAP/Active Directory) to your installation for authentication. To achieve this copy the following block from the Defaults.pm and paste it into the Config.pm.

# This is an example configuration for an LDAP auth. backend.
# (take care that Net::LDAP is installed!)
#    $Self->{AuthModule} = 'Kernel::System::Auth::LDAP';
#    $Self->{'AuthModule::LDAP::Host'} = 'ldap.example.com';
#    $Self->{'AuthModule::LDAP::BaseDN'} = 'dc=example,dc=com';
#    $Self->{'AuthModule::LDAP::UID'} = 'uid';

# Check if the user is allowed to auth in a posixGroup
# (e. g. user needs to be in a group xyz to use otrs)
#    $Self->{'AuthModule::LDAP::GroupDN'} = 'cn=otrsallow,ou=posixGroups,dc=example,dc=com';
#    $Self->{'AuthModule::LDAP::AccessAttr'} = 'memberUid';
# for ldap posixGroups objectclass (just uid)
#    $Self->{'AuthModule::LDAP::UserAttr'} = 'UID';
# for non ldap posixGroups objectclass (with full user dn)
#    $Self->{'AuthModule::LDAP::UserAttr'} = 'DN';

# The following is valid but would only be necessary if the
# anonymous user do NOT have permission to read from the LDAP tree
#    $Self->{'AuthModule::LDAP::SearchUserDN'} = '';
#    $Self->{'AuthModule::LDAP::SearchUserPw'} = '';

# in case you want to add always one filter to each ldap query, use
# this option. e. g. AlwaysFilter => '(mail=*)' or AlwaysFilter => '(objectclass=user)'
# or if you want to filter with a locigal OR-Expression, like AlwaysFilter => '(|(mail=*abc.com)(mail=*xyz.com))'
#    $Self->{'AuthModule::LDAP::AlwaysFilter'} = '';

# in case you want to add a suffix to each login name, then
# you can use this option. e. g. user just want to use user but
# in your ldap directory exists user@domain.
#    $Self->{'AuthModule::LDAP::UserSuffix'} = '@domain.com';

# In case you want to convert all given usernames to lower letters you
# should activate this option. It might be helpful if databases are
# in use that do not distinguish selects for upper and lower case letters
# (Oracle, postgresql). User might be synched twice, if this option
# is not in use.
#    $Self->{'AuthModule::LDAP::UserLowerCase'} = 0;

# In case you need to use OTRS in iso-charset, you can define this
# by using this option (converts utf-8 data from LDAP to iso).
#    $Self->{'AuthModule::LDAP::Charset'} = 'iso-8859-1';

# Net::LDAP new params (if needed - for more info see perldoc Net::LDAP)
#    $Self->{'AuthModule::LDAP::Params'} = {
#        port    => 389,
#        timeout => 120,
#        async   => 0,
#        version => 3,
#    };

# Die if backend can't work, e. g. can't connect to server.
#    $Self->{'AuthModule::LDAP::Die'} = 1;

You should uncomment the following settings as a minimum.

The minimum required to connect to a directory server is:

$Self->{AuthModule} = 'Kernel::System::Auth::LDAP';
$Self->{'AuthModule::LDAP::Host'} = 'ldap.example.com';
$Self->{'AuthModule::LDAP::BaseDN'} = 'dc=example,dc=com';
$Self->{'AuthModule::LDAP::UID'} = 'uid';

Host

The DNS name or IP of your directory server.

BaseDN

The starting point in your directory tree.

UID

The attribute used for login and identification.

Note

This is sAMAccountName for an Active Directory.

To use multiple back ends, add an additional section of the example code to the Config.pm. Please make sure to add a numeric value [1-9] to all settings to indicate which settings belong to which back end.

### Backend One
$Self->{AuthModule} = 'Kernel::System::Auth::LDAP';
$Self->{'AuthModule::LDAP::Host'} = 'ldap.example.com';
$Self->{'AuthModule::LDAP::BaseDN'} = 'dc=example,dc=com';
$Self->{'AuthModule::LDAP::UID'} = 'uid';

### Backend Two
$Self->{AuthModule1} = 'Kernel::System::Auth::LDAP';
$Self->{'AuthModule::LDAP::Host1'} = 'ldap.example.com';
$Self->{'AuthModule::LDAP::BaseDN1'} = 'dc=example,dc=com';
$Self->{'AuthModule::LDAP::UID1'} = 'uid';

Warning

All back ends will are used in succession. The UID must be unique to all back ends, otherwise some side effects may occur.

To synchronize with a specific directory server (see Agent User Data below), you must add the appropriate setting to your Agent Authentication Back End. To achieve this copy the following block from the Defaults.pm and paste it into the Config.pm.

$Self->{'AuthModule::UseSyncBackend'} = 'AuthSyncBackend';

To use multiple back ends, add an additional section of the example code to the Config.pm. Please make sure to add a numeric value [1-9] to all settings to indicate which settings belong to which back end.

$Self->{'AuthModule::UseSyncBackend1'} = 'AuthSyncBackend1';

Reuse of an Agent Synchronization Back End is also possible.

$Self->{'AuthModule::UseSyncBackend1'} = 'AuthSyncBackend';

Agent Synchronization Back End

It is advisable to synchronize the agent data so that agents need not be manually added to the users table prior to authorization. Additionally, groups and roles can be added automatically using security objects of the directory server.

Agent User Data

Syncing user data upon login. To achieve this copy the following block from the Defaults.pm and paste it into the Config.pm.

# This is an example configuration for an LDAP auth sync. backend.
# (take care that Net::LDAP is installed!)
#    $Self->{AuthSyncModule} = 'Kernel::System::Auth::Sync::LDAP';
#    $Self->{'AuthSyncModule::LDAP::Host'} = 'ldap.example.com';
#    $Self->{'AuthSyncModule::LDAP::BaseDN'} = 'dc=example,dc=com';
#    $Self->{'AuthSyncModule::LDAP::UID'} = 'uid';

# The following is valid but would only be necessary if the
# anonymous user do NOT have permission to read from the LDAP tree
#    $Self->{'AuthSyncModule::LDAP::SearchUserDN'} = '';
#    $Self->{'AuthSyncModule::LDAP::SearchUserPw'} = '';

# in case you want to add always one filter to each ldap query, use
# this option. e. g. AlwaysFilter => '(mail=*)' or AlwaysFilter => '(objectclass=user)'
# or if you want to filter with a logical OR-Expression, like AlwaysFilter => '(|(mail=*abc.com)(mail=*xyz.com))'
#    $Self->{'AuthSyncModule::LDAP::AlwaysFilter'} = '';

# AuthSyncModule::LDAP::UserSyncMap
# (map if agent should create/synced from LDAP to DB after successful login)
# you may specify LDAP-Fields as either
#  * list, which will check each field. first existing will be picked ( ["givenName","cn","_empty"] )
#  * name of an LDAP-Field (may return empty strings) ("givenName")
#  * fixed strings, prefixed with an underscore: "_test", which will always return this fixed string
#    $Self->{'AuthSyncModule::LDAP::UserSyncMap'} = {
#        # DB -> LDAP
#        UserFirstname => 'givenName',
#        UserLastname  => 'sn',
#        UserEmail     => 'mail',
#    };

The minimum required to connect to a directory server is:

$Self->{AuthSyncModule} = 'Kernel::System::Auth::Sync::LDAP';
$Self->{'AuthSyncModule::LDAP::Host'} = 'ldap.example.com';
$Self->{'AuthSyncModule::LDAP::BaseDN'} = 'dc=example,dc=com';
$Self->{'AuthSyncModule::LDAP::UID'} = 'uid';

Host

The DNS name or IP of your directory server.

BaseDN

The starting point in your directory tree.

UID

The attribute used for login and identification.

Note

This is sAMAccountName for an Active Directory.

Note

Multiple Agent Synchronization Back End blocks can be used. Please make sure to add a numeric value [1-9] to all settings to indicate which settings belong to which back end. Each AuthSyncModule must be explicitly used in an Agent Authentication Back End.

Agent Group Data

It is possible to use security objects to synchronize users to OTRS groups. To achieve this copy the following block from the Defaults.pm and paste it into the Config.pm.

Note

Groups must be available in OTRS to use this feature.

Agent Role Data

It is possible to use security objects to synchronize users to OTRS roles. To achieve this copy the following block from the Defaults.pm and paste it into the Config.pm.

Note

Roles must be available in OTRS to use this feature.

Agent Configuration Options

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Agents ↔ Groups

Efficient and straightforward management of permissions is essential in a growing business. Easy assignment of a particular user to a group for quick access, or to remove access, to resources is a must in every case.

The OTRS interface provides you both with the possibility to manage an agent’s access to one or more particular groups. As well, you can change multiple users access to any one group, efficiently and elegantly.

Use this screen to add one or more agents to one or more groups. To use this function, at least one agent and one group need to have been added to the system. The management screen is available in the Agents ↔ Groups module of the Users, Groups & Roles group.

Manage Agent-Group Relations

Manage Agents ↔ Groups Relations

To assign some groups to an agent:

Click on an agent in the Agents column.

Select the permissions you would like to connect the agent to groups with.

Click on the Save or Save and finish button.

Change Group Relations for Agent

To assign some agents to a group:

Click on a group in the Groups column.

Select the permissions you would like to connect the group to agents with.

Click on the Save or Save and finish button.

Change Agent Relations for Group

Note

If several agents or groups are added to the system, use the filter box to find a particular agent or group by just typing the name to filter.

Multiple agents or groups can be assigned in both screens at the same time. Additionally clicking on an agent or clicking on a group in the relations screen will open the Edit Agent screen or the Edit Group screen accordingly.

Warning

Accessing an agent or a group provides no back link to the relations screen.

Agents ↔ Groups Relations Reference

When assigning an agent to a group or vice versa, several permissions can be set as connection between an agent and a group. The following permissions are available by default:

ro

Read only access to the ticket in this group/queue.

move_into

Permissions to move tickets into this group/queue.

create

Permissions to create tickets in this group/queue.

note

Permissions to add notes to tickets in this group/queue.

owner

Permissions to change the owner of tickets in this group/queue.

priority

Permissions to change the ticket priority in this group/queue.

chat_owner

Agents have full rights for a chat and can accept chat requests.

chat_participant

Agents may normally participate in a chat.

chat_observer

Agents may take part silently in a chat.

rw

Full read and write access to the tickets in this group/queue.

See also

Not all available permissions are shown by default. See System::Permission setting for permissions that can be added. These additional permissions can be added:

stats

Gives access to the stats page.

bounce

Permissions to bounce an email message (with bounce button in Ticket Zoom screen).

compose

Permissions to compose an answer for a ticket.

customer

Permissions to change the customer of a ticket.

forward

Permissions to forward a message (with the forward button).

pending

Permissions to set a ticket to pending.

phone

Permissions to add a phone call to a ticket.

responsible

Permissions to change the responsible agent for a ticket.

Note

By setting a checkbox in the header of a column will set all the checkboxes in the selected column. By setting the checkbox in the last rw column will set all the checkboxes in the selected row.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Agents ↔ Roles

As an organization grows, groups cannot be the denominator used for processing access rights. Roles become more and more a need because a role has a special set of permissions assigned. One mustn’t give individual permissions, but the role carries the permissions built-in.

OTRS allows easy access to a predefined set of permissions via one or more roles defined. These roles are assigned easily to one or more agents, or one or more agent to a role.

Use this screen to add one or more agents to one or more roles. To use this function, at least one agent and one role need to have been added to the system. The management screen is available in the Agents ↔ Roles module of the Users, Groups & Roles group.

Manage Agent-Role Relations

Manage Agents ↔ Roles Relations

To assign some roles to an agent:

Click on an agent in the Agents column.

Select the roles you would like to the agent belongs to.

Click on the Save or Save and finish button.

Change Role Relations for Agent

To assign some agents to a role:

Click on a role in the Roles column.

Select the agents you would like to add to the role.

Click on the Save or Save and finish button.

Change Agent Relations for Role

Note

If several agents or roles are added to the system, use the filter box to find a particular agent or role by just typing the name to filter.

Multiple agents or roles can be assigned in both screens at the same time. Additionally clicking on an agent or clicking on a role in the relations screen will open the Edit Agent screen or the Edit Role screen accordingly.

Warning

Accessing an agent or a role provides no back link to the relations screen.

Note

By setting the checkbox in the header of the column Active will set all the checkboxes in the column.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Customers

Use this screen to add customer companies to the system. A fresh OTRS installation contains no customers by default. The customer management screen is available in the Customers module of the Users, Groups & Roles group.

Customer Management Screen

Manage Customers

Note

Adding or editing a customer is possible only by using database back end. Using external directory services like LDAP will disable the customer management functionality.

To add a customer:

Click on the Add Customer button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Customer Screen

Warning

Customers can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a customer:

Click on a customer in the list of customers.

Modify the fields.

Click on the Save or Save and finish button.

Edit Customer Screen

To find a customer:

Enter a search term to the search box in the left sidebar.

Click on the magnifying glass icon in the right part of the field or hit an Enter.

Note

If several customers are added to the system, use the search box to find a particular customer. Only the first 1000 customers are listed by default.

Customer Settings

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

Customer ID *

The internal name of the customer. Should contain only letters, numbers and some special characters.

Customer *

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.

Street

The street name of the customer.

Zip

The zip code of the customer.

City

The headquarter city of the customer.

Country

The country of the customer. Choose a country from the list.

URL

The web page or other URL of the customer.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

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.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Customers ↔ Groups

Your organization grows, and it’s not practical at some point to assign permissions to individual users, you need to assign the permissions to all customer users of a customer.

OTRS allows you to assign group permissions to a customer. Access works just the same as for agents, preventing a customer from modifying and viewing a request. Thus allowing the customer to focus on the results of the original communication and funneling the discussion through one ticket.

See also

Assign a single customer user to a group using Customer Users ↔ Groups.

Use this screen to add one or more customers to one or more groups. To use this function, at least one customer and one group need to have been added to the system. The management screen is available in the Customers ↔ Groups module of the Users, Groups & Roles group.

Manage Customer-Group Relations

Customer group support needs to be enabled in at least one customer user back end to use this function. For the default OTRS back end, this can be enabled in the system configuration by clicking on the Enable it here! button.

Enable Customer Group Feature

Note

To enable this feature in systems using a directory server or multiple non-default back ends, a custom configuration file needs to be placed in Kernel/Config/Files (for example named ZZZ_CustomerBackend.pm). Once activated, all customer users from this back end will require group assignment.

Warning

After making changes to the back end, the server cache will be deleted, which may cause a temporary drop in performance.

Manage Customers ↔ Groups Relations

Note

To be able to use this feature, you have to activate its setting first.

Enable Customer-Group Support

To assign some groups to a customer:

Click on a customer in the Customers column.

Select the permissions you would like to connect the customer to groups with.

Click on the Save or Save and finish button.

Change Group Relations for Customer

To assign some customers to a group:

Click on a group in the Groups column.

Select the permissions you would like to connect the group to customers with.

Click on the Save or Save and finish button.

Change Customer Relations for Group

To change customer default groups:

Click on the Edit Customer Default Groups button in the left sidebar.

Add or modify groups in setting CustomerGroupCompanyAlwaysGroups.

Deploy the modified system configurations.

CustomerGroupCompanyAlwaysGroups System Configuration Screen

These groups are automatically assigned to all customers.

Note

If several customers or groups are added to the system, use the search box to find a particular customer or use the filter box to find a particular group by just typing the name to filter.

Multiple customers or groups can be assigned in both screens at the same time. Additionally clicking on a customer or clicking on a group in the relations will open the Edit Customer screen or the Edit Group screen accordingly.

Warning

Accessing a customer or a group provides no back link to the relations screen.

Customers ↔ Groups Relations Reference

When assigning a customer to a group or vice versa, several permissions can be set as connection between a customer and a group. The following permissions are available by default:

Same Customer

Gives customer users group based access to tickets from customer users of the same customer (ticket CustomerID is a CustomerID of the customer user).

ro

Read only access to the resource.

rw

Full read and write access to the resource.

Note

By setting a checkbox in the header of a column will set all the checkboxes in the selected column.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Customer Users

A record of who your company deals with requires more information about that individual: physical location for shipping and billing purposes, as well as contact information for email and phone contact.

OTRS offers a great way to save individual information about contacts within organizations which your company serves. You can add as many personal connections into OTRS as needed.

Use this screen to add a customer user to the system. A fresh OTRS installation contains no customer users by default. The customer user management screen is available in the Customer Users module of the Users, Groups & Roles group.

Customer User Management Screen

Manage Customer Users

Warning

A customer user can only be added to the system when at least one customer exists. Create one or more Customers first.

Note

Adding or editing a customer user is possible only by using database back end. Using external directory services like LDAP will disable the customer user management functionality.

To add a customer user:

Click on the Add Customer User button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Customer User Screen

Warning

Customer users can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a customer user:

Click on a customer user in the list of customer users.

Modify the fields.

Click on the Save or Save and finish button.

Edit Customer User Screen

To find a customer user:

Enter a search term to the search box in the left sidebar.

Click on the magnifying glass icon in the right part of the field or hit an Enter.

Note

If several customer users are added to the system, use the search box to find a particular customer user. Only the first 1000 customer users are listed by default.

The customer user permissions can be controlled by adding a customer or a customer user to Groups. This can result a complex matrix of permissions. The effective permissions for a customer user can be checked in the bottom of the Edit Customer User screen.

Effective Permissions for Customer User Widget

See also

Customer Users ↔ Groups needs to be enabled to use this feature.

Customer User Settings

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

Note

These are the default fields available for the internal database table.

Title or salutation

Some name prefix can be added here like Mr., Dr., Jr., etc.

Firstname *

The first name of the customer user.

Lastname *

The last name of the customer user.

Username *

The username of the customer user to login to the system.

Password

The password of the customer user. This will be auto-generated if left empty.

Email *

The email address of the customer user.

Customer *

The customer company the customer user belongs to. Select a customer from the list of Customers.

Phone

The phone number of the customer user.

Fax

The fax number of the customer user.

Mobile

The cellphone number of the customer user.

Street

The street name of the customer.

Zip

The zip code of the customer.

City

The headquarter city of the customer.

Country

The country of the customer user.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

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.

See also

It is possible to assign multiple customers to customer users via the Customer Users ↔ Customers screen.

Customer User Back Ends

The system works with many customer user data attributes such as username, email address, phone number, etc. These attributes are displayed in both the agent and the external interface, and also used for the authentication of customer users.

Customer data used or displayed within the system is highly customizable. The user login and the email address are always needed for customer authentication.

You can use two types of customer back end: database or LDAP. If you already have another customer back end (e.g. SAP), it is possible to write a module that uses it.

The administrator interface does not support the configuration of external back ends. Administrators need to edit the file Kernel/Config.pm by copying and pasting code snippets from Kernel/Config/Defaults.pm manually in case of using On-Premise system or ((OTRS)) Community Edition.

Warning

Do not modify the file Kernel/Config/Defaults.pm, it will be overwritten after upgrading the system! Copy and paste the code snippets into Kernel/Config.pm instead.

Note

The following configurations are taken care of by the Customer Solution Team in OTRS. Please contact the Customer Solution Team via support@otrs.com or in the OTRS Portal.

Database

This is the default customer user back end for new installations. The example below shows the configuration of a database customer back end, which uses customer user data stored in the database table customer_user.

    # CustomerUser
    # (customer user database backend and settings)
    $Self->{CustomerUser} = {
        Name   => Translatable('Database Backend'),
        Module => 'Kernel::System::CustomerUser::DB',
        Params => {

            # if you want to use an external database, add the
            # required settings
#            DSN  => 'DBI:odbc:yourdsn',
#            Type => 'mssql', # only for ODBC connections
#            DSN => 'DBI:mysql:database=customerdb;host=customerdbhost',
#            User => '',
#            Password => '',
            Table => 'customer_user',
#            ForeignDB => 0,    # set this to 1 if your table does not have create_time, create_by, change_time and change_by fields

            # CaseSensitive defines if the data storage of your DBMS is case sensitive and will be
            # preconfigured within the database driver by default.
            # If the collation of your data storage differs from the default settings,
            # you can set the current behavior ( either 1 = CaseSensitive or 0 = CaseINSensitive )
            # to fit your environment.
            #
#            CaseSensitive => 0,

            # SearchCaseSensitive will control if the searches within the data storage are performed
            # case sensitively (if possible) or not. Change this option to 1, if you want to search case sensitive.
            # This can improve the performance dramatically on large databases.
            SearchCaseSensitive => 0,
        },

        # customer unique id
        CustomerKey => 'login',

        # customer #
        CustomerID    => 'customer_id',
        CustomerValid => 'valid_id',

        # The last field must always be the email address so that a valid
        #   email address like "John Doe" <john.doe@domain.com> can be constructed from the fields.
        CustomerUserListFields => [ 'first_name', 'last_name', 'email' ],

#        CustomerUserListFields => ['login', 'first_name', 'last_name', 'customer_id', 'email'],
        CustomerUserSearchFields           => [ 'login', 'first_name', 'last_name', 'customer_id' ],
        CustomerUserSearchPrefix           => '*',
        CustomerUserSearchSuffix           => '*',
        CustomerUserSearchListLimit        => 250,
        CustomerUserPostMasterSearchFields => ['email'],
        CustomerUserNameFields             => [ 'title', 'first_name', 'last_name' ],
        CustomerUserEmailUniqCheck         => 1,

#        # Configures the character for joining customer user name parts. Join single space if it is not defined.
#        # CustomerUserNameFieldsJoin => '',

#        # show now own tickets in customer panel, CompanyTickets
#        CustomerUserExcludePrimaryCustomerID => 0,
#        # generate auto logins
#        AutoLoginCreation => 0,
#        # generate auto login prefix
#        AutoLoginCreationPrefix => 'auto',
#        # admin can change customer preferences
#        AdminSetPreferences => 1,
        # use customer company support (reference to company, See CustomerCompany settings)
        CustomerCompanySupport => 1,
        # cache time to live in sec. - cache any database queries
        CacheTTL => 60 * 60 * 24,
#        # Consider this source read only.
#        ReadOnly => 1,
        Map => [

            # Info about dynamic fields:
            #
            # Dynamic Fields of type CustomerUser can be used within the mapping (see example below).
            # The given storage (third column) then can also be used within the following configurations (see above):
            # CustomerUserSearchFields, CustomerUserPostMasterSearchFields, CustomerUserListFields, CustomerUserNameFields
            #
            # Note that the columns 'frontend' and 'readonly' will be ignored for dynamic fields.

            # note: Login, Email and CustomerID needed!
            # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly, http-link-target, link class(es)
            [ 'UserTitle',        Translatable('Title or salutation'), 'title',          1, 0, 'var', '', 0, undef, undef ],
            [ 'UserFirstname',    Translatable('Firstname'),           'first_name',     1, 1, 'var', '', 0, undef, undef ],
            [ 'UserLastname',     Translatable('Lastname'),            'last_name',      1, 1, 'var', '', 0, undef, undef ],
            [ 'UserLogin',        Translatable('Username'),            'login',          1, 1, 'var', '', 0, undef, undef ],
            [ 'UserPassword',     Translatable('Password'),            'pw',             0, 0, 'var', '', 0, undef, undef ],
            [ 'UserEmail',        Translatable('Email'),               'email',          1, 1, 'var', '', 0, undef, undef ],
#            [ 'UserEmail',        Translatable('Email'),               'email',          1, 1, 'var', '[% Env("CGIHandle") %]?Action=AgentTicketCompose;ResponseID=1;TicketID=[% Data.TicketID | uri %];ArticleID=[% Data.ArticleID | uri %]', 0, '', 'AsPopup OTRSPopup_TicketAction' ],
            [ 'UserCustomerID',   Translatable('CustomerID'),          'customer_id',    0, 1, 'var', '', 0, undef, undef ],
#            [ 'UserCustomerIDs',  Translatable('CustomerIDs'),         'customer_ids',   1, 0, 'var', '', 0, undef, undef ],
            [ 'UserPhone',        Translatable('Phone'),               'phone',          1, 0, 'var', '', 0, undef, undef ],
            [ 'UserFax',          Translatable('Fax'),                 'fax',            1, 0, 'var', '', 0, undef, undef ],
            [ 'UserMobile',       Translatable('Mobile'),              'mobile',         1, 0, 'var', '', 0, undef, undef ],
            [ 'UserStreet',       Translatable('Street'),              'street',         1, 0, 'var', '', 0, undef, undef ],
            [ 'UserZip',          Translatable('Zip'),                 'zip',            1, 0, 'var', '', 0, undef, undef ],
            [ 'UserCity',         Translatable('City'),                'city',           1, 0, 'var', '', 0, undef, undef ],
            [ 'UserCountry',      Translatable('Country'),             'country',        1, 0, 'var', '', 0, undef, undef ],
            [ 'UserComment',      Translatable('Comment'),             'comments',       1, 0, 'var', '', 0, undef, undef ],
            [ 'ValidID',          Translatable('Valid'),               'valid_id',       0, 1, 'int', '', 0, undef, undef ],

            # Dynamic field example
#            [ 'DynamicField_Name_X', undef, 'Name_X', 0, 0, 'dynamic_field', undef, 0, undef, undef ],
        ],

        # default selections
        Selections => {

#            UserTitle => {
#                'Mr.' => Translatable('Mr.'),
#                'Mrs.' => Translatable('Mrs.'),
#            },
        },
    };

If you want to customize the customer user data, change the columns or add new ones to the customer_user table in the database.

For example, to add a new field for room number:

Add a new column room to table customer_user.

MySQL or MariaDB:

root> mysql -u root -p -e 'ALTER TABLE otrs.customer_user ADD room VARCHAR (250)'

PostgreSQL (from the /opt/otrs directory):

otrs> psql -c 'ALTER TABLE customer_user ADD COLUMN room varchar(250)'

Copy the $Self->{CustomerUser} section from Kernel/Config/Defaults.pm into Kernel/Config.pm.

Add the new column to the Map array.

[ 'UserRoom', 'Room', 'room', 0, 1, 'var', '', 0, undef, undef ],

You can set the HTTP link target and link class (the last two keys) to undef in map array elements, if they are not to be used. These keys add target="" and class="" attributes to the HTTP link element, respectively. They are ignored if HTTP link is not set (it is '' in this example).

Note

It is recommended to always use English words for names.

See also

Names can be translated into other languages with custom translation files. For more information, see the Custom Translation File chapter in the developer manual.

LDAP

If you have an LDAP directory with your customer user data, you can use it as the customer user back end. The example below shows the configuration of a LDAP customer user back end.

# CustomerUser
# (customer user ldap backend and settings)
    $Self->{CustomerUser} = {
        Name => 'LDAP Backend',
        Module => 'Kernel::System::CustomerUser::LDAP',
        Params => {
            # ldap host
            Host => 'bay.csuhayward.edu',
            # ldap base dn
            BaseDN => 'ou=seas,o=csuh',
            # search scope (one|sub)
            SSCOPE => 'sub',
            # The following is valid but would only be necessary if the
            # anonymous user does NOT have permission to read from the LDAP tree
            UserDN => '',
            UserPw => '',
            # in case you want to add always one filter to each ldap query, use
            # this option. e. g. AlwaysFilter => '(mail=*)' or AlwaysFilter => '(objectclass=user)'
            AlwaysFilter => '',
            # if the charset of your ldap server is iso-8859-1, use this:
#            # SourceCharset => 'iso-8859-1',
            # die if backend can't work, e. g. can't connect to server
            Die => 0,
            # Net::LDAP new params (if needed - for more info see perldoc Net::LDAP)
            Params => {
                port    => 389,
                timeout => 120,
                async   => 0,
                version => 3,
            },
        },
        # customer unique id
        CustomerKey => 'uid',
        # customer #
        CustomerID => 'mail',
        CustomerUserListFields => ['cn', 'mail'],
        CustomerUserSearchFields => ['uid', 'cn', 'mail'],
        CustomerUserSearchPrefix => '',
        CustomerUserSearchSuffix => '*',
        CustomerUserSearchListLimit => 250,
        CustomerUserPostMasterSearchFields => ['mail'],
        CustomerUserNameFields => ['givenname', 'sn'],
        # Configures the character for joining customer user name parts. Join single space if it is not defined.
        CustomerUserNameFieldsJoin => '',
        # show customer user and customer tickets in the external interface
        CustomerUserExcludePrimaryCustomerID => 0,
        # add a ldap filter for valid users (expert setting)
#        # CustomerUserValidFilter => '(!(description=gesperrt))',
        # admin can't change customer preferences
        AdminSetPreferences => 0,
        # cache time to live in sec. - cache any ldap queries
#        CacheTTL => 0,
        Map => [
            # note: Login, Email and CustomerID needed!
            # var, frontend, storage, shown (1=always,2=lite), required, storage-type, http-link, readonly, http-link-target, link class(es)
            [ 'UserTitle',       Translatable('Title or salutation'), 'title',               1, 0, 'var', '', 1, undef, undef ],
            [ 'UserFirstname',   Translatable('Firstname'),           'givenname',           1, 1, 'var', '', 1, undef, undef ],
            [ 'UserLastname',    Translatable('Lastname'),            'sn',                  1, 1, 'var', '', 1, undef, undef ],
            [ 'UserLogin',       Translatable('Username'),            'uid',                 1, 1, 'var', '', 1, undef, undef ],
            [ 'UserEmail',       Translatable('Email'),               'mail',                1, 1, 'var', '', 1, undef, undef ],
            [ 'UserCustomerID',  Translatable('CustomerID'),          'mail',                0, 1, 'var', '', 1, undef, undef ],
            # [ 'UserCustomerIDs', Translatable('CustomerIDs'),         'second_customer_ids', 1, 0, 'var', '', 1, undef, undef ],
            [ 'UserPhone',       Translatable('Phone'),               'telephonenumber',     1, 0, 'var', '', 1, undef, undef ],
            [ 'UserAddress',     Translatable('Address'),             'postaladdress',       1, 0, 'var', '', 1, undef, undef ],
            [ 'UserComment',     Translatable('Comment'),             'description',         1, 0, 'var', '', 1, undef, undef ],

            # this is needed, if "SMIME::FetchFromCustomer" is active
            # [ 'UserSMIMECertificate', 'SMIMECertificate', 'userSMIMECertificate', 0, 1, 'var', '', 1, undef, undef ],

            # Dynamic field example
            # [ 'DynamicField_Name_X', undef, 'Name_X', 0, 0, 'dynamic_field', undef, 0, undef, undef ],
        ],
    };

To activate and configure the LDAP back end:

Copy the $Self->{CustomerUser} section from Kernel/Config/Defaults.pm into Kernel/Config.pm.

Remove the comments (# characters) from the beginning of the lines.

If additional customer user attributes are stored in your LDAP directory, such as a manager name, a mobile phone number, or a department, this information can be displayed in OTRS.

To display additional customer user attributes from LDAP directory:

Expand the Map array in Kernel/Config.pm with the entries for these attributes.

[ 'UserMobilePhone', 'Mobile Phone', 'mobilephone', 1, 0, 'var', '', 1, undef, undef ],

Note

It is recommended to always use English words for names.

See also

Names can be translated into other languages with custom translation files. For more information, see the Custom Translation File chapter in the developer manual.

Multiple Customer User Back Ends

If you want to use more than one customer user data source, the CustomerUser configuration parameter should be expanded with a number, like CustomerUser1 and CustomerUser2.

The following configuration example shows usage of both a database and an LDAP customer user back end.

# Data source 1: customer user database back end and settings.
    $Self->{CustomerUser1} = {
        Name   => 'Database Backend',
        Module => 'Kernel::System::CustomerUser::DB',
        Params => {
            DSN => 'DBI:odbc:yourdsn',
            DSN => 'DBI:mysql:database=customerdb;host=customerdbhost',
            User => '',
            Password => '',
            Table => 'customer_user',
        },
        # Other setting here.
    };

# Data source 2: customer user LDAP back end and settings.
    $Self->{CustomerUser2} = {
        Name => 'LDAP Backend',
        Module => 'Kernel::System::CustomerUser::LDAP',
        Params => {
            Host => 'bay.csuhayward.edu',
            BaseDN => 'ou=seas,o=csuh',
            SSCOPE => 'sub',
            UserDN => '',
            UserPw => '',
            AlwaysFilter => '',
            Die => 0,
            Params => {
                port    => 389,
                timeout => 120,
                async   => 0,
                version => 3,
            },
        },
        # Other setting here.
    };

It is possible to integrate up to 10 different customer back ends. Use the Customer Users screen to view or edit (assuming write access is enabled) all customer user data.

Customer User Data in Dynamic Fields

Sometimes it can be useful to also store customer user data directly in dynamic fields of a ticket, for example to include this data in special statistics later.

The dynamic field values will be set when a ticket is created or when the customer user of a ticket is changed. The values of the dynamic fields are taken from the customer user data. This works for all back ends, but is especially useful for LDAP back ends.

To activate this optional feature:

Activate the setting Ticket::EventModulePost###4100-DynamicFieldFromCustomerUser.

Activate the setting DynamicFieldFromCustomerUser::Mapping, and modify its value. This setting should contain the map between customer user field names and names of dynamic fields which will inherit their values.

Create the dynamic fields, if the dynamic fields are not present in the system yet.

Enable display of the dynamic fields in the Properties widget, so you can check their current values easily. You can do this via following instructions.

Note

The dynamic fields in question must not be enabled in the following action forms:

Forms###AgentFrontend::TicketCreate::Email::CreateProperties

Forms###AgentFrontend::TicketCreate::Phone::CreateProperties

Forms###AgentFrontend::TicketCreate::SMS::CreateProperties

Forms###AgentFrontend::Ticket::Action::Customer

If they were, the field values from the screen would have precedence over the automatically set values.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Customer Users ↔ Customers

In an organization, for example, which views its customers as it’s departments and teams, a customer user may have to have access to multiple customers tickets for controlling purposes. Maybe you have partners who represent several different companies, or a corporation wants to have a look at all the requests of their subsidiaries.

For all situations, OTRS provides the means. Aside from a primary customer, your customer users can gain access to multiple customer tickets as defined by you.

Use this screen to add one or more customer users to one or more customers. To use this function, at least one customer user and one customer need to have been added to the system. The management screen is available in the Customer Users ↔ Customers module of the Users, Groups & Roles group.

Manage Customer User-Customer Relations

Manage Customer Users ↔ Customers Relations

Note

This module is for assigning a customer user to additional customer records. The primary customer is assigned via the Customer User Settings.

To assign some customers to a customer user:

Click on a customer user in the Customer Users column.

Select the customers you would like to assign to the customer user.

Click on the Save or Save and finish button.

Change Customer Relations for Customer User

To assign some customer users to a customer:

Click on a customer in the Customers column.

Select the customer users you would like to assign to the customer.

Click on the Save or Save and finish button.

Change Customer User Relations for Customer

In the previous versions of OTRS it was only possible to enable or disable access to company tickets for customer users for every customer user back end via CustomerUserExcludePrimaryCustomerID parameter. It was not possible to select the primary customer ID, because it was assumed to be always there anyways, and for the same reason it is still not possible if CustomerUserExcludePrimaryCustomerID is disabled for that customer user back end.

In order to allow privilege separation for customer users of a common company, it should be possible to remove access to tickets of the same company and then individually reassign access to specific customer users. Then these customer users have company ticket access while all others do not.

To allow privilege separation for the customer users of the same company:

Go to the System Configuration screen.

Search for the setting CustomerDisableCompanyTicketAccess and enable it to make sure not all customer users get access to company tickets until the configuration is finished.

Copy the $Self->{CustomerUser} section from Kernel/Config/Defaults.pm into Kernel/Config.pm.

Remove the comment (# character) from the beginning of the line contained CustomerUserExcludePrimaryCustomerID and set the value to 1.

CustomerUserExcludePrimaryCustomerID => 1,

Set Customer Users ↔ Customers relations for customer users who need to have access to company tickets.

Go to the System Configuration screen.

Search for the setting CustomerDisableCompanyTicketAccess and disable it to allow access to company tickets only for customer users configured in step 5.

Note

If several customer users or customers are added to the system, use the search box to find a particular customer user or customer. Only the first 1000 customer users and customers are listed by default.

Multiple customer users or customers can be assigned in both screens at the same time. Additionally clicking on a customer user or clicking on a customer in the relations screen will open the Edit Customer User screen or the Edit Customer screen accordingly.

Warning

Accessing a customer user or a customer provides no back link to the relations screen.

Note

By setting a checkbox in the header of a column will set all the checkboxes in the selected column.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Customer Users ↔ Groups

Customer users shouldn’t need to be bothered with the internal workings of your service desk. A single point of contact request can trigger several processes within your organization, all of which having the customer user information attached and are visible to the customer.

OTRS allows you to assign group permissions to customer users. Access works just the same as for agents, preventing a customer from modifying and viewing a request. Thus allowing the customer to focus on the results of the original communication and funneling the discussion through one ticket.

See also

Assign a group to an entire customer using Customers ↔ Groups.

Use this screen to add one or more customer users to one or more groups. To use this function, at least one customer user and one group need to have been added to the system. The management screen is available in the Customers Users ↔ Groups module of the Users, Groups & Roles group.

Manage Customer User-Group Relations

Customer group support needs to be enabled in at least one customer user back end to use this function. For the default OTRS back end, this can be enabled in the system configuration by clicking on the Enable it here! button.

Enable Customer Group Feature

Note

To enable this feature in systems using a directory server or multiple non-default back ends, a custom configuration file needs to be placed in Kernel/Config/Files (for example named ZZZ_CustomerBackend.pm). Once activated, all customer users from this back end will require group assignment.

Warning

After making changes to the back end, the server cache will be deleted, which may cause a temporary drop in performance.

Manage Customer Users ↔ Groups Relations

To assign some groups to a customer user:

Click on a customer user in the Customer Users column.

Select the permissions you would like to connect the customer user to groups with.

Click on the Save or Save and finish button.

Change Group Relations for Customer User

To assign some customer users to a group:

Click on a group in the Groups column.

Select the permissions you would like to connect the group to customer users with.

Click on the Save or Save and finish button.

Change Customer User Relations for Group

To change customer user default groups:

Click on the Edit Customer User Default Groups button in the left sidebar.

Add or modify groups in setting CustomerGroupAlwaysGroups.

Deploy the modified system configurations.

CustomerGroupAlwaysGroups System Configuration Screen

These groups are automatically assigned to all customer users.

Note

If several customer users or groups are added to the system, use the search box to find a particular customer user or use the filter box to find a particular group by just typing the name to filter.

Multiple customer users or groups can be assigned in both screens at the same time. Additionally clicking on a customer user or clicking on a group in the relations screen will open the Edit Customer User screen or the Edit Group screen accordingly.

Warning

Accessing a customer user or a group provides no back link to the relations screen.

Customer Users ↔ Groups Relations Reference

When assigning a customer user to a group or vice versa, several permissions can be set as connection between a customer user and a group. The following permissions are available by default:

ro

Read only access to the resource.

rw

Full read and write access to the resource.

Note

By setting a checkbox in the header of a column will set all the checkboxes in the selected column.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Customer Users ↔ Services

Use this screen to add one or more customer users to one or more services. To use this function, at least one customer user and one service need to have been added to the system. The management screen is available in the Customers Users ↔ Services module of the Users, Groups & Roles group.

Manage Customer User-Service Relations

Manage Customers Users ↔ Services Relations

To allocate some services to a customer user:

Click on a customer user in the Customer Users column.

Select the services you would like to allocate to the customer user.

Click on the Save or Save and finish button.

Change Service Relations for Customer User

To allocate some customer users to a service:

Click on a service in the Services column.

Select the customer users you would like to allocate to the service.

Click on the Save or Save and finish button.

Change Customer User Relations for Service

Note

If several customer users or services are added to the system, use the search box to find a particular customer user or use the filter box to find a particular service by just typing the name to filter.

Multiple customer users or services can be assigned in both screens at the same time. Additionally clicking on a customer user or clicking on a service in the relations screen will open the Edit Customer User screen or the Edit Service screen accordingly.

Warning

Accessing a customer user or a service provides no back link to the relations screen.

Note

By setting a checkbox in the header of a column will set all the checkboxes in the selected column.

Manage Default Services

It is possible to add default services, so that all customer users may access them. This prevents having to add each service to each customer user.

To edit the default services:

Click on the Edit default services button in the left sidebar.

Select the services which should be selectable for all customer users.

Click on the Save or Save and finish button.

Allocate Services to Customer User Screen

Warning

Mixing default services and customer specific services can be confusing. If a customer user has specific services assigned, then the default services will be not applied.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Groups

Use this screen to add groups to the system. A fresh OTRS installation contains some default groups. The group management screen is available in the Groups module of the Users, Groups & Roles group.

Group Management Screen

Manage Groups

To add a group:

Click on the Add Group button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Group Screen

Warning

Groups can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a group:

Click on a group in the list of groups.

Modify the fields.

Click on the Save or Save and finish button.

Edit Group Screen

Note

If several groups are added to the system, use the filter box to find a particular group by just typing the name to filter.

Group Settings

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

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.

Note

Renaming a group does not affect permissions previously given. When group1 is now called group2, then all the permissions are the same for the users which used to be assigned to group1. This result is because OTRS uses IDs for the relationship, and not the name.

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.

Note

Invalidating a group does not remove the permissions from the user, but only makes them invalid. If you reactivate this group, even with a new name, the permissions take effect.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Default Groups

Every agent’s account should belong to at least one group or role. In a fresh installation, there are some pre-defined groups available:

admin

Allowed to perform administrative tasks in the system.

stats

Qualified to access the stats module of OTRS and generate statistics.

users

Agents should belong to this group, with read and write permissions. They can then access all functions of the ticket system.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Roles

Use this screen to add roles to the system. A fresh OTRS installation contains no roles by default. The role management screen is available in the Roles module of the Users, Groups & Roles group.

Role Management Screen

Manage Roles

To add a role:

Click on the Add Role button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Role Screen

Warning

Roles can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a role:

Click on a role in the list of roles.

Modify the fields.

Click on the Save or Save and finish button.

Edit Role Screen

Note

If several roles are added to the system, use the filter box to find a particular role by just typing the name to filter.

Role Settings

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

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.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Roles ↔ Groups

Use this screen to add one or more roles to one or more groups. To use this function, at least one role and one group need to have been added to the system. The management screen is available in the Roles ↔ Groups module of the Users, Groups & Roles group.

Manage Role-Group Relations

Manage Roles ↔ Groups Relations

To assign some groups to a role:

Click on a role in the Roles column.

Select the permissions you would like to connect the role to groups with.

Click on the Save or Save and finish button.

Change Group Relations for Role

To assign some roles to a group:

Click on a group in the Groups column.

Select the permissions you would like to connect the group to roles with.

Click on the Save or Save and finish button.

Change Role Relations for Group

Note

If several roles or groups are added to the system, use the filter box to find a particular role or group by just typing the name to filter.

Multiple roles or groups can be assigned in both screens at the same time. Additionally clicking on a role or clicking on a group in the relations screen will open the Edit Role screen or the Edit Group screen accordingly.

Warning

Accessing a role or a group provides no back link to the relations screen.

Roles ↔ Groups Relations Reference

When assigning a role to a group or vice versa, several permissions can be set as connection between a role and a group. The following permissions are available by default:

ro

Read only access to the ticket in this group/queue.

move_into

Permissions to move tickets into this group/queue.

create

Permissions to create tickets in this group/queue.

note

Permissions to add notes to tickets in this group/queue.

owner

Permissions to change the owner of tickets in this group/queue.

priority

Permissions to change the ticket priority in this group/queue.

chat_observer

Users with this permission type will only be able to observe chats in a channel after they have been invited.

chat_participant

Users with this permission type will be able to take part in a chat, but only after they get invited to it.

chat_owner

Users with this permission type will be able to accept chat customer/public requests and do all kinds of observer and participant actions on a chat.

rw

Full read and write access to the tickets in this group/queue.

See also

Not all available permissions are shown by default. See System::Permission setting for permissions that can be added. These additional permissions can be added:

stats

Gives access to the stats page.

bounce

Permissions to bounce an email message (with bounce button in Ticket Zoom screen).

compose

Permissions to compose an answer for a ticket.

customer

Permissions to change the customer of a ticket.

forward

Permissions to forward a message (with the forward button).

pending

Permissions to set a ticket to pending.

phone

Permissions to add a phone call to a ticket.

responsible

Permissions to change the responsible agent for a ticket.

Note

By setting a checkbox in the header of a column will set all the checkboxes in the selected column. By setting the checkbox in the last rw column will set all the checkboxes in the selected row.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Processes & Automation

Working effectively with tickets requires more than just the possibility to manually change their state, add information, communicate with other persons and finally close the tickets.

Automation frees agents from reoccurring and time-consuming tasks and allows them to focus on activities, where their interaction is required.

Process management guides customer users and agents through ticket creation to closure ensuring that tickets take defined workflows at any time.

OTRS offers many options to automate tasks based on events, time, external systems and defined processes. OTRS also includes the possibility to add individual information types to tickets and help agents to lower their error rate when working with tickets by allowing only defined activities for tickets in specific states.

Contents

Access Control Lists (ACL)

Manage Access Control Lists

ACL Settings

Edit ACL Structure

Match settings

Change settings

Modifiers

ACL Examples

Move Ticket to Queue Based on Priority

Move Ticket to Queue Based on Priority Stored in Database

Disable Ticket Close in Queue and Hide Close Ticket Action

Remove State

Using Regular Expressions

Disallow Process For Customer

ACL Reference

Dynamic Fields

Manage Dynamic Fields

Dynamic Field Settings

General Dynamic Field Settings

Checkbox Dynamic Field Settings

Contact With Data Dynamic Field Settings

Date Dynamic Field Settings

Date / Time Dynamic Field Settings

Dropdown Dynamic Field Settings

Multiselect Dynamic Field Settings

Text Dynamic Field Settings

Textarea Dynamic Field Settings

Database Dynamic Field

Web Service Dynamic Field

Display Dynamic Fields on Screens

Dynamic Field in Business Object Detail View

Dynamic Field in Ticket and Article Action

Dynamic Field in Business Object List

Dynamic Field in Ticket Create Screen

Dynamic Field in Ticket Bulk Action

Dynamic Field in the Print Output

Dynamic Field in External Interface

Add Dynamic Fields to Search Engine

Set Default Value via Ticket Event Module

Set Default Value via User Preferences

Generic Agent

Manage Generic Agent Jobs

Generic Agent Job Settings

General Job Settings

Automatic Execution

Event Based Execution

Select Tickets

Update/Add Ticket Attributes

Add Note

Execute Ticket Commands

Execute Custom Module

Process Management

Manage Processes

Process Elements

Example process

Process Specification

Introduce The Process Elements

Create Necessary Resources

Create User Task Activity Dialogs

Create Sequence Flows

Create Sequence Flow Actions

Create Activities

Create Process Path

Web Services

Manage Web Services

Web Service Settings

General Web Service Settings

Provider Web Service Settings

Requester Web Service Settings

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Access Control Lists (ACL)

Working with tickets can become a bewildering task. Many options are given to process, or close tickets, even if they are not needed in the current state of a ticket or due to the role of the current agent. Hiding unneeded entries cleans up the menu bar and gets it easier to work with, hiding values from dynamic fields or next queues lowers chance of human error.

OTRS uses access control lists (ACL) to restrict agents and customer users on ticket options, allowing only correct and meaningful activities with a ticket. OTRS administrators can easily generate ACLs in the graphical interface to prevent ticket closure until meeting specific requirements, prevent tickets from being moved to queues before adding the defined information and much more.

Use this screen to manage access control lists in the system. A fresh OTRS installation contains no access control lists by default. The access control lists management screen is available in the Access Control Lists (ACL) module of the Processes & Automation group.

ACL Management Screen

Manage Access Control Lists

Note

When creating some access control lists, please keep in mind that they are executed alphabetically as displayed in the access control lists overview.

Warning

ACL restrictions will be ignored for the superuser account (UserID 1).

To create a new ACL:

Click on the Create New ACL button in the left sidebar.

Fill in the required fields.

Click on the Save button.

You will be redirected to Edit ACL screen to edit the ACL structure.

Create New ACL Screen

To edit an ACL:

Click on an ACL in the list of ACLs or you are already redirected here from Create New ACL screen.

Modify the fields and the ACL structure.

Click on the Save or Save and finish button.

Deploy all ACLs.

Edit ACL Structure Screen

To delete an ACL:

Click on an ACL in the list of ACLs.

Set the Validity option to invalid or invalid-temporarily.

Click on the Save button. A new Delete Invalid ACL button will appear in the left sidebar.

Click on the Delete Invalid ACL button.

Click on the Delete button in the confirmation screen.

Deploy all ACLs.

Warning

ACLs are written into ZZZACL.pm file in Perl format. Without deploying, all ACLs are still in this cache file even if they are deleted or the Validity option is set to invalid or invalid-temporarily. Don’t forget to deploy all ACLs after modifications!

To deploy all ACLs:

Click on the Deploy ACLs button in the left sidebar.

Note

New or modified ACLs have to deploy in order to make affect the behavior of the system. Setting the Validity option to valid just indicates, which ACLs should be deployed.

To export all ACLs:

Click on the Export ACLs button in the left sidebar.

Choose a location in your computer to save the Export_ACL.yml file.

To import ACLs:

Click on the Browse… button in the left sidebar.

Select a previously exported .yml file.

Click on the Overwrite existing ACLs? checkbox, if you would like to overwrite the existing ACLs.

Click on the Import ACL configuration(s) button.

Deploy the imported ACLs with Deploy ACLs button.

Note

If several ACLs are added to the system, use the filter box to find a particular ACL by just typing the name to filter.

Warning

Changing the name of this object should be done with care, the check only provides verification for certain settings and ignores things where the name can’t be verified. Some examples are dashboard filters, access control lists (ACLs), and processes (sequence flow actions) to name a few. Documentation of your setup is key to surviving a name change.

ACL Settings

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

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Description

Like comment, but longer text can be added here.

Stop after match

ACLs are evaluated in alphabetical order. This setting disables the evaluation of the subsequent ACLs.

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.

Edit ACL Structure

The ACL definition can be split into two big parts, Match settings and Change settings. In the matching sections the ACLs contain attributes that has to be met in order to use the ACL. If the attributes defined in the ACL do not match with the attributes that are sent, then the ACL does not take any affect, but any other match ACL will. The change sections contain the rules to reduce the possible options for a ticket.

Match settings

Properties

This section contains matching options that can be changed on the fly. For example on a ticket creation time the data of the ticket changes dynamically as the agent sets the information. If an ACL is set to match a ticket attribute then only when the matching attribute is selected the ACL will be active and might reduce other ticket attributes, but as soon as another value is selected the ACL will not take any affect.

PropertiesDatabase

This section is similar to Properties but does not take changes in ticket attributes that are not saved into the database, this means that changing an attribute without submit will not make any effect. This section is not use for ticket creation screens (as tickets are not yet created in the database).

Change settings

Possible

This section is used to reset the data to be reduce to only the elements that are set in this section.

PossibleAdd

This section is used to add missing elements that were reduced in other ACLs. This section is only used in together with other ACLs that have Possible or PossibleNot sections.

PossibleNot

This section is used to remove specific elements from the current data. It could be used stand alone or together with other ACLs with a Possible or PossibleAdd sections.

Modifiers

In order to make the development of ACLs easier and more powerful there is a set of so called modifiers for the attributes on each section. This modifiers are explained below:

[Not]

This modifier is used to negate a value, for example [Not]2 low. Talking about priorities will be the same as to have: 1 very low, 3 normal, 4 high, 5 very high.

[RegExp]

It is used to define a regular expression for matching several values, for example [RegExp]low. In this case talking about priorities is the same as 1 very low, 2 low.

[regexp]

It is very similar to [RegExp] but it is case insensitive.

[NotRegExp]

Negated regular expressions, for example [NotRegExp]low. Talking about priorities is the same as 3 normal, 4 high, 5 very high.

[Notregexp]

It is very similar to [NotRegExp] but it is case insensitive.

ACL Examples

Move Ticket to Queue Based on Priority

This example shows you how to allow movement into a queue of only those tickets with ticket priority 5 very high.

First, it needs to have a name. In this case, it is 100-Example-ACL. Note that the ACLs will be numerically sorted before execution, so you should use the names carefully. The comment and the description fields are optional.

100-Example-ACL - Basic Settings

Secondly, you have a Properties section which is a filter for your tickets. All the criteria defined here will be applied to a ticket to determine if the ACL must be applied or not. In our example, a ticket will match if it is in the queue Raw and has priority 5 very high. This is also affected by changes in the form (e. g. if the ticket is the queue Raw and had a priority 3 normal at this moment the ACL will not match, but then priority drop-down is selected and the priority is changed now to 5 very high then will also match).

100-Example-ACL - Match Settings

Lastly, a section Possible defines modifications to the screens. In this case, from the available queues, only the queue Alert can be selected in a ticket screen.

100-Example-ACL - Change Settings

Note

Don’t forget to set Validity to valid and deploy the newly created ACL.

Move Ticket to Queue Based on Priority Stored in Database

This example is very similar to the first one, but in this case only tickets in the queue Raw and with a priority 5 very high, both stored in the database will match. This kind of ACLs does not consider changes in the form before the ticket is really updated in the database.

101-Example-ACL

Disable Ticket Close in Queue and Hide Close Ticket Action

This example shows how to disable the closing of tickets in the queue Raw, and hide the Close Ticket action. It is possible to filter a ticket field (state) with more than one possible values to select from. It is also possible to limit the actions that can be executed for a certain ticket. In this case, the ticket cannot be closed.

102-Example-ACL

Remove State

This example shows how it is possible to define negative filters (the state closed successful will be removed). You can also see that not defining match properties for a ticket will match any ticket, i. e. the ACL will always be applied. This may be useful if you want to hide certain values by default, and only enable them in special circumstances (e. g. if the agent is in a specific group).

103-Example-ACL

Using Regular Expressions

This example shows you how you can use regular expressions for matching tickets and for filtering the available options. This ACL only shows Hardware services for tickets that are created in queues that start with HW.

104-Example-ACL

Disallow Process For Customer

This ACL restricts the process P14 in the external interface using the customer ID TheCustomerID.

105-Example-ACL

ACL Reference

Properties, keys and values that can be used in ACLs are highly depend on the OTRS installation. For example the possibilities can be extended by installing extension modules, as well as it can be depend on the customer user mapping set in Config.pm. Therefore it is not possible to provide a full ACL reference, that contains all settings.

For properties, keys and values that can be used in ACLs, see the following example ACL in YAML format.

---
- ChangeBy: root@localhost
  ChangeTime: 2020-04-15 16:46:23
  Comment: ACL Reference.
  ConfigMatch:
    Properties:
      # Match properties (current values from the form).
      CustomerUser:
        UserLogin:
        - some login
        UserCustomerID:
        - some customer ID
        Group_rw:
        - some group
      DynamicField:
        # Names must be in DynamicField_<field_name> format.
        # Values for dynamic fields must always be the untranslated internal
        #   data keys specified in the dynamic field definition and not the
        #   data values shown to the user.
        DynamicField_Field1:
        - some value
        DynamicField_OtherField:
        - some value
        DynamicField_TicketFreeText2:
        - some value
        # more dynamic fields
      Frontend:
        Endpoint:
        - AgentFrontend::KnowledgeBaseArticleDetailView::Property
        - AgentFrontend::PersonalPreferences
        - AgentFrontend::ProcessTicketNextStep
        - AgentFrontend::Ticket::Action::Close
        - AgentFrontend::Ticket::Action::Customer
        - AgentFrontend::Ticket::Action::EmailOutbound
        - AgentFrontend::Ticket::Action::FreeText
        - AgentFrontend::Ticket::Action::Link
        - AgentFrontend::Ticket::Action::Lock
        - AgentFrontend::Ticket::Action::Merge
        - AgentFrontend::Ticket::Action::Move
        - AgentFrontend::Ticket::Action::Note
        - AgentFrontend::Ticket::Action::Owner
        - AgentFrontend::Ticket::Action::Pending
        - AgentFrontend::Ticket::Action::PhoneCallInbound
        - AgentFrontend::Ticket::Action::PhoneCallOutbound
        - AgentFrontend::Ticket::Action::Print
        - AgentFrontend::Ticket::Action::Priority
        - AgentFrontend::Ticket::Action::Redirect
        - AgentFrontend::Ticket::Action::Responsible
        - AgentFrontend::Ticket::Action::SmsOutbound
        - AgentFrontend::Ticket::Action::TicketHistory
        - AgentFrontend::Ticket::Action::Unlock
        - AgentFrontend::Ticket::Action::Unwatch
        - AgentFrontend::Ticket::Action::Watch
        - AgentFrontend::TicketArticle::Action::CopyLink
        - AgentFrontend::TicketArticle::Action::Forward
        - AgentFrontend::TicketArticle::Action::MarkAsImportant
        - AgentFrontend::TicketArticle::Action::Plain
        - AgentFrontend::TicketArticle::Action::Print
        - AgentFrontend::TicketArticle::Action::Redirect
        - AgentFrontend::TicketArticle::Action::Reply
        - AgentFrontend::TicketArticle::Action::ReplyAll
        - AgentFrontend::TicketArticle::Action::ReplyToNote
        - AgentFrontend::TicketArticle::Action::ReplyViaSms
        - AgentFrontend::TicketArticle::Action::Split
        - AgentFrontend::TicketArticle::Action::UnmarkAsImportant
        - AgentFrontend::TicketCreateEmail
        - AgentFrontend::TicketCreatePhone
        - AgentFrontend::TicketCreateProcess
        - AgentFrontend::TicketCreateSMS
        - AgentFrontend::TicketDetailView::Property
        - AgentFrontend::TicketList::Bulk
        - AgentFrontend::TicketList::Filter
        - ...
        - ExternalFrontend::PersonalPreferences
        - ExternalFrontend::ProcessTicketCreate
        - ExternalFrontend::ProcessTicketNextStep
        - ExternalFrontend::TicketCreate
        - ExternalFrontend::TicketDetailView
        - ...
      Owner:
        UserLogin:
        - some login
        Group_rw:
        - some group
        Role:
        - admin
        # more owner attributes
      Priority:
        ID:
        - some ID
        Name:
        - some name
        # more priority attributes
      Process:
        ProcessEntityID:
        # the process that the current ticket is part of
        - Process-9c378d7cc59f0fce4cee7bb9995ee3eb
        ActivityEntityID:
        # the current activity of the ticket
        - Activity-f8b2fdebe54eeb7b147a5f8e1da5e35c
        ActivityDialogEntityID:
        # the current activity dialog that the agent/customer is using
        - ActivityDialog-aff0ae05fe6803f38de8fff6cf33b7ce
      Queue:
        Name:
        - Raw
        QueueID:
        - some ID
        GroupID:
        - some ID
        Email:
        - some email
        RealName:
        - OTRS System
        # more queue attributes
      Responsible:
        UserLogin:
        - some login
        Group_rw:
        - some group
        Role:
        - admin
        # more responsible attributes
      Service:
        ServiceID:
        - some ID
        Name:
        - some name
        ParentID:
        - some ID
        # more service attributes
      SLA:
        SLAID:
        - some ID
        Name:
        - some name
        Calendar:
        - some calendar
        # more SLA attributes
      State:
        ID:
        - some ID
        Name:
        - some name
        TypeName:
        - some state type name
        TypeID:
        - some state type ID
        # more state attributes
      Ticket:
        Queue:
        - Raw
        State:
        - new
        - open
        Priority:
        - some priority
        Lock:
        - lock
        CustomerID:
        - some ID
        CustomerUserID:
        - some ID
        Owner:
        - some owner
        DynamicField_Field1:
        - some value
        DynamicField_MyField:
        - some value
        # more ticket attributes
      Type:
        ID:
        - some ID
        Name:
        - some name
        # more type attributes
      User:
        UserLogin:
        - some_login
        Group_rw:
        - some group
        Role:
        - admin
    PropertiesDatabase:
      # Match properties (existing values from the database).
      # Please note that Frontend is not in the database, but in the framework.
      # See section "Properties", the same configuration can be used here.
  ConfigChange:
    Possible:
      # Reset possible options (white list).
      Action:
      # Possible action options (white list).
      - ...
      ActivityDialog:
      # Limit the number of possible activity dialogs the agent/customer can use in a process ticket.
      - ActivityDialog-aff0ae05fe6803f38de8fff6cf33b7ce
      - ActivityDialog-429d61180a593414789a8087cc4b3c6f
      - ...
      Endpoint:
      # Limit the functions on agent interface.
      - AgentFrontend::KnowledgeBaseArticleDetailView::Property
      - AgentFrontend::PersonalPreferences
      - AgentFrontend::ProcessTicketNextStep
      - AgentFrontend::Ticket::Action::Close
      - AgentFrontend::Ticket::Action::Customer
      - AgentFrontend::Ticket::Action::EmailOutbound
      - AgentFrontend::Ticket::Action::FreeText
      - AgentFrontend::Ticket::Action::Merge
      - AgentFrontend::Ticket::Action::Move
      - AgentFrontend::Ticket::Action::Note
      - AgentFrontend::Ticket::Action::Owner
      - AgentFrontend::Ticket::Action::Pending
      - AgentFrontend::Ticket::Action::PhoneCallInbound
      - AgentFrontend::Ticket::Action::PhoneCallOutbound
      - AgentFrontend::Ticket::Action::Priority
      - AgentFrontend::Ticket::Action::Redirect
      - AgentFrontend::Ticket::Action::Responsible
      - AgentFrontend::Ticket::Action::SmsOutbound
      - AgentFrontend::TicketArticle::Action::CopyLink
      - AgentFrontend::TicketArticle::Action::Forward
      - AgentFrontend::TicketArticle::Action::Redirect
      - AgentFrontend::TicketArticle::Action::Reply
      - AgentFrontend::TicketArticle::Action::ReplyAll
      - AgentFrontend::TicketArticle::Action::ReplyToNote
      - AgentFrontend::TicketArticle::Action::ReplyViaSms
      - AgentFrontend::TicketArticle::Action::Split
      - AgentFrontend::TicketCreateEmail
      - AgentFrontend::TicketCreatePhone
      - AgentFrontend::TicketCreateProcess
      - AgentFrontend::TicketCreateSMS
      - AgentFrontend::TicketDetailView::Property
      - AgentFrontend::TicketList::Bulk
      - AgentFrontend::TicketList::Filter
      - ...
      # Limit the functions on external interface.
      - ExternalFrontend::PersonalPreferences
      - ExternalFrontend::ProcessTicketCreate
      - ExternalFrontend::ProcessTicketNextStep
      - ExternalFrontend::TicketCreate
      - ExternalFrontend::TicketDetailView
      - ...
      Process:
      # Limit the number of possible processes that can be started.
      - Process-9c378d7cc59f0fce4cee7bb9995ee3eb
      - Process-12345678901234567890123456789012
      - ...
      Ticket:
      # Possible ticket options (white list).
        Queue:
        - Raw
        - some other queue
        State:
        - some state
        Priority:
        - 5 very high
        DynamicField_Field1:
        - some value
        DynamicField_MyField:
        - some value
        # more dynamic fields
        NewOwner:
        # For ticket action screens, where the Owner is already set.
        - some owner
        OldOwner:
        # For ticket action screens, where the Owner is already set.
        - some owner
        Owner:
        # For ticket create screens, because Owner is not set yet.
        - some owner
        # more ticket attributes
    PossibleAdd:
       # Add options (white list).
       # See section "Possible", the same configuration can be used here.
    PossibleNot:
       # Remove options (black list).
       # See section "Possible", the same configuration can be used here.
  CreateBy: root@localhost
  CreateTime: 2020-04-15 16:46:23
  Description: This is the long description of the ACL to explain its usage.
  ID: 1
  Name: 200-ACL-Reference
  StopAfterMatch: 0
  ValidID: 3

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

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

Manage Dynamic Fields

To create a new dynamic field:

Choose an object in the left sidebar and select a dynamic field type from its drop-down.

Fill in the required fields.

Click on the Save button.

Create New Dynamic Field Screen

To edit a dynamic field:

Click on a dynamic field in the list of dynamic fields.

Modify the fields.

Click on the Save or Save and finish button.

Edit Dynamic Field Screen

To delete a dynamic field:

Click on the trash icon in the last column of the overview table.

Click on the Confirm button.

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

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

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

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 Tickets → Edit contacts with data to add some data.

Contact With Data Management Screen

To add a new contact with data:

Select a dynamic field from the drop-down list in Actions widget of the left sidebar.

Click on the Add contact with data button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Contact With Data Screen

To edit a contact with data:

Click on a contact with data in the list of contact with data entries.

Modify the fields.

Click on the Save or Save and finish button.

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:

Create a new dynamic field of type contact with data.

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).

Add the list of mandatory attribute keys comma separated (Name and ValidID are not needed).

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

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

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.

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.

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

Select an existing contact using autocomplete and choosing a contact.

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

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

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

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).

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

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:

https://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

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

Dropdown Dynamic Field Settings

Drop-down dynamic field is used to store a single value, from a closed list.

Dropdown 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.

Show link

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

https://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.

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

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:

https://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

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:

Go to the System Configuration screen.

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

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

See also

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

Deploy the modified system configuration.

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

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

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

Display Dynamic Field Property Card in Properties Widget

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

Go to the System Configuration screen.

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

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

ArticleDynamicFields:
- Test1

Add Dynamic Field to Communication Stream Widget Configuration

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

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

Go to the System Configuration screen.

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

Add the dynamic field to the list and enabled it.

Add Dynamic Field to Business Process Information Widget Configuration

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

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:

Go to the System Configuration screen.

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

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

Fields:
- Name: DynamicField_Test1

Add Dynamic Field to Close Ticket Form Configuration

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

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:

Go to the System Configuration screen.

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

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

See also

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

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

To add a ticket dynamic field as a list filter:

Go to the System Configuration screen.

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

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

AvailableDynamicFieldFilters:
- Test1

Add Dynamic Field Filter to Ticket List Configuration

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

Dynamic Field in Ticket Create Screen

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

Go to the System Configuration screen.

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

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

See also

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

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

Dynamic Field in Ticket Bulk Action

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

Go to the System Configuration screen.

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

Add the dynamic field to the list and enabled it.

Add Dynamic Field to Ticket Bulk Configuration

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

Dynamic Field in the Print Output

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

Go to the System Configuration screen.

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

Add the dynamic field to the list and enabled it.

Add Dynamic Field to Print Ticket Configuration

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

Dynamic Field in External Interface

To add a dynamic field to the external interface:

Go to System Configuration screen.

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

Select the screen where the dynamic field should be displayed.

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

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.

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

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.

Repeat the steps for other views, if needed.

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:

Go to System Configuration screen.

Navigate to Frontend → Agent → DocumentSearch and Frontend → External → DocumentSearch in the navigation tree.

Search for the setting DocumentSearch::Agent::DynamicField and DocumentSearch::External::DynamicField respectively.

Click on the Edit this setting button.

Click on the + button to add the dynamic field.

Enter the name of the dynamic field to the text box and click on the tick button.

Select 0 - Disabled or 1 - Enabled.

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

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.

Go to the System Configuration screen.

Navigate to Core → Event → Ticket and search for the setting Ticket::EventModulePost###9600-TicketDynamicFieldDefault.

Click on the Edit this setting button to activate the setting.

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

Deploy the modified system configuration.

Activate Ticket Event Module

Example: activate Field1 in TicketCreate event:

Go to the System Configuration screen.

Navigate to Core → Ticket → DynamicFieldDefault and search for the setting Ticket::TicketDynamicFieldDefault###Element1.

Click on the Edit this setting button to activate the setting.

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

Deploy the modified system configuration.

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.

Go to the System Configuration screen.

Navigate to Frontend → Agent → View → Preferences and search for the setting PreferencesGroups###DynamicField.

Click on the Edit this setting button to activate the setting.

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

Deploy the modified system configuration.

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

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

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Generic Agent

Processing tickets require often a workflow. Let’s say “if-then” activities.

If specific conditions match like:

A ticket is from one particular customer.

A ticket is assigned to an appropriate queue.

A ticket has a defined priority.

A ticket contains defined keywords.

Outlined activities must be performed like changing the ticket priority, moving the ticket to another group, assigning a service to a ticket, and many more.

Also time-based activities can be required like cleaning up the spam-queue once a week.

OTRS supports this with the Generic Agent. Here, simple or compound time and event-based tasks are configurable in the OTRS front end without the requirement to learn a scripting language. Depending on search criteria, and time or event criteria, tickets will automatically be acted upon.

Use this screen to manage generic agent jobs in the system. A fresh OTRS installation contains no generic agent jobs by default. The generic agent job management screen is available in the Generic Agent module of the Processes & Automation group.

Generic Agent Management Screen

Manage Generic Agent Jobs

To create a new generic agent job:

Click on the Add Job button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Create New Generic Agent Job Screen

To edit a generic agent job:

Click on a generic agent job in the list of generic agent jobs.

Modify the fields.

Click on the Save or Save and finish button.

Edit Generic Agent Job Screen

To delete a generic agent job:

Click on the trash icon in the fourth column of the overview table.

Click on the Confirm button.

Delete Generic Agent Job Screen

Note

If several generic agent jobs are added to the system, use the filter box to find a particular generic agent job by just typing the name to filter.

Generic Agent Job Settings

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

General Job Settings

Job Settings - General

Job 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.

Validity

Set the validity of this resource. This resource can be used in OTRS only, if this field is set to Yes. Setting this field to No will disable the use of the resource.

Automatic Execution

Fill in this section to set the times for automatic execution of the job.

Job Settings - Automatic Execution

Schedule minutes

Select the minutes in which the job has to be executed. For example if 10 is selected, the job will be executed in every hour in 00:10, 01:10, 02:10, etc.

Schedule hours

Select the hours in which the job has to be executed. For example if 10 is selected for minutes and 02 is selected for hours, the job will be executed in every day in 02:10.

Schedule days

Select the days in which the job has to be executed. For example if 10 is selected for minutes, 02 is selected for hours and Fri is selected for days, the job will be executed in every week in Friday 02:10.

Event Based Execution

Fill in this section to set events that trigger the execution of the job.

Job Settings - Event Based Execution

Event Triggers

This is a list of already added events. If no events are added yet, the list contains no elements. Elements can be deleted by clicking on the trash icon in the last column.

Add Event Trigger

Select an object and a related event that will trigger the job.

Select Tickets

This section contains all the attributes, that you can use to select the affected tickets.

Fields are self-explained, so there is no additional explanation here.

Update/Add Ticket Attributes

Fill in this section to update and/or add ticket attributes.

Fields are self-explained, so there is no additional explanation here.

Add Note

Fill in this section to add a note to tickets that are affected by job execution.

Job Settings - Add Note

Execute Ticket Commands

Fill in this section, if you would like to make execute a custom command with the job.

Job Settings - Execute Ticket Commands

Send agent/customer notifications on changes

If Yes is selected, a notification will be sent to agents and customers about ticket changes.

CMD

Enter a command here, that will be executed. ARG[0] will be the ticket number. ARG[1] the ticket ID.

Note

Use :: as directory separator, if the value contains a path.

Delete tickets

If Yes is selected, the generic agent job will delete the matched tickets.

Warning

All affected tickets will be removed from the database and cannot be restored!

Execute Custom Module

Fill in this section, if you would like to make execute a custom module with the job.

Job Settings - Execute Custom Module

Module

This is the path for the module to be executed.

Note

Use :: as directory separator, if the value contains a path.

Param key

Enter the key of the parameter, that should be passed to the module.

Param value

Enter the value of the parameter, that should be passed to the module.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Process Management

Maximizing performance while minimizing human error is a requirement of organizations of all sizes. This need is covered by defined processes and workflows, for recurring tasks. Ensuring all required information is available in the right place, and contacts are informed about their responsibilities like adding information, approving requests, etc.

OTRS supports this requirement by process management. Process tickets help by using the required mandatory and optional fields (see Dynamic Fields) that information is not forgotten upon ticket creation or during later steps of the process. Process tickets are simple to handle for customer users and agents, so no intensive training is required.

Processes are designed completely and efficiently within the OTRS front end to fit the requirements of your organization.

Use this screen to manage processes in the system. The process management screen is available in the Process Management module of the Processes & Automation group.

Manage Processes

To create a new process:

Click on the Create New Process button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add activities, user task activity dialogs, sequence flows and sequence flow actions.

Set State to Active.

Deploy all processes.

Create New Process Screen

To edit a process:

Click on a process in the list of processes.

Modify the fields and the process path.

Click on the Save or Save and finish button.

Deploy all processes.

To copy a process:

Click on the copy icon in the fifth column of list of processes.

Click on the newly created process to edit it.

To delete a process:

Click on a process in the list of processes.

Set the State option to Inactive.

Click on the Save button. A new Delete Inactive Process button will appear in the left sidebar.

Click on the Delete Inactive Process button.

Click on the Delete button in the confirmation screen.

Deploy all processes.

Warning

Processes are written into file in Perl format. Without deploying, all processes are still in this cache file even if they are deleted or the State option is set to Inactive or FadeAway. Don’t forget to deploy all processes after modifications!

Give some time for agents to complete the running process tickets before the process will be deleted. It is possible to mark a process for deletion, i. e. set the process as not to be selected anymore. Process states can be:

Active

Processes can be used in new process tickets.

FadeAway

Processes cannot be selected any more for new tickets, but existing tickets still can use the process.

Inactive

Processes are deactivated and cannot be used for new or existing tickets.

To deploy all processes:

Click on the Deploy All Processes button in the left sidebar.

Note

New or modified processes have to deploy in order to make affect the behavior of the system. Setting the State option to Active just indicates, which processes should be deployed.

To export a process:

Click on the export icon in the fourth column of list of processes.

Choose a location in your computer to save the Export_ProcessEntityID_xxx.yml file.

Warning

The exported file contains only the process itself, and doesn’t contain the Queues, Agents, Dynamic Fields, etc. needed for the process.

To import a process:

Click on the Browse… button of the Configuration Import widget in the left sidebar.

Select a previously exported .yml file.

Click on the Import process configuration button.

Deploy all processes.

Note

Before import a process, it is still necessary to create all Queues, Agents and Dynamic Fields, as well as to set System Configuration, that are needed by each process before the import. If the process requires the use of Access Control Lists (ACL) those are also needed to be set manually.

Note

If several processes are added to the system, use the filter box to find a particular process by just typing the name to filter.

Process Elements

The element names of the process modeler have been adapted to the Business Process Model and Notation (BPMN) ISO naming convention. The following task activities can be used as basic elements of the process.

Script task activity

Script task activity is executed by the process management module and it can set dynamic field values or manage tickets automatically.

Script Task Activity Window

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

Activity name *

The name of this resource. Any type of characters can be entered to this field including uppercase letters and spaces.

Activity type *

The following types of task activities can be used:

Script task activity (selected for now)

Service task activity

User task activity

Activity description

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity.

Activity error code

Define a custom error code for script or service task activities. The custom error code must be a positive integer number.

Can start processes in

Defines, where can the processes be started by the agents or customer users. A process can be started in the following interfaces:

Agent Interface

Agent and External Interface

External Interface

Script *

In this drop-down can be selected which script should be triggered immediately if the activity is set. Click on the Configure button to add parameters (key-value pairs) for the script.

Service task activity

Service task activity uses a web service to complete the task.

Service Task Activity Window

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

Activity name *

The name of this resource. Any type of characters can be entered to this field including uppercase letters and spaces.

Activity type *

The following types of task activities can be used:

Script task activity

Service task activity (selected for now)

User task activity

Activity description

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity.

Activity error code

Define a custom error code for script or service task activities. The custom error code must be a positive integer number.

Can start processes in

Defines, where can the processes be started by the agents or customer users. A process can be started in the following interfaces:

Agent Interface

Agent and External Interface

External Interface

Web Service *

Select one of the Web Services from the drop-down list.

Invoker *

Select an invoker for the web service. Click on the Configure button to add parameters for the invoker.

User task activity

User task activity can be used when the task is being done by an agent or a customer user.

User Task Activity Window

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

Activity name *

The name of this resource. Any type of characters can be entered to this field including uppercase letters and spaces.

Activity type *

The following types of task activities can be used:

Script task activity

Service task activity

User task activity (selected for now)

User Task Activity Dialogs

You can assign user task activity dialogs to this activity by dragging the elements with the mouse from the left list to the right list. Ordering the elements within the list is also possible by drag and drop.

Click on the Create New User Task Activity Dialog button to create new dialogs.

Example process

Processes are more complex than other resources in OTRS. To create a process, you need to do several steps. The following chapters shows you, how to define a process from the specification and create the needed resources. Let’s see an example to make it more demonstrative. We will define a book order process.

Process Specification

The book order process has four states.

Recording the demand

Before an order will be placed, the demand for literature by an employee will be recorded. The following book is needed in our example:

Title: Prozessmanagement für Dummies
Autor: Thilo Knuppertz
ISBN: 3527703713

Approval by manager

The head of the employee’s department needs to decide on the order. In case of a denial, a reason should be recorded by the manager. In case of approval, the order is passed to the purchasing department.

Processing by purchasing department

Purchasing now has the task to find out where the book can be ordered with the best conditions. If it is out of stock, this can be recorded in the order. In case of a successful order purchasing will record the supplier, the price and the delivery date.

Processing by the mail room

The shipment will arrive at the company. The incoming goods department checks the shipment and records the date of receipt. Now the employee will be informed that their order has arrived and is ready to be collected.

Introduce The Process Elements

If we assume that a ticket acts in this workflow like an accompanying document that can receive change notes, we already have a clear picture of process tickets.

From the analysis of the example process we can identify the following necessary items:

Possibility to record data, let’s call this user task activity dialog.

Check which can react to changed data automatically, let’s call this sequence flow.

Change which can be applied to a process ticket after successful transitions of a process ticket, let’s call this sequence flow action.

A possibility to offer more than just one user task activity dialog to be available. In our example this is needed when the manager must have the choice between Approve and Deny. Let’s call this activity.

Now, with activities, user task activity dialogs, sequence flows and sequence flow actions we have the necessary tools to model the individual steps of our example. What is still missing is an area where for each workflow the order of the steps can be specified. Let’s call this process.

Create Necessary Resources

Before the creation of the process and its parts is necessary to prepare the system. We need to define some Queues, Agents and Dynamic Fields as well as set some System Configuration settings.

Create the following Queues:

Management

Employees

Purchasing

Post office

Create the following Agents:

Manager

Employee

Create the following Dynamic Fields:

Object

Type

Name

Label

Possible values

Ticket

Text

Title

Title

Ticket

Text

Author

Author

Ticket

Text

ISBN

ISBN

Ticket

Dropdown

Status

Status

Approval

Approval denied

Approved

Order denied

Order placed

Shipment received

Ticket

Text

Supplier

Supplier

Ticket

Text

Price

Price

Ticket

Date

DeliveryDate

Delivery date

Ticket

Date

DateOfReceipt

Date of receipt

Set the following System Configuration settings:

Ticket::Responsible

Enabled

AgentFrontend::TicketDetailView::Widget::BusinessProcessInformation###DynamicField

Author → 1 - Enabled

DateOfReceipt → 1 - Enabled

DeliveryDate → 1 - Enabled

ISBN → 1 - Enabled

Price → 1 - Enabled

Status → 1 - Enabled

Supplier → 1 - Enabled

Title → 1 - Enabled

AgentFrontend::TicketDetailView::Widget::BusinessProcessInformation###DynamicFieldGroups

Book → Title,Author,ISBN

General → Status

Order → Price,Supplier,DeliveryDate

Shipment → DateOfReceipt

Note

Don’t forget to deploy the modified system configuration settings.

Now, go back to the Process Management screen and click on the Create New Process. Fill in the required fields.

Book Ordering - Create New Process

The new process is created. You can add some process element now.

Create User Task Activity Dialogs

Click on the User Task Activity Dialogs item in the Available Process Elements widget in the left sidebar. This action will expand the User Task Activity Dialogs options and will collapse all others doing an accordion like effect. Click on the Create New User Task Activity Dialog button.

Book Ordering - User Task Activity Dialogs

In the opened popup screen fill in the Dialog Name as well as the Description (short) fields. For this example we will leave all other fields as the default.

Book Ordering - Add User Task Activity Dialog

To assign fields to the user task activity dialog simple drag the required field from the Available Fields pool and drop into the Assigned Fields pool. The order in the Assigned Fields pool is the order as the fields will have in the screen. To modify the order simply drag and drop the field within the pool to rearrange it in the correct place.

In this example we will use:

Article field for comments.

DynamicField_Title, DynamicField_Author, DynamicField_ISBN fields for the data to be collected for the order.

DynamicField_Status with the possibility to choose Approval.

Drag these fields from the Available Fields pool and drop into the Assigned Fields pool.

Note

In this screen all dynamic fields has the prefix DynamicField_ as in DynamicField_Title. Do not confuse with the field Title that is the ticket title.

Book Ordering - Add User Task Activity Dialog Fields

As soon as the fields are dropped into the Assigned Fields pool another popup screen is shown with some details about the field. We will leave the default options and only for Article fields we should make sure that the Communication Channel field is set to OTRS and that the Is visible for customer is not checked.

Book Ordering - Edit User Task Activity Dialog Fields

After all fields are filled in, click on the Save and finish button to save the changes and go back to the project management screen.

Create the following user task activity dialogs with fields:

Recording the demand (already created before)

Article field for comments.

DynamicField_Title, DynamicField_Author, DynamicField_ISBN fields for the data to be collected for the order.

DynamicField_Status with the possibility to choose Approval.

Approval denied

Article field for comments.

DynamicField_Status with the possibility to choose Approval denied.

Approved

DynamicField_Status with the possibility to choose Approved.

Order denied

Article field for comments.

DynamicField_Status with the possibility to choose Order denied.

Order placed

DynamicField_Supplier, DynamicField_Price, DynamicField_DeliveryDate fields for purchasing.

DynamicField_Status with the possibility to choose Order placed.

Shipment received

DynamicField_DateOfReceipt for the mail room.

DynamicField_Status with the possibility to choose Shipment received.

Create Sequence Flows

Click on the Sequence Flows item in the Available Process Elements widget in the left sidebar. This action will expand the Sequence Flows options and will collapse all others doing an accordion like effect. Click on the Create New Sequence Flow button.

Book Ordering - Sequence Flows

In the opened popup screen fill in the Sequence Flow Name. For this example in the Condition Expressions we will use just one condition expression and just one field. For both we can leave the Type of Linking as and and we will use the filed match type value as String.

Book Ordering - Add Sequence Flow

After all fields are filled in, click on the Save and finish button to save the changes and go back to the project management screen.

Create the following sequence flows:

Approval (already created before)

Check if the DynamicField_Status is set to Approval.

Approval denied

Check if the DynamicField_Status field is set to Approval denied.

Approved

Check if the DynamicField_Status field is set to Approved.

Order denied

Check if the DynamicField_Status field is set to Order denied.

Order placed

Check if the DynamicField_Status field is set to Order placed.

Shipment received

Check if the DynamicField_Status field is set to Shipment received.

Create Sequence Flow Actions

Click on the Sequence Flow Actions item in the Available Process Elements widget in the left sidebar. This action will expand the Sequence Flow Actions options and will collapse all others doing an accordion like effect. Click on the Create New Sequence Flow Action button.

Book Ordering - Sequence Flow Actions

In the opened popup screen fill in the Sequence Flow Action Name and the Sequence Flow Action module then click on the Save button. A new Configure button will appear next to the module field.

Book Ordering - Add Sequence Flow Action

Click on the Configure button and add the needed configuration parameter keys and values.

Book Ordering - Sequence Flow Action Parameters

After all fields are filled in, click on the Save and finish button to save the changes and go back to the project management screen.

See also

Each module has its own and different parameters. Please review the module documentation to learn all require and optional parameters.

DynamicFieldSet

TicketArticleCreate

TicketCreate

TicketCustomerSet

TicketLockSet

TicketOwnerSet

TicketQueueSet

TicketResponsibleSet

TicketSLASet

TicketSendEmail

TicketServiceSet

TicketStateSet

TicketTitleSet

TicketTypeSet

All sequence flow action modules are located in the legacy named Kernel/System/ProcessManagement/TransitionAction.

Create the following sequence flow actions:

Move the process ticket into the “Management” queue (already created before)

To be executed when the sequence flow Approval applied.

Change ticket responsible to “Manager”

To be executed when the sequence flow Approval applied.

Move process ticket into the “Employees” queue

To be executed when:

The sequence flow Approval denied applied.

The sequence flow Order denied applied.

The sequence flow Shipment received applied.

Change ticket responsible to “Employee”

To be executed when:

The sequence flow Approval denied applied.

The sequence flow Order denied applied.

The sequence flow Shipment received applied.

Move process ticket into the “Purchasing” queue

To be executed when the sequence flow Approved applied.

Move process ticket into the “Post office” queue

To be executed when the sequence flow Order placed applied.

Close ticket successfully

To be executed when the sequence flow Shipment received applied.

Close ticket unsuccessfully

To be executed when:

The sequence flow Approval denied applied.

The sequence flow Order denied applied.

There are places where the same sequence flow actions should be executed. Therefore it is reasonable to make it possible to link sequence flow actions freely with sequence flows to be able to reuse them.

Create Activities

Click on the Activities item in the Available Process Elements widget in the left sidebar. This action will expand the Activities options and will collapse all others doing an accordion like effect. Click on the Create New Activity button.

Book Ordering - Activities

In the opened popup screen fill in the Activity name field and select User task activity from the Activity type drop-down.

Book Ordering - Add Activity

To assign dialogs to the activity simple drag the required dialogs from the Available User Task Activity Dialogs pool and drop into the Assigned User Task Activity Dialogs pool. The order in the Assigned User Task Activity Dialogs pool is the order as the dialogs will be presented in the ticket detail view. To modify the order simply drag and drop the dialog within the pool to rearrange it in the correct place.

Note

This order is specially important in the first activity, since the first user task activity dialog for this activity is the only one that is presented when the process starts.

In this example we need to assign only the Recording the demand user task activity dialog. Drag this dialog from the Available User Task Activity Dialogs pool and drop into the Assigned User Task Activity Dialogs pool.

Book Ordering - Assign User Task Activity Dialog

After all fields are filled in, click on the Save and finish button to save the changes and go back to the project management screen.

Create the following activities:

Recording the demand (already created before)

Assign the user task activity dialog Recording the demand.

Approval

Assign the user task activity dialogs Approval denied and Approved.

Order

Assign the user task activity dialogs Order denied and Order placed.

Incoming

Assign the user task activity dialog Shipment received.

Process complete

This is an activity without possible user task activity dialogs. It will be set after Approval denied, Order denied or Shipment received and represents the end of the process.

Now we can clearly see that activities are precisely defined states of a process ticket. After a successful sequence flow a process ticket moves from one activity to another.

Create Process Path

Let us conclude our example with the last missing piece in the puzzle, the process as the a flow describer. In our case this is the whole ordering workflow. Other processes could be office supply ordering or completely different processes.

The process has a starting point which consists of the start activity and the start user task activity dialog. For any new book order, the first user task activity dialog of the first activity is the first screen that is displayed. If this is completed and saved, the process ticket will be created and can follow the configured workflow.

The process also contains the directions for how the process ticket can move through the process. Let’s call this process path. It consists of the start activity, one or more sequence flows (possibly with sequence flow actions) and other activities.

Assuming that the activities has already assigned their user task activity dialogs, drag an activity from the accordion in the Available Process Elements widget in the left sidebar and drop it into the canvas area below the process information. Notice that an arrow from the process start (white circle) to the activity is placed automatically. This is the first activity and its first user task activity dialog is the first screen that will be shown when the process starts.

Book Ordering - First Activity On Canvas

Next, drag another activity into the canvas too. Now we will have two activities in the canvas. The first one is connected to the start point and the second has no connections. You can hover the mouse over each activity to reveal their own activity dialogs.

Book Ordering - Second Activity On Canvas

Then let’s create the process path (connection) between this two activities. For this we will use the sequence flows. Click on sequence flow in the accordion, drag a sequence flow and drop it inside the first activity. As soon as the sequence flow is dropped the end point of the sequence flow arrow will be placed next to the process start point. Drag the sequence flow arrow end point and drop it inside the other activity to create the connection between the activities.

Book Ordering - First Sequence Flow On Canvas

Now that the process path between the actions is defined, then we need to assign the sequence flow actions to the sequence flow. Double click the sequence flow label in the canvas to open a new popup window.

Book Ordering - Assign First Sequence Flow Action

After the sequence flow actions are assigned, click on the Save button to go back to the main process edit screen. Click on Save button below the canvas to save all other changes.

Complete the process path by adding the following activities, sequence flows and sequence flow actions:

Recording the demand (already created before)

Possible sequence flow: Approval

Starting activity: Recording the demand

Next activity: Approval

If the condition of this activity is fulfilled, the ticket will move to activity Approval.

Additionally, the following sequence flow actions are executed:

Move the process ticket into the “Management” queue

Change ticket responsible to “Manager”

The activity Recording the demand is a defined step of the process ticket, where there is the possibility for the sequence flow Approval. If this applies, the ticket will move to the next activity Approval, and the sequence flow actions Move the process ticket into the “Management” queue and Change ticket responsible to “Manager” are executed. In the activity Approval, the user task activity dialogs Approval denied and Approved are available.

Approval

Possible sequence flow: Approval denied

Starting activity: Approval

Next activity: Process complete

If this matches, the process ticket will move to activity Process complete.

Additionally, the following sequence flow actions are executed:

Move process ticket into the “Employees” queue

Change ticket responsible to “Employee”

Close ticket unsuccessfully

Possible sequence flow: Approved

Starting activity: Approval

Next activity: Order

If this matches, the process ticket will move to activity Order.

Additionally, the following sequence flow actions are executed:

Move process ticket into the “Purchasing” queue

We can see that from the current activity, which defines a step of the process ticket, there are one or more possibilities for sequence flow which have exactly one target activity (and possibly one or more sequence flow actions).

Order

Possible sequence flow: Order denied

Starting activity: Order

Next activity: Process complete

If this matches, the process ticket will move to activity Process complete.

Additionally, the following sequence flow actions are executed:

Move process ticket into the “Employees” queue

Change ticket responsible to “Employee”

Close ticket unsuccessfully

Possible sequence flow: Order placed

Starting activity: Order

Next activity: Incoming

If this matches, the process ticket will move to activity Incoming.

Additionally, the following sequence flow actions are executed:

Move process ticket into the “Post office” queue

Incoming

Possible sequence flow: Shipment received

Starting activity: Incoming

Next activity: Process complete

If this matches, the process ticket will move to activity Process complete.

Additionally, the following sequence flow actions are executed:

Move process ticket into the “Employees” queue

Change ticket responsible to “Employee”

Close ticket successfully

The complete process path for the book ordering process will then look like this:

Book Ordering - Process Complete

After you finish the process path, click on Save and finish button below the canvas to go back to the process management screen.

Click on the Deploy All Processes button in the left sidebar. This will gather all processes information form the database and create a cache file (in Perl language). This cache file is actually the processes configuration that the system will use to create or use process tickets.

Note

Any change that is made on the process will require to re-deploy the process in order to get the change reflected in the system.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Web Services

In a connected world, a ticket system needs to be able to react to requests from other systems and also to send requests or information to other systems:

CRM systems

Project management systems

Documentation management systems

and many more

The ticket system must be reachable by other services without manual intervention by an agent.

OTRS supports this requirement by the Generic Interface. It empowers the administrator to create a web service for a specific task without scripting language knowledge. OTRS reacts on incoming REST or SOAP requests and create objects or provides object data to other systems transparently.

A web service is a communication method between two systems, in our case OTRS and a remote system. In its configuration, the operation or invoker determine the direction of communication, and the mapping and transport take care of how the data is received and interpreted.

In its configuration it can be defined what actions the web service can perform internally (operation), what actions the OTRS request can perform remote system (invokers), how data is converted from one system to the other (mapping), and over which protocol the communication will take place (transport).

The generic interface is the framework that makes it possible to create web services for OTRS in a predefined way, using already made building blocks that are independent from each other and interchangeable.

Use this screen to manage web services in the system. A fresh OTRS installation contains no web service by default. The web service management screen is available in the Web Services module of the Processes & Automation group.

Web Service Management Screen

Manage Web Services

To create a web service:

Click on the Add Web Service button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Create New Web Service Screen

To edit a web service:

Click on a web service in the list of web services.

Modify the fields.

Click on the Save or Save and finish button.

Edit Web Service Screen

To delete a web service:

Click on a web service in the list of web services.

Click on the Delete Web Service button in the left sidebar.

Click on the Delete button in the confirmation dialog.

Delete Web Service Screen

To clone a web service:

Click on a web service in the list of web services.

Click on the Clone Web Service button in the left sidebar.

Enter a new name for the web service.

Clone Web Service Screen

To export a web service:

Click on a web service in the list of web services.

Click on the Export Web Service button in the left sidebar.

Choose a location in your computer to save the Export_ACL.yml file.

Warning

All stored passwords in the web service configuration will be exported in plain text format.

To see the configuration history of a web service:

Click on a web service in the list of web services.

Click on the Configuration History button in the left sidebar.

Web Service Configuration History Screen

To use the debugger for a web service:

Click on a web service in the list of web services.

Click on the Debugger button in the left sidebar.

Web Service Debugger Screen

To import a web service:

Click on the Add Web Service button in the left sidebar.

Click on the Import Web Service button in the left sidebar.

Click on the Browse… button in the dialog.

Select a previously exported .yml file.

Add a name for the imported web service (optional). Otherwise the name will be taken from the configuration file name.

Click on the Import button.

Web Service Settings

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

General Web Service Settings

Web Service Settings - General

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.

Description

Like comment, but longer text can be added here.

Remote system

Debug threshold

The default value is Debug. When configured in this manner all communication logs are registered in the database. Each subsequent debug threshold value is more restrictive and discards communication logs of lower order than the one set in the system.

Debug threshold levels (from lower to upper):

Debug

Info

Notice

Error

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.

Provider Web Service Settings

Web Service Settings - OTRS as Provider

Network transport

Select which network transport would you like to use with the web service. Possible values are HTTP::REST and HTTP::SOAP.

Note

After selecting the transport method, you have to save the configuration with clicking on the Save button. A Configuration button will be displayed next to this field.

Configuration

The Configuration button is visible only, after a network transport was selected and saved. See the configuration for OTRS as Provider - HTTP::REST and OTRS as Provider - HTTP::SOAP below.

Add Operation

This option is visible only, after a network transport was selected and saved. Selecting an operation will open a new screen for its configuration.

Web Service Settings - OTRS as Provider - Operation

OTRS as Provider - HTTP::REST

Web Service Settings - OTRS as Provider - HTTP::REST

OTRS as Provider - HTTP::SOAP

Web Service Settings - OTRS as Provider - HTTP::SOAP

Requester Web Service Settings

Web Service Settings - OTRS as Requester

Network transport

Select which network transport would you like to use with the web service. Possible values are HTTP::REST and HTTP::SOAP.

Note

After selecting the transport method, you have to save the configuration with clicking on the Save button. A Configuration button will be displayed next to this field.

Configuration

The Configuration button is visible only, after a network transport was selected and saved. See the configuration for OTRS as Requester - HTTP::REST and OTRS as Requester - HTTP::SOAP below.

It is possible to use both object and array format as a JSON response of the remote system. However, in the case it is an array, system stores it as an object internally, where ArrayData is used as a key and a value is an array. Because of that, responded JSON array can be mapped efficiently, but has to be considered as an object described above (key is ArrayData, but * can also be used as wildcard).

Add error handling module

This option is visible only, after a network transport was selected and saved. Selecting an operation will open a new screen for its configuration.

Web Service Settings - OTRS as Provider - Error Handling Module

OTRS as Requester - HTTP::REST

Web Service Settings - OTRS as Requester - HTTP::REST

OTRS as Requester - HTTP::SOAP

Web Service Settings - OTRS as Requester - HTTP::SOAP

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Agent Interface

Completely new user interface has been developed for agents. This setting makes it possible to edit the agent styles that are selectable for all agents.

Contents

Styles

Manage Styles

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Styles

Use this screen to manage styles and choose style variants for use in agent interface. A fresh OTRS installation already contains some variants by default. The style management screen is available in the Styles module of the Agent Interface group.

Agent Style Management Screen

The management screen consists of two widget. In the Edit Styles widget can be selected the styles for editing. The Defaults widget defines, which variant will be used as default for the agent interface. The agents can override this setting and they can select a different variant in they personal preferences, but they can not edit the styles.

Manage Styles

Styles are grouped into four categories: Bright, High Contrast Bright, Dark and High Contrast Dark.

To edit a style, select a category first. The edit screen will be opened for the selected category.

The Edit Layout section is the same for all categories.

Agent Style Layout Edit Screen

The following settings are available when adding or editing this resource.

Enable

Select whether the style is available for agents.

Header Logo

The logo is a small image that is displayed in the header of all pages.

To change the logo, click on the Select image to upload button, and select a new logo image. Recommended file format is PNG.

Favicon

The favorite icon is an icon that is displayed in the URL bar of the web browser.

To change the favorite icon, click on the Select image to upload button, and select a new icon. This is usually a 16×16 pixel image in PNG or ICO format.

Some categories contain different variants. Each variant can be customize in the same manner.

Agent Style Variant

The following settings are available when adding or editing this resource.

Enable

Select whether the variant is available for agents.

Name

The name of this resource. Any type of characters can be entered to this field including uppercase letters and spaces.

Primary Color

This color will be used as the background color of primary buttons and the color of textual links and hovered icons.

To change the primary color, just select a new color from the color palette. You can chose from the pre-selected colors or define other colors by choosing it from the color selector or typing the hexadecimal value. The new color will be displayed in the preview widget immediately.

Secondary Color

This color will be used as the background color of table rows and the color of icon links.

To change the secondary color, just select a new color from the color palette. You can chose from the pre-selected colors or define other colors by choosing it from the color selector or typing the hexadecimal value. The new color will be displayed in the preview widget immediately.

Prominent Color

This color will be used as the background color of the organizer sidebar.

To change the prominent color, just select a new color from the color palette. You can chose from the pre-selected colors or define other colors by choosing it from the color selector or typing the hexadecimal value. The new color will be displayed in the preview widget immediately.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

External Interface

The need to transport valuable information about service to users is a major one for a service desk. Not always is it possible or plausible to do this via a corporate internet. The customers of a service desk need a one-stop solution for all their service needs.

OTRS provides access to create and manage demands, as well as receive valuable information such as the service catalog and knowledge base.

The following chapter describes the administration tools needed to implement corporate identity and manage language-based content.

Contents

Customer Service Catalogue

Manage Categories

Category Settings

Manage Items

Item Settings

Custom Pages

Manage Custom Pages

Custom Page Settings

Home Page

Hero Unit

Ticket List

Image Teasers

Link Lists

Content Cards

Layout

Include Custom Scripts

Web Analytics Example

Cookies and Local Storage

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Customer Service Catalogue

Use this screen to add categories and items for use in external interface. A fresh OTRS installation doesn’t contain any categories or items by default. The catalogue management screen is available in the Customer Service Catalogue module of the External Interface group.

This module consists of two management screens: a category management screen and an item management screen.

Customer Service Catalogue Management Screen

Manage Categories

Use this screen to add categories to collect the same items into groups. The Category Management screen in available via the Go to category management button or via the Category Management module.

Category Management Screen

To add a category:

Click on the Add Category button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Category Screen

To edit a category:

Click on a category in the list of categories.

Modify the fields.

Click on the Save or Save and finish button.

Edit Category Screen

To delete a category:

Click on the trash icon in the Delete column of the overview table.

Click on the Confirm button.

Delete Category Screen

Note

If several categories are added to the system, use the filter box to find a particular category by just typing the name to filter.

Category Settings

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

Title *

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.

Sub-category of

It is possible to add the new category under an existing one as sub-category. This will be displayed as Parent Category::Child Category.

Language *

Select a language from the available languages of the system.

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.

Manage Items

Use this screen to add items to the catalogue. Items can be collected into categories. The Item Management screen in available via the Go to item management button or via the Item Management module.

Item Management Screen

To add an item:

Click on the Add Item button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Item Screen

To edit an item:

Click on an item in the list of items.

Modify the fields.

Click on the Save or Save and finish button.

Edit Item Screen

To delete an item:

Click on the trash icon in the Delete column of the overview table.

Click on the Confirm button.

Delete Item Screen

Note

If several items are added to the system, use the filter box to find a particular item by just typing the name to filter.

Item Settings

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

Internal Title *

The name of this resource, that is only displayed in the administrator interface. Any type of characters can be entered to this field including uppercase letters and spaces. The name will be displayed in the overview table.

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.

Item Content

In this widget can be added some localized content for the item.

Title *

The name of this resource in the given language. Any type of characters can be entered to this field including uppercase letters and spaces.

Text *

The text for this item in the given language.

Categories

One ore more categories can be selected for the item in which the item should be visible.

Note

Only those categories can be selected, that have the same language as the selected language for this widget.

Link *

A link to an internal or an external URL.

Add new item content

Select which languages should be added to create localized item content. All added languages can hold its own localized content, that are explained above.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Custom Pages

Use this screen to add custom pages for use in external interface. A fresh OTRS installation already contains some custom pages by default. The custom page management screen is available in the Custom Pages module of the External Interface group.

Custom Page Management Screen

Manage Custom Pages

Warning

Make sure to save your changes when you finish. The new configuration will be immediately deployed.

To add a custom page:

Click on the Add Custom Page button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Custom Page Screen

To edit a custom page:

Click on a custom page in the list of custom pages.

Modify the fields.

Click on the Save or Save and finish button.

Edit Custom Page Screen

To delete a custom page:

Click on the trash icon in the fourth column of the overview table.

Click on the Confirm button.

Delete Custom Page Screen

Note

If several custom pages are added to the system, use the filter box to find a particular custom page by just typing the name to filter.

Custom Page Settings

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

Internal Title *

The name of this resource, that is only displayed in the administrator interface. Any type of characters can be entered to this field including uppercase letters and spaces. The name will be displayed in the overview table.

Slug *

This will be the URL of the custom page. Recommended characters are lowercase letters, numbers and minus sign.

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.

Custom Page Content

In this widget can be added some localized content for the item.

Title *

The name of this resource in the given language. Any type of characters can be entered to this field including uppercase letters and spaces.

Content *

The text for this item in the given language.

Add new custom page content

Select which languages should be added to create localized item content. All added languages can hold its own localized content, that are explained above.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Home Page

Use this screen to define home page configuration for different user languages, that are displayed in the external interface. The home page management screen is available in the Home Page module of the External Interface group.

This screen contains several widget for each languages, where localized content can be added.

Warning

Make sure to save your changes when you finish. The new configuration will be immediately deployed.

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

Hero Unit

Hero Unit Widget

Title

This is the most important sentence or motto of the home page.

Background Style

Define the behavior of background image and background color. The following options are available:

Only use the background image

Only use the background color

Use the background image and overlay it with the selected color

Background Image

Select an image used as background image for the hero unit. To select an image, click on the Select image to upload button and chose an image from your file system.

Background Color

To change the background color, just select a new color from the color palette. You can chose from the pre-selected colors or define other colors by choosing it from the color selector or typing the hexadecimal value.

Ticket List

Ticket List Widget

Show a ticket list for logged in users

This setting defines if the ticket list should be visible for logged in users or not.

Row Title

This is an optional title for the row, that contains this widget in the external interface.

Image Teasers

The image teasers are displayed in a separate row in the external interface.

Image Teasers Widget

Row Title

This is an optional title for the row, that contains this widget in the external interface.

Row Background Color

To change the background color, just select a new color from the color palette. You can chose from the pre-selected colors or define other colors by choosing it from the color selector or typing the hexadecimal value.

You can add up to three image teasers by clicking on the Add button in the top right corner of the widget.

Image Teaser

Image

Select an image to display it in the image teaser widget. To select an image, click on the Select image to upload button and chose an image from your file system.

Title *

The heading text that are displayed in this item.

Text *

The text for this item.

Link Target *

An URL that will be opened after clicking on this item in the external interface.

Link Lists

The link lists are displayed in a separate row in the external interface.

Link Lists Widget

Row Title

This is an optional title for the row, that contains this widget in the external interface.

You can add up to four link lists by clicking on the Add button in the top right corner of the widget.

Link List

Title *

The heading text that are displayed in this item.

Link Text

Add the text for the show more link.

Link Target

Add the URL for the show more link.

Link List Type *

Specifies the functionality how the item will be added.

Add the Items Manually

Clicking on the edit button a new widget will be visible to add the items.

Add the Items Manually

Show the Results of a Search

Clicking on the edit button a new widget will be visible to add the items.

Show the Results of a Search

Content Cards

The link lists are displayed in a separate row in the external interface.

Content Cards Widget

Row Title

This is an optional title for the row, that contains this widget in the external interface.

You can add up to three content cards by clicking on the Add button in the top right corner of the widget.

Content Card

Title *

The heading text that are displayed in this item.

Text *

The text for this item.

Link Text

Add the text for the show more link.

Link Target

An URL that will be opened after clicking on this item in the external interface.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Layout

Use this screen to edit the layout displayed in external interface. The layout management screen is available in the Layout module of the External Interface group.

Edit Layout Screen

A fresh OTRS installation already contains a default layout. In this screen all parameters can be changed.

Warning

Make sure to save your changes when you finish. The new configuration will be immediately deployed.

Logo

The logo is a small image that is displayed in the top left corner of the external pages.

To change the logo, click on the Select image to upload button, and select a new logo image. Recommended file format is PNG.

Favicon

The favorite icon is an icon that is displayed in the URL bar of the web browser.

To change the favorite icon, click on the Select image to upload button, and select a new icon. This is usually a 16×16 pixel image in PNG or ICO format.

Primary Color

Primary color is the most important color of the external pages (see the preview screen).

To change the primary color, just select a new color from the color palette. You can chose from the pre-selected colors or define other colors by choosing it from the color selector or typing the hexadecimal value. The new color will be displayed in the preview widget immediately.

Highlight Color

Highlight color is the second color of the external pages using for status badges, links, etc.

To change the highlight color, just select a new color from the color palette. You can chose from the pre-selected colors or define other colors by choosing it from the color selector or typing the hexadecimal value. The new color will be displayed in the preview widget immediately.

Default Avatar

Will be used as the default avatar for all outgoing communication.

To change the avatar, click on the Select image to upload button, and select a new avatar image.

Custom CSS

Use this text area to add custom CSS to be applied in the external interface.

Custom CSS Widget

Include Custom Scripts

External interface application has been built with security-first mindset in place. It contains several mechanisms to make sure that all code in the front end is provided directly by the OTRS framework.

In addition, a security standard called Content Security Policy headers is now leveraged by the built-in web server. It serves as a last line of defense and in case some unexpected code still makes it to the client, it will make sure that the user’s browser simply refuses to run it.

However, a use-case still exists in which even a modern web application might still need to run some additional code, provided it is vetted and included by the administrators. One example could be an external integrated chat solution, but could also be an inline code snippet used for external web analytics.

See also

Including custom scripts can be done in the System Configuration with the following settings:

ExternalFrontend::ExternalScripts

ExternalFrontend::InlineScripts

WebApp::Server::AdditionalOrigins

Web Analytics Example

In this example, we outline the steps to include custom scripts used by a web analytics provider in the external interface application. They will be run each time the application is used in order to track and report the behavior of the user for later analysis.

We start with the provided code snippet below, from a third party provider.

<script async src="https://www.example.com/track/js?id=UA-XXXXXX-Y"></script>
<script>
   window.dataLayer = window.dataLayer || [];
   function track(){dataLayer.push(arguments);}
   track('js', new Date());

   track('config', 'UA-XXXXXX-Y');
</script>

First line of the snippet refers to an external resource which should be loaded by the script tag.

In the script block below, we have some inline code which is run immediately when the page is loaded.

Adding External Script Resources

First, we need to include the external script location in the appropriate configuration:

Go to the System Configuration screen.

Search for the setting ExternalFrontend::ExternalScripts.

Click on the setting in order to edit it.

In case a value is already present, click on the plus button. Otherwise, proceed below.

Enter the full location of the external resource in the text field. For example: https://www.example.com/track/js?id=UA-XXXXXX-Y.

Click on the check mark in order to save the modified setting.

Deploy the modified system configuration.

Adding Inline Code Snippets

Next, we have to also include the inline part of the original snippet:

Go to the System Configuration screen.

Search for the setting ExternalFrontend::InlineScripts.

Click on the setting in order to edit it.

In case a value is already present, click on the plus button. Otherwise, proceed below.

Enter the full code snippet in the text area, minus any script tags. For example:

window.dataLayer = window.dataLayer || [];
function track(){dataLayer.push(arguments);}
track('js', new Date());

track('config', 'UA-XXXXXX-Y');

Click on the check mark in order to save the modified setting.

Deploy the modified system configuration.

Rebuilding the External Interface Application

In order to apply the changes, we also need to rebuild the external interface application. Drop down to shell, and execute the following command:

bin/otrs.WebServer.pl --deploy-assets

Whitelisting Additional Origins in the Security Headers

If you now try to access the external interface application, you will be able to verify that the scripts are included in the code. However, your browser will probably block access to all inline and external resources, therefore the code might fail with some errors.

This behavior is by design, since external resources can only be loaded if they are specifically whitelisted in the Content Security Policy headers.

To check for blocked code, please use suitable web browser inspection tools. In our example, we will be using Mozilla Firefox and its web console available via Tools → Web Developer → Web Console menu item, or via the F12 shortcut key.

For the example code snippet, you might receive following errors in the console when the application is accessed:

Browser Console Errors and Warnings

From the console errors we can see that the external script resource was prevented from being loaded (lines 1 and 3). In addition to that, two evaluation calls were also blocked (lines 2 and 5). All errors reference a Content Security Policy rule under the name of script-src, which signals script resources.

We need to add both the external resource and the evaluation calls to the additional origins list of the Content Security Policy headers:

Go to the System Configuration screen.

Search for the setting WebApp::Server::AdditionalOrigins.

Click on the setting in order to edit it.

In case a value for script-src is already present, click on the plus button next to it. Otherwise, proceed below.

Enter the domain part only of the blocked resource in the text field. For example: https://www.example.com. This allows the external resource to be loaded.

Click on the plus button next to the field, so another value is added.

Enter the following directive in the new field, including the quotes: 'unsafe-eval'. This allows the evaluation calls to be executed.

Click on the check mark in order to save the modified setting.

Deploy the modified system configuration.

There is no need to rebuild the external interface application at this point, as the additional origins configuration should be immediately in effect.

If you reload the external interface application, you might get some additional errors. In our example, it might be the following:

Additional Browser Console Errors and Warnings

This error points that an additional resource that was also blocked, an image at a specific location (line 1). We can deduce this via the name of the Content Security Policy rule img-src, which references an image resource. In order to add it to the whitelist, try the following:

Go to the System Configuration screen.

Search for the setting WebApp::Server::AdditionalOrigins.

Click on the setting in order to edit it.

In case a value for img-src is already present, click on the plus button next to it. Otherwise, proceed below.

Enter the domain part only of the blocked resource in the text field. For example: https://www.example.com. This allows the external image resource to be loaded.

Click on the check mark in order to save the modified setting.

Deploy the modified system configuration.

Try again to reload the external interface application and check if there are more errors. If not, your scripts are now probably working as expected.

Unfortunately, it is not possible to predict what kind of resources your scripts might be requiring. But, no worries, you can whitelist most of them, just make sure to follow the trail of hints shown in the browser console log. Find a corresponding header rule in the configuration and update it accordingly.

Note

Some resources might only be requested by others, hence several iterations might be needed until everything is configured properly.

Warning

Whitelisting external resources opens potential security risks in your OTRS application! Only allow those resources that you are sure are not malicious and come from reputable sources. Keep in mind that if something is secure today, does not mean it will be tomorrow. Stay safe!

Cookies and Local Storage

The applications need cookies and local storage for proper working. Both the cookie and the local storage are stored on the user’s computer. This storage does not include personal data, they are only needed for the operation of the application.

The only cookie stored when the user visits the external interface is AuthenticationCustomer. This cookie stores the session ID of the logged in customer user and has a lifetime of 16 hours.

Additionally, the following key-value pairs are stored in the web browser’s local storage:

Plugins/Store/PublicChat/External/MutationsSharerStorage = {
    "type": "Plugins/Store/PublicChat/External/publicUuid",
    "payload": {
        "publicUuid": "<uuid-string>"
    }
}
Plugins/Store/LoggerOptions/External = {
    "logLevel": "info",
    "logRecord": false
}
Plugins/Store/PublicChat/External/MutationsSharerNotification = notification-<notification-id>
Apps/External/Plugins/Store = {
    "accessToken": null,
    "deviceUuid": null,
    "isLanguageSet": false,
    "language": "en",
    "passwordExpirySoonWarning": null
}
Apps/External/Plugins/Store/MutationsSharerStorage = {
    "type": "language",
    "payload": {
        "language": "en"
    }
}
Apps/External/Plugins/Store/PrivacyNotice = {
    "isNoticeVisible": true
}
Apps/External/Plugins/Store/MutationsSharerNotification = notification-<notification-id>
Plugins/Store/PerlProfiler/External = {
    "perlProfiler": {}
}
Plugins/Store/PublicChat/External = {
    "publicUuid": "<uuid-string>"
}

The UUID values in the local storage are auto-generated when the user visits the external interface for the first time. The local storage has no expiration date and stores data used for the application itself. Additional notification entries might get spawned during the usage, and are used to sync the data state across multiple instances of the application.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

OTRS Group Services

A strong partner is good to have when dealing with mission-critical systems. Whether it be maintenance or for consuming cloud services, your partner should be tightly integrated.

The following chapter describes the tools you have available to integrate your system with the powerful cloud service offered by the OTRS Group.

Contents

Cloud Services

Manage Cloud Services

Activate SMS Cloud Service

Support Data Collector

Manage Support Data Collector

Collected Data

Cloud Services Section

Database Section

Document Search Section

Operating System Section

OTRS Section

System Registration

Manage System Registration

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Cloud Services

Use this screen to add cloud services to the system. A fresh OTRS installation doesn’t contain any configured cloud services by default. The cloud service management screen is available in the Cloud Services module of the OTRS Group Services group.

Cloud Service Management Screen

Manage Cloud Services

Activate SMS Cloud Service

To be able to use SMS cloud service in OTRS, you have to activate it first. To activate the SMS cloud service:

Click on the Activate SMS Cloud Service button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Cloud Service Screen

Configuration

The following settings are available when adding an SMS cloud service. The fields marked with an asterisk are mandatory.

Phone field for agent *

Agent data field from which the mobile phone number for sending messages via SMS should be taken.

Phone field for customer *

Customer data field from which the mobile phone number for sending messages via SMS should be taken.

Sender string *

Will be shown as sender name of the SMS (Not longer than 11 characters).

Allowed role members

If selected, only agents assigned to these roles will be able to receive notifications via SMS.

Perform URL shortening

Perform URL shortening before sending the message.

Phone black list

A blacklist of telephone numbers where it is forbidden to send SMS messages to. Phone numbers must be added in international format without spaces, e.g. +491791234567, one number per field.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

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.

Data Protection Information

In order to be able to use the SMS transmission feature of the OTRS AG, the Data Protection Information needs to be read and understood.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Support Data Collector

Support data collector is used to collect some data and sent to OTRS Group on a regular basis, if the system is registered.

Use this screen to review the data to be sent to OTRS Group. The support data collector screen is available in the Support Data Collector module of the OTRS Group Services group.

Download Support Bundle Screen

Manage Support Data Collector

Support data collector is used to collect some data and sent to OTRS Group on a regular basis, if the system is registered. To register your system:

Click on the System Registration button in the left sidebar.

Follow the registration instructions.

To show what kind of data will be sent:

Click on the Show transmitted data button in the left sidebar.

Review the System Registration Data and Support Data in the newly opened screen.

To manually trigger the support data sending:

Click on the Send Update button in the left sidebar.

To generate a support bundle:

Click on the Generate Support Bundle button in the left sidebar.

Download the generated support bundle.

Open it with an archive manager and review the content.

Download Support Bundle Dialog

Collected Data

The screen contains several sections. Each section has some entries with a traffic light, that indicates the following:

Gray LED means information, just displays a value.

Green LED means OK, the entry has a good value.

Yellow LED means notification, you have to check the value, but it is not an error.

Red LED means error, you have to do something to solve the issue.

Cloud Services Section

This section displays information about OTRS cloud services.

Available SMS

This entry shows information about your available SMS messages. If they are getting low, the LED changes to red.

Database Section

This section displays information about the database used by OTRS.

Outdated Tables

Display the outdated database tables. Green LED means, there are no outdated tables.

Table Presence

Display whether all needed tables exist in the database or not.

Client Connection Charset

Display the character set for the client connection. It must be utf8.

Server Database Charset

Display the character set of the database server. It must be utf8.

Table Charset

Display the character set of the database table. It must be utf8.

InnoDB Log File Size

Display the log file size for InnoDB driver. It must be at least 512 MB.

Invalid Default Values

Display the invalid default values. Green LED means, there are no invalid default values.

Maximum Query Size

Display the maximum size of a database query. It must be at least 1024 MB.

Database Size

Display the size of database. This is just an information.

Default Storage Engine

Display the default storage engine of the database. It must be InnoDB.

Table Storage Engine

Display the storage engine of the database tables. It must be InnoDB.

Database Version

Display the database driver version. Green LED means, the version is high enough.

Document Search Section

This section displays information about document search and the used cluster.

Cluster

The name of the used cluster.

Cluster Health Details

Display some internal variables of the used cluster.

Indices Health

Display information about indices.

Indices Size

Display the size of each index.

Node Health

Display information about the used node.

Operating System Section

This section displays information about the running operating system and installed software components.

Environment Dependencies

Display information about environment dependencies.

OTRS Disk Partition

Display the disk partition to where OTRS is installed.

Information Disk Partitions Usage

Display the used space per disk partitions.

Distribution

Display the distribution name of the operating system.

Kernel Version

Display the kernel version of the operating system.

System Load

Display the system load of the operating system. The system load should be at maximum the number of CPUs the system has (e.g. a load of 8 or less on a system with 8 CPUs is OK).

Perl Version

Display the version of Perl.

Free Swap Space (%)

Display the free swap space as percentages. There should be more than 60% free swap space.

Used Swap Space (MB)

Display the used swap space in megabytes. There should be no more than 200 MB swap space used.

OTRS Section

This section displays information about the OTRS instance.

Article Search Index Status

Display information about indexed articles.

Articles Per Communication Channel

Display the number of articles per communication channels.

Communication Log

Display aggregated information about communications.

Communication Log Account Status (last 24 hours)

Display information about communication log account status in the last 24 hours.

Concurrent Users Details

Display information about the logged in users at the same time separated by hourly.

Concurrent Users

Display information about the number of maximum logged in users in the same time.

Config Settings

Display some important configuration settings from system configurations.

Daemon

Display whether the OTRS daemon is running or not.

Database Records

Display the main OTRS object and the related number of records in the database.

Default Admin Password

Green LED means, that the default administrator password was changed.

Email Sending Queue

Display the number of emails that are queued for sending.

FQDN (Domain Name)

Display the fully qualified domain name set in system configuration setting FQDN.

File System Writable

Display whether the file system is writable or not.

Legacy Configuration Backups

Green LED means, there are no legacy configuration backup files found.

Package Installation Status

Green LED means, that all packages are installed correctly.

Package Framework Version Status

Green LED means, that the OTRS framework version is suitable for the installed packages.

Package Verification Status

Green LED means, that all installed packages are verified by the OTRS Group.

Package List

Display the list of installed packages.

Push Events Status

Display the status of the push events per day.

Session Config Settings

Display the maximum allowed sessions per agents and customers.

Spooled Emails

Display the number of emails that are in the sending pool.

SystemID

Display the system identifier set in system configuration setting SystemID.

Invalid Users with Locked Tickets

Display the number of users, who are set to invalid, but have some ticket locked for him.

Open Tickets

Display the number of open tickets in the system. You will not have performance trouble until you have about 60,000 open tickets in your system.

Ticket Search Index Module

Display the ticket search index module set in system configuration setting Ticket::SearchIndex::ForceUnfilteredStorage.

Time Settings

Display timezone information for OTRS, for the calendars and for users.

UI - Agent Skin Usage

Display the used skins per agents.

UI - Agent Theme Usage

Display the used theme on the agent interface.

UI - Special Statistics

Display some statistics about personal modifications like using favorites, custom menu ordering, etc.

OTRS Version

Display the version number of OTRS.

WebSocket Connection

Display connection status for WebSocket connections.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

System Registration

If the free trial or the registration period is expired, the system will lock itself. In these cases you have to register your system or you have to extend the registration.

Use this screen to register your system with the OTRS Group. The registration screen is available in the System Registration module of the OTRS Group Services group.

Un-Registred System Screen

Manage System Registration

To register your system:

Obtain an OTRS ID. You have to register in the OTRS Portal. After the registration you will get your OTRS ID.

Go to the System Registration module of the OTRS Group Services group, and enter your OTRS ID and your password.

System Registration - Add OTRS ID

Click on the Next button.

Select the system type and enter a description.

System Registration - Select System Type

Click on the Register button.

Check your registration.

Registered System

To edit the system registration:

Click on the Edit details button in the left sidebar.

Modify the system type and the description.

Click on the Update button.

Edit System Registration Screen

To show the transmitted data:

Click on the Show transmitted data button in the left sidebar.

Review the data in JSON format.

Overview of Transmitted Data Screen

See also

Detailed explanation of the fields is available in the Support Data Collector chapter.

To overview the registered system:

Click on the Overview of registered systems button in the left sidebar.

Log in to the OTRS Portal.

Review the list of registered systems.

To deregister a system:

Click on the Deregister system button in the left sidebar.

Note

You can’t deregister your system if you’re using the STORM powered by OTRS™ or having a valid service contract.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Chat

The chat feature allows the agents to provide real time communication with each other, with customer users or with public users. The chat feature is enabled by default.

Contents

Chat Channels

Manage Chat Channels

Chat Channel Settings

Manage Chat Support

Chat Integration

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Chat Channels

Being able to offer chat possibilities to customers is a must-have for many organizations. Depending on the amount of customer chat requests and the organization’s structure, it must be possible to group chat requests.

OTRS offers chat channels with different permissions per channel, so it is, e.g. possible to have different chat channels for registered contract customers and public prospects.

Use this screen to add chat channels to the system. A fresh OTRS installation already contains a chat channel by default. The chat channel management screen is available in the Chat Channels module of the Chat group.

Chat Channel Management Screen

Manage Chat Channels

To add a chat channel:

Click on the Add Chat Channel button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add Chat Channel Screen

Warning

Chat channels can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a chat channel:

Click on a chat channel in the list of chat channels.

Modify the fields.

Click on the Save or Save and finish button.

Edit Chat Channel Screen

Chat Channel Settings

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

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.

Group *

Select which Groups can access the chat channel.

Available to customer users

Select the checkbox if you want to display the chat channel for customer users.

Available to public users

Select the checkbox if you want to display the chat channel for public users.

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.

Comment

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

Manage Chat Support

Note

The chat feature is enabled by default.

To enable or disable the chat feature:

Go to System Configuration screen.

Navigate to Core → Chat in the navigation tree.

Enable or disable the setting ChatEngine::Active.

When the chat feature is enabled, the Default channel is automatically created if it does not exist.

To review all chat related settings:

Go to System Configuration screen.

Search for the term ChatEngine in the search box.

Review the settings.

See also

Agents need to have at least ro permissions to the groups set up in the following settings:

ChatEngine::PermissionGroup::ChatReceivingAgents

ChatEngine::PermissionGroup::ChatStartingAgents

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Chat Integration

You can easily integrate the public chat into a website. Just copy the code snippets from here. If you would like to make any adaptations, please modify the fields in the configuration widget. All changes are applied immediately to the snippet, so you can make your changes and copy the snippet to your clipboard afterwards. Please note that changes made on this page are not remembered.

Use this screen to generate the chat integration code. The chat integration configuration and snippet generator is available in the Chat Integration module of the Chat group.

To configure the chat and generate code snippet:

Select a pre-selected chat channel in the Pre-selected channel field.

Select a primary color for the chat design.

Customize the texts in the Texts section.

Chat Integration – Configuration

Note

All changes made in the Configuration tab will not be saved. Every time you open this dialog, all fields will be reset to default values.

You can check the result in the Preview widget.

Chat Integration – Preview

Note

The preview uses the real chat module. Other agents have to be available for chatting to preview all features.

Copy the code snippet from the Integration Code widget and paste it into your website right before the </body> element.

Chat Integration – Integration Code

If mixed content warning is displayed in the browser console, an administrator has to check that the system configuration setting HttpType is properly set. The website must run on the same protocol for chat widget to work.

For example, if the website is running OTRS on SSL, the system configuration option must be set to https.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Administration

Any system requires configuration. Configuring a system should be an easy task and the tools for configuration fit-for-purpose.

OTRS offers several administration tools to configure, monitor, control and extend OTRS.

Contents

Calendars

Manage Calendars

Calendar Settings

General Calendar Settings

Calendar Ticket Appointments

Import Appointments

FAQ Category

Manage FAQ Categories

FAQ Category Settings

FAQ Language

Manage FAQ Languages

FAQ Language Settings

Package Manager

Manage Packages

Install Packages

Update Packages

Reinstall Packages

Uninstall Packages

Performance Log

Session Management

Manage Sessions

SQL Box

Query SQL statements

SQL Settings

SQL Examples

System Configuration

Manage System Configurations

Using The Navigation Tree

Import And Export System Configurations

Business Object Configuration

Business Object Lists

Business Object Detail Views

Forms

Business Cards

Business Object Reference

Column Names

Filter Names

Filter Value Types

Form Fields

System Log

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Calendars

When working with customers, resource planning and scheduling can be a complex task. Appointments enable you to meet your customers where and whenever needed.

OTRS supports this requirement with calendars. Calendars allow management of appointments and resources inside the ticket system. You can connect your tickets to scheduled tasks and make them available to all users to see. This feature adds transparency to show your teams workload and prevent users from promising resources which are not available.

Use this screen to manage calendars in the system. A fresh OTRS installation contains no calendars by default. The calendar management screen is available in the Calendars module of the Administration group.

Calendar Management Screen

Manage Calendars

To add a new calendar:

Click on the Add Calendar button in the left sidebar.

Fill in the required fields.

Click on the Save button.

Add New Calendar Screen

Warning

Calendars can not be deleted from the system. They can only be deactivated by setting the Validity option to invalid or invalid-temporarily.

To edit a calendar:

Click on a calendar in the list of calendars.

Modify the fields.

Click on the Save or Save and finish button.

Edit Calendar Screen

To export a calendar:

Click on the export icon in the list of calendars.

Choose a location in your computer to save the Export_Calendar_CalendarName.yml file.

To import calendars:

Click on the Browse… button in the left sidebar.

Select a previously exported .yml file.

Click on the Overwrite existing entities checkbox, if you would like to overwrite the existing calendars.

Click on the Import Calendar button.

Note

If several calendars are added to the system, use the filter box to find a particular calendar by just typing the name to filter.

Calendar Settings

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

General Calendar Settings

Calendar 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.

Color *

The calendar color that will be displayed in the calendar overview screens.

To change the calendar color, just select a new color from the color palette. You can chose from the pre-selected colors or define other colors by choosing it from the color selector or typing the hexadecimal value.

Permission group *

Select which Groups can access the calendar.

Depending on the group field, the system will allow users the access to the calendar according to their permission level.

Read only: users can see and export all appointments in the calendar.

Move into: users can modify appointments in the calendar, but without changing the calendar selection.

Create: users can create and delete appointments in the calendar.

Read/write: users can manage the calendar itself.

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.

Calendar Ticket Appointments

Define rules for creating automatic appointments in this calendar based on ticket data. To add a new rule, click on the Add Rule button.

Calendar Settings - Ticket Appointments

Start date

Select a start date for the ticket appointment.

End date

Select the end date for the ticket appointment.

Queues *

Select one or more queues to narrow down for which tickets appointments will be automatically created.

Search attributes

Additional search attributes can be added for further filtering by selecting an attribute and clicking on the ⊞ button.

By default, these events can trigger an update of a calendar appointment:

TicketSLAUpdate

TicketQueueUpdate

TicketStateUpdate

TicketCreate

ArticleCreate

TicketPendingTimeUpdate

TicketDynamicFieldUpdate_.*

Import Appointments

If at least one calendar have been added to the system, it is possible to import some appointments into the calendar.

To import some appointments:

Click on the Import Appointments button in the left sidebar.

Upload an iCal file and select a calendar.

Click on the Import appointments button.

Import Appointments Screen

Upload *

Click on the Browse… button, and select a valid iCal (.ics) file to upload.

Calendar *

Select an available calendar.

Note

If desired calendar is not listed here, please make sure that you have at least create permissions.

Update existing appointments?

If checked, all existing appointments in the calendar with same UniqueID will be overwritten.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

FAQ Category

Use this screen to manage categories available in the knowledge base articles. A fresh OTRS installation already contains a category by default. The category management screen is available in the FAQ Category module of the Administration group.

FAQ Category Management Screen

Manage FAQ Categories

To add a category:

Click on the Add category button in the left sidebar.

Fill in the required fields.

Click on the Submit button.

Add Category Screen

To edit a category:

Click on a category in the list of categories.

Modify the fields.

Click on the Submit button.

Edit Category Screen

To delete a category:

Click on the trash icon in the list of categories.

Click on the Yes button in the confirmation dialog.

Delete Category Screen

FAQ Category Settings

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

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.

Subcategory of

It is possible to add the new category under an existing one as sub-category. This will be displayed as Parent Category::Child Category.

Permission *

Agent groups that can access articles in this category.

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.

Comment *

Add additional information to this resource. It is recommended to always fill this field as a description of the resource with a full sentence for better clarity, because the comment will be also displayed in the overview table.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

FAQ Language

Use this screen to manage languages available in the knowledge base articles. A fresh OTRS installation already contains some languages by default. The language management screen is available in the FAQ Language module of the Administration group.

FAQ Language Management Screen

Manage FAQ Languages

To add a language:

Click on the Add language button in the left sidebar.

Fill in the required field.

Click on the Submit button.

Add Language Screen

To edit a language:

Click on a language in the list of languages.

Modify the field.

Click on the Submit button.

Edit Language Screen

To delete a language:

Click on the trash icon in the list of languages.

Click on the Yes button in the confirmation dialog.

Delete Language Screen

FAQ Language Settings

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

Name *

The ISO 639-1 code of a language.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Package Manager

Modular systems can be extended by adding additional software packages to the framework. Administrators need an easy way to see which features are installed in which version and for sure to add, update and remove packages.

OTRS uses a package manager to perform all package-related activities as mentioned above in the graphical interface.

Note

This module is only available when using On-Premise or the ((OTRS)) Community Edition. To see a list of installed modules, you may also see the Support Data Collector.

Use this screen to install and manage packages that extend the functionality of OTRS. The package manager screen is available in the Package Manager module of the Administration group.

Package Manager Screen

Manage Packages

Warning

The installation of packages which are not verified by the OTRS Group is not possible by default.

See also

You can activate the installation of not verified packages in the system configuration setting Package::AllowNotVerifiedPackages.

Install Packages

To install a package from online repository:

Select an online repository from the drop-down in the left sidebar.

Click on the Update repository information button to refresh the available package list.

Select a package from the Online Repository widget and click on the Install in the last column.

Follow the installation instructions.

After installation, the package is displayed in the Local Repository widget.

Online Repository Widget

See also

The repository list can be changed in system configuration setting Package::RepositoryList.

To install a package from file:

Click on the Browse… button in the left sidebar.

Select an .opm file from your local file system.

Click on the Install Package button.

Follow the installation instructions.

After installation, the package is displayed in the Local Repository widget.

Local Repository Widget

Update Packages

To update a package from online repository:

Check the available packages in the Online Repository widget if there is Update in the Action column.

Click on the Update link.

Follow the update instructions.

After updating, the package is displayed in the Local Repository widget.

To update a package from file:

Click on the Browse… button in the left sidebar.

Select an .opm file which is newer than the installed package.

Click on the Install Package button.

Follow the update instructions.

After updating, the package is displayed in the Local Repository widget.

To update all packages:

Click on the Update all installed packages button in the left sidebar.

Follow the update instructions.

After updating, the package is displayed in the Local Repository widget.

This feature reads the information of all defined package repositories and determines if there is a new version for every installed package in the system and calculates the correct order to update the packages respecting all other package dependencies, even if new versions of existing packages require new packages not yet installed in the system.

Note

If there are packages installed that do not have a corresponding repository defined in the system, they can not be updated by this feature and will be marked as failed (due to the missing on-line repository).

Reinstall Packages

If at least one of the package files are modified locally, the package manager marks the package as broken, and need to reinstall.

To reinstall a package:

Select the package from the Local Repository widget that are marked for reinstall.

Click on the Reinstall link in the Action column.

Follow the installation instructions.

Uninstall Packages

To uninstall a package:

Select the package from the Local Repository widget.

Click on the Uninstall link in the Action column.

Follow the uninstall instructions.

Local Repository Widget

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Performance Log

Performance is always a crucial topic for web-based applications. Administrators need to have the possibility to see which activities use which time to execute over time to identify potential increases over time and take proper measures.

OTRS supports this requirement with the performance log. The performance log can, when it is activated, log activities and display various activity types and their min/max/average response time and a number of requests for different time frames.

Use this screen to view the performance log of OTRS. The log overview screen is available in the Performance Log module of the Administration group.

Note

To be able to see performance log in OTRS, you have to enabled its setting first.

Enable Performance Log Support

If the performance log is enabled, OTRS collects all the information about requests and responses in an overview table.

Performance Log Screen

Clicking on an entry will show the details.

Performance Log Details Screen

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Session Management

Administrators of web-based applications need to have access to the information who’s connected to the system and, if required, delete unwanted sessions.

OTRS offers the session management to quickly get an overview of agent and customer sessions, unique agents and customers currently logged in and the ability to kill sessions with just a mouse click.

Use this screen to manage logged in user sessions in the system. The session management screen is available in the Session Management module of the Administration group.

Session Management Screen

The first widget lists sessions and tokens. Sessions are used for logins to the administrator interface, while logins to the agent interface, to the external interface or to the generic interface use tokens.

The widget List of tokens (one time only) shows special one time tokens used for the password recovery and two-factor setup. These tokens are short-lived and can be used for only a single action.

Manage Sessions

To see a logged in user session:

Select a logged in user from the list of sessions.

Click on the token.

See the details.

Session Management Details Screen

To kill a session:

Select a logged in user from the list of sessions.

Click on the Kill this session link in the Kill column.

Session Kill Screen

Note

The current administrator session is displayed with a darker gray row background. This allows you to identify your own session in the list easier.

Warning

Clicking the Kill this session link removes the session immediately without confirmation. The unsaved work of the user will be lost!

To kill all sessions:

Click on the Kill all sessions button in the left sidebar.

Warning

Clicking the Kill all session link removes all sessions or tokens immediately without confirmation. The unsaved work of the users will be lost!

Note

If several users are logged in to the system, use the filter box to find a particular session by just typing the name to filter.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

SQL Box

Note

This feature is not enabled by default. Activate the system configuration setting Frontend::Module###AdminSelectBox to enable this feature.

In a ticket system, it is usually possible to have statistics that show a summarized view of ticket information when needed. Sometimes, it is however required to access the database directly to have even more individual reports, allow external statistic tools to query information from the system or perform in-depth analysis of a ticket behavior.

Direct access to the database requires access to the command line which an administrator may not have. In addition to the username and password for the command line access, which is not given by all organizations, the username and password for the database are needed. These hurdles can prevent an administrator from using the database for more complex searches and operations.

OTRS offers application administrators the SQL Box in the graphical interface. It allows read access to the database. All results can be seen in the GUI or exported to CSV/Excel files.

Use this screen to query SQL statements in the system. The SQL box screen is available in the SQL Box module of the Administration group.

SQL Box Screen

Query SQL statements

Note

The SQL statements entered here are sent directly to the application database. By default, it is not possible to change the content of the tables, only SELECT queries are allowed.

Warning

It is possible to modify the application database via SQL box. To do this, you have to enabled the system configuration setting AdminSelectBox::AllowDatabaseModification. Activate it to your own risk!

To execute an SQL statement:

Enter the SQL statement into the SQL box.

Select the result format.

Click on the Run Query button.

SQL Box Widget

SQL Settings

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

SQL *

The SQL statement to be queried.

Limit

Enter a number to limit the result to at most this number of rows. Leaving this field empty means there is no limit.

Note

Don’t use LIMIT inside the SQL statement. Always use this field to limit the number of results.

Result format

The format of the SQL statement result.

HTML

The results are visible below the SQL box in a new widget.

CSV

The results can be downloaded in comma separated plain text format.

Excel

The results can be downloaded as Microsoft Excel spreadsheet.

SQL Examples

To list some information about agents and output the results as HTML:

SELECT id, login , first_name, last_name, valid_id FROM users

SQL Box Result

To list all tables, you need to leave empty the Limit field and run the following query:

SHOW TABLES

To show the structure of the users table, you need to limit the results to 1 and run the following query (see the table header for the columns):

SELECT * FROM users

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

System Configuration

Modern systems have many ways to configure their behavior. Some use configuration files edited on the command line, and some use a graphical interface (and save the information to configuration files in the background), yet others use a database. Maintaining changes and auditing can sometimes be an issue, as it is not always clear who made a change. Making bulk changes is not always possible, and rolling back changes a chore.

OTRS uses a comfortable graphical interface to configure the system. All changes to the default system configuration are stored in the database and can be audited (who changed a setting and when, what was the old and what is the new value) and rolled back to a previous state in case of misconfiguration.

Comfortable search allows finding the needed settings quickly and easily.

See also

By using the System Configuration History package, you can easily roll back changes made by users. Contact sales@otrs.com to add this feature to your system.

Use this screen to manage the system configuration settings. OTRS brings about 1750 configuration settings. The system configuration management screen is available in the System Configuration module of the Administration group.

Manage System Configurations

Note

For security reasons, the configuration settings for the database connection cannot be changed in the graphical user interface of the system configuration. These have to be set manually in Kernel/Config.pm.

To modify a system configuration, you need to do several steps. The following example shows you, how to find, modify, deploy and reset the system configuration FirstnameLastnameOrder.

Find the system configuration by entering a search term lastname into to search box.

With the full-text search, all configuration settings can be scanned for one or more keywords. The full-text search not only searches through the names of the configuration settings, but also the descriptions and values. This allows an element to be found easily even if its name is unknown.

System Configuration - Search For Setting

Select the setting from the search results.

System Configuration - Setting Found

Click on the header of the widget to see the options.

System Configuration - Setting Expanded

Hover the mouse over the widget body to see the Edit this setting button.

System Configuration - Setting Hovered

Click on the Edit this setting button to activate the edit mode. In edit mode the widget gets an orange border on the left.

Note

If a setting is currently edited by another administrator, it is not possible to get access to the edit mode for that setting until the other administrator finished their work.

System Configuration - Setting Clicked

Change the value of the setting. Editing can be cancelled by clicking the Cancel button on the right or hitting the Escape key on your keyboard. When editing is cancelled, all changes made during the current editing session are discarded.

System Configuration - Setting Modified

Click on the Save button. If the modification is saved, the widget gets a green border on the left.

System Configuration - Setting Saved

Go back and click on the Deployment button in the left sidebar. You are also notified in the notification bar, that you have undeployed settings.

System Configuration - Setting Changes

Review the changes.

You can click on the ⇄ button in the top right corner to compare the changes side-by-side.

System Configuration - Setting Different

Click on the Deploy selected changes button. If several settings are changed, it is possible to deploy only the selected settings.

Add a deployment comment, that explain for other administrators, what is changed and why. Use full sentence here.

System Configuration - Deploy Setting

Go back and search again the term lastname to find the modified setting. The widget has a gray border on the left to indicate, this setting is modified.

System Configuration - Setting Deployed

To reset the setting, click on the header of the widget to see the options. Then click on the Reset setting button.

System Configuration - Reset Setting

Click on the Confirm button.

Deploy the settings.

Using The Navigation Tree

Each configuration setting is classified by a category and a navigation group. Navigation groups are individual elements in the main navigation tree. By selecting one of these navigation entries, all settings assigned to the selected group will be shown. As long as no extensions are installed, the category selection is automatically hidden, but as soon as a package is installed which brings its own configuration settings (such as ITSM modules or Survey), the category selection will be revealed. Selecting a category makes the main navigation tree show only the navigation groups belonging to the selected category.

System Configuration Navigation Tree

To expand an element, click on the arrow next to it. The number between the parentheses indicates how many settings belongs to this element. If an element has no number, this element is only a wrapper category. It doesn’t have settings, it has only sub-categories.

Using the navigation tree results the same as search for a setting. If you would like to see for a setting to which group belongs to, expand it by clicking on the header of the widget.

System Configuration - Setting Expanded

For example FirstnameLastnameOrder can be found in Frontend → Base.

Import And Export System Configurations

Click on the Import & Export button in the left sidebar to access the import-export screen.

System Configuration - Import and Export

To export the system configurations:

Click on the Export current configuration button in the Export widget.

Save the Export_Current_System_Configuration.yml file to your local file system.

Rename the file to a more descriptive name.

To import the system configurations:

Click on the Browse… button in the Import widget.

Select a previously exported .yml file.

Click on the Import system configuration button.

Business Object Configuration

The following section contains a description of the business object configuration, including the business object lists, business object detail views, business cards and forms.

Business Object Lists

The business object lists provide a tabular view of items with support for configurable columns, sorting and filtering. These lists can be used in many contexts, including as stand-alone screens, widgets, actions, etc.

The default configuration of business object lists can be defined in several places, depending on the screen or element where they are used.

AgentFrontend::<BusinessObjectListType>::<SlugName>###DefaultConfig

Standalone or static list screens which are usable via their own URL.

An Example of the Unlocked Tickets Screen

The following system configuration settings are relevant:

AgentFrontend::KnowledgeBaseArticleList::Static###DefaultConfig

AgentFrontend::KnowledgeBaseArticleList::Added###DefaultConfig

AgentFrontend::KnowledgeBaseArticleList::Updated###DefaultConfig

AgentFrontend::KnowledgeBaseArticleList::Rated###DefaultConfig

AgentFrontend::KnowledgeBaseArticleList::Custom1###DefaultConfig

AgentFrontend::KnowledgeBaseArticleList::Custom2###DefaultConfig

AgentFrontend::KnowledgeBaseArticleList::Custom3###DefaultConfig

AgentFrontend::KnowledgeBaseArticleList::Custom4###DefaultConfig

AgentFrontend::KnowledgeBaseArticleList::Custom5###DefaultConfig

AgentFrontend::TicketList::Static###DefaultConfig

AgentFrontend::TicketList::Unresolved###DefaultConfig

AgentFrontend::TicketList::Unlocked###DefaultConfig

AgentFrontend::TicketList::Reminders###DefaultConfig

AgentFrontend::TicketList::Escalations###DefaultConfig

AgentFrontend::TicketList::Created###DefaultConfig

AgentFrontend::TicketList::Closed###DefaultConfig

AgentFrontend::TicketList::Queues###DefaultConfig

AgentFrontend::TicketList::Legacyservice###DefaultConfig

AgentFrontend::TicketList::Legacystatus###DefaultConfig

AgentFrontend::TicketList::Legacyescalations###DefaultConfig

AgentFrontend::TicketList::Legacyresponsible###DefaultConfig

AgentFrontend::TicketList::Legacywatcher###DefaultConfig

AgentFrontend::TicketList::Custom1###DefaultConfig

AgentFrontend::TicketList::Custom2###DefaultConfig

AgentFrontend::TicketList::Custom3###DefaultConfig

AgentFrontend::TicketList::Custom4###DefaultConfig

AgentFrontend::TicketList::Custom5###DefaultConfig

BusinessObjectListType

Type of the business object list to use.

Possible values for the BusinessObjectListType key:

TicketList
KnowledgeBaseArticleList

SlugName

Determines the search engine-friendly URL part via which the screen is available.

Note

Currently only single word search engine-friendly URL parts are supported. Also note that the first character of the search engine-friendly URL part will always be converted to lower case variant, for example:

AgentFrontend::TicketList::Static => /agent/tickets/static
AgentFrontend::TicketList::Unresolved => agent/tickets/unresolved
AgentFrontend::TicketList::Reminders => agent/tickets/reminders
AgentFrontend::KnowledgeBaseArticleList::Added => agent/knowledge-base-articles/added

AgentFrontend::WebNotificationList###DefaultConfig

The default configuration for the Web Notifications list.

An Example of the Web Notifications List Screen

Link to the reference of the system configuration:

AgentFrontend::WebNotificationList###DefaultConfig

AgentFrontend::Search###DefaultConfig

The default configuration for the Search Results list.

An Example of the Search Results List Screen

Link to the reference of the system configuration:

AgentFrontend::Search###DefaultConfig

AgentFrontend::TicketList::ArticlePreview###DefaultConfig

The default configuration for the Article Preview in the Ticket list.

An Example of the Article Preview in the Ticket List Screen

Link to the reference of the system configuration:

AgentFrontend::TicketList::ArticlePreview###DefaultConfig

AgentFrontend::*###DefaultConfig

The default configuration for the inline business object lists. Inline list tables are shown as part of several actions like Merge Ticket, Link Objects or Append to Ticket.

An Example of the Link Objects Action in the Ticket Detail View

The following system configuration settings are relevant:

AgentFrontend::Merge::Ticket###DefaultConfig

AgentFrontend::LinkObject::Ticket###DefaultConfig

AgentFrontend::LinkObject::KnowledgeBaseArticle###DefaultConfig

AgentFrontend::LinkObject::CalendarAppointment###DefaultConfig

AgentFrontend::Chat::AppendToTicket###DefaultConfig

AgentFrontend::*AddressBookList*###DefaultConfig

The default configuration for the Customer User and Customer address book screens. The address books allow contextual adding of customer and customer user records to target form fields.

An Example of the Customer User Address Book List Screen

The following system configuration settings are relevant:

AgentFrontend::CustomerUserAddressBookList::Email###DefaultConfig

AgentFrontend::CustomerUserAddressBookList::SMS###DefaultConfig

AgentFrontend::CustomerCompanyAddressBookList###DefaultConfig

Each business object list setting has a Config key which contains its configuration.

See also

The detailed explanation of the possible Config key values can be found in the Business Object List YAML Configuration chapter.

YAML Configuration Basics

Before we delve too deeply into the business object configuration, it is important to explain the YAML syntax which is heavily used for some of the setting values.

YAML (a recursive acronym for YAML Ain’t Markup Language) is a human-readable data-serialization language. It is commonly used for configuration files, but it can describe data structures of arbitrary complexity.

Although YAML supports many of them, only a few data types are used in the context of OTRS configuration:

Scalar

This is the most basic data type; it could be a number, a string, or a boolean expression. Sometimes it is also referred to as a value.

Number: 42
String1: Foo
String2: 'Foo bar'
String3: "Foo bar Xyzzy"
Boolean1: 1
Boolean2: 0

Note

Scalar data type is never used on its own, but it is always part of another higher-level structure.

List

List contains an arbitrary number of items which can be of any data type. Sometimes it is also referred to as an array.

Each item in a list is divided from others by a separator in the form of a minus sign followed by a single space.

List1:
- Item1
- Item2
- Item3

It is recommended that list items are indented via a minus sign followed by a single space. This style is used throughout this guide and default configuration.

Warning

In YAML, the number of spaces is important. The number of spaces used for indentation must always be consistent, otherwise unexpected structures or syntax errors can occur.

Note

To define an empty list, you can use the square bracket syntax:

EmptyList: []

Object

Object is a data type consisting of key/value pairs, separated by the colon punctuation mark. Sometimes it is also referred to as a hash.

Object key is always on the left side of the colon punctuation mark, while the value is always on its right side (or indented below):

Object1:
  Key1: Value1
  Key2: Value2
  Key3: Value3

It is recommended that object key/value pairs are indented with two spaces. This style is used throughout this guide and default configuration.

Warning

In YAML, the number of spaces is important. The number of spaces used for indentation must always be consistent, otherwise unexpected structures or syntax errors can occur.

Note

To define an empty object, you can use the curly brackets syntax:

EmptyObject: {}

To signal that a text uses YAML syntax, it is recommended to add a document header to its first line that consists of three consecutive minus signs, followed by the line break. By doing this consistently, it becomes very easy to identify YAML structures when mixed with other configurations.

With the three basic data types explained above, it is possible to create more complex structures. For example, an array of hashes:

---
Array:
- Key1: A
  Key2: B
  Key3: C
- Key1: 1
  Key2: 2
  Key3: 3
- Key1: I
  Key2: II
  Key3: III

Note

In a list that contains multiple object keys, only the first key must be prefixed with the minus sign followed by a space. Each subsequent key must be prefixed with two spaces.

The following example illustrates the usage of a hash of arrays:

---
Hash:
  Key:
    Subkey1:
    - Item1
    - Item2
    - Item3
    Subkey2:
    - Item4
    - Item5
    - Item6

Note

If the object keys are separated by other structures, it is important to keep them on the same indentation level. Since they are all siblings, they must be prefixed by the same number of spaces.

It is also possible to mix the data types that result in more complex data structures:

---
Key1:
- Subkey1: Value1
- Subkey2: Value2
Key2: Value3
Key3:
  Subkey3:
  - Value4
  - Value5

YAML supports comments in its code, so it is possible to include additional text that will be ignored during parsing. This is useful in case users need to describe certain parts of the structure, perhaps for future reference, or to quickly ignore part of the code without actually removing it.

Comments can be marked with #. Any following text will be ignored.

---
# This is a comment
Key: Value # This is another comment
# Key2: Value 2

In the example above, the last line will be ignored too since it starts with #.

If you actually want to use the pound sign as part of your string of values, simply enclose the complete string in quotes.

---
String: 'Comments start with # character'

When you edit an OTRS system setting with the YAML value type, a suitable text editor will be displayed.

System Setting with a YAML Value

When saving the setting, the YAML structure will be checked for validity. In case of an error, it is possible to change and correct the structure.

Error in a YAML Structure

It is important to understand that only the syntax of the structure is checked during validation. A deep validation will not occur. It is your responsibility as an administrator to ensure that the configuration you specify is correct.

Warning

The most common errors that occur are related to indentation. You have to ensure that your indentations are consistent, especially the indentations of the different data types. For example, the following two structures are considered different.

---
Object:
   Key:
      Subkey: Value

---
Object:
   Key:
   Subkey: Value

Since the Subkey in the second example is not aligned properly within its parent Key, it is considered to be its sibling part and not a child. In this case the actual value of the Key will be empty.

Business Object List YAML Configuration

A business object list YAML configuration can have many parameters. The following example shows how to construct a business object list in general.

Type: BusinessObject
BusinessObjectType: Ticket
ScreenTitle: <Some Screen Title>
Changeable: 1
FilterPresets:
  "<Displayed Filter Preset Name>":
    <FilterName1>:
      Value: <Value>
    <FilterName2>:
      Value:
      - <Value1>
      - <Value2>
    <FilterName3>:
      Value:
        <Parameter1>: <Value1>
        <Parameter2>: <Value2>
  ...
ActiveFilters:
  <FilterName1>:
    Value: <Value>
  <FilterName2>:
    Value:
    - <Value1>
    - <Value2>
  <FilterName3>:
    Value:
      <Parameter1>: <Value1>
      <Parameter2>: <Value2>
      ...
  ...
AllowGETConfig:
- <ConfigurationName1>
- <ConfigurationName2>
- ...
Columns:
  <ColumnName1>:
    IsVisible: 0|1|2
    IsInlineEditable: 0|1
  ...
DefaultColumnOrder:
- <ColumnName1>
- <ColumnName2>
- ...
HideAvailableFilters:
- <FilterName1>
- <FilterName2>
- ...
ItemsPerPage: 10
Limit: 1000
SortBy:
- Column: <ColumnName>
  Direction: Down|Up
- ...
AvailableDynamicFieldFilters:
- <FilterName1>
- <FilterName2>
- ...

The following YAML keys and values can be used for business object lists.

Type

Defines the type of the setting. This is an internal value which is always set to BusinessObject and must not be changed.

Warning

Changing this value might result in a broken system configuration.

BusinessObjectType

Defines the business object type of the business object list. This is an internal value which is specific for the current list type and must not be changed.

Warning

Changing this value might result in a broken system configuration.

ScreenTitle

Defines the title of the business object list.

Note

In some places, you may notice # translatable comments that are displayed next to the text values. This marker is only used for the internal collection of translatable strings and has no effect in the changed settings. Adding this comment to modified values will not result in the actual text translation.

The visible text in the configuration can be translated into other languages with custom translation files. For more information, see the Custom Translation File chapter in the developer manual.

Changeable

Defines whether the business object list can be personalized by the user in the front end. If turned off, the view configuration will not be available and also filter presets for the view cannot be saved. The value can be 1 (on) or 0 (off). The assumed default is off when the key is not used in the definition.

FilterPresets

Defines the pre-defined filters used for the business object list. Multiple filters can be defined here. The filter value can be a string, array or a hash. The following YAML snippet shows examples for all types.

FilterPresets:
  Closed:
    StateType:
      Value: Closed
  Locked:
    LockIDs:
      Value:
      - 2
  "Reminder Reached":
    TicketPending_DateTimeRelative:
      Value:
        Format: minute
        Point: 1
        Start: Before

See also

The list of possible filter names can be found in the Filter Names chapter.

ActiveFilters

Defines the filters that are active when displaying the business object list. Multiple filters can be added here; each is defined by the filter name. The filter value can be a string, array or a hash. The following YAML snippet shows examples for both.

ActiveFilters:
  StateType:
    Value: Closed
  TicketClose_DateTimeRelative:
    Value:
      Start: Before
      Point: 1
      Format: minute

See also

The list of possible filter names can be found in the Filter Names chapter.

AllowGETConfig

Defines what parameters can be changed via the URL with the Config URL query parameter:

AllowGETConfig:
- VisibleColumns
- SortBy
- ActiveFilters
- FilterPresets
- ItemsPerPage
- FilterPresetSelected

The list should contain names of other configuration keys for which definition will be allowed when passed via the correct URL query parameter to the view.

See also

For an example and more information, please see the section about Custom URL Support.

Columns

Defines the columns that are available for the business object list in the front end.

IsVisible

Defines whether the column is not visible (0), not visible by default but the agent can make it visible (1) or visible by default (2).

IsInlineEditable

Defines whether the value in the column is inline editable (1) or not (0).

See also

The list of possible column names can be found in the Column Names chapter.

DefaultColumnOrder

Defines the default column order in the business object list.

HideAvailableFilters

Defines the filters which are not available for the agents in the front end, either in the view configuration or in the filter presets.

ItemsPerPage

Defines the number of objects per page that are displayed by default and the number of new objects that are loaded when the agent scrolls down the list. If omitted, it takes the default value of 10. Although there is no upper limit, it is not advisable to set the value greater than 100 for performance reasons.

Limit

Defines the maximum amount of displayed objects in a business object list. Most of the list types in the system are limited to an upper boundary of 10,000 objects for performance reasons.

SortBy

Defines the sorting criteria and the sorting order of the objects in the business object list.

AvailableDynamicFieldFilters

Defines the list of dynamic fields by name which are available as filters.

Business Object Detail Views

The business object detail views can be organized into several families.

The following settings define the default column layout configuration for the detail view screens.

An Example of the Ticket Detail View

The following system configuration settings are relevant:

AgentFrontend::CustomerCompanyDetailView###001-Framework

AgentFrontend::CustomerUserDetailView###001-Framework

AgentFrontend::KnowledgeBaseArticleDetailView###001-Framework

AgentFrontend::TicketDetailView###001-Framework

The following settings define the default column layout configuration for the business object overview screens.

An Example of the Dashboard Screen

The following system configuration settings are relevant:

AgentFrontend::CalendarOverview###001-Framework

AgentFrontend::Dashboard###001-Framework

AgentFrontend::StatisticReportOverview###001-Framework

The following settings define the default column layout configuration for the business object create screens.

An Example of the Create Email Ticket Screen

The following system configuration settings are relevant:

AgentFrontend::CustomerCompanyCreate###001-Framework

AgentFrontend::CustomerUserCreate###001-Framework

AgentFrontend::KnowledgeBaseArticleCreate###001-Framework

AgentFrontend::StatisticCreateUpdateView###001-Framework

AgentFrontend::StatisticReportCreateUpdateView###001-Framework

AgentFrontend::TicketCreate::Email###001-Framework

AgentFrontend::TicketCreate::Phone###001-Framework

AgentFrontend::TicketCreate::Process###001-Framework

AgentFrontend::TicketCreate::SMS###001-Framework

The following settings define the custom column layout configurations for adding additional widgets to a specific view. By default, these are empty settings. If additional widgets are added to them, they will be merged with the remaining settings for the corresponding view.

The following system configuration settings are relevant:

AgentFrontend::CalendarOverview###100-Custom

AgentFrontend::CustomerCompanyCreate###100-Custom

AgentFrontend::CustomerCompanyDetailView###100-Custom

AgentFrontend::CustomerUserCreate###100-Custom

AgentFrontend::CustomerUserDetailView###100-Custom

AgentFrontend::Dashboard###100-Custom

AgentFrontend::KnowledgeBaseArticleCreate###100-Custom

AgentFrontend::KnowledgeBaseArticleDetailView###100-Custom

AgentFrontend::StatisticCreateUpdateView###100-Custom

AgentFrontend::StatisticReportCreateUpdateView###100-Custom

AgentFrontend::StatisticReportOverview###100-Custom

AgentFrontend::TicketCreate::Email###100-Custom

AgentFrontend::TicketCreate::Phone###100-Custom

AgentFrontend::TicketCreate::Process###100-Custom

AgentFrontend::TicketCreate::SMS###100-Custom

AgentFrontend::TicketDetailView###100-Custom

Each of the above settings has the same key structure:

Type

Type of the business object screen.

Possible values for the Type key:

BusinessObjectCreate
BusinessObjectDetailView
BusinessObjectOverview

BusinessObjectType

Business object type behind the screen.

Possible values for the BusinessObjectType key:

CustomerCompany
CustomerUser
Dashboard
KnowledgeBaseArticle
Statistic
StatisticReport
Ticket

ColumnLayout

The YAML configuration for different column views.

See also

The detailed explanation of the ColumnLayout key can be found in the Business Object Detail View YAML Configuration chapter.

Business Object Detail View YAML Configuration

The YAML structure defines the content for the one, two or three column views. The definition contains the information about which widgets are displayed per default in each view.

 OneColumn:
   1:
   - Name: <WidgetName1>
   - Name: <WidgetName2>
   ...
 TwoColumns:
   1:
   - Name: <WidgetName1>
   - Name: <WidgetName2>
   ...
   2:
   - Name: <WidgetName3>
   - Name: <WidgetName4>
   ...
 ThreeColumns:
   1:
   - Name: <WidgetName1>
   - Name: <WidgetName2>
   ...
   2:
   - Name: <WidgetName3>
   - Name: <WidgetName4>
   ...
   3:
   - Name: <WidgetName5>
   - Name: <WidgetName6>
   ...
StripeSidebar:
- Name: StripePeople
...

Note

The sidebar is only available for business objects of type Ticket.

Available widget names depend on the specific business object screen.

CalendarOverview

Possible widget names for the Calendar Overview screen.

AppointmentsToday
AppointmentsThisWeek
AppointmentsThisMonth

CustomerCompanyCreate

Possible widget names for the Add Customer screen.

CreateProperties

CustomerCompanyDetailView

Possible widget names for the Customer detail view screen.

CustomerInformation
CustomerUserList
EscalatedTickets
OpenTickets
ReminderTickets
TicketList

CustomerUserCreate

Possible widget names for the Add Customer User screen.

CreateProperties

CustomerUserDetailView

Possible widget names for the Customer User detail view screen.

CustomerInformation
EscalatedTickets
OpenTickets
ReminderTickets
TicketList

Dashboard

Possible widget names for the Dashboard screen.

CalendarView
CustomerList
CustomerUserList
DashboardIframe
DashboardImage
DashboardPeople
EscalatedTickets
KnowledgeBaseArticleList
News
OpenTickets
QueueOverview
RecentlyUpdatedKnowledgeBaseArticles
ReminderTickets
TicketList
UnlockedTickets

KnowledgeBaseArticleCreate

Possible widget names for the Add Knowledge Base Article screen.

CreateProperties

KnowledgeBaseArticleDetailView

Possible widget names for the Knowledge Base Article detail view screen.

KBAAttachments
KBAItemField1
KBAItemField2
KBAItemField3
KBAItemField4
KBAItemField5
KBAItemField6
KBALinkedObjects::CalendarAppointment
KBALinkedObjects::KnowledgeBaseArticle
KBALinkedObjects::Ticket
KBAProperties
KBARating
People

StatisticCreateUpdateView

Possible widget names for the Create Statistic and Edit Statistic screens.

CreateUpdateProperties

StatisticReportCreateUpdateView

Possible widget names for the Create Report and Edit Report screens.

CreateUpdateProperties

StatisticReportOverview

Possible widget names for the Statistics and Reports overview screen.

StatisticLists
StatisticMetrics
StatisticReportList
StatisticStatic

TicketCreate::Email

Possible widget names for the Create Email Ticket screen.

CreateProperties
CustomerHistory
CustomerInformation
CustomerUserHistory

TicketCreate::Phone

Possible widget names for the Create Phone Ticket screen.

CreateProperties
CustomerHistory
CustomerInformation
CustomerUserHistory

TicketCreate::SMS

Possible widget names for the Create SMS Ticket screen.

CreateProperties
CustomerHistory
CustomerInformation
CustomerUserHistory

TicketCreate::Process

Possible widget names for the Create Process Ticket screen.

CreatePropertiesProcess
ProcessInformation

TicketDetailView

Possible widget names for the ticket detail view screen.

Attachments
BusinessProcessInformation
CommunicationCompact
CommunicationStream
CustomerInformation
FormDrafts
LinkedObjects::CalendarAppointment
LinkedObjects::KnowledgeBaseArticle
LinkedObjects::Ticket
People
Properties

Widget Type Definitions

Each widget type provides its own definition that will be inherited by any widget that uses it. For example, let’s take a look how this definition looks for one of the dashboard widget types:

An Example of the Ticket List Widget Type in the Dashboard Screen

The configuration of this widget type is located in the AgentFrontend::Dashboard::WidgetType###TicketList system configuration setting in YAML format.

A widget type definition contains the following general YAML keys:

Type: BusinessObject
BusinessObjectType: Ticket
ActiveFilters: {}
FilterPresets: {}
Columns: {}
Collapsed: 0
Hidden: 0

Type

Defines whether the related widget type handles a business object or other data. BusinessObject is currently the only supported type, but this might be extended by installed packages.

BusinessObjectType

This key defines the type of object the configuration is valid for. Based on this type, the front end and the back end will handle this object differently. New business object types may also be added by installed packages.

ActiveFilters

This key defines the default filters that are active when displaying the business object list. It contains a hash of filters. A single filter also has a hash structure that normally contains a filter value. The value can be a string, array or hash for special filters like dates.

ActiveFilters:
  <FilterName1>:
    Value:
      <Value>
  <FilterName2>:
     Value:
       <Value>

The following example illustrates two active filters which are showing only tickets that were closed recently:

ActiveFilters:
  StateType:
    Value: Closed
  TicketClose_DateTimeRelative:
    Value:
      Start: Before
      Point: 1
      Format: minute

See also

The list of possible filter names can be found in the Filter Names chapter.

FilterPresets

A hash of default filter preset names with a defined set of filters.

FilterPresets:
  "<Filter Preset Name 1>":
     <FilterName1>:
        Value: <Value>
  "<Filter Preset Name 2>":
     <FilterName2>:
        Value: <Value>

The following example illustrates three separate filter presets: locked, unlocked and unread tickets.

FilterPresets:
  Locked:
    LockIDs:
      Value:
      - 2
  Unlocked:
    LockIDs:
      Value:
      - 1
  Unread:
    AgentTicketFlagSeen:
      Value: Unread

See also

The list of possible filter names can be found in the Filter Names chapter.

Widget Definitions

Each widget provides its own definition that will be merged with the configuration of the inherited widget type. For example, let’s take a look at what this definition looks like for one of the widgets in the customer business object detail view:

An Example of the Reminder Tickets Widget in the Customer Detail View

The configuration of this widget is located in the AgentFrontend::CustomerCompanyDetailView::Widget###ReminderTickets system configuration setting in YAML format.

A widget definition contains the following general YAML keys:

Title: Reminders # Translatable
Active: 1
IsVisible: 1
IsAlwaysPresent: 0
IsDuplicatable: 1
Config: {}

Active

Defines whether the widget is active.

Collapsed

Defines whether the form group is collapsed by default.

Config

This key contains the complete default configuration of a widget. If left empty, the configuration of the widget type is used.

Hidden

Defines whether the widget is hidden.

IsVisible

Defines whether the widget is visible per default.

IsAlwaysPresent

Defines whether the widget can be removed from a view by the user.

IsDuplicatable

Defines whether the widget can be placed in a view multiple times.

Title

Defines the displayed title of a widget in the header section.

Note

In some places, you may notice # translatable comments that are displayed next to the text values. This marker is only used for the internal collection of translatable strings and has no effect in the changed settings. Adding this comment to modified values will not result in the actual text translation.

The visible text in the configuration can be translated into other languages with custom translation files. For more information, see the Custom Translation File chapter in the developer manual.

If the widget contains a business object list:

Columns

A hash with column names that are displayed in the business object list.

Columns:
  <ColumnName1>:
     IsVisible: <Value>
  <ColumnName2>:
     IsVisible: <Value>

Possible values for the IsVisible key:

0 = not available

1 = available but not visible

2 = available and visible

See also

The list of possible column names can be found in the Column Names chapter.

ArticleDynamicFields

Contains a list of dynamic fields to be displayed in the article preview. The prefix DynamicField_ must be added, for example DynamicField_MyFieldName.

ArticleDynamicFields:
  - <DynamicField_FieldName1>
  - <DynamicField_FieldName2>
  ...

ArticleViewType

Defines whether the articles should be displayed collapsed or expanded by default.

ArticleViewType: collapsed

DefaultColumnOrder

An array of column names that defines the default column order in the business object list.

DefaultColumnOrder:
- <ColumnName1>
- <ColumnName2>
...

DefaultFilterPresetFields

Defines the default filter preset fields and their values.

DefaultFilterPresetFields:
  <FilterName1>:
    Value: '<Value>'
  <FilterName2>:
    Value: '<Value>'

CountPolling

This determines whether the organizer item queries the current number of its objects in the background and displays them in a speech bubble next to the icon.

CountPolling: ShowNumberFoundItems

Possible values for the CountPolling key:

0 = do not show number

ShowNumberFoundItems = show number of found tickets

Header

This key contains the definition of information fields to be displayed in the header section of the agent business cards.

Header:
  Properties:
  - Name: Avatar
    IsVisible: 1

HideAvailableFilters

This key contains a list of filter names that are not present in the list of available filters in the widget configuration.

HideAvailableFilters:
- <FilterName1>
- <FilterName2>
- <FilterName3>

The following example hides filters for the ticket customer, text search and ticket type:

HideAvailableFilters:
- CustomerID
- Fulltext
- TypeIDs

Identifier

Defines the property that will be used as a full-width card in the Properties widget. The property must be a unique identifier of the business object. If defined this property can be configured separately from other cards.

Identifier:
  Name: TicketNumber
  IsVisible: 0

InitialLimit

Defines the limit of displayed agents in the stripe sidebar in the collapsed state.

ItemsPerPage

A number that defines the number of items per page or load.

Limit

A number that defines the maximum amount of displayed items.

LastUsedFilterPreset

Defines the last used filter preset of a widget. This will be automatically applied when the widget is loaded.

LastUsedFilterPreset: "Reminder Reached"

Properties

The properties are special containers (cards) within a widget that contain detailed information about a specific value of the associated business object. The cards have the option to allow editing of the associated value directly, such as setting a new queue or the owner of a ticket. The properties list in the configuration contains the name and default visibility state of every property.

Properties:
- Name: ArchiveFlag
  IsVisible: 1
- Name: Created
  IsVisible: 1
- Name: CustomerTickets
  IsVisible: 1
- Name: Lock
  IsVisible: 1
  IsInlineEditable: 0
- Name: Watch
  IsVisible: 1
  IsInlineEditable: 0

Possible values for the IsVisible key:

0 = not available

1 = available but not visible

2 = available and visible

Possible values for the IsInlineEditable key:

0 = not editable

1 = editable

ShowPropertyOnEmpty

Defines whether the customer or customer user business card is displayed in the customer information widget when it does not contain a value.

ShowPropertyOnEmpty: 1

Note

This key is supported only by the customer and customer user business cards and cannot be used for regular property cards.

SortBy

Defines the sort order of the business object list. To sort by multiple columns simultaneously, add each sort column as a separate element in the configuration.

SortBy:
- Column: Created
  Direction: Down
- Column: Priority
  Direction: Up

See also

The list of sortable columns per business object type can be found in the Column Names chapter. Look for the ⇅ marker next to the column name.

Note

Only certain business object types support the multi-sorting feature, please see Column Names chapter for more information.

Forms

The configurable forms can be used in many screens, including ticket and article actions. The form configuration will define the fields and properties displayed for each action. Here is the form of Add Note action as an example.

Form of Add Note Action

The configuration of this form is located in the Forms###AgentFrontend::Ticket::Action::Note system configuration setting in YAML format.

In general a form can contain a list of fields and form groups. Both are optional and can be added multiple times.

---
- <Field>
- ...
- <FormGroup>
- ...

The field is the basic element of a form. A field can have multiple properties.

- Name: <InternalName>
  Label: <Displayed Label>
  Config:
    <Parameter>:
    - <value>
    - ...
  Default: <default value>
  Description: <some description>
  Disabled: 1
  Hidden: 1
  Hint: <some hint>
  Required: 1

The following keys and values can be used for the fields.

Warning

The keys marked with the * symbol are mandatory. Skipping them might result in broken configuration and/or non-functional features.

If a non-mandatory key is missing from the form field configuration, it will assume the built-in default behavior.

Warning

Most forms and their fields are subject to existing Access Control Lists (ACL). These rules have the final word on which values can be used in the fields and which will overwrite the form configuration.

Name *

Defines the internal name of the field. This key has pre-defined values for each form.

See also

The list of possible field names can be found in the Form Fields chapter.

The dynamic fields can also be added to the form by using the DynamicField_ prefix and the name of the dynamic field. For example, if there is a dynamic field with the name TestDropdown, you need to use DynamicField_TestDropdown in the form configuration.

Label

Defines the label of the field displayed above the input element. If omitted, the default label is displayed for the field specified with Name.

Note

In some places, you may notice # translatable comments that are displayed next to the text values. This marker is only used for the internal collection of translatable strings and has no effect in the changed settings. Adding this comment to modified values will not result in the actual text translation.

The visible text in the configuration can be translated into other languages with custom translation files. For more information, see the Custom Translation File chapter in the developer manual.

Config

Defines the values that can be selected in a drop-down list. The values depend on the field specified with Name.

- Name: StateID
  Config:
    StateType:
    - open
    - pending auto
    - pending reminder
    - closed
  Default: 4 # open

Note

The Config key is not applicable for all fields. It is only supported for specific fields. If the key is missing from the default configuration, it is most likely not supported by that field.

Default

Defines the default value for the field. If the form field refers to an ID, the default value will be an ID from the appropriate database table.

In the example above, the state type open has the id=4 in the ticket_state table.

Note

The Default key must refer to a constant value. Substituting it with search terms, regular expressions or similar constructs is currently not supported.

Description

Defines the description of the field. The description is displayed next to the label as a bubble icon and shows a tooltip when the mouse is hovered.

Disabled

Defines whether the field is displayed in a disabled state. A disabled field means that the field is read-only. The field value will, however, be sent by submitting the form.

Hidden

Defines whether the field will be hidden. A hidden field is still part of the form and its value will be sent by submitting the form, but it will not be displayed in the user interface.

Hint

Defines explanation text for the field which is displayed below the input element as help text.

Required

Defines whether the field is mandatory. A mandatory field cannot be empty.

The fields can be grouped into form groups. The form groups can contain other form groups or fields. The form groups can be displayed in one, two or three column layouts.

- Label: <Displayed Label>
  Collapsible: 1
  Collapsed: 1
  Fields:
  - <Field>
  - ...
  - <FormGroup>
  - ...
  - ColumnLayout: N # Repeated N-times (2 or 3)
    Fields:
    - <Field>
    - ...
    - <FormGroup>
    - ...

The following keys and values can be used for the form groups.

Warning

The keys marked with the * symbol are mandatory. Skipping them might result in broken configuration and/or non-functional features.

Label *

Defines the label of the form group.

Collapsible

Defines whether the form group is collapsible.

Collapsed

Defines whether the form group is collapsed by default.

Fields *

Lists the fields and form groups that belong to this form group. There is no limitation on how many fields can be added or how many form groups can be nested.

If the form group has no fields and acts only as placeholder, then this key has to be defined as an empty list.

- Label: Placeholder Form Group
  Fields: []

ColumnLayout

Defines the grid in the form component. The fields are displayed in one column layout by default. This key can be used only for the two or three column layouts. The width of the columns are the same, 50%-50% for two column layout and 33%-33%-33% for three column layout.

- Label: Two Column Example
  - ColumnLayout: 2
    Fields:
    - Name: IsVisibleForCustomer
  - ColumnLayout: 2
    Fields:
    - Name: MarkAsImportant

Business Cards

Business cards are used throughout the system to display additional information about agent users.

An Example of the Ticket Owner Business Card

The configuration of this business card is located in the AgentFrontend::BusinessCard::User system configuration setting in YAML format.

AdditionalProperties

This key is used to show additional user fields in the agent business card. Each field is referenced by its Name key. It is possible to customize its DisplayName and control visibility via IsVisible flag (1 shows it, 0 hides it).

Contact

This key defines contact options in agent business cards. Each property item is referencing a user field with some contact information via the Name key (i.e. UserEmail), an icon to show the user (regular weight only!) and can be made visible via the IsVisible: 1 key. By default, clicking on these contact icons will copy the value of the user field to the clipboard.

Alternatively, the Link key can be specified to show a URL instead. Each Link key supports the TemplateToolkit syntax for replacements, and will receive all of the field values of the user via the Data variable.

Chat

This key adds an icon to call the chat function directly from a business card.

Header

This key defines the information shown in the header of a business card. Each field is referenced by its Name key. It is only possible to control the visibility via IsVisible flag (1 shows it; 0 hides it).

Business Object Reference

This chapter lists all possible values for specific business object configurations. The values can be different in each setting.

Column Names

The columns can be referenced by their name. This section lists the possible column names for specific business object types.

Note

The columns marked with the ⇅ symbol are sortable. The default limit for the multi-sorting feature is a maximum of three columns at a time, unless explicitly mentioned differently.

ChatRequest

Possible column names:

Action

Channel ⇅

CreateTime ⇅

Description

RequesterName ⇅

RequesterType ⇅

Type

Note

This business object type does not support the multi-sorting feature. Sorting is supported only by a single column at a time.

CustomerCompany

Possible column names depend on the available fields in the CustomerCompany###Map configuration array. For the default database back end, these include:

CustomerCompanyCity ⇅

CustomerCompanyComment ⇅

CustomerCompanyCountry ⇅

CustomerCompanyName ⇅

CustomerCompanyStreet ⇅

CustomerCompanyURL ⇅

CustomerCompanyZIP ⇅

CustomerID ⇅

ValidID ⇅

Additional column names which are always available:

ClosedTickets

Edit

OpenTickets

CustomerUser

Possible column names depend on the available fields in the CustomerUser###Map and the CustomerCompany###Map configuration arrays. For the default database back ends, these include:

CustomerCompanyCity ⇅

CustomerCompanyComment ⇅

CustomerCompanyCountry ⇅

CustomerCompanyName ⇅

CustomerCompanyStreet ⇅

CustomerCompanyURL ⇅

CustomerCompanyValidID ⇅

CustomerCompanyZIP ⇅

CustomerID ⇅

UserCity ⇅

UserComment ⇅

UserCountry ⇅

UserCustomerID ⇅

UserEmail ⇅

UserFax ⇅

UserFirstname ⇅

UserLastname ⇅

UserLogin ⇅

UserMobile ⇅

UserPassword ⇅

UserPhone ⇅

UserStreet ⇅

UserTitle ⇅

UserZip ⇅

ValidID ⇅

Additional column names which are always available:

Chat

ClosedTickets

CreateTicket

Edit

OpenTickets

SwitchToCustomer

FormDraft

Possible column names:

Delete

Saved

Title

Type

KnowledgeBaseArticle

Possible column names:

Category ⇅

Changed ⇅

Created ⇅

Language ⇅

Number ⇅

State ⇅

Title ⇅

Valid ⇅

KnowledgeBaseArticleAttachment

Possible column names:

ContentType ⇅

CreateTime ⇅

Download

Filename ⇅

Filesize ⇅

Preview

Note

This business object type does not support the multi-sorting feature. Sorting is supported only by a single column at a time.

Search

Possible column names:

Result

Source

Type

Statistic

Possible column names:

Changed ⇅

Created ⇅

ObjectName ⇅

ObjectType ⇅

StatNumber ⇅

StatType ⇅

Title ⇅

Valid

Note

This business object type does not support the multi-sorting feature. Sorting is supported only by a single column at a time.

StatisticReport

Possible column names:

ChangeTime ⇅

CreateTime ⇅

CronDefinition

Description

Language

Name ⇅

Valid ⇅

Note

This business object type does not support the multi-sorting feature. Sorting is supported only by a single column at a time.

Ticket

Possible column names:

Age ⇅

ArticleTree

Changed ⇅

Created ⇅

CreatedBy

CustomerCompanyName

CustomerID ⇅

CustomerName

CustomerUserID

EscalationResponseTime ⇅

EscalationSolutionTime ⇅

EscalationTime ⇅

EscalationUpdateTime ⇅

Lock ⇅

Owner ⇅

PendingTime ⇅

Priority ⇅

Queue ⇅

Responsible ⇅

Sender

Service ⇅

SLA ⇅

State ⇅

Subject

TicketNumber ⇅

Title ⇅

Type ⇅

Watch

TicketArticle

Possible column names:

ArticleNumber ⇅

ArticleProperties

Attachment

Channel ⇅

CreateTime ⇅

Direction

Sender

Status

Subject

Note

This business object type does not support the multi-sorting feature. Sorting is supported only by a single column at a time.

TicketAttachment

Possible column names:

ContentType ⇅

CreateTime ⇅

Direction ⇅

Download

Filename ⇅

Filesize ⇅

Preview

Note

This business object type does not support the multi-sorting feature. Sorting is supported only by a single column at a time.

WebNotification

Possible column names:

CreateTime ⇅

Name ⇅

ObjectReference ⇅

ObjectType ⇅

Subject ⇅

Filter Names

Filters can be referenced by their names. This section lists the possible filter names for specific business object types. Each filter has a value type displayed next to it that can be used to quickly jump to the reference.

See also

The list of possible filter value types can be found in the Filter Value Types chapter.

Note

The filters marked with the × symbol support array values for multiple matches.

ChatRequest

The following filter names and values can be used for the Chat Request business object lists.

ChannelIDs: array ×

Defines the IDs of the chat channels.

Create_DateTimeRange: absolute date

Defines the absolute range of the chat request creation time.

Create_DateTimeRelative: relative date

Defines the relative range of the chat request creation time.

RequesterType: array ×

Defines the type of the user that initiated the chat request.

User

The user is an agent.

Customer

The user is a customer user.

Public

The user is anonymous (public user).

Type: array ×

Defines the type of the chat request.

Invitation

The invitation to a chat initiated by another agent user.

Request

A chat request initiated by a customer user or a public user.

CustomerCompany

The following filter names and values can be used for the Customer business object lists.

CustomerCompanyCity: string

Defines the text when searching for the customer city. Wildcard * can be used. The search is case insensitive.

CustomerCompanyComment: string

Defines the text when searching for the customer comment. Wildcard * can be used. The search is case insensitive.

CustomerCompanyCountry: string

Defines the text when searching for the customer country. Wildcard * can be used. The search is case insensitive.

CustomerCompanyName: string

Defines the text when searching for the customer name. Wildcard * can be used. The search is case insensitive.

CustomerCompanyStreet: string

Defines the text when searching for the customer street. Wildcard * can be used. The search is case insensitive.

CustomerCompanyURL: string

Defines the text when searching for the customer URL. Wildcard * can be used. The search is case insensitive.

CustomerCompanyZIP: string

Defines the text when searching for the customer postcode. Wildcard * can be used. The search is case insensitive.

CustomerID: string

Defines the text when searching for the customer ID. Wildcard * can be used. The search is case insensitive.

ValidID: array ×

Defines the IDs of the customer validity. By default, these include:

1 = valid

2 = invalid

3 = invalid-temporarily

CustomerUser

The following filter names and values can be used for the Customer User business object lists.

CustomerCompany_CustomerCompanyCity: string

Defines the text when searching for the customer city. Wildcard * can be used. The search is case insensitive.

CustomerCompany_CustomerCompanyComment: string

Defines the text when searching for the customer comment. Wildcard * can be used. The search is case insensitive.

CustomerCompany_CustomerCompanyCountry: string

Defines the text when searching for the customer country. Wildcard * can be used. The search is case insensitive.

CustomerCompany_CustomerCompanyName: string

Defines the text when searching for the customer name. Wildcard * can be used. The search is case insensitive.

CustomerCompany_CustomerCompanyStreet: string

Defines the text when searching for the customer street. Wildcard * can be used. The search is case insensitive.

CustomerCompany_CustomerCompanyURL: string

Defines the text when searching for the customer URL. Wildcard * can be used. The search is case insensitive.

CustomerCompany_CustomerCompanyZIP: string

Defines the text when searching for the customer postcode. Wildcard * can be used. The search is case insensitive.

CustomerCompany_ValidID: array ×

Defines the IDs of the customer validity. By default, these include:

1 = valid

2 = invalid

3 = invalid-temporarily

CustomerID: string

Defines the text when searching for the related customer ID. Wildcard * can be used. The search is case insensitive.

UserCity: string

Defines the text when searching for the customer user city. Wildcard * can be used. The search is case insensitive.

UserComment: string

Defines the text when searching for the customer user comment. Wildcard * can be used. The search is case insensitive.

UserCountry: string

Defines the text when searching for the customer user country. Wildcard * can be used. The search is case insensitive.

UserCustomerID: string

Defines the text when searching for the customer user ID. Wildcard * can be used. The search is case insensitive.

UserEmail: string

Defines the text when searching for the customer user email address. Wildcard * can be used. The search is case insensitive.

UserFax: string

Defines the text when searching for the customer user fax number. Wildcard * can be used. The search is case insensitive.

UserFirstname: string

Defines the text when searching for the customer user first name. Wildcard * can be used. The search is case insensitive.

UserLastname: string

Defines the text when searching for the customer user last name. Wildcard * can be used. The search is case insensitive.

UserLogin: string

Defines the text when searching for the customer user login name (username). Wildcard * can be used. The search is case insensitive.

UserMobile: string

Defines the text when searching for the customer user mobile number. Wildcard * can be used. The search is case insensitive.

UserPhone: string

Defines the text when searching for the customer user phone number. Wildcard * can be used. The search is case insensitive.

UserStreet: string

Defines the text when searching for the customer user street. Wildcard * can be used. The search is case insensitive.

UserTitle: string

Defines the text when searching for the customer user title. Wildcard * can be used. The search is case insensitive.

UserZip: string

Defines the text when searching for the customer user postcode. Wildcard * can be used. The search is case insensitive.

ValidID: array ×

Defines the IDs of the customer user validity. By default, these include:

1 = valid

2 = invalid

3 = invalid-temporarily

KnowledgeBaseArticle

The following filter names and values can be used for the Knowledge Base Article business object lists.

Approved: boolean

Defines whether the article has been approved.

CategoryIDs: array ×

Defines the IDs of the article categories.

CreatedUserIDs: array ×

Defines the IDs of the agents who created the article.

ItemChange_DateTimeRange: absolute date

Defines the absolute range of the article change time.

ItemChange_DateTimeRelative: relative date

Defines the relative range of the article change time.

ItemCreate_DateTimeRange: absolute date

Defines the absolute range of the article create time.

ItemCreate_DateTimeRelative: relative date

Defines the relative range of the article create time.

Keyword: string

Defines the text when searching for the article keyword. Wildcard * can be used. The search is case insensitive.

LanguageIDs: array ×

Defines the IDs of the article language. By default, these include:

en

de

LastChangedUserIDs: array ×

Defines the IDs of the agents who changed the article last.

Number: string

Defines the text when searching for the article number. Wildcard * can be used.

Rate: comparison

Compares the article rating in percentage against the supplied value.

StateIDs: array ×

Defines the IDs of the article state. By default, these include:

1 = internal (agent)

2 = external (customer)

3 = public (all)

Title: string

Defines the text when searching for the article title. Wildcard * can be used. The search is case insensitive.

ValidIDs: array ×

Defines the IDs of the article validity. By default, these include:

1 = valid

2 = invalid

3 = invalid-temporarily

Votes: comparison

Compares the number of votes for the article against the supplied value.

What: string

Defines the text when searching through the article full text. Wildcard * can be used. The search is case insensitive.

KnowledgeBaseArticleAttachment

The following filter names and values can be used for the Knowledge Base Article Attachment business object lists.

Create_DateTimeRange: absolute date

Defines the absolute range of the attachment create time.

Create_DateTimeRelative: relative date

Defines the relative range of the attachment create time.

Filename: string

Defines the text when searching for the attachment filename. Wildcard * and regular expressions can be used. The search is case insensitive.

Type: string

Defines the text when searching for the attachment MIME type. Wildcard * and regular expressions can be used. The search is case insensitive.

Search

The following filter names and values can be used for the Search business object lists.

Appointment Calendar: string

Defines the calendar in which to search for the appointment. Please set it to a string value formatted as:

CalendarID#

Where # is the ID of the calendar, i.e. CalendarID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Appointment. Otherwise, it will be ignored.

Appointment Schedule: string

Defines the type of the appointment.

AllDay

The appointment is an all day appointment (i.e. it does not have the time component).

TimeFrame

The appointment is a time frame appointment (i.e. it has the time component).

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Appointment. Otherwise, it will be ignored.

DocumentType: string

Defines the type of document to be searched. By default, these include:

Appointment = Calendar Appointments

FAQ = Knowledge Base Articles

Ticket = Tickets

FAQ FAQ Categories: string

Defines the knowledge base article category for which you are searching. Please set it to a string value formatted as:

CategoryID#

Where # is the ID of the category, i.e. CategoryID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value FAQ. Otherwise, it will be ignored.

FAQ FAQ Languages: string

Defines the knowledge base article language for which you are searching. Please set it to a string value formatted as:

LanguageID#

Where # is the ID of the language, i.e. LanguageID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value FAQ. Otherwise, it will be ignored.

FAQ Has attachments: string

Defines the presence of knowledge base article attachments.

HasAttachments

The article has at least one attachment.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value FAQ. Otherwise, it will be ignored.

FAQ State: string

Defines the knowledge base article state for which you are searching. Please set it to a string value formatted as:

StateID#

Where # is the ID of the state, i.e. StateID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value FAQ. Otherwise, it will be ignored.

Ticket Has attachments: string

Defines the presence of the ticket article attachments.

HasAttachments

The ticket article has at least one attachment.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket Owner: string

Defines the ID of the agent who is the ticket owner. Please set it to a string value formatted as:

OwnerID#

Where # is the ID of the agent, i.e. OwnerID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket Priority: string

Defines the ID of the ticket priority. Please set it to a string value formatted as:

PriorityID#

Where # is the ID of the priority, i.e. PriorityID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket Queue: string

Defines the ID of the ticket queue. Please set it to a string value formatted as:

QueueID#

Where # is the ID of the queue, i.e. QueueID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket Responsible: string

Defines the ID of the agent who is the ticket responsible. Please set it to a string value formatted as:

ResponsibleID#

Where # is the ID of the agent, i.e. ResponsibleID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket Sender type: string

Defines the sender of the ticket articles.

SenderTypeAgent

The sender of the ticket article is an agent user.

SenderTypeCustomer

The sender of the ticket article is a customer user.

SenderTypeSystem

The sender of the ticket article is a system user.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket Service Level Agreement (SLA): string

Defines the ID of the ticket SLA. Please set it to a string value formatted as:

SLAID#

Where # is the ID of the SLA, i.e. SLAID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket Service: string

Defines the ID of the ticket service. Please set it to a string value formatted as:

ServiceID#

Where # is the ID of the service, i.e. ServiceID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket State: string

Defines the ID of the ticket state. Please set it to a string value formatted as:

StateID#

Where # is the ID of the state, i.e. StateID1.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Ticket Visible to customer: string

Defines whether the ticket articles are visible to the customer user.

IsVisibleForCustomer

Ticket article is visible to the customer user.

Warning

This filter is applicable only when the filter DocumentType is defined and set to the value Ticket. Otherwise, it will be ignored.

Statistic

The following filter names and values can be used for the Statistic business object lists.

StatNumber: string

Defines the text when searching for the statistic number. Wildcard * can be used.

StatType: array ×

Defines the statistic type for which you are searching.

static

The statistic is of the static type.

dynamic

The statistic is of the dynamic type.

Title: string

Defines the text when searching for the statistic name. Wildcard * can be used. The search is case insensitive.

ObjectName: array ×

Defines the statistic object name to be searched. By default, these include:

Ticketlist

TicketAccountedTime

TicketAccumulation

TicketSolutionResponseTime

FAQAccess

StateAction

ObjectType: array ×

Defines the statistic object type to be searched.

DynamicList

The object type is a list.

DynamicMatrix

The object type is a matrix.

Static

The object type is static.

Valid: array ×

Defines the IDs of the statistic validity. By default, these include:

1 = valid

0 = invalid

StatisticReport

The following filter names and values can be used for the Report business object lists.

Name: string

Defines the text when searching for the report name. Wildcard * can be used. The search is case insensitive.

Description: string

Defines the text when searching for the report description. Wildcard * can be used. The search is case insensitive.

LanguageID: string

Defines the report language code, i.e. de.

ValidID: array ×

Defines the IDs of the report validity. By default, these include:

1 = valid

2 = invalid

3 = invalid-temporarily

Ticket

The following filter names and values can be used for the Ticket business object lists.

AgentCreator: boolean

Defines whether the ticket was created by the current agent.

AgentInvolved: boolean

Defines whether the current agent is involved in the ticket.

AgentOwner: boolean

Defines whether the current agent is the ticket owner.

AgentQueues: boolean

Defines whether the ticket is in one of the subscribed queues of the current agent. Agents can subscribe to queues via their My Queues personal preference.

AgentResponsible: boolean

Defines whether the current agent is the ticket responsible.

AgentServices: boolean

Defines whether the ticket has one of the subscribed services of the current agent. Agents can subscribe to services via their My Services personal preference.

AgentTicketFlagSeen: string

Defines whether the current agent has read the ticket.

Unread

All articles are unread by the current agent.

Read

All articles are read by the current agent.

AgentWatcher: boolean

Defines whether the current agent is watching the ticket.

ArticleCreate_DateTimeRange: absolute date

Defines the absolute range of the ticket article creation time.

ArticleCreate_DateTimeRelative: relative date

Defines the relative range of the ticket article creation time.

Chat_ChatterName: string

Defines the text when searching for the chat article participants. Wildcard * can be used. The search is case insensitive.

Chat_MessageText: string

Defines the text when searching for the chat article message. Wildcard * can be used. The search is case insensitive.

CreatedQueueIDs: array ×

Defines the IDs of the queues where the ticket was originally created.

CreatedUserIDs: array ×

Defines the IDs of the agents who created the ticket.

CustomerID: string

Defines the text when searching for the ticket customer ID field. Use this filter for a complex search. Wildcard * can be used. The search is case insensitive.

CustomerIDRaw: string

Defines the text when searching for the ticket customer ID field. Use this filter for an exact match. The search is case insensitive.

CustomerUserID: string

Defines whether the ticket is accessible to a specific customer user in the external interface. Supports only exact match. The search is case insensitive.

CustomerUserLogin: string

Defines the text when searching for the ticket customer user ID field. Use this filter for the complex search. Wildcard * can be used. The search is case insensitive.

CustomerUserLoginRaw: string

Defines the text when searching for the ticket customer user ID field. Use this filter for an exact match. The search is case insensitive.

Fulltext: string

Defines the text when searching for the ticket article full text. Wildcard * can be used. The search is case insensitive.

LockIDs: array ×

Defines the IDs of the ticket lock types. By default, these include:

1 = unlock

2 = lock

3 = tmp_lock

MIMEBase_AttachmentName: string

Defines the text when searching for the article attachment names. Wildcard * can be used. The search is case insensitive.

MIMEBase_Bcc: string

Defines the text when searching for the article blind carbon copy field. Wildcard * can be used. The search is case insensitive.

MIMEBase_Body: string

Defines the text when searching for the article body. Wildcard * can be used. The search is case insensitive.

MIMEBase_Cc: string

Defines the text when searching for the article carbon copy field. Wildcard * can be used. The search is case insensitive.

MIMEBase_From: string

Defines the text when searching for the article sender field. Wildcard * can be used. The search is case insensitive.

MIMEBase_Subject: string

Defines the text when searching for the article subject field. Wildcard * can be used. The search is case insensitive.

MIMEBase_To: string

Defines the text when searching for the article recipient field. Wildcard * can be used. The search is case insensitive.

OwnerIDs: array ×

Defines the IDs of the agents who are the ticket owners.

PriorityIDs: array ×

Defines the IDs of the ticket priorities.

QueueIDs: array ×

Defines the IDs of the ticket queues.

ResponsibleIDs: array ×

Defines the IDs of the agents who are the ticket responsibles.

SearchInArchive: string

Defines how the search behaves related to the ticket archive status.

ArchivedTickets

Search in archived tickets only.

NotArchivedTickets

Search in unarchived tickets only.

AllTickets

Search in all tickets.

ServiceIDs: array ×

Defines the IDs of the ticket services.

SLAIDs: array ×

Defines the IDs of the ticket SLAs.

SMS_PhoneNumbers: string

Defines the text when searching for the SMS article recipient phone numbers. Wildcard * can be used. The search is case insensitive.

SMS_Text: string

Defines the text when searching for the SMS article body. Wildcard * can be used. The search is case insensitive.

SMS_TransactionNumbers: string

Defines the text when searching for the SMS article transaction numbers. Wildcard * can be used. The search is case insensitive.

StateIDs: array ×

Defines the IDs of the ticket states.

StateType: string

Defines the ticket state category.

Open

Search in open tickets only.

Closed

Search in closed tickets only.

Warning

Despite its name, this filter does not apply to the actual ticket state types. Open and Closed are not valid state types. They are group constructs included for compatibility reasons. If a ticket is in a state which has any of the state types defined in the Ticket::ViewableStateType setting, it will be considered as open; otherwise, it is closed.

StateTypeIDs: array ×

Defines the IDs of the ticket state types.

TicketChange_DateTimeRange: absolute date

Defines the absolute range of the ticket change time.

TicketChange_DateTimeRelative: relative date

Defines the relative range of the ticket change time.

TicketClose_DateTimeRange: absolute date

Defines the absolute range of the ticket close time.

TicketClose_DateTimeRelative: relative date

Defines the relative range of the ticket close time.

TicketCreate_DateTimeRange: absolute date

Defines the absolute range of the ticket create time.

TicketCreate_DateTimeRelative: relative date

Defines the relative range of the ticket create time.

TicketEscalation_DateTimeRange: absolute date

Defines the absolute range of the ticket escalation time.

TicketEscalation_DateTimeRelative: relative date

Defines the relative range of the ticket escalation time.

TicketLastChange_DateTimeRange: absolute date

Defines the absolute range of the ticket last change time.

TicketLastChange_DateTimeRelative: relative date

Defines the relative range of the ticket last change time.

TicketNumber: string

Defines the text when searching for the ticket number. Wildcard * can be used.

TicketPending_DateTimeRange: absolute date

Defines the absolute range of the ticket pending time.

TicketPending_DateTimeRelative: relative date

Defines the relative range of the ticket pending time.

Title: string

Defines the text when searching for the ticket title. Wildcard * can be used. The search is case insensitive.

TypeIDs: array ×

Defines the text when searching for the ticket type.

WatchUserIDs: array ×

Defines the IDs of the agents who are watching the ticket.

TicketArticle

The following filter names and values can be used for the Ticket Article business object lists.

CommunicationChannelID: array

IsVisibleForCustomer: string

SenderTypeID: array

TicketAttachment

The following filter names and values can be used for the Ticket Attachment business object lists.

Article: string

Create_DateTimeRange: absolute date

Create_DateTimeRelative: relative date

Direction: array ×

Filename: string

Type: string

WebNotification

The following filter names and values can be used for the Web Notification business object lists.

Name: array ×

Subject: string

ObjectTypes: array ×

Seen: array ×

ObjectReferences: array ×

Filter Value Types

Every filter supports exactly one kind of a value type. Depending on this type, the following structures should be used to define it in the YAML configuration.

Boolean

A simple value that is considered either true or false.

<FilterName1>:
  Value: 1
<FilterName2>:
  Value: 0

1

The filter is active (turned on).

0

The filter is inactive (turned off).

String

A text value, normally used when searching. Check specific filters for more details.

<FilterName1>:
  Value: simple
<FilterName2>:
  Value: 'String with spaces or special characters like @$#!+*'

Array

An array value normally used to search for multiple values at the same time.

<FilterName1>:
  Value:
  - 1
  - 2
  - 3
<FilterName2>:
  Value:
  - 4
  - 5

Absolute date

The time range value between two absolute dates.

<FilterName1>:
  Value:
    Start: '2020-01-01 00:00:00'
    End: '2020-02-01 00:00:00'
<FilterName2>:
  Value:
    Start: '2020-02-01 00:00:00'
    End: '2020-03-01 00:00:00'

Start

Absolute timestamp in ISO format for the start of the range (i.e. 2020-01-01 00:00:00). The value must be supplied in the current system time zone (configurable via the OTRSTimeZone system setting).

End

Absolute timestamp in ISO format for the end of the range (i.e. 2020-02-01 00:00:00). The value must be supplied in the current system time zone (configurable via the OTRSTimeZone system setting).

Relative date

The time range value relative to the current time.

<FilterName1>:
  Value:
    Start: Last
    Point: 1
    Format: month
<FilterName2>:
  Value:
    Start: Before
    Point: 3
    Format: day

Start

The type of the relative range.

Possible values for the Start key:

Last = within the last…

Before = more than … ago

Point

Integer value of the time unit (i.e. 3).

Format

Time unit of the relative range.

Possible values for the Format key:

minute
hour
day
week
month
year

Comparison

The comparison with the supplied value.

<FilterName1>:
  Value:
    Type: Equals
    Value: 25
<FilterName2>:
  Value:
    Start: GreaterThan
    Value: 50

Type

The type of the comparison.

Possible values for the Type key:

Equals = equals …

GreaterThan = greater than …

GreaterThanEquals = greater than or equals …

SmallerThan = smaller than …

SmallerThanEquals = smaller than or equals …

Value

Integer value to compare against (i.e. 25).

Form Fields

The form fields can be defined via their Name key. This section lists the values of the Name key for the specific settings.

See also

Form fields can be made mandatory by setting their Required key to 1.

Possible field names for ticket actions:

Forms###AgentFrontend::Ticket::Action::Close

Configurable form for the Close Ticket action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Close

Possible values for the Name key of the form field:

AccountedTime
AddMessage
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::Customer

Configurable form for the Change Customer action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Customer

Possible values for the Name key of the form field:

CustomerUserID
CustomerID

Forms###AgentFrontend::Ticket::Action::EmailOutbound

Configurable form for the Send Email Outbound action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::EmailOutbound

Possible values for the Name key of the form field:

AccountedTime
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
EmailSecurity
From
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::FreeText

Configurable form for the Change Free Fields action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::FreeText

Possible values for the Name key of the form field:

AccountedTime
AddMessage
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::Merge

Configurable form for the Merge Ticket action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Merge

Possible values for the Name key of the form field:

AddMessage
Attachments
Body
DynamicField
From
HistoryComment
HistoryType
IsVisibleForCustomer
MarkAsImportant
Messages
RelevantKnowledge
SenderType
Subject
To

Forms###AgentFrontend::Ticket::Action::Move

Configurable form for the Move Ticket action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Move

Possible values for the Name key of the form field:

AccountedTime
AddMessage
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::Note

Configurable form for the Add Note action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Note

Possible values for the Name key of the form field:

AccountedTime
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::Owner

Configurable form for the Change Owner action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Owner

Possible values for the Name key of the form field:

AccountedTime
AddMessage
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::Pending

Configurable form for the Set Pending Time action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Pending

Possible values for the Name key of the form field:

AccountedTime
AddMessage
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::PhoneCallInbound

Configurable form for the Add Phone Call Inbound action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::PhoneCallInbound

Possible values for the Name key of the form field:

AccountedTime
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::PhoneCallOutbound

Configurable form for the Add Phone Call Outbound action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::PhoneCallOutbound

Possible values for the Name key of the form field:

AccountedTime
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::Priority

Configurable form for the Change Priority action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Priority

Possible values for the Name key of the form field:

AccountedTime
AddMessage
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::Responsible

Configurable form for the Change Responsible action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::Responsible

Possible values for the Name key of the form field:

AccountedTime
AddMessage
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::Ticket::Action::SmsOutbound

Configurable form for the Send SMS Outbound action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Ticket::Action::SmsOutbound

Possible values for the Name key of the form field:

AccountedTime
Body
CustomerID
CustomerUserID
DynamicField
FlashMessage
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Title
To
TypeID

Possible field names for article actions:

Forms###AgentFrontend::TicketArticle::Action::Forward

Configurable form for the Forward via Email action.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketArticle::Action::Forward

Possible values for the Name key of the form field:

AccountedTime
Attachments
Bcc
Body
Cc
DynamicField
EmailSecurity
From
HistoryComment
HistoryType
IsVisibleForCustomer
MarkAsImportant
Messages
RelevantKnowledge
SenderType
StandardTemplateID
StateID
Subject
To

Forms###AgentFrontend::TicketArticle::Action::Redirect

Configurable form for the Redirect via Email action.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketArticle::Action::Redirect

Possible values for the Name key of the form field:

AddMessage
Body
From
HistoryType
Messages
RedirectTo
StateID
Subject
To

Forms###AgentFrontend::TicketArticle::Action::Reply

Configurable form for the Reply via Email action.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketArticle::Action::Reply

Possible values for the Name key of the form field:

AccountedTime
Attachments
Bcc
Body
Cc
DynamicField
EmailSecurity
From
HistoryComment
HistoryType
IsVisibleForCustomer
MarkAsImportant
Messages
RelevantKnowledge
SenderType
StandardTemplateID
StateID
Subject
To

Forms###AgentFrontend::TicketArticle::Action::ReplyAll

Configurable form for the Reply to All via Email action.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketArticle::Action::ReplyAll

Possible values for the Name key of the form field:

AccountedTime
Attachments
Bcc
Body
Cc
DynamicField
EmailSecurity
From
HistoryComment
HistoryType
IsVisibleForCustomer
MarkAsImportant
Messages
RelevantKnowledge
SenderType
StandardTemplateID
StateID
Subject
To

Forms###AgentFrontend::TicketArticle::Action::ReplyToNote

Configurable form for the Reply via Note action.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketArticle::Action::ReplyToNote

Possible values for the Name key of the form field:

AccountedTime
Attachments
AutoInvolvedAgents
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
Title
To
TypeID

Forms###AgentFrontend::TicketArticle::Action::ReplyViaSms

Configurable form for the Reply via SMS action.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketArticle::Action::ReplyViaSms

Possible values for the Name key of the form field:

AccountedTime
Body
CustomerID
CustomerUserID
DynamicField
FlashMessage
HistoryComment
HistoryType
InformAgent
InvolvedAgent
IsVisibleForCustomer
MarkAsImportant
Messages
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Title
To
TypeID

Forms###AgentFrontend::TicketArticle::Action::Split

Configurable form for the Split Article action.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketArticle::Action::Split

Possible values for the Name key of the form field:

LinkAs
Messages
ProcessID
Target

Possible field names for the ticket create properties forms:

Forms###AgentFrontend::TicketCreate::Email::CreateProperties

Configurable form for the Properties widget of the New Email Ticket screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketCreate::Email::CreateProperties

Possible values for the Name key of the form field:

AccountedTime
Attachments
Bcc
Body
Cc
CustomerID
CustomerUserID
DynamicField
EmailSecurity
HistoryComment
HistoryType
IsVisibleForCustomer
LinkTicketID
LinkType
OwnerID
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
Signature
SLAID
StandardTemplateID
StateID
Subject
To
TypeID

Forms###AgentFrontend::TicketCreate::Phone::CreateProperties

Configurable form for the Properties widget of the New Phone Ticket screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketCreate::Phone::CreateProperties

Possible values for the Name key of the form field:

AccountedTime
Attachments
Body
CustomerID
CustomerUserID
DynamicField
From
HistoryComment
HistoryType
IsVisibleForCustomer
LinkTicketID
LinkType
OwnerID
PendingDate
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
SenderType
ServiceID
SLAID
StandardTemplateID
StateID
Subject
To
TypeID

Forms###AgentFrontend::TicketCreate::SMS::CreateProperties

Configurable form for the Properties widget of the New SMS Ticket screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::TicketCreate::SMS::CreateProperties

Possible values for the Name key of the form field:

AccountedTime
Body
CustomerID
CustomerUserID
DynamicField
FlashMessage
HistoryComment
HistoryType
IsVisibleForCustomer
OwnerID
PendingDate
PriorityID
QueueID
RelevantKnowledge
ResponsibleID
Sender
SenderType
ServiceID
SLAID
StandardTemplateID
StateID
Subject
To
TypeID

Possible field names for knowledge base article actions:

Forms###AgentFrontend::KnowledgeBaseArticleCreate::Properties

Configurable form for the Properties widget of the Create Knowledge Base Article screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::KnowledgeBaseArticleCreate::Properties

Possible values for the Name key of the form field:

Approved
Attachments
Category
DynamicFields
Field1
Field2
Field3
Field4
Field5
Field6
Keywords
Language
State
Title
Valid

Forms###AgentFrontend::KnowledgeBaseArticleUpdate::Properties

Configurable form for the Properties widget of the Edit Knowledge Base Article screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::KnowledgeBaseArticleUpdate::Properties

Possible values for the Name key of the form field:

Approved
Attachments
Category
DynamicFields
Field1
Field2
Field3
Field4
Field5
Field6
Keywords
Language
State
Title
Valid

Possible field names for customer actions:

Forms###AgentFrontend::CustomerCompanyCreate::Properties

Configurable form for the Properties widget of the Create Customer screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::CustomerCompanyCreate::Properties

Possible values for the Name key depend on the available fields in the CustomerCompany###Map configuration array. For the default database back end, these include:

CustomerCompanyCity
CustomerCompanyComment
CustomerCompanyCountry
CustomerCompanyName
CustomerCompanyStreet
CustomerCompanyURL
CustomerCompanyZIP
CustomerID
ValidID

Additional column names which are always available:

DataSource

Warning

In case Multiple Customer User Back Ends are configured, all possible fields must be present in the form configuration in order to be able to modify them. Both configurations must be kept in sync, otherwise it will not be possible to modify the customer records.

Forms###AgentFrontend::CustomerCompanyUpdate::Properties

Configurable form for the Properties widget of the Edit Customer screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::CustomerCompanyUpdate::Properties

Possible values for the Name key depend on the available fields in the CustomerCompany###Map configuration array. For the default database back end, these include:

CustomerCompanyCity
CustomerCompanyComment
CustomerCompanyCountry
CustomerCompanyName
CustomerCompanyStreet
CustomerCompanyURL
CustomerCompanyZIP
CustomerID
ValidID

Warning

In case Multiple Customer User Back Ends are configured, all possible fields must be present in the form configuration in order to be able to modify them. Both configurations must be kept in sync, otherwise it will not be possible to modify the customer records.

Possible field names for customer user actions:

Forms###AgentFrontend::CustomerUserCreate::Properties

Configurable form for the Properties widget of the Create Customer User screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::CustomerUserCreate::Properties

Possible values for the Name key depend on the Customer User Back Ends configuration. For the default database back end, these include:

UserCity
UserComment
UserCountry
UserCustomerID
UserEmail
UserFax
UserFirstname
UserLastname
UserLogin
UserMobile
UserPassword
UserPhone
UserStreet
UserTitle
UserZip
ValidID

For most customer user preference modules registered under CustomerPersonalPreference###* namespace, it is also possible to show dedicated form fields. By default, these include:

Preference_LoginForbidden
Preference_PGP
Preference_SMIME
Preference_TwoFactor

Additional column names which are always available:

DataSource

Warning

In case of Multiple Customer User Back Ends, all possible fields must be present in the form configuration in order to be able to modify them. Both configurations must be kept in sync, otherwise it will not be possible to modify the customer user records.

Forms###AgentFrontend::CustomerUserUpdate::Properties

Configurable form for the Properties widget of the Edit Customer User screen.

Link to the reference of the system configuration:

Forms###AgentFrontend::CustomerUserUpdate::Properties

Possible values for the Name key depend on the Customer User Back Ends configuration. For the default database back end, these include:

UserCity
UserComment
UserCountry
UserCustomerID
UserEmail
UserFax
UserFirstname
UserLastname
UserLogin
UserMobile
UserPassword
UserPhone
UserStreet
UserTitle
UserZip
ValidID

For most customer user preference modules registered under CustomerPersonalPreference###* namespace, it is also possible to show dedicated form fields. By default, these include:

Preference_LoginForbidden
Preference_PGP
Preference_SMIME
Preference_TwoFactor

Warning

In case of Multiple Customer User Back Ends, all possible fields must be present in the form configuration in order to be able to modify them. Both configurations must be kept in sync, otherwise it will not be possible to modify the customer user records.

Possible field names for calendar appointment actions:

Forms###AgentFrontend::Calendar::AppointmentCreate::Properties

Configurable form for the Add Appointment action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Calendar::AppointmentCreate::Properties

Possible values for the Name key of the form field:

AllDay
CalendarID
Description
EndTime
Location
Notification
Recurrence
ResourceID
StartTime
TeamID
TicketPlugin
Title

Forms###AgentFrontend::Calendar::AppointmentUpdate::Properties

Configurable form for the Edit Appointment action.

Link to the reference of the system configuration:

Forms###AgentFrontend::Calendar::AppointmentUpdate::Properties

Possible values for the Name key of the form field:

AllDay
CalendarID
Description
EndTime
Location
Notification
Recurrence
ResourceID
StartTime
TeamID
TicketPlugin
Title

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

System Log

Professional systems log their activities in one or more log files to help administrators when troubleshooting or to get an overview of what is going on in their system on a detailed level.

These logs are usually not available to application administrators without a certain level of permissions, and skills, on the operating system.

OTRS allows application administrators to access the system log comfortably by using the graphical interface without the need to have access to the server’s command shell. The administrator can decide which level of logging is needed, to make sure that the log files are not unnecessarily filled.

Use this screen to view log entries of OTRS. The log overview screen is available in the System Log module of the Administration group.

System Log Screen

Each line in the log contains a timestamp, the log priority, the system component and the log entry itself.

Note

If several log entries are displayed in the log, use the filter box to find a particular log entry by just typing the name to filter.

To adjust the logging settings of the system:

Go to System Configuration screen.

Navigate to Core → Log in the navigation tree.

Review the settings.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Tutorials

Any system requires configuration. Configuring a system should be an easy task and the tools for configuration fit-for-purpose.

OTRS offers several administration tools to configure, monitor, control and extend OTRS.

Contents

Archiving Tickets

Creating New Phone Ticket on Incoming Calls

Custom URL Support

Triggering Actions

Pre-populating Form Fields

Submitting Actions

Custom Business Object Lists

Inline Editing

Inline Editing in Business Object Lists

Inline Editing in Property Cards

External Link Previews

Article Meta Filters

Dynamic Field Value

Troubleshooting

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Archiving Tickets

OTRS can be used as an audit-proof system. In this case deleting closed tickets may not be a good idea. Therefore a feature has been implemented that allows you to archive tickets.

Tickets that match certain criteria can be marked as archived. These tickets are not accessed if an agent do a regular ticket search or run a generic agent job. The system itself does not have to deal with a huge amount of tickets any longer as only the latest tickets are taken into consideration. This can result in a huge performance gain on large systems.

To use the archive feature:

Go to the System Configuration screen.

Search for the setting Ticket::ArchiveSystem and enable the setting.

Go to the Generic Agent screen.

Click on the Add job button in the left sidebar.

Provide a name in the Job Settings section, and select proper options to schedule this job.

Define the ticket filters in the Select Tickets section. It might be a good idea to only archive those tickets in a closed state that have been closed a few months before.

In the Update/Add Ticket Attributes section, set the field Archive selected tickets to archive tickets.

Click on the Save button.

Run the job. The system will display all tickets which will be archived when executing the generic agent job.

Note

When you search for tickets, the system default is to search tickets which are not archived. If you want to search through archived tickets also, simply add the Archive search filter while defining search criteria.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Creating New Phone Ticket on Incoming Calls

It is possible to integrate OTRS with third-party computer telephony integration (CTI) solutions and make them work in unison. On as simple action as a click on a button in the CTI incoming call screen, the OTRS New Phone Ticket screen can be opened with the customer pre-selected by their phone number.

The only pre-requisite for the example below is that the used CTI software is able to open a link of a certain format in the web browser.

First, edit the customer user configuration file and add the phone number field to CustomerUserSearchFields (in our case it is aptly named phone):

CustomerUserSearchFields => [ 'login', 'first_name', 'last_name', 'customer_id', 'phone' ],

Note

For more information on how to provide custom user configuration please see the Customer User Back Ends chapter.

Warning

The customer user configuration is provided as an additional Perl module file. It is your responsibility to check the validity of the supplied file, since any syntax mistakes can lead to a broken system.

Optionally, you can also add the phone field to CustomerUserListFields array, if you want to see the telephone number while searching for customer users:

CustomerUserListFields => [ 'first_name', 'last_name', 'phone', 'email' ],

Note

The customer user configuration mentioned above is taken care of by the Customer Solution Team in OTRS. Please contact the Customer Solution Team via support@otrs.com or in the OTRS Portal.

Configure your CTI software to open the following link when you answer the phone:

https://otrs.example.com/agent/ticket/create/phone?CustomerUserSearch=1&CustomerUserID=callernumber
https://otrs.example.com/agent/ticket/create/phone?CustomerUserSearch=1&CustomerUserID=callerloginname

For example, for customer user John Smith with login name johnsmith and telephone number 12345678:

https://otrs.example.com/agent/ticket/create/phone?CustomerUserSearch=1&CustomerUserID=12345678
https://otrs.example.com/agent/ticket/create/phone?CustomerUserSearch=1&CustomerUserID=johnsmith

Where otrs.example.com is the FQDN of the OTRS system in question. Which exact value you use in the end (caller number or login name) depends on what your CTI software can construct the link with.

When the ticket create screen is open in OTRS, a search will be conducted for the supplied value. In case only one customer user with that information is found, they will be pre-selected as the ticket customer user, and added to the related fields.

Note

In case you would like to do a search by the customer user email address, first make sure that the CustomerUserPostMasterSearchFields key of the customer user configuration is set to an appropriate field. Additionally, you must use an alternative URL query parameter called CustomerPostMasterSearch=1, since the email addresses use a different search mechanism. Finally, provide the email address for search as the CustomerUserID parameter, but you make sure to URL encode the value because it can contain some unsafe characters.

Note

Mechanism described above works for any of the following ticket create screens:

New Phone Ticket (default slug: /agent/ticket/create/phone)

New Email Ticket (default slug: /agent/ticket/create/email)

New SMS Ticket (default slug: /agent/ticket/create/sms)

New Process Ticket (default slug: /agent/ticket/create/process)

Considering the new process ticket screen consists of a more complex form, you must also provide a correct ProcessID parameter in order for the process to be pre-selected. For example:

https://otrs.example.com/agent/ticket/create/process?ProcessID=Process-9690ae9ae455d8614d570149b8ab1199&CustomerUserSearch=1&CustomerUserID=12345678

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Custom URL Support

Most OTRS front ends support automation via custom URL addresses, whether for specifying configuration parameters, or automating forms. This mechanism can be used to integrate OTRS easily into existing workflows, or just provide a quick pre-configured overview of objects. There is no limit to number of use-cases.

Triggering Actions

Actions in the agent interface can be automatically triggered via a special URL parameter called TriggerAction. The approach outlined below works for any action which is registered for the current screen.

For example, let’s trigger the Change Free Fields action available in the ticket detail view.

Identify the slug name of the view in question. For the ticket detail view and the ticket with ID 1 this is:

/agent/ticket/1

Identify the BusinessObjectType of the screen where the action should be triggered. In our case, for the ticket detail view, this is:

Ticket

Go to System Configuration in the administrator interface and search for the action registration setting in question. In our case this is:

AgentFrontend::Ticket::Action###FreeText

Identify the value of the Component key in the setting, which is the name of the front end component. In our case this is:

TicketFreeText

Construct the action identifier in form of <BusinessObjectType>::<Component>. In our case, this is:

Ticket::TicketFreeText

Append a query parameter to the URL of the detail view named TriggerAction, and set it to the action identifier, which is the value constructed in the previous step:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText

Note

In case of custom URL query parameter values, we have to take care to encode all special characters that are normally used in URLs (e.g. double quotes). This process is called “URL encoding”, and can be done by any of freely available on-line tools, like the Online Text Tools.

When visiting the URL as constructed above, the action will be automatically triggered:

Automatically Triggered Change Free Fields Action

Note

Please keep in mind that any restrictions applied to the regular screen actions will still be honored. For example, you will not be able to trigger an action which is currently not accessible, e.g. because you don’t have permissions to it, or it was filtered out by the ACL rules in effect.

Pre-populating Form Fields

OTRS form fields can be pre-populated with values supplied via URL query parameters. The approach outlined below works for any form in the agent and external interface.

For example, let’s see how we can pre-populate the Title field of the Change Free Fields action form, which we triggered in the previous example.

Since this action is not initially shown on the screen, we will keep the trigger action parameter in place, and just add on to it:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText

Identify the name of the form field in question.

In our case, we are dealing with the following form:

Forms###AgentFrontend::Ticket::Action::FreeText

According to the form fields reference, field is aptly named:

Title

Append a query parameter to the URL of the detail view with the name of the field, and set it to the desired value:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText&Title=Some+text

Note

Additional URL query parameters can be chained with an ampersand character (&).

Note

In case of custom URL query parameter values, we have to take care to encode all special characters that are normally used in URLs (e.g. double quotes). This process is called “URL encoding”, and can be done by any of freely available on-line tools, like the Online Text Tools.

When visiting the URL as constructed above, the action will be automatically triggered and the field pre-populated:

Pre-populated Title Field of the Change Free Fields Action

The approach can be repeated for all other fields in the form, for example, if we would also like to set the Service field (field name ServiceID) to a hypothetical value Service 2 with an ID of 2, we can add it to the existing URL like this:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText&Title=Some+text&ServiceID=2

When visiting the URL as constructed above, the action will be automatically triggered and both fields pre-populated:

Pre-populated Title and Service Fields of the Change Free Fields Action

Note

In case of most drop-down fields that contain business objects (e.g. services, queues, etc.), you must always provide the ID of the object, not its label. You can recognize these form fields by the ID suffix in their name. You should always do a lookup of the object ID value, and set the field to it.

Note

Please keep in mind that any restrictions applied to the regular action form fields will still be honored. For example, you will not be able to set a value to a disabled field, or select an option which was filtered out by the ACL rules in effect.

Submitting Actions

Actions in the agent interface can be automatically submitted by via a special URL parameter called SubmitForm. The approach outlined below works for any action which is registered for the current screen.

For example, let’s see how we can submit the Change Free Fields action form, which we already triggered and pre-populated in previous examples.

Since this action is not initially shown on the screen, we will keep the trigger action parameter in place, as well as some form field parameters, and just add on to it:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText&Title=Some+text&ServiceID=2

Append a query parameter to the URL of the detail view named SubmitForm and set 1 as its value:

/agent/ticket/1?TriggerAction=Ticket%3A%3ATicketFreeText&Title=Some+text&ServiceID=2&SubmitForm=1

When visiting the URL as constructed above, the action will be automatically triggered, both fields pre-populated and the action immediately submitted:

Automatically Submitted Change Free Fields Action

Note

Please keep in mind that any restrictions applied to the regular action forms will still be honored. For example, you will not be able to submit an invalid form by omitting a mandatory field, or setting a field to an invalid value.

Custom Business Object Lists

All static business object lists in the agent interface support custom configuration via a special URL parameter called Config. The approach outlined below works for similar screens which are listed in the following section, and for any keys documented in the YAML reference.

For example, let’s see how we can set an active filter preset for a business object list by carefully constructing a direct URL for the view.

Identify the slug name of the view in question. We will be using AgentFrontend::TicketList::Static which has the slug:

/agent/tickets/static

Go to System Configuration in the administrator interface and search for the screen configuration setting in question, in our case this is:

AgentFrontend::TicketList::Static###DefaultConfig

Make sure that the key AllowGETConfig in the screen configuration contains the properties FilterPresets and FilterPresetSelected, which we will pass via the query parameter.

To be able change these keys, they must present in the list, otherwise they will be ignored. For more information, please see the key reference.

Screen Configuration with Defined Allowed Keys

Construct a valid YAML configuration that defines a user-defined filter preset and sets it as pre-selected.

---
FilterPresets:
  "Total Tickets":
    CustomerID:
      Value: my-customer@otrs.com
FilterPresetSelected: "Total Tickets"

Convert the YAML structure from previous step into JSON syntax, since YAML is unsuitable for passing via parameters. If we do this, we get the following analogous structure.

{
   "FilterPresets": {
      "TotalTickets": {
         "CustomerID": {
            "Value": "my-customer@otrs.com"
         }
      }
   },
   "FilterPresetSelected": "Total Tickets"
}

Remove all the extra white space to compress this configuration into a single line.

{"FilterPresets":{"Total Tickets":{"CustomerID":{"Value":"my-customer@otrs.com"}}},"FilterPresetSelected":"Total Tickets"}

To pass the configuration to the screen located at /agent/tickets/static, we just need to define an URL query parameter named Config and set the JSON structure above as its value.

Note

In case of custom URL query parameter values, we have to take care to encode all special characters that are normally used in URLs (e.g. double quotes). This process is called “URL encoding”, and can be done by any of freely available on-line tools, like the Online Text Tools.

/agent/tickets/static?Config=%7B%22FilterPresets%22%3A%7B%22Total%20Tickets%22%3A%7B%22CustomerID%22%3A%7B%22Value%22%3A%22my-customer%40otrs.com%22%7D%7D%7D%2C%22FilterPresetSelected%22%3A%22Total%20Tickets%22%7D

Example of the Filter Preset Defined via URL Query Parameter

Note

Did you know that you can use many freely available on-line tools to do the conversion steps outlined above? Some of them even support chaining, like the Online YAML Tools for the example above.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Inline Editing

OTRS provides an inline editing feature to easily modify any of the ticket attributes right in a list table or a property card. This allows for fast contextual edits, which can amplify an already instituted workflow for tickets and make it easier for agent users to do their daily work.

Inline Editing in Business Object Lists

For an example, we will demonstrate how to turn on inline editing for the State ticket attribute in the Recently Created Tickets list screen.

Go to the System Configuration screen.

Search for the setting AgentFrontend::TicketList::Created###DefaultConfig.

Edit the setting and change the IsInlineEditable flag to 1 under the State column.

State:
  IsVisible: 2
  IsInlineEditable: 1

Search for the setting AgentFrontend::Ticket::InlineEditing::Property###State and verify the required permission level and lock state on the ticket, in order for the editing to be allowed for the user. By default, this attribute will require state permission type and ticket in a locked state.

Deploy the modified system configuration.

From now on, the State ticket attribute will be editable in a popover which is displayed by hovering the value in the same table column on the Recently Created Tickets list screen. By using the provided drop-down field, the ticket state can be changed after clicking on the Save button.

Ticket State Inline Editing in Business Object List

Warning

Please note that inline editing is only applicable for ticket lists in the organizer items or static screens, and not widgets. Ticket lists in widgets have very limited space, and the column popovers are disabled for them all together.

Note

For granular permission to the inline editing of ticket attributes, you can also employ Access Control Lists (ACL). Each ticket attribute can be targeted by the AgentFrontend::Ticket::InlineEditing::Property::* endpoint namespace.

For our example from above, this can be done by the targeting the AgentFrontend::Ticket::InlineEditing::Property::State context.

Inline Editing in Property Cards

For an example, we will demonstrate how to turn on inline editing for a ticket dynamic field property card in the Properties widget on the ticket detail view.

The following example uses a dynamic field named Test1. Please make sure that you replace it with the actual name of your dynamic field.

Go to the System Configuration screen.

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

Edit the setting and add a property definition under the Properties key for the dynamic field in question:

Properties:
- Name: DynamicField_Test1
  IsVisible: 2
  IsInlineEditable: 1

Note the IsInlineEditable flag which is set to 1 in order to activate inline editing feature for this property card.

Search for the setting AgentFrontend::Ticket::InlineEditing::Property###DynamicField.

Edit the setting and add a configuration for the dynamic field by clicking on the plus button. Choose the name of the dynamic field under the DynamicFieldName key. Verify the required permission level and lock state on the ticket, in order for the editing to be allowed for the user. By default, this attribute will require rw permission type and ticket in an unlocked state.

Dynamic Field Inline Editing Configuration

Deploy the modified system configuration.

From now on, the configured dynamic field property card will be editable in the Properties widget of the ticket detail view. An editing icon in the upper right corner of the property card will switch the card in the editing mode. The dynamic field value can then be changed changed after clicking on the Save button.

Dynamic Field Inline Editing in Properties Widget

Warning

Please note that property cards are shown only for defined dynamic field values. If a ticket does not have a dynamic field value set, the property card will not be shown, and, in turn, it will not be possible to edit it inline. Similarly, in case you remove an existing dynamic field value, property card will disappear.

Note

For granular permission to the inline editing of ticket dynamic field values, you can also employ Access Control Lists (ACL). Each dynamic field can be targeted by the AgentFrontend::Ticket::InlineEditing::Property::DynamicField_* endpoint namespace.

For our example from above, this can be done by the targeting the AgentFrontend::Ticket::InlineEditing::Property::DynamicField_Test1 context.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

External Link Previews

OTRS supports link previews via several features aimed at integrating externally provided content. By having contextual information in the right place, agent’s daily work can be made much more streamlined and straightforward.

Article Meta Filters

Article content can be automatically scanned and relevant information extracted with the help of meta filters.

For example, let’s configure extraction of CVE codes from article preview in the ticket detail view and display direct links to external pages with more information.

Go to the System Configuration in the administrator interface, and enable the AgentFrontend::TicketDetailView::ArticleMeta master switch for the article meta feature.

Search for the setting AgentFrontend::TicketDetailView::ArticleMetaFilters###0002-Custom and enable it.

Edit the setting, and set its value to the following YAML configuration:

---
- Label: CVE Details
  Name: cvedetails
  Target: _blank
  URL: https://www.cvedetails.com/cve/<MATCH1>-<MATCH2>-<MATCH3>
  URLPreview: https://www.cvedetails.com/cve/<MATCH1>-<MATCH2>-<MATCH3>
  RegExp:
  - (CVE|CAN)\-(\d{3,4})\-(\d{2,})
  Active: 1

To configure the Content Security Policy, search for the setting WebApp::Server::AdditionalOrigins.

Add the following origin under the frame-src key, in order to allow these web pages for embedding in the OTRS application:

https://www.cvedetails.com

Additional Origins for Content Security Policy

Deploy the modified system configuration.

To test the feature, you will now need a ticket article that contains at least one valid CVE identifier in its text, for example CVE-2019-1290.

Article Meta Preview

A button will be shown below the preview area in the Communication Stream or Communication Compact widget, which leads to the external page. Hovering over this button will show a preview popover with the scaled down content of the same page.

Dynamic Field Value

A dynamic field can be configured to show a link preview based on its value. The value can be used as whole or part of the link in question.

The following example use a dynamic field named Field1. Please make sure that you replace it with the actual name of your dynamic field.

Configure the dynamic field to show a link based on its value via Link for preview setting. Please see the setting reference for more information.

You can use the following value for testing:

https://example.com/handle?query=[% Data.Field1 | uri %]

Configure the display of the dynamic field value in ticket detail view, for example in the Properties widget. Please see the relevant guide for more information.

Search for the setting WebApp::Server::AdditionalOrigins in the System Configuration.

Add the following origin under the frame-src key, in order to allow these web pages for embedding in the OTRS application:

https://example.com

Additional Origins for Content Security Policy

Deploy the modified system configuration.

To test the feature, you will now need a ticket with a value set for the dynamic field in question. To set this field via a ticket action, please see the relevant guide for more information.

Dynamic Field Link Preview

If defined, the ticket dynamic field value will be shown as a property card in the Properties widget, in form of a button which leads to the configured link. Hovering over this button will show a preview popover with the scaled down content of the same page.

Troubleshooting

In case you can not see the preview of the configured link, please note that target web servers might have a configuration in place that prevents them from being embedded in external pages. This is indicated by following or similar errors in the browser console:

Load denied by X-Frame-Options: “SAMEORIGIN” from “site”, site does not permit cross-origin framing from “site”.

Firefox prevented this page from loading in this context because the page has an X-Frame-Options policy that disallows it.

The blocking is normally done via the X-Frame-Options response header which can be set to the prevent the preview on the browser level. If you have the control of the target web server configuration, you might be able to relax this restriction by including the OTRS domain name in the list of allowed origins, or lift the restriction all together.

For more information, please take a look at X-Frame-Options page in the Mozilla Developer Network.

Alternatively, the newer frame-ancestors directive of the Content Security Policy header can be used to block embedding of the target server. This is indicated by following or similar error in the browser console:

Refused to display 'https://example.com/...' in a frame because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'".

For more information, please take a look at CSP: frame-ancestors page in the Mozilla Developer Network.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Glossary

Activity

Part of the process management.

Agent

An agent is a user which services customer users. The person working for your organization.

Back end

A configuration file, module, script or other functional item within OTRS which is not reachable via the browser.

Calendar

Defines working hours, time-zone, and holidays to be applied when using escalation times.

Customer

Physical organizations to which customer users are assigned. These provide the function to group users together which belong to a single organization.

Customer User

Physical persons, and their contact data, which belong to a customer. These are the people raising tickets.

Dynamic Field

A field used in tickets and articles to extend the data which can be saved in a ticket or article. They are saved from values in the database or accessed from outside resources.

Escalation Times

The defined amount of working time before a ticket breaches an agreement.

Front end

The graphical interface to OTRS as viewed in a browser.

Group

This is a resource within OTRS. An agent or a customer can be assigned permissions to this resource as needed. Additionally, they can be used for access control, processes and web services.

Invoker

An invoker is a special Perl module which allows OTRS to provide information to a remote system via REST or HTTP. Invokers must be developed in Perl by a back end developer.

Mapping

A mapping allows OTRS to provide inbound and outbound translation of data allowing us to offer a specific data construction to rebuild incoming structures to meet our needs.

Operation

Similar to a web hook, a provider operation offers a specific sub-set of OTRS Perl API functionality to external systems.

Process

Part of the process management.

Process Path

Part of the process management.

Resource

A resource is any object which has effective permissions. This can be, but is not limited to, a ticket, dashboard widget, statistic, or module.

Screen

A graphical interface to OTRS viewed in a browser (see also Front end).

Service

A means of delivering added value to customers by making it easier for customers or helping them to achieve their desired results without them having to personally bear the responsibility for specific costs and risks.

Service Level Agreement

A service level agreement (SLA) is a contract between a service provider (either internal or external) and the end user that defines the level of service expected from the service provider. SLAs are output-based in that their purpose is specifically to define what the customer will receive.

Service Request

(see also Ticket).

Sequence Flow

Part of the process management.

Sequence Flow Action

Part of the process management.

SLA

(see also Service Level Agreement).

Ticket

A ticket is a collection of all communications with a customer during the course of a service request. A ticket contains article, which are the communication received from or sent to customers, agents, external systems, etc. Tickets belong to a customer user, are assigned to agents and reside in queues.

Transport

A transport is the method chosen for communication. OTRS support REST and SOAP.

User Task Activity Dialog

Part of the process management.

Working Time

A definition of minutes passed during the defined working hours of any calendar.

OTRS Offers an Ideal Solution for Companies of Any Size Learn more

Index

A | B | C | D | E | F | G | I | M | O | P | R | S | T | U | W

A

Activity

Agent

B

Back end

C

Calendar

Customer

Customer User

D

Dynamic Field

E

Escalation Times

F

Front end

G

Group

I

Invoker

M

Mapping

O

Operation

P

Process

Process Path

R

Resource

S

Screen

Sequence Flow

Sequence Flow Action

Service

Service Level Agreement

Service Request

SLA

T

Ticket

Transport

U

User Task Activity Dialog

W

Working Time