Documentation

tasks.task.list

Returns array of tasks, each containing array of fields. In contrast to task.item.list, parameters of the tasks.task.list query can be specified in any sequence, as well as skip unnecessary parameters.

To get data for all tasks, user must have admin access permissions. Department manager will get access only to tasks in his/her hierarchy branch.

Also, tasks in "Favourites" can be retrieved via filtering by the parameter $filter[::SUBFILTER-PARAMS][FAVORITE]=Y.

Attention! Fields must be specified in select, because the default fields may be modified in the future.

Function parameters

Parameters

ParameterDescription
orderArray for sorting of result. Array of the type {"sorting_field": 'sort_order' [, ...]}.
Field for sorting can have the following values:
  • ID - task ID;
  • TITLE - task name;
  • TIME_SPENT_IN_LOGS - time spent indicated in logs;
  • DATE_START - start date;
  • CREATED_DATE - date when created;
  • CHANGED_DATE - date when task was modified last;
  • CLOSED_DATE - date closed;
  • START_DATE_PLAN - plan start date;
  • END_DATE_PLAN - plan finish date;
  • DEADLINE - deadline;
  • REAL_STATUS - task status. Constants that reflect task statuses:
    • STATE_NEW = 1;
    • STATE_PENDING = 2;
    • STATE_IN_PROGRESS = 3;
    • STATE_SUPPOSEDLY_COMPLETED = 4;
    • STATE_COMPLETED = 5;
    • STATE_DEFERRED = 6;
    • STATE_DECLINED = 7;
  • STATUS_COMPLETE - task complete flag;
  • PRIORITY - priority;
  • MARK - evaluation;
  • CREATED_BY_LAST_NAME - task created by; 
  • RESPONSIBLE_LAST_NAME - last name of the task responsible user; 
  • GROUP_ID - workgroup. 
  • TIME_ESTIMATE - time spent on task;
  • ALLOW_CHANGE_DEADLINE - flag "Allow for responsible user to change deadline";
  • ALLOW_TIME_TRACKING - flag enabling task time tracking;
  • MATCH_WORK_TIME - skip weekends;
  • FAVORITE - favourite;
  • SORTING - sorting index;
  • MESSAGE_ID - search index ID;

Note: For Bitrix24 Self-hosted editions this list of fields for sorting can be returned via the method CTasks::getAvailableOrderFields().

Direction of sorting can have the following values:
  • asc - by ascension;
  • desc - by descension;
 Optional. By default, filtering is performed by descension of task ID.
filterArray type {"filtered_field": "filter value" [, ...]}. Filtered field can have the following values:
  • ID - task ID;
  • PARENT_ID - parent task ID;
  • GROUP_ID - workgroup ID;
  • CREATED_BY - creator;
  • STATUS_CHANGED_BY - user who was the last to modify task status;
  • PRIORITY - priority;
  • FORUM_TOPIC_ID - forum topic ID;
  • RESPONSIBLE_ID - responsible;
  • TITLE - task name (can be searched by template [%_]) ;
  • TAG -  tag;
  • REAL_STATUS - task status. Constants that reflect task statuses:
    • STATE_NEW = 1;
    • STATE_PENDING = 2;
    • STATE_IN_PROGRESS = 3;
    • STATE_SUPPOSEDLY_COMPLETED = 4;
    • STATE_COMPLETED = 5;
    • STATE_DEFERRED = 6;
    • STATE_DECLINED = 7;
  • STATUS - status for sorting. Similar to REAL_STATUS, but additionally has three meta-statuses:
    • -3 - task almost overdue;
    • -2 - task not viewed;
    • -1 - overdue task.
  • MARK - evaluation;
  • SITE_ID - site ID;
  • ADD_IN_REPORT - task in report (Y|N);
  • DATE_START - date when task started;
  • DEADLINE - deadline;
  • CREATED_DATE - date of creation;
  • CLOSED_DATE - date of completion;
  • CHANGED_DATE - date of last change;
  • ACCOMPLICE - observer ID;
  • AUDITOR - auditor ID;
  • DEPENDS_ON - previous task ID; 
  • ONLY_ROOT_TASKS -   root tasks only (not subtasks) as well as subtasks of parent task to which current user does not have access to (Y|N).
  • STAGE_ID - stage;
  • UF_CRM_TASK - CRM elements;

Type of filtration can be specified in front of the name of filtered field:
  • "!" - not equal
  • "<" - less
  • "<=" - less or equal
  • ">" - more
  • ">=" - more or equal

"filter value" - single value or array.

