Extract Data from HCM Using Spectra Services

Introduction

Cloud HCM provides a capability to extract data from HCM using underlying new generation BOSS/Spectra platform.

Objectives

Upon completing this tutorial, you will understand how to:

Query Worker extraction views and their hierarchy of objects
Asynchronously submit and track extraction job requests for retrieval of selected Worker hierarchy data
Download extract output files

Prerequisites

Before you begin:

Contact Oracle CoE to make sure that Spectra platform, including RODS data replication, is provisioned in your pod
Perform required security configuration, including:
- Data security setup
- OAuth client app setup

Refer to the Configure Security for Extracting Data from HCM Using Spectra Services tutorial.

Use Cases

This functionality allows you to address the following use cases.

Full Data Extraction

Full extraction of Worker data can be either one-off or periodic activity.

You can retrieve entire object hierarchy or just a subset of it.

Full data extraction will retrieve all the records that match the filtering criteria and output files may be very large.

Date effective objects will be retrieved as of requested effective date, where current extraction date is the default.

Incremental Data Extraction

Incremental extraction of Worker data is typically a periodic, scheduled activity.

You can retrieve entire object hierarchy or just a subset of it.

In this use case you want to retrieve only objects that got changed since the previous extraction run where the first extraction run is the baseline. To achieve this, timeUpdated attributes filters have to be applied at any level that is subject to change detection.

Incremental data extraction query can apply additional filtering criteria. Output files will be typically smaller comparing to full extraction since they will contain delta only.

Only current values of attributes will be retrieved.

Date effective objects will be retrieved as of requested effective date, where current extraction date is the default.

Caution:

Physically deleted records will not be returned using filtering by timeUpdated.

Task 1: Choosing an Extraction View

Choose which extraction view to use, depending on required objects and attributes. Available views are listed below, along with the objects and attributes that can be extracted.

Worker Assignment Extracts

Use workerAssignmentExtracts to extract workers' employment assignment data.

View Path	workerAssignmentExtracts

Object	Attributes	Relationship Type
workerAssignmentExtract	id effectiveStartDate effectiveEndDate effectiveSequence effectiveLatestChange assignmentType assignmentNumber primaryFlag businessTitle workAtHomeFlag officeBuilding officeFloor officeMailStop officeNumber primaryAssignmentFlag primaryWorkRelationshipFlag timeUpdated updatedBy timeCreated createdBy systemPersonType labourUnionMemberFlag managerFlag probationEndDate probationPeriod probationPeriodUnit normalHours frequency endTime startTime noticePeriod noticePeriodUOM workerCategory assignmentCategory hourlyPaidOrSalaried projectedEndDate projectedStartDate assignmentStatusType expenseCheckSendToAddress retirementAge retirementDate synchronizeFromPositionFlag fullTimeOrPartTime permanentAssignmentFlag seniorityBasis overtimePeriod adjustedFullTimeEquivalent annualWorkingDuration annualWorkingDurationUnit annualWorkingRatio standardFrequency standardWorkingHours standardAnnualWorkingDuration sequence	n/a
workerAssignmentExtract.department	id name title effectiveStartDate effectiveEndDate	one-to-one
workerAssignmentExtract.legalEmployer	id name effectiveStartDate effectiveEndDate	one-to-one
workerAssignmentExtract.legislation	territoryCode territoryShortName	one-to-one
workerAssignmentExtract.position	id effectiveStartDate effectiveEndDate name code	one-to-one
workerAssignmentExtract.grade	id effectiveStartDate effectiveEndDate name code	one-to-one
workerAssignmentExtract.location	id effectiveStartDate effectiveEndDate name code	one-to-one
workerAssignmentExtract.location.mainAddress	id effectiveStartDate effectiveEndDate county state province townOrCity postalCode countryCode longPostalCode addressLine1 addressLine2 addressLine3 addressLine4	one-to-one
workerAssignmentExtract.location.mainAddress.country	territoryCode territoryShortName	one-to-one
workerAssignmentExtract.job	id effectiveStartDate effectiveEndDate name code jobFunctionCode managerLevel	one-to-one
workerAssignmentExtract.job.jobFamily	id effectiveStartDate effectiveEndDate name code	one-to-one
workerAssignmentExtract.collectiveAgreement	id effectiveStartDate effectiveEndDate name	one-to-one
workerAssignmentExtract.personType	id userPersonType	one-to-one
workerAssignmentExtract.workerUnion	id effectiveStartDate effectiveEndDate name	one-to-one
workerAssignmentExtract.assignmentUserStatus	id userStatus	one-to-one
workerAssignmentExtract.businessUnit	id effectiveStartDate effectiveEndDate name	one-to-one
workerAssignmentExtract.account	codeCombinationId concatenatedSegments chartOfAccountsId	one-to-one
workerAssignmentExtract.ledger	ledgerId name	one-to-one
workerAssignmentExtract.workRelationship	id startDate workerType timeCreated timeUpdated	one-to-one
workerAssignmentExtract.localName	id effectiveStartDate effectiveEndDate lastName firstName displayName listName timeCreated timeUpdated	one-to-one
workerAssignmentExtract.globalName	id effectiveStartDate effectiveEndDate lastName firstName displayName listName timeCreated timeUpdated	one-to-one
workerAssignmentExtract.personDetail	id personNumber effectiveStartDate effectiveEndDate timeCreated timeUpdated	one-to-one

