REST API for Oracle Fusion Cloud HCM

Manage In and Out Time Events

This use case describes the scenarios in which a worker records both In and Out events using an external time collection device.

The image displays the transfer of the worker's In and Out events records from the external Time Collection Device to the Time and Labor application.

Report Normal Shift Start and Stop Times

On Monday, the worker records In and Out time events without taking a meal break.

The following table shows the Time and Labor configuration that applies to this scenario.

Configuration	Purpose
Time device event mappings	Maps the supplier device events to the corresponding application events.
Time device rule	Validates the time entry against the worker's schedule.
Time submission rule	Saves the time card when the worker reports an Out event on Monday, Tuesday, Wednesday, and Thursday. Submits the time card when the worker reports an Out event on Friday.

The following table describes the application processing actions that occur for the reported In and Out time events:

Time Event	Application Processing
On Monday, the worker reports in at 8:00 AM.	Imports the In time event using the REST web service. Validates the imported time event using event mappings. Creates an incomplete time card entry for the In event. An exception is attached to the incomplete time card entry as the Out time event has not been received yet.
The worker reports out at 5:00 PM.	Imports the Out time event using the REST web service. Validates the imported time event using event mappings. Completes the earlier time card entry after receiving the Out event. Runs the time device rule, which validates the time events imported from the time device. Runs the time submission rule, which saves the time card.

Example URL

The following is the format of the resource URL.

POST

/hcmRestApi/resources/11.13.18.05/timeEventRequests/

Example Request for the In Event

The following is an example of the request body in JSON format.

{
         "requestNumber": "20201",
         "sourceId": "HWM_CLOCK_TIME",
         "requestTimestamp": "2018-09-17T09:00:00.000+01:00",
         "timeEvents": [
            {
               "deviceId": "111",
               "eventDateTime": "2018-09-17T08:02:00.000+01:00",
               "SupplierDeviceEvent": "HWM_CLOCK_TIME_IN",
               "reporterId": "955160008184353",
               "reporterIdType": "PERSON",
               "timeEventAttributes": [
                  {
                     "name": "PayrollTimeType",
                     "value": "Regular",
                  }
               ]
            }
         ]
      }

Example Response for the In Event

The following is an example of the response body in JSON format.

