Absence REST Service - User Documentation

Attributes
JSON Schema
Supported operations
Describe
Read
Create
Update/Withdraw
Examples
Security
Row Finders
Format:
Examples:
Notes:

This document provides details related to Absence REST service. This REST service supports creation of Absences in Basic Mode. Absence
Type could belong to any pattern - General, Illness Injury, Maternity, Adoption. The REST service also can be used to retrieve absences and
update/delete existing absences.

Attributes
Attributes data has been provided with the LOV's and default values.

Attribute Can be Can be Visible Allowable values Comments

entered entered on Get (for create/update)
while while
Create update

personAbsenceEntryId No No Yes

absenceEntryBasicFlag No No Yes

absenceTypeId No No Yes Derived from AbsenceType

absenceType Yes No Yes Valid absence type LOV attached to convert AbsenceType to
AbsenceTypeId

absenceCaseId No No Yes

absencePatternCd No No Yes

agreementId No No Yes

authStatusUpdateDate No No Yes

bandDtlId No No Yes

certificationAuthFlag No No Yes

childEventTypeCd No No Yes

conditionStartDate No No Yes

confirmedDate No No Yes

consumedByAgreement No No Yes

diseaseCode No No Yes

employeeShiftFlag No No Yes

frequency No No Yes

initialReportById No No Yes

initialTimelyNotifyFlag No No Yes

objectVersionNumber No No Yes

overridden No No Yes

periodOfIncapToWorkFlag No No Yes
processingStatus No No Yes

projectId No No Yes

splCondition No No Yes

legalEntityId No No Yes Derived based on AbsenceType and Employer

employer Yes No Yes Valid Employer name

absenceTypeReasonId No No Yes Derived from AbsenceReason

absenceReason Yes Yes Yes Valid Absence LOV attached to convert absenceReason to
Reason absenceReasonId

personId No No Yes Derived from PersonNumber

personNumber Yes No Yes Valid Person Name

unitOfMeasure No No Yes

startDate Yes Yes Yes

startTime Yes Yes Yes

startDateDuration Yes Yes Yes

endDate Yes Yes Yes

endTime Yes Yes Yes

endDateDuration Yes Yes Yes

absenceStatusCd Yes Yes Yes 'SAVED' or LOV attached

'SUBMITTED'
If absence status is SUBMITTED then approval status
should be APPROVED/AWAITING

If the absence is SAVED then approval status will be

ignored and set it to NULL

ORA_WITHDRAWN is allowed in update mode

openEndedFlag Yes Yes Yes 'Y' or 'N'

plannedEndDate No No Yes

notificationDate No No Yes

submittedDate No No Yes

timelinessOverrideDate No No Yes

comments Yes Yes Yes

approvalStatusCd No No Yes By default approval status is "Approved" if the

approvals are not enabled at Absence type level.

Will be set to "AWAITING APPROVAL" if the approval

are enabled.It will be override the value whatever
passed over JSON.

createdBy No No Yes

creationDate No No Yes

duration No No Yes Derived based on

legalentityId,StartDate,StartTime,EndDate and
EndTime

absenceDispStatus No No Yes LOV displayed for absence status.

lastUpdateDate No No Yes

lastUpdateLogin No No Yes

lastUpdatedBy No No Yes

startDateTime Yes Yes Yes

endDateTime Yes Yes Yes

legislativeDataGroupId No No Yes Derived based on Person and AbsenceType

absencePatternCd No No Yes Derived based on AbsenceType

singleDayFlag Yes Yes Yes Derived based on AbsenceType

periodOfServiceId No No Yes Derived based on AbsenceType

userMode Yes Yes Yes EMP,MGR & ADMIN default its "EMP"

legislationCode No No Yes

blockedLeaveCandidate Yes Yes Yes LOV has been defined using Lookup code

establishmentDate No No Yes

lateNotifyFlag No No Yes

dataSecurityPersonId No No Yes

effectiveStartDate No No Yes

effectiveEndDate No No Yes

source Yes Yes Yes Set to "REST" by default

JSON Schema
The JSON schema to create an absence should be the following