Worker Legislative Information Extract

Use workerLegislativeInfoExtract to extract workers' legislative information data.

View Path	workers/$views/workerLegislativeInfoExtract

Object	Attributes	Relationship Type
worker	id	n/a
worker.personDetail	id effectiveStartDate effectiveEndDate personNumber	one-to-one
worker.legislativeInformation	id effectiveStartDate effectiveEndDate gender maritalStatus maritalStatusChangeDate highestEducationLevel timeUpdated updatedBy timeCreated createdBy	one-to-one
worker.legislativeInformation.legislation	territoryCode territoryShortName	one-to-one

Worker Names Extract

Use workerNamesExtract to extract workers' names data.

View Path	workers/$views/workerNamesExtract

Object	Attributes	Relationship Type
worker	id	n/a
worker.personDetail	id effectiveStartDate effectiveEndDate personNumber	one-to-one
worker.names	id effectiveStartDate effectiveEndDate lastName firstName middleNames title prefix suffix knownAs previousLastName honors militaryRank displayName fullName listName orderName nameLanguage type timeUpdated updatedBy timeCreated createdBy	one-to-many
worker.names.legislation	territoryCode territoryShortName	one-to-one
worker.names.language	languageCode	one-to-one

Worker Phones Extract

Use workerPhonesExtract to extract workers' phones data.

View Path	workers/$views/workerPhonesExtract

Object	Attributes	Relationship Type
worker	id	n/a
worker.personDetail	id effectiveStartDate effectiveEndDate personNumber	one-to-one
worker.phones	id type primaryFlag phoneNumber areaCode countryCodeNumber extension validity timeUpdated updatedBy timeCreated createdBy	one-to-many
worker.phones.legislation	territoryCode territoryShortName	one-to-one

Worker Emails Extract

Use workerEmailsExtract to extract workers' emails data.

View Path	workers/$views/workerEmailsExtract

Object	Attributes	Relationship Type
worker	id	n/a
worker.personDetail	id effectiveStartDate effectiveEndDate personNumber	one-to-one
worker.emails	id type primaryFlag emailAddress timeUpdated updatedBy timeCreated createdBy	one-to-many

Multiple languages:

Translatable attributes are only available in English at this point.

Task 2: Preparing and Testing an Extraction Query

Each extraction view has a query API that allows to build and test extraction queries.

URL	`/api/boss/data/objects/ora/hcmHrCore/employment/v1/{{viewPath}}/$query`
HTTP method	`POST`
Request template	{ "collection": { "limit": {{limit}}, "offset": {{offset}}, "sortBy": [ {{sortAttributes}} ], "filter": "{{topLevelFilter}}" }, "fields": [ {{topLevelAttributes}} ], "accessors": { "{{childObject}}": { "collection": { "filter": "{{childLevelFilter}}" }, "fields": [ {{childLevelAttributes}} ], "accessors": { {{nestedChildAccessors}} } }, ... } }
Response template	200 OK { "items": [ {{items}} ], "hasMore": {{hasMore}} }

Objects and Attributes

Define what data to extract, i.e. which objects and attributes should be included. Including child objects requires adding accessors whereas including specific fields requires listing them in the fields array. See the complete example.

Filtering

Define how data should be filtered. You can use following expressions to build filters for your query.

