timeman.timecontrol.reports.get

The method gets a report on the detected workplace absence.

Parameters

Parameter IDLE_MINUTES is available only, if you are a supervisor or administrator. If not defined, time is automatically taken from the module settings.

Call example

JavaScript

BX24.callMethod('timeman.timecontrol.reports.get', {
	user_id: 2,
	year: 2018,
	month: 8,
	workday_hours: 8,
	idle_minutes: 15
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('timeman.timecontrol.reports.get', Array(
	'USER_ID => 2,
	'YEAR' => 2018,
	'MONTH' => 8,
	'WORKDAY_HOURS' => 8,
	'IDLE_MINUTES' => 15
), $_REQUEST["auth"]);

Response example

{
	"result": {
		report: {
			month_title: 'August',
			date_start: "2018-08-01T00:00:00+03:00",
			date_finish: "2018-08-31T23:59:59+03:00",
			days: [
				{
					index: "20180816",
					day_title: "16.08.2018",
					workday_complete: false,
					workday_date_start: "2018-08-16T14:08:35+03:00",
					workday_date_finish: "2018-08-16T11:20:00+03:00",
					workday_duration: 10115,
					workday_duration_config: 28800,
					workday_duration_final: 6914,
					workday_time_leaks_user: 0,
					workday_time_leaks_real: 3201,
					workday_time_leaks_final: 21886,
					reports: [
						{
							id: 459,
							type: "TM_START",
							date_start: "2018-08-16T14:08:35+03:00",
							date_finish: "2018-08-16T14:08:35+03:00",
							duration: 0,
							active: false,
							entry_id: 35,
							report_type: "NONE",
							report_text: null,
							system_text: "",
							source_start: "TM_EVENT",
							source_finish: "TM_EVENT",
							ip_start: "93.60.295.11",
							ip_finish: "10.10.255.255",
							ip_start_network: false,
							ip_finish_network: {
								ip: "10.10.255.255",
								range: "10.0.0.0-10.255.255.255",
								name: "Office network 10.x.x.x"
							}
						}
					]
				}
			]
		},
		user: {
			id:2,
			name:"John Harrington",
			first_name:"John",
			last_name:"Harrington",
			work_position:"IT specialist",
			avatar:"http://test.bitrix24.com/upload/resize_cache/main/072/100_100_2/42-17948709.gif",
			last_activity_date:"2018-08-15T16:25:34+03:00"
		}

	}
}

Keys description

• report - report information.
  • month_title - name of the month.
  • date_start - start date for selected period in ATOM format.
  • date_start - finish date for selected period in ATOM format.
  • days - list of completed work days.
    • index - weekday index.
    • day_title - date (in site format).
    • workday_complete - workday is completed (true / false).
    • workday_date_start - date of workday start in ATOM format.
    • workday_date_finish - date of workday finish in ATOM format (if workday_complete = false. The date when the report is generated is specified in this field).
    • workday_duration - workday duration as per timesheet in seconds (with considered break interval, specified by the user).
    • workday_duration_final - complete actual workday duration in seconds (with account of pause break, set by the user, unconfirmed absences or absences due to personal reasons).
    • workday_duration_config - required workday duration in seconds.
    • workday_time_leaks_user - pause break duration, specified by the user in seconds.
    • workday_time_leaks_real - pause break duration, defined by the Time Management automatic registration (unconfirmed workplace absences and absence by personal reasons).
    • workday_time_leaks_final - if positive number: the amount of unfinished worktime in seconds. If the number is negative: amount of worktime finished above the defined time (overtime).
    • reports - list of records with detected absences (values are available only at the head and full detail level).
      • id - record ID. It is required to use the timeman.timecontrol.report.add method.
      • type - type of record (types selection list is described below).
      • active - record active status.
      • date_start- date of registration start in the ATOM format.
      • date_finish - date when the registration in ATOM format finishes (if active = true, the date of the generated report is specified in this field).
      • report_type - type of absence (work - away for work-related issues, private - away due to private reasons, none - not specified, equals to private).
      • report_text - reason for absence description.
      • system_text - system description of reason for absence (parameter is available only at the head detail level).
      • source_start - record start data provider (types selection list is described below).
      • source_finish - record finish data provider (types selection list is described below).
      • ip_start - IP address at the record start (parameter is available only at the head detail level).
      • ip_start_network - IP address decoding at the record start, if the IP address is not included into the office network - false (parameter is available only at the head detail level).
        • ip - IP address at the record start.
        • range - range that includes the specified IP address.
        • name - name of range that include the specified IP address.
      • ip_finish - IP address at the record finish. (parameter is available only at the head detail level).
      • ip_finish_network - IP address decoding at the record finish, if the IP address is not included into the office network - false (parameter is available only at the head detail level).
        • ip - IP address at the record finish.
        • range - range that includes the specified IP address.
        • name - name of range that includes the specified IP address.
• user - information about the user.
  • id - user ID.
  • name - user first and last names.
  • first_name - user name.
  • last_name - user last name.
  • work_position - position.
  • avatar - link to avatar (if empty, the avatar is not specified).
  • personal_gender - user gender.
  • last_activity_date - date of the last user action in the ATOM format.

Possible type of records (type)

• IDLE - Idle (registered by desktop application).
• OFFLINE - Offline.
• DESKTOP_ONLINE - Desktop app launch is registered (type is available at the head detail level).
• DESKTOP_OFFLINE - Offline desktop application is registered (type is available only at the head detail level).
• DESKTOP_START - Desktop application start is registered (type is available only at the head detail level).
• TM_START - Workday start.
• TM_PAUSE - Break pause.
• TM_CONTINUE - Workday continued.
• TM_END - Workday finished.

Possible sources of records (source_start, source_finish)

• ONLINE_EVENT - User authorization event.
• OFFLINE_AGENT - Agent that sets online status.
• DESKTOP_OFFLINE_AGENT - Agent that sets offline status for desktop application.
• DESKTOP_ONLINE_EVENT - Event that sets the online attribute for desktop application.
• DESKTOP_START_EVENT - Event that sets the launch attribute for desktop application.
• IDLE_EVENT - Event that changes the Idle status (registered with the desktop app).
• TM_EVENT - Event that changes workday duration (start, break pause, finish).

Response example in case an error

{
    "error": "ACCESS_ERROR",
    "error_description": "You don't have access to this method"
}

• Key error - error code.
• Key error_description - brief error description.

Possible error codes

When returns an empty 'days' array

In case of 'days' array returned empty, first you need to set correct options for access to the report and data collection (you must have admin privilidges and executes in console on any Bitrix24 account page):

BX.rest.callMethod('timeman.timecontrol.settings.set', {
    active: true,
REPORT_SIMPLE_TYPE: 'all',
    REPORT_FULL_TYPE: 'all',
    report_request_type: 'user',
    report_request_users: [BX.message.USER_ID],
}, function(result){
    if(result.error())
    {
        console.error(result.error().ex);
    }
    else
    {
        console.log(result.data());
    }
});

Next, open or close the working day. Now, this user's report will contain the following data:

BX.rest.callMethod('timeman.timecontrol.reports.get', {
    user_id: BX.message.USER_ID,
    year: 2019,
    month: 1,
    workday_hours: 8,
    idle_minutes: 15
}).then(e => console.log(e))