_getCalendar

Gathers the data of Jobs within a set Time Period (Months, Weeks, Days etc.), can have several filters for results.

Parameters

start

A Unix epoch time format of the beginning date of the period which Job data will be collected within. (e.g 1705406400, which translates to noon on the 16th of January, 2024)

end

A Unix epoch time format of the ending date of the period which Job data will be collected within. (e.g 1706702400, which translates to noon on the 31st of January, 2024)

Filter Parameters

Optional parameters which limit the results given:

form_ids

An array of Form IDs. This will filter out Jobs within the time period set by "start" and "end", which are not set to any Forms within this array. (e.g "490335, 490336", only Jobs which have one of either these two Forms will be returned)

department_ids

An array of existing Department IDs. Filters out any Jobs which are not assigned to a Department within the requested array.

If "department_ids" has the value of 0, Jobs not assigned any Department will also be returned.

user_ids

An array of User IDs. Filters out any Jobs which are not assigned to any Users within the array. If "user_ids" includes the value 0, Jobs not assigned to any User will also be included. If "user_ids" includes the value -2, Jobs which are Outsourced will be included.

active_only

A boolean filter which if set to "true" will exclude Jobs linked to inactive Users.

job_type_ids

An array of existing Job Types. Filters out any Jobs which are not assigned to a Job Type within the requested array.

This parameter can also be used to exclude Jobs related to the specified Job Types from results. (For this, the IDs of the Job Types need to be negative, e.g for a Job Type with the ID 45459 you want to exclude from Calendar results, "job_type_ids" should include the value -45459, instead of 45459.)

statuses

Filters Jobs to only include those which have the requested Status(es): 0 => Incomplete 1 => Complete 2 => Processed 3 => Requires Customer Authorisation 4 => Authorised 5 => Cancelled

overdue

If given a set value (e.g "overdue"), will only include Jobs which are overdue to be completed.

hide_secondary

If set to 1, only Primary Jobs will be included, Secondary Jobs are excluded. If not given a value or given a value of 0, Secondary Jobs can be included. (subject to other filters)

search

A string variable which will exclude Jobs which do not contain any data that matches the string given. (e.g "11:59")

Example One

With 2 Jobs created: (For 21st January 2024, assigned to User with ID 92447, being Job Type 1, not assigned to a Department, and an Incomplete status, being Overdue at this time.) (For 24th January 2024, assigned to User with ID 92447, being Job Type 2, not assigned to a Department, and an Incomplete Status but not Overdue.)

No filtering parameters in this example:

FM_api('Appointments_getCalendar', [
	'start' => '1704067200',
	'end'=> '1707696000'
	]
);

Result

[["502011",["712679","0","A Test Customer"],"2024-01-21 11:59:00","1","92447","0","test create\/complete 358","[{\"content\":\"\",\"createdby\":0,\"noteTime\":0}]",["street address 1","street address 2","Test town","tEst county",""],"{\"emails\":[],\"email\":\"\"}",["012345678",""],"0","2024-01-21 12:58:00"],["502012",["712679","0","A Test Customer"],"2024-01-24 14:12:40","1","92447","0","test create\/complete 359","[{\"content\":\"\",\"createdby\":0,\"noteTime\":0}]",["street address 1","street address 2","Test town","tEst county",""],"{\"emails\":[],\"email\":\"\"}",["012345678",""],"0","2024-01-24 15:11:00"]]

Example Two

2 Created Jobs: (For 21st January 2024, assigned to User with ID 92447, being Job Type 1, not assigned to a Department, and an Incomplete status, being Overdue at this time.) (For 24th January 2024, assigned to User with ID 92447, being Job Type 2, not assigned to a Department, and an Incomplete Status but not Overdue.)

These parameters have a specified User ID, the "Incomplete" status and "Overdue" as filters, resulting in only the earliest Job being returned:

FM_api('Appointments_getCalendar', [
    'start' => '1704067200',
    'end' => '1707696000',
    'user_ids' => [
                    '92447'
                  ],
    'statuses' => [
                    '0'
                  ],
    'overdue' => [
                    'overdue'
                 ],
    'active_only' => 'true'
]

Result

[["502011",["712679","0","A Test Customer"],"2024-01-21 11:59:00","1","92447","0","test create\/complete 358","[{\"content\":\"\",\"createdby\":0,\"noteTime\":0}]",["street address 1","street address 2","Test town","tEst county",""],"{\"emails\":[],\"email\":\"\"}",["012345678",""],"0","2024-01-21 12:58:00"]]

Example Three

3 Jobs Created: (For 21st January 2024, being Job Type 1, not assigned to a Department, and an Incomplete status, being Overdue at this time.) (For 24th January 2024, being Job Type 2, not assigned to a Department, and an Incomplete Status but not Overdue.) (For 26th January 2024, being Job Type 1, assigned to a Department with ID 397100 and has the status "Requires Customer Authorisation")

These parameters have Jobs assigned to any Department excluded, any Job which is specifically the type with an ID of 182005 (Being "Job Type 1" in this case) is also excluded, only Jobs assigned to the form with an ID of 490341 are included:

FM_api('Appointments_getCalendar', [
	'start' => '1704067200',
	'end'=> '1707696000',
	'form_ids' => [
			'490341'
	              ],
	'department_ids' => [
			      '0'
			    ],
	'job_type_ids' => [
			    '-182005'
			  ]
	]
);

Result

[["502012",["712679","0","A Test Customer"],"2024-01-24 14:12:40","1","92447","0","test create\/complete 359","[{\"content\":\"\",\"createdby\":0,\"noteTime\":0}]",["street address 1","street address 2","Test town","tEst county",""],"{\"emails\":[],\"email\":\"\"}",["012345678",""],"0","2024-01-24 15:11:00"]]

Results On Failure

If the "start" parameter is not included:

{"error":"missing or invalid parameter: start"}