Purpose	Expression	Example
Equality test	`field = value`	`ename = 'KING'`
Inequality test	`field != value`	`activeFlag != true`
Greater-than test Less-than test	`field > value field < value`	`sal > 1999.99 hireDate < '2000-01-01' timeUpdated> '1900-01-01T13:51:54Z'`
Greater-than-or-equal-to test Less-than-or-equal-to test	`field >= value field <= value< code>`	`sal >= 1999.99 hireDate <= '2000-01-01' timeUpdated >= '1900-01-01T13:51:54Z'`
Pattern-matching	`field LIKE 'pattern'`	`job LIKE 'SALES%'`
Membership test	`field IN (value1, ..., valueN)`	`deptno IN (10, 20, 40)`
Case-insensitivity comparison	`field ~= value field ~!= value field ~> value field ~< value field ~>= value field ~<= value field ~LIKE 'pattern' field ~IN (value1, ..., valueN)`	`ename ~= 'king'`
Existence test (for one-to-many relationships)	`child[expression]`	`assignments[startDate = null]`
Logical conjunction	`expression AND expression`
Logical disjunction	`expression OR expression`
Logical negation	`!(expression)`

Filtering by child objects in one-to-one relationship:

In case of one-to-one relationships you can refer to child objects and their attributes in the filter clause just as to other parent object's attributes, for example legalEmployer.id in (1001, 1002).

Filtering child objects in one-to-many relationship:

In case of one-to-many relationships, the existence test in the table above will filter parents that have at least one child meeting the criteria. However, it doesn't mean that child records, if retrieved, will be filtered automatically. If you want to ensure that you only get child records meeting the criteria, you have to repeat the filter at the child level too.

For example, if you want to retrieve only phones of type W1, you need to apply the following filters:


