Overview

The getLeaveRequests and updateLeaveRequest functions are provided to allow an external system to manage the approval, cancellation or decline of leave requests initially created in NetSuite. The external system performs two actions:

  • Periodically call getLeaveRequests to obtain new and updated leave requests based on supplied criteria, the data returned will be used to replicate the NetSuite leave request in the external system.
  • On change of status of the external system representation of a leave request the new status will be submitted to NetSuite using the updateLeaveRequest call. The system can also optionally supply new required hours for each day of the leave request as long as the required hours is less than the original request.
Leave Request Functions

Get Leave Requests

The get leave request function returns a list of leave requests filtered by the supplied parameters. The request accepts the following parameters:


Parameter NameMandatory?Field TypeDescription
lastmodifiedafteryes??If specified only leave requests modified after this date time will be provided.
status

Only leave requests of this status will be returned.
subsidiary
integerIf the NetSuite account specify the subsidiary internalid, Only leave requests with a matching subsidiary will be returned 
employee
integerIf specified only leave requests with a matching employee will be returned.


Leave requests matching the criteria parameters will be returned as an array, containing the following data for each leave request


FieldField TypeDescription
idintegerThe NetSuite internalid of the leave request. this should be used to identify the leave request when calling updateLeaveRequest
namestringA prefixed autonumber field identifying the leave request for example LEAVEREQ1250
employeeintegerThe NetSuite internalid of the employee
leavetypeintegerThe NetSuite internalid of the leave type (corresponding to the type of leave Annual Leave, Personal Carers Leave etc). The ID can be found in the list of pay component sub types which are also used for timesheets
startdatedateThe date of the first day of the leave request
enddatedateThe date of the last day of the leave request
requiredhoursfloatThe total required hours for the leave request (sum of the hours of the days field)
statusstringThe status of the leave request
lastmodifiedstringThe date and time the leave request was last updated
daysobject[]A list of day objects
day.trandatedateThe date that hours are required for the leave period
day.hoursfloatThe hours required on the given day to take leave
day.leavetypeintegerThe internalid of the leave type (field is not currently used and will always be the same as the leave type)


The following is an example of a request and a successful response.


RequestResponse
{
 "action": "function",
 "function" : "getleaverequests" 
 }
{
 "success":true,
 "data":[{
	"id":"1250",
	"name":"LEAVEREQ1250",
	"employee":"41",
	"leavetype":"21",
	"startdate":"2011-12-25",
	"enddate":"2012-01-06",
	"requiredhours":15.2,
	"status": "PENDING",
	"lastmodified":"21/4/2012 2:25 PM",
	"days":[
		{
			"hours": 7.6
			"trandate": "2016-08-02"
			"leavetype": "21"
		},
		{
			"hours": 7.6
			"trandate": "2016-08-03"
			"leavetype": "21"
		}
	]}
}


Updating a Leave Request

The status of a leave request can be updated by making an updateleaverequest function call for each leave request. In addition to updating the status the request can optionally update the hours required on each day as long as the total required hours is less than the original required hours.


The update leave request takes the following parameters:


Parameter NameMandatory?Field TypeDescription
idyesintegerThe NetSuite internal id of the leave request to be updated
employeeyesintegerThe NetSuite internal id of the employee who the request id is for
statusyesstringThe new status that chould be set on the leave request
days
arrayAn array of day objects containing date and hours values (see changes to the required hours)
trandate
dateThe date that hours are required for the leave period
hours
floatThe hours required on the given day to take leave
leavetype
integer(this field is not used)

Why is employee required

The NetSuite internal ID of the employee is required as validation. If the employee ID does not match the employee set on the leave request. The request will be rejected.


The following is an example of a request and successful response.


RequestResponse
{
  "action": "function",
  "function" : "updateleaverequest",
  "id" : "1608",
  "employee" : "41",
  "status" : "APPROVED"
}
{
"success": true
"id": "1608"
"processms": "1369"
}

Updating the Required Hours For A Leave Request

In addition to changing the status of the leave request, if the actual hours required for the period of leave have changed the optional "days" parameter can be supplied. A change of required hours will only be accepted if the total required hours is the same or less than the original request. When the optional days parameter is included the following fields will be updated on the NetSuite leave request:

  • Required Hours (set to the total of the hours specified on each day)
  • Start Date (will be set to the earliest day date)
  • End Date (will be set to the latest day date)

In the following example the leave request has been approved but as the employee is only rostered to work 4.5 hours on the first day the original required hours for the first day is updated to 4.5 (Note: The days specified replaces the existing day data).


RequestResponse
{
  "action": "function",
  "function" : "updateleaverequest",
  "id" : "1608",
  "employee" : "41",
  "status" : "APPROVED",
  "days":[
		{
			"hours": 4.5
			"trandate": "2016-08-02"
		},
		{
			"hours": 7.6
			"trandate": "2016-08-03"
		}
	]}
}
{
"success": true
"id": "1608"
"processms": "1369"
}


Error Codes

The following error codes can be returned from the leave requests functions.

TBC

Leave Request Status List

The status of a leave request when returned in the getLeaveRequests or set with the updateLeaveRequest function should be set to the Name of the status listed in the table below.


NameInternal IDMeaning
PENDING1The leave request has been created and is awaiting approval
APPROVED2The leave request has been approved, time will have been created
DECLINED3The supervisor has declined the leave request
CANCELLED4The employee or supervisor has cancelled the leave request
PROCESSED5One or more time records associated with this leave request have been included on a payrun
MANUALPROCESSED6One or more time records associated with this leave request have been included on a payrun






  • No labels