{
"type": "object",
"title": "Absence Entry Request",
"description": "Request to enter an absence",
"properties": {
"personAbsenceEntryId": {
"type": "Long",
"description": "System generated unique identifier for the absence."
},
"absenceTypeId": {
"type": "Long",
"description": "Identifier for the absence type."
},
"absenceType": {
"type": "string",
"description": "Absence type name."
},
"employer": {
"type": "string",
"description": "Employer name."
},
"absenceReasonId": {
"type": "string",
"description": "Identifier for absence reason"
},
"absenceReason": {
"type": "string",
"description": "Absence reason string."
},
"personNumber": {
"type": "String",
 "description": "Person number of the person whose absence is
reported"
},
"startDate": {
"type": "Date",
"description": "Start date of the absence."
},
"startTime": {
"type": "string",
"description": "Start time of the absence."
},
"startDateDuration": {
"type": "BigDecimal",
"description": "Duration of absence on the first day of absence"
},
"endDate": {
"type": "string",
"description": "End date of the absence."
},
"endTime": {
"type": "string",
"description": "End time of the absence on the End date."
},
"endDateDuration": {
"type": "BigDecimal",
"description": "Duration of absence on the last day of absence."
},
"absenceStatusCd": {
"type": "string",
"description": "Status of the absence created (Saved or Submitted).",
"enum": ["SAVED","SUBMITTED"]
},
"plannedEndDate": {
"type": "Date",
"description": "Planned end date of the absence."
},
"notificationDate": {
"type": "Date",
"description": "Date on which the absence was first notified."
},
"conditionStartDate": {
"type": "Date",
"description": "Illness start date."
},
"confirmedDate": {
"type": "Date",
"description": "Date when the absence was confirmed"
},
"comments": {
"type": "string",
"description": "Comments for the absence"
},
"blockedLeaveCandidate": {
"type": "string",
"description": ""
 }
....
}

Supported operations

Describe
A describe can be done on the absences resource sending http GET request

URL : <host : port >/hcmAbsencesApi/resources/latest/absences/describe

Headers :

Authorization : Credentials

Read
Details of existing absences can be obtained by sending http GET request

URL : <host : port >/hcmAbsencesApi/resources/latest/absences

We need add row finders (view criteria) to drill down to a specific absence

Headers :

Authorization : Credentials

Create
Client can call create operation by sending a POST request on the absences resource

URL : <host : port >/hcmAbsencesApi/resources/latest/absences

Headers :

Authorization : Credentials

Content-Type : application/vnd.oracle.adf.resourceitem+json

Update/Withdraw
Existing absence entries can be updated using http PATCH request, the information that is passed in such request will be added/modified.

URL : <host : port >/hcmAbsencesApi/resources/latest/absences/{id}

Headers :

Authorization : Credentials

Content-Type : application/vnd.oracle.adf.resourceitem+json

Examples
Following are some sample requests that can be used to create absences

Basic absence for a time based employee

 {
"personNumber": "955160008182159",
"employer": "Vision Corporation",
"absenceType": "Sick Time",
"startDate": "2016-06-15",
"startTime": "08:00",
"endDate": "2016-06-18",
"endTime": "17:00",
"absenceStatusCd": "SUBMITTED"
}

Basic absence for a duration based employee

{
"personNumber": "955160008182159",
"employer": "Vision Corporation",
"absenceType": "Sick Time",
"startDate": "2016-06-15",
"startDateDuration": "8",
"endDate": "2016-06-18",
"endDateDuration": "8",
"absenceStatus": "SUBMITTED"
}

Flex Field Support

{
"personNumber": "955160008182159",
"employer": "Vision Corporation",
"absenceType": "US Illness",
"startDate": "2017-08-10",
"startTime": "08:00",
"endDate": "2017-08-10",
"endTime": "16:00",
"absenceStatusCd": "SUBMITTED",
"absenceRecordingDFF" :[{
"__FLEX_Context": "US",
"ancZbenUsLocation": "testDFF"
}]
}

with-drawn the previously recorded absence

{
"absenceStatus": "ORA_WITHDRAWN"
}
 Updating the recorded absence

{
"startTime": "10:00",
"endTime": "12:00",
"comments":"testing"
}

with-drawn the previously recorded absence

{
"absenceStatus": "ORA_WITHDRAWN"
}

Security
Customer needs to create custom roles and grant the below aggregate privileges to these custom roles

ANC_REST_SERVICE_ACCESS_ABSENCES_PRIV - for all CRUD operations(create,update,delete and view absences)

ANC_REST_SERVICE_ACCESS_ABSENCES_RO_PRIV – Get Operation(view the absences)

The seeded HCM Integration Specialist Job Role already has the above privileges granted.

Row Finders

Rowfinder name attributes Mandatory fields

findByAbsenceEntryId personAbsenceEntryId

findByAbsenceTypeId absenceEntryId

findByPersonAndAbsenceTypeId personId,absenceTypeId

findByAbsDate startDate

findByAbsStartAndEndDate startDate,endDate

findByPersonAbsenceTypeIdAndAbsDate personId,absenceTypeId,startDate & endDate

findByPersonId personId

findAbsenceUsingAllAbsParameters personId,absenceTypeId,startDate & endDate personId

Format:
finder=<rowfinderName>;<attr1>=<value1>,<attr2>=<value2>,..

Examples:
http://<host:port>/hcmAbsencesApi/resources/latest/absences?finder=findAbsenceusingAllAbsParameters;personId=300100002626734,absence
TypeId=300100033341954

http://<host:port>/hcmAbsencesApi/resources/latest/absences?finder=findByPersonId;personId=300100031932152
http://<host:port>/hcmAbsencesApi/resources/latest/absences?finder=findByAbsenceTypeId;absenceTypeId=300100037938140

http://<host:port>/hcmAbsencesApi/resources/latest/absences?finder=findByAbsDate;startDate=2017-07-04

Notes:
Approvals
When an absence is created using REST, a check is made to verify if approvals have been enabled for the absence type. If
enabled, absence approval status is set to "AWAITING" and a approval notification is generated. If approvals are not enabled,
absence status is automatically set to "APPROVED".
Similar checks are also performed when an absence is updated/withdrawn using REST API.
Through REST API,"Denied" absences cannot be created.

For Time-based Schedules,start and end time need to be provided but are not mandatory. If no values specified, defaults to
"00:00-23:59"

For Elapsed Schedules (startDateDuration and EndDateDuration) are validated and errors will be thrown if validation is failed.

Delete operation is not allowed.

By default user mode attribute of the absence record IS set as "EMP". if the logged person and the employee for whom absence is are
the same then the mode is set to "EMP"(Employee) otherwise "MGR"(Manager). "ADMIN" mode must be explicitly passed in while
invoking the REST API.

If an authorized user tries to perform rest operations without having REST role or privilege then it throws "401 Unauthorized" exception
with message as "Not authorized. Operation: get". This exception message points to Get operation.

Data security is applied. User will be prevented from viewing/modifying absences for employees they don't have access to.