{
    "collection": {
        "filter": "phones[type = 'W1']"
    },
    "accessors": {
        "phones": {
            "collection": {
                "filter": "type = 'W1'"
            },
...

Filtering by effective date:

In case of date-effective objects, you will get data effective as of current date by default. In order to retrieve data effective as of specific date, use $effectiveDate HTTP query parameter.

For example, if you want to retrieve data effective as of 2023-01-01, use the following URL for your query:

/api/boss/data/objects/ora/hcmHrCore/employment/v1/{{viewPath}}/$query?$effectiveDate=2023-01-01

Sorting

Define how data should be sorted. Sorting is expressed by an array of sort attributes including the sorting direction (asc or desc). For example:

"sortBy": [
    {
        "totalAmount": "desc"
    },
    {
        "paidAmount": "asc"
    }
]

Paging

Define how data should be paginated. Client can control the paging by providing limit and offset parameters. For example:

"limit": 200,
"offset": 400

Default limit is 25 and maximum limit is 1000.

Default offset is 0 and indicates the beginning of the results.

The top level hasMore attribute in the response indicates if there are more results to be fetched.

Paginating should not be used as an alternative way to extract data. When querying this API, there is no guarantee that the data won't change in-between the requests. Use the asynchronous API for data extraction.

Example

The example extract query below is designed to retrieve assignments information along with legal employer and department details, that:

Are primary assignments
Are of type Employee
Do not belong to Legal Employers with IDs 10001 and 10002
Are effective as of extraction date
Got updated (or created) since the previous run

Request Example

Notice the limit parameter and timeUpdated attribute condition with the timestamp of the previous extract run.

POST /api/boss/data/objects/ora/hcmHrCore/employment/v1/workerAssignmentExtracts/$query
 
{
    "collection": {
        "limit": 10,
        "filter": "primaryFlag = true and timeUpdated > '2025-05-01T00:00:00Z' and assignmentType = 'E' and !(legalEmployer.id in (10001, 10002))"
    },
    "fields": [ "id", "assignmentType", "assignmentStatusType", "effectiveStartDate", "effectiveEndDate", "businessTitle", "workAtHomeFlag", "assignmentNumber", "timeUpdated" ],
    "accessors": {
        "personDetail": {
            "fields": [ "personNumber" ]
        },
        "globalName": {
            "fields": [ "firstName", "lastName" ]
        },
        "department": {
            "fields": [ "id", "name", "title" ]
        },
        "legalEmployer": {
            "fields": [ "id", "name" ]
        },
        "workRelationship": {
            "fields": [ "id" ]
        }
    }
}

Response Example

200 OK
 
{
    "items": [
        {
            "id": "300000795682243",
            "assignmentType": "E",
            "assignmentStatusType": "ACTIVE",
            "effectiveStartDate": "2018-06-14",
            "effectiveEndDate": "4712-12-31",
            "businessTitle": "Aeronautical Engineer Level-9352",
            "workAtHomeFlag": false,
            "assignmentNumber": "EHDLWorker_190903_1637",
            "timeUpdated": "2025-05-06T11:42:17.821Z",
            "$id": "300000795682243",
            "$context": {
                "etag": "89"
            },
            "personDetail": {
                "personNumber": "HDLWorker_190903_1637",
                "$id": "100000329366771",
                "$context": {
                    "etag": ""
                }
            },
            "globalName": {
                "firstName": "Raymond-Olivier",
                "lastName": "Beer-TrÃ¶st",
                "$id": "300000795668871",
                "$context": {
                    "etag": ""
                }
            },
            "department": {
                "id": "300000044556980",
                "name": "South - Venaria DC-GROUP/SFIELESOIT74155",
                "title": null,
                "$id": "300000044556980",
                "$context": {
                    "etag": "13",
                    "links": {
                        "$self": {
                            "href": "https://example.com/api/boss/data/objects/ora/hcmHrCore/workStructures/v1/departments/300000044556980?$effectiveDate=2025-05-13"
                        }
                    }
                }
            },
            "legalEmployer": {
                "id": "300000046740247",
                "name": "PSR_US_LE_1",
                "$id": "300000046740247",
                "$context": {
                    "etag": "15",
                    "links": {
                        "$self": {
                            "href": "https://example.com/api/boss/data/objects/ora/hcmHrCore/workStructures/v1/legalEmployers/300000046740247?$effectiveDate=2025-05-13"
                        }
                    }
                }
            },
            "workRelationship": {
                "id": "100000329414679",
                "$id": "100000329414679",
                "$context": {
                    "etag": "1"
                }
            }
        },
        {
            "id": "300000795670049",
            "assignmentType": "E",
            "assignmentStatusType": "ACTIVE",
            "effectiveStartDate": "2018-05-28",
            "effectiveEndDate": "4712-12-31",
            "businessTitle": "Civil Engineer-6864",
            "workAtHomeFlag": false,
            "assignmentNumber": "EHDLWorker_190903_11128",
            "timeUpdated": "2025-05-06T11:42:25.787Z",
            "$id": "300000795670049",
            "$context": {
                "etag": "89"
            },
            "personDetail": {
                "personNumber": "HDLWorker_190903_11128",
                "$id": "100000329383875",
                "$context": {
                    "etag": ""
                }
            },
            "globalName": {
                "firstName": "Charlotte-PÃ©nÃ©lope",
                "lastName": "Beer-TrÃ¶st",
                "$id": "300000795669677",
                "$context": {
                    "etag": ""
                }
            },
            "department": {
                "id": "300000044582197",
                "name": "Human Resources-GROUP/AT081000101",
                "title": null,
                "$id": "300000044582197",
                "$context": {
                    "etag": "13",
                    "links": {
                        "$self": {
                            "href": "https://example.com/api/boss/data/objects/ora/hcmHrCore/workStructures/v1/departments/300000044582197?$effectiveDate=2025-05-13"
                        }
                    }
                }
            },
            "legalEmployer": {
                "id": "300000046740247",
                "name": "PSR_US_LE_1",
                "$id": "300000046740247",
                "$context": {
                    "etag": "15",
                    "links": {
                        "$self": {
                            "href": "https://example.com/api/boss/data/objects/ora/hcmHrCore/workStructures/v1/legalEmployers/300000046740247?$effectiveDate=2025-05-13"
                        }
                    }
                }
            },
            "workRelationship": {
                "id": "100000329453488",
                "$id": "100000329453488",
                "$context": {
                    "etag": "1"
                }
            }
        },
        ...
    ],
    "hasMore": true
}

Task 3: Submitting an Extract Job Request

Once the query is defined, an extract job request can be submitted using Job Scheduler API.

URL	`/api/saas-batch/jobscheduler/v1/jobRequests`
HTTP method	`POST`
Request template	For `workerAssignmentExtracts` view: { "jobDefinitionName": "AsyncDataExtraction", "serviceName": "boss", "requestParameters": { "boss.module": "oraHcmHrCoreEmployment", "boss.resource.name": "workerAssignmentExtracts", "boss.resource.version": "v1", "boss.outputFormat": "json", "boss.request.system.param.effectiveDate": "{{effectiveDate}}", "boss.advancedQuery": "{{query}}" } } For other views: { "jobDefinitionName": "AsyncDataExtraction", "serviceName": "boss", "requestParameters": { "boss.module": "oraHcmHrCoreEmployment", "boss.resource.name": "workers", "boss.resource.version": "v1", "boss.businessView": "{{viewName}}", "boss.outputFormat": "json", "boss.request.system.param.effectiveDate": "{{effectiveDate}}", "boss.advancedQuery": "{{query}}" } } `boss.request.system.param.effectiveDate` is an optional parameter that should be provided only if you want to retrieve data effective as of date different from current date.
Response template	On successful submission, `202` response code will be returned, along with the `Location` header with the URL pointing to the particular job request instance. 202 Accepted Location: {{jobRequestUrl}}

Paging when extracting data:

While you might have used pagination controls, i.e. limit and offset parameters, when building and test the query, you don't want the extraction results to be constrained by them. Remove any usage of limit and offset parameters when submitting a query.

Passing the query :

The query passed when submitting the extraction job request must be in the form of a standard JSON string. Take the query prepared and tested using $query API endpoint and:

Escape all double quotes (" → \")
Remove any newline characters (\n)
Potentially reduce other whitespaces (e.g. indentations)

Overall you want to go, for example, from:

{
    "collection": {
        "limit": 100,
        "filter": "totalAmount > 10000"
    },
    "fields": [ "id", "totalAmount" ]
}

To:

{\"collection\": {\"filter\": \"totalAmount > 10000\"},\"fields\": [ \"id\", \"totalAmount\" ]}

Example

Request Example

POST /api/saas-batch/jobscheduler/v1/jobRequests
 
{
    "jobDefinitionName": "AsyncDataExtraction",
    "serviceName": "boss",
    "requestParameters": {
        "boss.module": "oraHcmHrCoreEmployment",
        "boss.resource.name": "workerAssignmentExtracts",
        "boss.resource.version": "v1",
        "boss.outputFormat": "json",
        "boss.advancedQuery": "{\"collection\": {\"filter\": \"primaryFlag = true and timeUpdated > '2025-05-01T00:00:00Z' and assignmentType = 'E' and !(legalEmployer.id in (10001, 10002))\"},\"fields\": [ \"id\", \"assignmentType\", \"assignmentStatusType\", \"effectiveStartDate\", \"effectiveEndDate\", \"businessTitle\", \"workAtHomeFlag\", \"assignmentNumber\", \"timeUpdated\" ],\"accessors\": {\"personDetail\": {\"fields\": [ \"personNumber\" ]},\"globalName\": {\"fields\": [ \"firstName\", \"lastName\" ]},\"department\": {\"fields\": [ \"id\", \"name\", \"title\" ]},\"legalEmployer\": {\"fields\": [ \"id\", \"name\" ]},\"workRelationship\": {\"fields\": [ \"id\" ]}}}"
    }
}

Response Example

202 Accepted
 
Location: https://example.com/api/saas-batch/jobscheduler/v1/jobRequests/42075

Task 4: Checking for Job Completion

Checking for completion involves using the Job Scheduler API to periodically poll the job request details, until it completes successfully or fails.

URL	`/api/saas-batch/jobscheduler/v1/jobRequests/{{jobRequestId}}`
HTTP method	`GET`

Successful completion:

A job request is considered successfully completed when the following conditions are met:

Attribtue	Expected value
`jobDetails.jobProgress.completed`	`true`
`jobDetails.jobProgress.status`	`SUCCEEDED`

Failed completion:

A job request is considered failed when the following condition is met. In such a case, the jobDetails.jobProgress.message attribute will contain the error message.

Attribtue	Expected value
`jobDetails.jobProgress.status`	`FAILED`

Example

Request Example

GET /api/saas-batch/jobscheduler/v1/jobRequests/42075

Response Examples

Below responses show different stages of a submitted job. See the jobProgress.status and jobProgress.completed attributes in particular.

Accepted / Enqueued

200 OK
 
{
    "jobDetails": {
        "jobRequestId": 42075,
        "jobRequest": {
            "jobDefinitionName": "AsyncDataExtraction",
            "serviceName": "boss",
            "systemDerivedVersion": "90",
            "jobSubmitter": "TM-MFITZIMMONS",
            "requestParameters": {
                "boss.module": "oraHcmHrCoreEmployment",
                "boss.resource.name": "workerAssignmentExtracts",
                "boss.resource.version": "v1",
                "boss.outputFormat": "json",
                "boss.advancedQuery": "{\"collection\": {\"filter\": \"primaryFlag = true and timeUpdated > '2025-05-01T00:00:00Z' and assignmentType = 'E' and !(legalEmployer.id in (10001, 10002))\"},\"fields\": [ \"id\", \"assignmentType\", \"assignmentStatusType\", \"effectiveStartDate\", \"effectiveEndDate\", \"businessTitle\", \"workAtHomeFlag\", \"assignmentNumber\", \"timeUpdated\" ],\"accessors\": {\"personDetail\": {\"fields\": [ \"personNumber\" ]},\"globalName\": {\"fields\": [ \"firstName\", \"lastName\" ]},\"department\": {\"fields\": [ \"id\", \"name\", \"title\" ]},\"legalEmployer\": {\"fields\": [ \"id\", \"name\" ]},\"workRelationship\": {\"fields\": [ \"id\" ]}}}"
            },
            "jobRetryNumber": 0,
            "timeoutThreshold": 14400
        },
        "jobStatus": "ENQUEUED",
        "jobProgress": {
            "status": "ACCEPTED",
            "message": "Job is submitted",
            "startTime": "2025-05-25T13:39:01Z",
            "endTime": "2025-05-25T13:39:15Z",
            "completedPercentage": "0",
            "completed": false
        }
    },
    "$context": {
        "links": {
            "$self": {
                "href": "https://example.com/api/saas-batch/jobscheduler/v1/jobRequests/42075"
            }
        }
    }
}

Running

200 OK
 
{
    "jobDetails": {
        "jobRequestId": 42075,
        "jobRequest": {
            "jobDefinitionName": "AsyncDataExtraction",
            "serviceName": "boss",
            "systemDerivedVersion": "90",
            "jobSubmitter": "TM-MFITZIMMONS",
            "requestParameters": {
                "boss.module": "oraHcmHrCoreEmployment",
                "boss.resource.name": "workerAssignmentExtracts",
                "boss.resource.version": "v1",
                "boss.outputFormat": "json",
                "boss.advancedQuery": "{\"collection\": {\"filter\": \"primaryFlag = true and timeUpdated > '2025-05-01T00:00:00Z' and assignmentType = 'E' and !(legalEmployer.id in (10001, 10002))\"},\"fields\": [ \"id\", \"assignmentType\", \"assignmentStatusType\", \"effectiveStartDate\", \"effectiveEndDate\", \"businessTitle\", \"workAtHomeFlag\", \"assignmentNumber\", \"timeUpdated\" ],\"accessors\": {\"personDetail\": {\"fields\": [ \"personNumber\" ]},\"globalName\": {\"fields\": [ \"firstName\", \"lastName\" ]},\"department\": {\"fields\": [ \"id\", \"name\", \"title\" ]},\"legalEmployer\": {\"fields\": [ \"id\", \"name\" ]},\"workRelationship\": {\"fields\": [ \"id\" ]}}}"
            },
            "jobRetryNumber": 0,
            "timeoutThreshold": 14400
        },
        "jobStatus": "RUNNING",
        "jobProgress": {
            "jobRequestId": 42075,
            "status": "RUNNING",
            "message": "Job status is changed to RUNNING",
            "startTime": "2025-05-25T13:39:27Z",
            "endTime": "2025-05-25T13:40:25Z",
            "completedPercentage": "50",
            "completed": false
        }
    },
    "$context": {
        "links": {
            "$self": {
                "href": "https://example.com/api/saas-batch/jobscheduler/v1/jobRequests/42075"
            }
        }
    }
}

200 OK
 
{
    "jobDetails": {
        "jobRequestId": 42075,
        "jobRequest": {
            "jobDefinitionName": "AsyncDataExtraction",
            "serviceName": "boss",
            "systemDerivedVersion": "90",
            "jobSubmitter": "TM-MFITZIMMONS",
            "requestParameters": {
                "boss.module": "oraHcmHrCoreEmployment",
                "boss.resource.name": "workerAssignmentExtracts",
                "boss.resource.version": "v1",
                "boss.outputFormat": "json",
                "boss.advancedQuery": "{\"collection\": {\"filter\": \"primaryFlag = true and timeUpdated > '2025-05-01T00:00:00Z' and assignmentType = 'E' and !(legalEmployer.id in (10001, 10002))\"},\"fields\": [ \"id\", \"assignmentType\", \"assignmentStatusType\", \"effectiveStartDate\", \"effectiveEndDate\", \"businessTitle\", \"workAtHomeFlag\", \"assignmentNumber\", \"timeUpdated\" ],\"accessors\": {\"personDetail\": {\"fields\": [ \"personNumber\" ]},\"globalName\": {\"fields\": [ \"firstName\", \"lastName\" ]},\"department\": {\"fields\": [ \"id\", \"name\", \"title\" ]},\"legalEmployer\": {\"fields\": [ \"id\", \"name\" ]},\"workRelationship\": {\"fields\": [ \"id\" ]}}}"
            },
            "jobRetryNumber": 0,
            "timeoutThreshold": 14400
        },
        "jobStatus": "RUNNING",
        "jobProgress": {
            "jobRequestId": 42075,
            "status": "RUNNING",
            "message": "Publishing BOSS job progress: JobProgress(jobRequestId=42075, resourcePath=oraHcmHrCoreEmployment/v1/workers, dataDocName=null, deploymentId=null, jobStatus=RUNNING, startTime=2025-05-25T13:40:18Z, endTime=2025-05-25T13:40:38Z, completedPercentage=30, completed=false, error=null)",
            "startTime": "2025-05-25T13:40:40Z",
            "endTime": "2025-05-25T13:40:40Z",
            "completedPercentage": "30",
            "completed": false
        }
    },
    "$context": {
        "links": {
            "$self": {
                "href": "https://example.com/api/saas-batch/jobscheduler/v1/jobRequests/42075"
            }
        }
    }
}

Successfully Completed

200 OK
 
{
    "jobDetails": {
        "jobRequestId": 42075,
        "jobRequest": {
            "jobDefinitionName": "AsyncDataExtraction",
            "serviceName": "boss",
            "systemDerivedVersion": "90",
            "jobSubmitter": "TM-MFITZIMMONS",
            "requestParameters": {
                "boss.module": "oraHcmHrCoreEmployment",
                "boss.resource.name": "workerAssignmentExtracts",
                "boss.resource.version": "v1",
                "boss.outputFormat": "json",
                "boss.advancedQuery": "{\"collection\": {\"filter\": \"primaryFlag = true and timeUpdated > '2025-05-01T00:00:00Z' and assignmentType = 'E' and !(legalEmployer.id in (10001, 10002))\"},\"fields\": [ \"id\", \"assignmentType\", \"assignmentStatusType\", \"effectiveStartDate\", \"effectiveEndDate\", \"businessTitle\", \"workAtHomeFlag\", \"assignmentNumber\", \"timeUpdated\" ],\"accessors\": {\"personDetail\": {\"fields\": [ \"personNumber\" ]},\"globalName\": {\"fields\": [ \"firstName\", \"lastName\" ]},\"department\": {\"fields\": [ \"id\", \"name\", \"title\" ]},\"legalEmployer\": {\"fields\": [ \"id\", \"name\" ]},\"workRelationship\": {\"fields\": [ \"id\" ]}}}"
            },
            "jobRetryNumber": 0,
            "timeoutThreshold": 14400
        },
        "jobStatus": "SUCCEEDED",
        "jobProgress": {
            "jobRequestId": 42075,
            "status": "SUCCEEDED",
            "message": "Job status is changed to SUCCEEDED",
            "startTime": "2025-05-25T13:39:27Z",
            "endTime": "2025-05-25T13:41:26Z",
            "completedPercentage": "100",
            "completed": true
        }
    },
    "$context": {
        "links": {
            "$self": {
                "href": "https://example.com/api/saas-batch/jobscheduler/v1/jobRequests/42075"
            }
        }
    }
}

Task 5: Fetching Extract Output Details

Once the job completes successfully, its output file information can be fetched. It involves using the Job File Manager API for the particular extract job request instance.

Output is stored in compressed chunks.

URL	`/api/saas-batch/jobfilemanager/v1/jobRequests/{{jobRequestId}}/outputFiles`
HTTP method	`GET`

File size:

File size is returned in the items.fileSize response attribute and expressed in bytes.

Enclosure link:

The URL to the actual file contents is returned in the items.$context.links.enclosure response attribute.

Example

Request Example

GET /api/saas-batch/jobfilemanager/v1/jobRequests/42075/outputFiles

Response Example

In the example below, the complete output is stored in two compressed files.

200 OK
 
{
    "items": [
        {
            "fileName": "result_1_json.zip",
            "fileSize": 9390419,
            "timeCreated": "2025-04-22T22:04:22.667Z",
            "$context": {
                "links": {
                    "enclosure": {
                        "href": "https://example.com/api/saas-batch/jobfilemanager/v1/jobRequests/40071/outputFiles/result_1_json.zip/content"
                    },
                    "$self": {
                        "href": "https://example.com/api/saas-batch/jobfilemanager/v1/jobRequests/40071/outputFiles/result_1_json.zip"
                    }
                }
            }
        },
        {
            "fileName": "result_2_json.zip",
            "fileSize": 4462724,
            "timeCreated": "2025-04-22T22:04:36.565Z",
            "$context": {
                "links": {
                    "enclosure": {
                        "href": "https://example.com/api/saas-batch/jobfilemanager/v1/jobRequests/40071/outputFiles/result_2_json.zip/content"
                    },
                    "$self": {
                        "href": "https://example.com/api/saas-batch/jobfilemanager/v1/jobRequests/40071/outputFiles/result_2_json.zip"
                    }
                }
            }
        }
    ],
    "totalItems": 2,
    "$context": {
        "links": {
            "$self": {
                "href": "https://example.com/api/saas-batch/jobfilemanager/v1/jobRequests/40071/outputFiles"
            }
        }
    }
}

Task 6: Downloading Extract Output

Finally the extract output files can be downloaded using the Job File Manager API for the particular extract job request instance and output file.

URL	`/api/saas-batch/jobfilemanager/v1/jobRequests/{{jobRequestId}}/outputFiles/{{fileName}}/content`
HTTP method	`GET`

Tip:

If needed, you can download large files more efficiently by implementing multithreaded download using the Range HTTP header as below.

Range: {{startByte}}-{{endByte}}/{{fileSize}}

Example

Request Example

GET /api/saas-batch/jobfilemanager/v1/jobRequests/42075/outputFiles/result_42075.json/content

Response Examples

Actual response is binary compressed file contents. Once uncompressed, it is full or partial (in case of Range header usage), unformatted JSON payload, with full or partial (in case of a file-chunk) results of the extraction query.

Full Uncompressed Results Example

{"items": [
    {"id":"300008335145001","assignmentType":"E","assignmentStatusType":"ACTIVE","effectiveStartDate":"2025-05-02","effectiveEndDate":"4712-12-31","businessTitle":"E7356262523","workAtHomeFlag":false,"assignmentNumber":"E7356262523","timeUpdated":"2025-05-01T07:53:15.722Z","$id":"300008335145001","$context":{"etag":"1"},"personDetail":{"personNumber":"7356262523","$id":"300008335144985","$context":{"etag":""}},"globalName":{"firstName":null,"lastName":"oracle","$id":"300008335144986","$context":{"etag":""}},"department":null,"legalEmployer":{"id":"300001939234024","name":"AORT Oracle United States","$id":"300001939234024","$context":{"etag":"6","links":{"$self":{"href":"/ora/hcmHrCore/workStructures/v1/$en-US/legalEmployers/300001939234024?$effectiveDate=2025-05-13"}}}},"workRelationship":{"id":"300008335144995","$id":"300008335144995","$context":{"etag":"1"}}},
    {"id":"300000310085281","assignmentType":"E","assignmentStatusType":"ACTIVE","effectiveStartDate":"2018-03-04","effectiveEndDate":"4712-12-31","businessTitle":"Medical Technologist Corporate Level-35321","workAtHomeFlag":false,"assignmentNumber":"EHDLWorker_190409_467490","timeUpdated":"2025-05-07T15:29:46.59Z","$id":"300000310085281","$context":{"etag":"90"},"personDetail":{"personNumber":"HDLWorker_190409_467490","$id":"100000127293313","$context":{"etag":""}},"globalName":{"firstName":"Martin-David","lastName":"Oestrovsky-Krein","$id":"300000310075057","$context":{"etag":""}},"department":{"id":"300000041568062","name":"GFIN Global Controlling-GROUP/GFINGC74155","title":null,"$id":"300000041568062","$context":{"etag":"13","links":{"$self":{"href":"/ora/hcmHrCore/workStructures/v1/$en-US/departments/300000041568062?$effectiveDate=2025-05-13"}}}},"legalEmployer":{"id":"300000046740247","name":"PSR_US_LE_1","$id":"300000046740247","$context":{"etag":"15","links":{"$self":{"href":"/ora/hcmHrCore/workStructures/v1/$en-US/legalEmployers/300000046740247?$effectiveDate=2025-05-13"}}}},"workRelationship":{"id":"100000127362395","$id":"100000127362395","$context":{"etag":"1"}}}
]}

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

Title and Copyright Information

Extract Data from HCM Using Spectra Services

G38643-01

July 2025

Oracle and/or its affiliates.