Ticket Automatic Tasks

7 views Markdown

The five endpoints that set up and manage the rules running on tickets by themselves.

Overview

Automatic tasks are rules that run on tickets by themselves. Every task has two halves: the conditions saying which tickets it looks at, and the results saying what it does to them.

The conditions are department, status, priority and waiting time. The results are moving a ticket, turning its status, changing its priority, assigning it, locking it and replying to the client. A task has to carry at least one field from each half.

The commonest use is closing solved tickets after a while. Take care when a task sends a reply: the rule mails the client on every ticket it matches.

Reference

Listing the Tasks

get/api/v1/admin/tickets/auto-tasks
Tickets/GetTicketAutoTasks admin

Returns the rules that run on tickets by themselves.

Response fields data[] — 14
idintThe task id.
namestringThe task name.
departmentsstring[]Condition: which departments. Empty means it does not care.
statusesstring[]Condition: which statuses.
prioritiesint[]Condition: which priorities.
delay_timeintCondition: how long the ticket has been waiting.
departmentintResult: moves the ticket to this department.
statusstringResult: turns the status into this.
priorityintResult: sets the priority to this.
assign_tointResult: assigns the ticket to this person.
mark_lockedboolResult: locks the ticket.
templatestringResult: the prepared reply to use.
repeat_actionboolWhether it runs again each time the condition holds.
replyobjectResult: the reply text to send, per language.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/tickets/auto-tasks' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.example.com/api/v1/admin/tickets/auto-tasks', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/auto-tasks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Each row carries both CONDITION and RESULT fields side by side; read them apart.
$tasks = Api::Tickets()->GetTicketAutoTasks()['data'];

Creating a Task

post/api/v1/admin/tickets/auto-tasks
Tickets/CreateTicketAutoTask admin condition and result both needed

Sets up a new rule to run on tickets.

Body 13
namestringreqThe task name.
departmentsstring[]Condition: tickets in these departments.
statusesstring[]Condition: tickets in these statuses.
prioritiesint[]Condition: tickets at these priorities.
delay_timeintCondition: tickets waiting this long.
departmentintResult: move to this department.
statusstringResult: turn the status into this.
priorityintResult: set the priority to this.
assign_tointResult: assign it to this person.
mark_lockedboolResult: lock the ticket.
templatestringResult: use this prepared reply.
replyobjectResult: send this text, per language.
repeat_actionboolRuns it again each time the condition holds.
Response fields 201 — data
dataobjectThe task created. Same shape as a list item.
Errors 4
name_required422The task name is empty.
trigger_required422No condition was given.
action_required422No result was given.
insufficient_scope403The key lacks the required scope.
Request 
curl -X POST 'https://panel.example.com/api/v1/admin/tickets/auto-tasks' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Cozulenleri kapat","statuses":["solved"],"delay_time":72,"mark_locked":true}'
const res = await fetch('https://panel.example.com/api/v1/admin/tickets/auto-tasks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Close solved tickets',
    statuses: ['solved'],      // kosul
    delay_time: 72,            // kosul
    mark_locked: true,         // sonuc
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/auto-tasks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name'        => 'Close solved tickets',
        'statuses'    => ['solved'],
        'delay_time'  => 72,
        'mark_locked' => true,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// At least ONE condition and ONE result are needed; sending only conditions gives a 422.
Api::Tickets()->CreateTicketAutoTask([
    'name'        => 'Close solved tickets',
    'statuses'    => ['solved'],   // condition
    'delay_time'  => 72,           // condition
    'mark_locked' => true,         // result
]);

Reading One Task

get/api/v1/admin/tickets/auto-tasks/{tid}
Tickets/GetTicketAutoTask admin

Returns a single automatic task.

Response fields data — 14
idintThe task id.
namestringThe task name.
departmentsstring[]Condition: which departments. Empty means it does not care.
statusesstring[]Condition: which statuses.
prioritiesint[]Condition: which priorities.
delay_timeintCondition: how long the ticket has been waiting.
departmentintResult: moves the ticket to this department.
statusstringResult: turns the status into this.
priorityintResult: sets the priority to this.
assign_tointResult: assigns the ticket to this person.
mark_lockedboolResult: locks the ticket.
templatestringResult: the prepared reply to use.
repeat_actionboolWhether it runs again each time the condition holds.
replyobjectResult: the reply text to send, per language.
Errors 2
not_found404No such task.
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/tickets/auto-tasks/3' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch(`https://panel.example.com/api/v1/admin/tickets/auto-tasks/${tid}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/auto-tasks/' . $tid);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// An empty condition field does NOT narrow the task, it widens it: every department matches.
$task = Api::Tickets()->GetTicketAutoTask(['tid' => $tid])['data'];