{
    "timeEventRequestId": 300100273290505,
    "requestNumber": "20201",
    "requestTimestamp": "2018-09-17T09:00:00.000+01:00",
    "sourceId": "HWM_CLOCK_TIME",
    "timeEvents": [
        {
            "timeEventId": 300100273290506,
            "timeEventRequestId": 300100273290505,
            "eventDateTime": "2018-09-17T08:02:00.000+01:00",
            "deviceId": "111",
            "supplierDeviceEvent": "HWM_CLOCK_TIME_IN",
            "reporterId": "955160008184353",
            "reporterIdType": "PERSON",
            "timeEventAttributes": [
                {
                    "timeEventAttributeId": 300100273290507,
                    "timeEventId": 300100273290506,
                    "name": "PayrollTimeType",
                    "value": "ZOTL_Regular",
                    "links": [
                        {
                            "rel": "self",
                            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents/300100273290506/child/timeEventAttributes/300100273290507",
                            "name": "timeEventAttributes",
                            "kind": "item",
                            "properties": {
                                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
                            }
                        },
                        {
                            "rel": "canonical",
                            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents/300100273290506/child/timeEventAttributes/300100273290507",
                            "name": "timeEventAttributes",
                            "kind": "item"
                        },
                        {
                            "rel": "parent",
                            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents/300100273290506",
                            "name": "timeEvents",
                            "kind": "item"
                        }
                    ]
                }
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents/300100273290506",
                    "name": "timeEvents",
                    "kind": "item",
                    "properties": {
                        "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
                    }
                },
                {
                    "rel": "canonical",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents/300100273290506",
                    "name": "timeEvents",
                    "kind": "item"
                },
                {
                    "rel": "parent",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505",
                    "name": "timeEventRequests",
                    "kind": "item"
                },
                {
                    "rel": "lov",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents/300100273290506/lov/ReporterIdTypeList1",
                    "name": "ReporterIdTypeList1",
                    "kind": "collection"
                },
                {
                    "rel": "lov",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents/300100273290506/lov/TimeLookupSharedAM_OraHwmTcdSupplierEventswithSource1",
                    "name": "TimeLookupSharedAM_OraHwmTcdSupplierEventswithSource1",
                    "kind": "collection"
                },
                {
                    "rel": "child",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents/300100273290506/child/timeEventAttributes",
                    "name": "timeEventAttributes",
                    "kind": "collection"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505",
            "name": "timeEventRequests",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "canonical",
            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505",
            "name": "timeEventRequests",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "child",
            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290505/child/timeEvents",
            "name": "timeEvents",
            "kind": "collection"
        }
    ]
}

Example Request for the Out Event

The following is an example of the request body in JSON format.

{
         "requestNumber": "20311",
         "sourceId": "HWM_CLOCK_TIME",
         "requestTimestamp": "2018-09-17T17:05:00.000+01:00",
         "timeEvents": [
            {
               "deviceId": "111",
               "eventDateTime": "2018-09-17T17:00:00.000+01:00",
               "SupplierDeviceEvent": "HWM_CLOCK_TIME_OUT",
               "reporterId": "955160008184353",
               "reporterIdType": "PERSON",
               "timeEventAttributes": [
                  {
                     "name": "PayrollTimeType",
                     "value": "Regular",
                  }
               ]
            }
         ]
      }

Example Response for the Out Event

The following is an example of the response body in JSON format.

{
    "timeEventRequestId": 300100273290511,
    "requestNumber": "20311",
    "requestTimestamp": "2018-09-17T17:05:00.000+01:00",
    "sourceId": "HWM_CLOCK_TIME",
    "timeEvents": [
        {
            "timeEventId": 300100273290512,
            "timeEventRequestId": 300100273290511,
            "eventDateTime": "2018-09-17T17:00:00.000+01:00",
            "deviceId": "123",
            "supplierDeviceEvent": "HWM_CLOCK_TIME_OUT",
            "reporterId": "955160008184353",
            "reporterIdType": "PERSON",
            "timeEventAttributes": [
                {
                    "timeEventAttributeId": 300100273290513,
                    "timeEventId": 300100273290512,
                    "name": "PayrollTimeType",
                    "value": "ZOTL_Regular",
                    "links": [
                        {
                            "rel": "self",
                            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents/300100273290512/child/timeEventAttributes/300100273290513",
                            "name": "timeEventAttributes",
                            "kind": "item",
                            "properties": {
                                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
                            }
                        },
                        {
                            "rel": "canonical",
                            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents/300100273290512/child/timeEventAttributes/300100273290513",
                            "name": "timeEventAttributes",
                            "kind": "item"
                        },
                        {
                            "rel": "parent",
                            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents/300100273290512",
                            "name": "timeEvents",
                            "kind": "item"
                        }
                    ]
                }
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents/300100273290512",
                    "name": "timeEvents",
                    "kind": "item",
                    "properties": {
                        "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
                    }
                },
                {
                    "rel": "canonical",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents/300100273290512",
                    "name": "timeEvents",
                    "kind": "item"
                },
                {
                    "rel": "parent",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511",
                    "name": "timeEventRequests",
                    "kind": "item"
                },
                {
                    "rel": "lov",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents/300100273290512/lov/ReporterIdTypeList1",
                    "name": "ReporterIdTypeList1",
                    "kind": "collection"
                },
                {
                    "rel": "lov",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents/300100273290512/lov/TimeLookupSharedAM_OraHwmTcdSupplierEventswithSource1",
                    "name": "TimeLookupSharedAM_OraHwmTcdSupplierEventswithSource1",
                    "kind": "collection"
                },
                {
                    "rel": "child",
                    "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents/300100273290512/child/timeEventAttributes",
                    "name": "timeEventAttributes",
                    "kind": "collection"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511",
            "name": "timeEventRequests",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "canonical",
            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511",
            "name": "timeEventRequests",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "child",
            "href": "http://<host>:<port>/hcmRestApi/resources/11.13.18.05/timeEventRequests/300100273290511/child/timeEvents",
            "name": "timeEvents",
            "kind": "collection"
        }
    ]
}

Report Fewer than 40 Hours in a Week

On Friday, the worker records In and Out time events.

The following table shows the Time and Labor configuration that applies to this scenario.

Configuration	Purpose
Time device event mappings	Maps the supplier device events to the corresponding application events.
Time device rule	Validates the time entry against the worker's schedule.
Time submission rule	Saves the time card when the worker reports an Out event on Monday, Tuesday, Wednesday, and Thursday. Submits the time card when the worker reports an Out event on Friday.
Time approval rule	Approves all submitted time cards totaling fewer than 40 hours.

At the end of that week, the worker reports only 30 hours.

The following table describes the application processing actions that occur for the reported In and Out time events:

Time Event	Application Processing
On Friday, the worker reports in at 8:00 AM.	Imports the In time event using the REST web service. Validates the imported time event using event mappings. Creates an incomplete time card entry for the In event. An exception is attached to the incomplete time card entry as the Out time event has not been received yet.
On Friday, the worker reports out at 4:30 PM.	Imports the Out time event using the REST web service. Validates the imported time event using event mappings. Completes the earlier time card entry after receiving the Out event. Runs the time device rule, which validates the time events imported from the time device. Runs the time submission rule, which submits the time card. Approves the time card as the total number of reported hours is fewer than 40 hours.

Example URL

The following is the format of the resource URL.

POST

/hcmRestApi/resources/11.13.18.05/timeEventRequests/

Example Request for the In Event

The following is an example of the request body in JSON format.

      {
         "requestNumber": "20283",
         "sourceId": "HWM_CLOCK_TIME",
         "requestTimestamp": "2015-10-16T08:01:00.000+01:00",
         "timeEvents": [
            {
               "deviceId": "111",
               "eventDateTime": "2015-10-16T08:00:00.000+01:00",
               "supplierDeviceEvent": "HWM_CLOCK_TIME_IN",
               "reporterId": "955160008184353",
               "reporterIdType": "PERSON",
               "timeEventAttributes": [
                  {
                     "name": "PayrollTimeType",
                     "value": "Regular",
                  }
               ]
            }
         ]
      }

Example Response for the In Event

The following is an example of the response body in JSON format.

{
    "timeEventRequestId": 300100273290565,
    "requestNumber": "20283",
    "requestTimestamp": "2015-10-16T08:01:00.000+01:00",
    "sourceId": "HWM_CLOCK_TIME",
    "timeEvents": [
        {
            "timeEventId": 300100273290566,
            "timeEventRequestId": 300100273290565,
            "eventDateTime": "2015-10-16T08:00:00.000+01:00",
            "deviceId": "111",
            "supplierDeviceEvent": "HWM_CLOCK_TIME_IN",
            "reporterId": "955160008184353",
            "reporterIdType": "PERSON",
            "timeEventAttributes": [
                {
                    "timeEventAttributeId": 300100273290567,
                    "timeEventId": 300100273290566,
                    "name": "PayrollTimeType",
                    "value": "ZOTL_Regular",
                    "links": [
[...]

Example Request for the Out Event

The following is an example of the request body in JSON format.

      {
         "requestNumber": "20299",
         "sourceId": "HWM_CLOCK_TIME",
         "requestTimestamp": "2015-10-16T16:31:00.000+01:00",
         "timeEvents": [
            {
               "deviceId": "111",
               "eventDateTime": "2015-10-16T16:30:00.000+01:00",
               "supplierDeviceEvent": "HWM_CLOCK_TIME_OUT",
               "reporterId": "955160008184353",
               "reporterIdType": "PERSON",
               "timeEventAttributes": [
                  {
                     "name": "PayrollTimeType",
                     "value": "Regular",
                  }
               ]
            }
         ]
      }

Example Response for the Out Event

The following is an example of the response body in JSON format.

{
    "timeEventRequestId": 300100273290605,
    "requestNumber": "20299",
    "requestTimestamp": "2015-10-16T16:30:00.000+01:00",
    "sourceId": "HWM_CLOCK_TIME",
    "timeEvents": [
        {
            "timeEventId": 300100273290606,
            "timeEventRequestId": 300100273290605,
            "eventDateTime": "2015-10-16T08:00:00.000+01:00",
            "deviceId": "111",
            "supplierDeviceEvent": "HWM_CLOCK_TIME_OUT",
            "reporterId": "955160008184353",
            "reporterIdType": "PERSON",
            "timeEventAttributes": [
                {
                    "timeEventAttributeId": 300100273290607,
                    "timeEventId": 300100273290606,
                    "name": "PayrollTimeType",
                    "value": "ZOTL_Regular",
                    "links": [
[...]

Report More Than 40 Hours in a Week

On Friday, the worker records In and Out time events.

The following table shows the Time and Labor configuration that applies to this scenario.

Configuration	Purpose
Time device event mappings	Maps the supplier device events to the corresponding application events.
Time device rule	Validates the time entry against the worker's schedule.
Time submission rule	Saves the time card when the worker reports an Out event on Monday, Tuesday, Wednesday, and Thursday. Submits the time card when the worker reports an Out event on Friday.
Time entry rule	Generates an exception if more than 40 hours are reported in a week.

The worker reports more than 40 hours at the end of the week.

The following table describes the application processing actions that occur for the reported In and Out time events:

Time Event	Application Processing
On Friday, the worker reports in at 8:00 AM.	Imports the In time event using the REST web service. Validates the imported time event using event mappings. Creates an incomplete time card entry for the In event. An exception is attached to the incomplete time card entry as the Out time event has not been received yet.
The worker reports out at 6:30 PM.	Imports the Out time event using the REST web service. Validates the imported time event using event mappings. Completes the earlier time card entry after receiving the Out event. Runs the time device rule, which validates the time events imported from the time device. Runs the time submission rule, which initiates the submit process. Runs the time entry rule, which generates an exception and moves the time card into In Error status.

Example URL

The following is the format of the resource URL.

POST

/hcmRestApi/resources/11.13.18.05/timeEventRequests/

Example Request for the In Event

The following is an example of the request body in JSON format.

{
         "requestNumber": "20107",
         "sourceId": "HWM_CLOCK_TIME",
         "requestTimestamp": "2015-10-09T08:01:00.000+01:00",
         "timeEvents": [
            {
               "deviceId": "111",
               "eventTime": "2015-10-09T08:00:00.000+01:00",
               "supplierDeviceEvent": "HWM_CLOCK_TIME_IN",
               "reporterId": "955160008184353",
               "reporterIdType": "PERSON",
               "timeEventAttributes": [
                  {
                     "name": "PayrollTimeType",
                     "value": "Regular",
                  }
               ]
            }
         ]
      }

Example Response for the In Event

The following is an example of the response body in JSON format.

{
    "timeEventRequestId": 300100273290765,
    "requestNumber": "20107",
    "requestTimestamp": "2015-10-09T08:01:00.000+01:00",
    "sourceId": "HWM_CLOCK_TIME",
    "timeEvents": [
        {
            "timeEventId": 300100273290766,
            "timeEventRequestId": 300100273290765,
            "eventDateTime": "2015-10-09T08:00:00.000+01:00",
            "deviceId": "111",
            "supplierDeviceEvent": "HWM_CLOCK_TIME_IN",
            "reporterId": "955160008184353",
            "reporterIdType": "PERSON",
            "timeEventAttributes": [
                {
                    "timeEventAttributeId": 300100273290767,
                    "timeEventId": 300100273290766,
                    "name": "PayrollTimeType",
                    "value": "ZOTL_Regular",
                    "links": [
[...]

Example Request for the Out Event

The following is an example of the request body in JSON format.

{ 
    "requestNumber": "20218", 
    "sourceId": "HWM_CLOCK_TIME", 
    "requestTimestamp": "2015-10-09T18:31:00.000+01:00", 
    "timeEvents": [ 
    { 
     "deviceId": "111", 
     "eventDateTime": "2015-10-   09T16:30:00.000+01:00", 
     "supplierDeviceEvent": "HWM_CLOCK_TIME_OUT", 
     "reporterId": "955160008184353", 
     "reporterIdType": "PERSON", 
     "timeEventAttributes": 
      [ 
         { 
           "name": "PayrollTimeType", 
           "value": "Regular", 
         } 
      ] 
     } 
   ] 
}

Example Response for the Out Event

The following is an example of the response body in JSON format.

{
    "timeEventRequestId": 300100273290795,
    "requestNumber": "20218",
    "requestTimestamp": "2015-10-09T18:31:00.000+01:00",
    "sourceId": "HWM_CLOCK_TIME",
    "timeEvents": [
        {
            "timeEventId": 300100273290796,
            "timeEventRequestId": 300100273290795,
            "eventDateTime": "2015-10-09T16:30:00.000+01:00",
            "deviceId": "111",
            "supplierDeviceEvent": "HWM_CLOCK_TIME_OUT",
            "reporterId": "955160008184353",
            "reporterIdType": "PERSON",
            "timeEventAttributes": [
                {
                    "timeEventAttributeId": 300100273290797,
                    "timeEventId": 300100273290796,
                    "name": "PayrollTimeType",
                    "value": "ZOTL_Regular",
                    "links": [
[...]