Optional. Records are not filtered by default.
ParameterDescription
orderArray for result sorting. Array type {"sort_field": 'sort order' [, ...]}.
Sorting field can have the following values:
  • ID - task ID;
  • PARENT_ID - parent task ID;
  • TITLE - task name;
  • DESCRIPTION - description;
  • MARK - evaluation;
  • PRIORITY - priority:
    • 0 - low;
    • 1 - medium;
    • 2 - high.
  • STATUS - status;
  • MULTITASK - multiple task;
  • NOT_VIEWED - task not viewed;
  • REPLICATE - recurring task;
  • GROUP_ID - workgroup. 
  • STAGE_ID - stage;
  • CREATED_BY - creator;
  • CREATED_DATE - date of creation;
  • RESPONSIBLE_ID - responsible;
  • ACCOMPLICE - participant ID;
  • AUDITOR - auditor ID;
  • CHANGED_BY - who modified task;
  • CHANGED_DATE - date when modified;
  • STATUS_CHANGED_DATE - date when status was updated;
  • CLOSED_BY - who closed task;
  • CLOSED_DATE - date when task is closed;
  • DATE_START - start date;
  • DEADLINE - deadline;
  • START_DATE_PLAN - planned start;
  • END_DATE_PLAN - planned completion date;
  • GUID - GUID (statistically unique 128-byte ID);
  • XML_ID - external code;
  • COMMENTS_COUNT - number of comments;
  • NEW_COMMENTS_COUNT - number of new comments;
  • TASK_CONTROL - task control;
  • ADD_IN_REPORT - add to report;
  • FORKED_BY_TEMPLATE_ID - created from template;
  • TIME_ESTIMATE - estimated time;
  • TIME_SPENT_IN_LOGS - estimated time from history log;
  • MATCH_WORK_TIME - skip weekends;
  • FORUM_TOPIC_ID - forum topic ID;
  • FORUM_ID - forum ID;
  • SITE_ID - site ID;
  • SUBORDINATE - task of subordinate;
  • FAVORITE - Favourites;
  • VIEWED_DATE - date when viewed last;
  • SORTING - sorting index;
  • DURATION_PLAN - duration (plan);
  • DURATION_FACT - duration (actual);
  • DURATION_TYPE - type of measurement unit within a scheduled duration: days, hours or minutes;

Optional. All the main noncomputable fields will be returned by default. List of fields can be clarified by sending tasks.task.getFields request.
limitNumber of records. Parameter is used to retrieve more than default number of records (50). All records cannot be retrieved in a single query due to system restrictions for all methods in REST API. You can execute several queries per 50 records to get all leads in response. Pass the 'start' parameter with the value multiple to value 50. Example:
start=0
start=50
start=100
startNumber of records to skip in the result. For example, with value 20, the result will skip all the first 20 entries and start displaying 21 entry onwards.

With value -1 disables the count.

Examples

  1. Print all tasks with the name "task for test", sorting by fields ID, TITLE, STATUS (sorting by ascension):
    BX24.callMethod(
    	'tasks.task.list', 
    	{filter:{TITLE:'task for test'}, select: ['ID','TITLE','STATUS'], order:{ID:'asc'}}, 
    	function(res){console.log(res.answer.result);}
    );
    

    Result:


  2. Printing all non-recurring tasks, added to "Favourites" with status higher than 2:
    BX.rest.callMethod('tasks.task.list', {filter:{'>STATUS':2, REPLICATE:'N', '::SUBFILTER-PARAMS':{FAVORITE:'Y'}}}, (res)=>{console.log(res.answer.result);})
    

    Result:

    result: {
    	tasks: [
    		{
    			id: "117",
    			parentId: null,
    			title: "123",
    			description: "Opisanie.   Ghhhhh",
    			mark: null,
    			priority: "0",
    			status: "6",
    			multitask: "N",
    			notViewed: "N",
    			replicate: "N",
    			groupId: "0",
    			stageId: "0",
    			createdBy: "1",
    			createdDate: "2019-03-15T15:41:27+02:00",
    			responsibleId: "1",
    			changedBy: "1",
    			changedDate: "2019-03-18T14:06:18+02:00",
    			statusChangedBy: "1",
    			statusChangedDate: "2019-03-18T14:05:54+02:00",
    			closedBy: null,
    			closedDate: null,
    			dateStart: null,
    			deadline: null,
    			startDatePlan: null,
    			endDatePlan: null,
    			guid: "{aef54f9d-8157-464b-9069-6ded9745e26d}",
    			xmlId: null,
    			commentsCount: null,
    			taskControl: "Y",
    			addInReport: "N",
    			forkedByTemplateId: null,
    			timeEstimate: "0",
    			timeSpentInLogs: null,
    			matchWorkTime: "N",
    			forumTopicId: null,
    			forumId: null,
    			siteId: "s1",
    			subordinate: "Y",
    			favorite: "Y",
    			exchangeModified: null,
    			exchangeId: null,
    			outlookVersion: "7",
    			viewedDate: "2019-03-18T14:07:08+02:00",
    			sorting: "2564.0000000",
    			durationPlan: "0",
    			durationFact: null,
    			durationType: "days",
    			descriptionInBbcode: "Y",
    			ufCrmTask: [ ],
    			ufTaskWebdavFiles: [
    				22
    			],
    			ufAuto915658270214: null,
    			ufAuto244510721805: null,
    			ufAuto637823431651: "0",
    			ufMailMessage: null,
    			ufAuto226929532613: "",
    			ufAuto187628303463: null,
    			auditors: [ ],
    			accomplices: [ ],
    			newCommentsCount: 0,
    			subStatus: "6",
    			creator: {
    				id: "1",
    				name: "John Smith",
    				link: "/company/personal/user/1/",
    				icon: "/upload/resize_cache/main/9b0/58_58_2/p2dVDwA46Nw.png",
    			},
    			responsible: {
    				id: "1",
    				name: "John Smith",
    				link: "/company/personal/user/1/",
    				icon: "/upload/resize_cache/main/9b0/58_58_2/p2dVDwA46Nw.png",
    			},
    		}
    	]
    },
    

Example for disabling page navigation:

$result = CRest::call(
    'tasks.task.list',
    [
        'filter' => [
            '>ID' => 50
        ],
        'start' => -1,
    ]
);
© «Bitrix24», 2001-2022
Up