Generic Agent

General Job Settings

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. A job can be renamed after creation.

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.

The job fires at every combination of selected minutes, hours, and days. At least one value must be selected in each of the three fields for the automatic schedule to be active. If any field is left empty, a warning is displayed and the job will not run on a schedule.

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.

Warning

The automatic execution should not be performed more than one per hour. Exceeding this limit may affect your system performance.

Schedule hours

Select the hours in which the job has to be executed. For example if 10 is selected for minutes and 03 is selected for hours, the job will be executed in every day in 03:10.

Schedule days

Select the days in which the job has to be executed. For example if 10 is selected for minutes, 03 is selected for hours and Fri is selected for days, the job will be executed in every week in Friday 03:10.

Event Based Execution

Fill in this section to set events that trigger the execution of the job. A job may have both a schedule and event triggers — they run independently of each other.

An event trigger watches for a specific change to a ticket, such as the ticket being moved to a different queue or a new article being added. When that change occurs, the job runs automatically.

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.

Each event trigger has an All Tickets checkbox:

• When unchecked (default), the job acts only on the specific ticket that fired the event.

• When checked, the job ignores the triggering ticket and instead runs the Select Tickets filter, processing all matching tickets — the same behavior as a scheduled run, but initiated by the event.

Add Event Trigger

Select an object and a related event that will trigger the job. Available event types include Ticket, Article, and Session. Additional types may be present depending on which features are active in the system.

Common ticket events:

Event	When it fires
TicketCreate	A new ticket is created.
TicketQueueUpdate	A ticket is moved to a different queue.
TicketStateUpdate	A ticket’s state changes.
TicketPriorityUpdate	A ticket’s priority changes.
TicketOwnerUpdate	A ticket’s owner changes.
TicketLockUpdate	A ticket is locked or unlocked.
ArticleCreate	A new article (email, note, phone call, etc.) is added.

Event execution

Controls whether the job runs immediately or in the background when an event fires.

Instant (may block screen)

The job runs synchronously as part of the same action that triggered the event. The agent’s screen may be briefly delayed while the job completes. This is the default.

Daemon

The job is handed off to the OTRS background service and runs asynchronously. The agent’s screen responds immediately without waiting.

Use Daemon when the job could match a large number of tickets, or when the job performs heavy processing such as Ticket Allocation calculations.

Note

When the same event fires for several tickets at once, each ticket gets its own separate background task. Tasks for different tickets can run in parallel, but at most one task per job and ticket combination is queued at any time. The order in which tasks for different tickets run is not guaranteed.

Prevent infinite loops

An infinite loop can occur when a job’s action re-fires the same event that triggered it. For example: a job that listens to queue changed and then moves the ticket to a different queue will re-fire queue changed, which would trigger the job again.

No

No protection. If the job’s action re-fires its own trigger event, the job will run again. This is the default for backward compatibility.

Yes

The system records that this job is already processing this ticket and event combination. If the same combination is seen again before the current run finishes, the second execution is silently skipped.

Enable this setting for any event-triggered job whose actions could re-fire the same event on the same ticket. The protection record expires after 10 minutes. This protection works for both Instant and Daemon execution modes.

Note

This protection is per job. Two different jobs listening to the same event can each still run once — they do not block each other.

Warning

Misconfiguration of event-triggered jobs, especially when Prevent infinite loops is set to No, can lead to repeated or infinite execution loops that degrade system performance.

Select Tickets

This section contains all the attributes that you can use to select the affected tickets. All fields are optional. Leaving all fields empty matches all tickets in the system, subject to the processing limit.

Multiple values selected within one field match tickets that have any of those values (OR). Using multiple fields requires a ticket to match all of them (AND).

Dynamic fields of type attachment could be used only in this section. However, it is not updatable by generic agent and this type of dynamic fields are not listed in Update/Add Ticket Attributes section.

Extended search conditions can be used for some fields and the possible syntaxes are:

Here are some examples for extended searches in the ticket title:

The time filter fields (Create times, Last changed times, Change times, Last close times, Close times, Pending times, Escalation times) each offer three options:

• No settings — this dimension is not used as a filter.

