Wialon for developers User guide API reference unit create_task

create_task

The unit/create_task method allows you to create a task for a unit. To edit an existing task, use unit/update_task. For information about how tasks work in the monitoring system, see Tasks.

In Wialon Local, this method is available starting from version 2504.

Endpoint

Copied!
svc=unit/create_task&params={
	"itemId": <long>,
	"props": {
		"key1": <long>,
		"key2": <text>,
		.....
	}
}

Request example:

Copied!
https://hst-api.wialon.com/wialon/ajax.html?
svc=unit/create_task&
params={
  "itemId": 1514,
  "props": {
    "task_sub_type": 22,
    "task_evt_name": "Refueling",
    "task_description": "Refuel the vehicle before the trip",
    "task_priority": 3,
    "task_params": {
      "filled": 40
    }
  }
}&
sid=SESSION_IDENTIFIER

Parameters

The request must contain the following parameters:

Parameter Description
itemId The ID of the unit.
props The object of task properties (key-value pairs). See the list of available properties below.

Task properties

The required properties are marked with an asterisk (*).

Property Type Description
task_sub_type* Integer The task subtype. Acceptable values are:
  • 21 (custom)
  • 22 (fuel filling)
  • 23 (battery charge)
  • 26 (maintenance work)
For all the subtypes, see Event and task subtypes.
task_evt_name* String The name of the task. It must not be empty.
task_description String The description of the task.
task_assignee Long The ID of the user to whom the task is assigned. You need the Act on behalf of this user access right to this user.
task_priority Integer The priority of the task. Acceptable values are:
  • 1 (Low)
  • 2 (Medium)
  • 3 (High)
If the property isn’t specified, 2 is used.
task_status Integer The status of the task. A new task always gets the 1 (New) status, so the property must be 1 or omitted.
task_create_time Integer The time when the task is created (UNIX time). If the property isn’t specified, is 0, or is later than the current server time, the current server time is used. The task update time is set to the same value.
task_address_x
task_address_y		 Double The coordinates of the task. Specify both properties. If only one of them is specified, both are ignored.
task_params Object Additional task parameters. Supported keys:
  • filled (amount of fuel filled)
  • charged (amount of energy charged)
  • cost (task cost)
  • engine_hours (vehicle engine hours)
  • mileage (vehicle mileage)
The filled and mileage values are specified in the measurement system of the unit.

The following properties can’t be set when a task is created. If you pass them, use the values below:

Property Acceptable value
task_id Any. The value is ignored, and the server generates the task ID.
task_update_time Any. The value is ignored, and the value of task_create_time is used.
task_tags An empty string.
task_comments An empty array.
task_done_rejected 0.

Access rights

To create a task, you need the Edit tasks access right to the unit. To assign the task to a user with task_assignee, you also need the Act on behalf of this user access right to this user.

The Tasks service must be enabled for the account.

Response

If the request is completed successfully, an empty response is returned.

Copied!
{}

To get the ID of the created task, use messages/get_task_messages.

Otherwise, an error code is returned. Example:

Copied!
{
    "error": 4,
    "reason": "INVALID_INPUT_PARAMS"
}

Error codes

Error code Description reason field value
4 Invalid input. One of the following:
  • a required parameter or property is missing or has a wrong type
  • task_sub_type has a value that isn’t in the list of acceptable values
  • task_evt_name is empty
  • task_status isn’t 1
  • the user specified in task_assignee doesn’t exist
  • task_tags, task_comments, or task_done_rejected isn’t empty
 INVALID_INPUT_PARAMS
6 Tasks aren’t supported for the item with the specified itemId. UNKNOWN_ERROR
7 Access denied. One of the following:
  • the unit with the specified itemId doesn’t exist or isn’t accessible to the current user
  • the Edit tasks access right to the unit is missing
  • the Act on behalf of this user access right to the user specified in task_assignee is missing
  • the Tasks service isn’t enabled for the account
 NO_ACCESS_TO_USER (only if the access right to the user is missing)

For the general error codes, see Error codes.

If you find a mistake in the text, please select it and press Ctrl+Enter.