Updating a Task

patch/api/v1/admin/tickets/auto-tasks/{tid}
Tickets/UpdateTicketAutoTask admin

Changes the task fields you send.

Body 13
namestringreqThe task name.
departmentsstring[]Condition: tickets in these departments.
statusesstring[]Condition: tickets in these statuses.
prioritiesint[]Condition: tickets at these priorities.
delay_timeintCondition: tickets waiting this long.
departmentintResult: move to this department.
statusstringResult: turn the status into this.
priorityintResult: set the priority to this.
assign_tointResult: assign it to this person.
mark_lockedboolResult: lock the ticket.
templatestringResult: use this prepared reply.
replyobjectResult: send this text, per language.
repeat_actionboolRuns it again each time the condition holds.
Response fields data — 14
dataobjectThe task as it now stands. Same shape as a list item.
Errors 5
name_required422The task name was emptied.
trigger_required422No condition remains after the change.
action_required422No result remains after the change.
not_found404No such task.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PATCH 'https://panel.example.com/api/v1/admin/tickets/auto-tasks/3' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"delay_time":48}'
const res = await fetch(`https://panel.example.com/api/v1/admin/tickets/auto-tasks/${tid}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ delay_time: 48 }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/auto-tasks/' . $tid);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['delay_time' => 48]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The condition-and-result rule is checked on the MERGED set: emptying the last one fails.
Api::Tickets()->UpdateTicketAutoTask(['tid' => $tid, 'delay_time' => 48]);

Deleting a Task

delete/api/v1/admin/tickets/auto-tasks/{tid}
Tickets/DeleteTicketAutoTask admin

Removes an automatic task.

Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the task removed.
Errors 2
not_found404No such task.
insufficient_scope403The key lacks the required scope.
Request 
curl -X DELETE 'https://panel.example.com/api/v1/admin/tickets/auto-tasks/3' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch(`https://panel.example.com/api/v1/admin/tickets/auto-tasks/${tid}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/auto-tasks/' . $tid);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// There is NO switch to pause a task; deleting it is the only way to stop it.
Api::Tickets()->DeleteTicketAutoTask(['tid' => $tid]);

Pitfalls

A condition and a result are both needed

A task has to carry at least one condition and at least one result. Sending conditions alone gives a match that does nothing, and sending results alone would give a rule applying to every ticket. Either one missing means the call is refused.

An empty condition widens rather than narrows

A condition field left empty draws no distinction: an empty department list matches tickets in every department. Reading that as "none" leads to writing a rule that touches the whole installation. To narrow the reach, fill the field in rather than leaving it empty.

The reply result really sends mail

A task with the reply field filled writes that text on every ticket matching the condition, and mail goes to the client. Paired with a wide condition, one rule change reaches hundreds of clients at once. Try a new reply rule against a narrow condition first.

The repeat option makes a rule ongoing

With repeat on, a task runs again every time the condition holds. On a rule that replies, that can mean the same text reaching the same client over and over. Leave repeat off for work that should happen once.

A task cannot be paused

Automatic tasks have no live switch; deleting a rule is the only way to stop it. To pause one, save its definition on your side, delete it and create it again later. The recreated task comes back with a new id.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Contact Us Open a Ticket

We use cookies to keep you signed in, remember your language and currency, and improve the site. Cookie Policy