• Relative time window — matches tickets where the event falls within a window relative to now. Set a direction (within the last, within the next, or more than … ago), a number (1–60), and a unit (minutes, hours, days, weeks, months, or years).

• Between two dates — matches tickets where the event falls between two specific dates.

Update/Add Ticket Attributes

Fill in this section to update and/or add ticket attributes. All fields are optional — leave a field empty to leave that attribute unchanged.

Dynamic fields of type date or date and time can be set to absolute, relative or no date. The values can be positive like +5 days or negative like -10 hours based on the current time.

Dynamic fields of type attachment are not listed in this section.

Pending date

Sets a pending reminder time relative to the moment the job runs. Enter a number and select a unit (minutes, hours, days, months, or years). For example, entering 2 with day(s) sets the reminder to 2 days from now.

Note

The pending time is only applied when the new state set by this job is a pending state, or — if no new state is configured — when the ticket is already in a pending state. If neither condition is true, this field has no effect.

All other fields in this section are self-explanatory.

Add Note

Fill in this section to add a note to tickets that are affected by job execution.

From

The sender name shown in the note. Defaults to GenericAgent if left empty.

Subject

The note subject line. Defaults to Note if left empty.

Text

The note body. This field must be filled for the note to be created. Maximum 200 characters.

Visible to customer

When unchecked (default), the note is internal and only visible to agents. When checked, the note is visible to the customer.

Time units

Time to book against the ticket for time accounting purposes.

Execute Ticket Commands

Fill in this section, if you would like to execute a command or delete tickets with the job.

Send agent/customer notifications on changes

If Yes is selected (default), notifications are sent to agents and customers about ticket changes according to the configured notification rules. If No is selected, all notifications for changes made by this job are suppressed.

CMD

Enter a command here, that will be executed. ARG[0] will be the ticket number. ARG[1] the ticket ID. Use :: as directory separator, if the value contains a path.

See also

Commands to be run by OTRS are blocked by default due to security reasons. You have to add the command to the allow list as described in Allow Program Safe to Run chapter.

Note

This feature is only available to On-Premise customers. If you are a Managed customer, this feature is taken care of by the Customer Solutions Team in OTRS. Please contact us via support@otrs.com or in the OTRS Portal.

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 Modules

Fill in this section to execute a custom module with the job, or to use a specialized ordering or pre-action module.

Order module

A module that receives the full list of matched tickets and returns them in a custom processing order. The job then processes tickets in that order. If the module returns no result, the job falls back to processing tickets in ascending ticket ID order and logs an error.

This module runs for both scheduled and event-triggered job executions.

The built-in option Ticket Allocation sorts tickets according to Ticket Allocation priority rules (queue priorities, service-time constraints, maximum tickets per queue) so that the most urgent tickets are processed first. Leave this field empty if you are not using Ticket Allocation.

Pre action module

A module that runs once per matched ticket, before the configured ticket actions are applied. It can modify which actions are taken on that specific ticket — for example, dynamically determining which agent should be assigned based on current workload. If the module returns no result or encounters an error, the original configured actions are used unchanged as a fallback and an error is logged.

This module runs for both scheduled and event-triggered job executions.

Warning

Ticket actions configured in this job may be overwritten by this module.

The built-in option Ticket Allocation automatically determines the right agent for each ticket based on availability, workload, group permissions, and optionally agent competences. Leave this field empty if you are not using Ticket Allocation.

Module

This is the path for a custom module to be executed once per matched ticket, after all other ticket attribute changes have been applied.

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. Up to six key/value parameter pairs can be defined. These parameters are injected into the job configuration before the module runs and will not overwrite any built-in job settings.

Execution Order Within a Job Run

When a job processes a ticket, actions are applied in the following sequence. This matters when combining multiple actions — for example, the note is created before the state changes, so it reflects the ticket state prior to any state update made by this job.

1. Pre action module (if configured).

2. Move to new queue.

3. Add note (if text body is set).

4. Change state and set pending time.

5. Set customer user / customer ID.

6. Change title.

7. Change type / service / SLA / priority.

8. Change owner / responsible / lock.

9. Update dynamic fields.

10. Apply archive flag.

11. Run custom module (Module field).

12. Run shell command (CMD field).

13. Delete ticket (if enabled — always last).