Documentation
What's NewUKG.comMarketplaceUKG Pro status

Release notes

The Release notes contain announcements, corrections, enhancements, and updates of note to the conceptual and reference documentation. New API resources and operations are listed in the Version history.

2024.R2

The following changes were made to the API and Developer Hub in 2024.R2.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation was enhanced to expose secondsAmount in order to export data with a higher precision for Accrual transactions and allow PTO data to be available with 6 decimals. (PS-310099)
  • Enhanced the Retrieve Marker Types (GET /v1/platform/change_indicators) API operation to capture Schedule Tag changes. (PS-188857)
  • The Developer Hub documentation for the Retrieve Net Changes for Activity Shifts (POST /v1/work/activity_shifts/net_changes/multi_read) API operation contained an incorrect service limit value of 100 employees per call. The service limit has been updated to reflect the actual limit of 50 employees per call. (PS-250847)
  • Calls to the Update Multiple Persons (POST /v1/commons/persons/multi_update) API operation caused tenants to time out after 8 minutes. The process now completes more quickly and does not time out. (PS-222711)
  • The Create or Update Integration List Parameters (POST /v1/platform/integration_list_parameters/apply_update) API operation did not create or update integration list parameters as specified in the request but instead prefixed "null_" to the specified names of the integration list parameters. (PS-286408)
  • In rare cases, the Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation returned incorrect sign-off information. (PS-291136)
  • In rare cases, calls to the Retrieve Paginated List of Locations (POST /v2/commons/locations/multi_read) API operation would time out due to a performance issue when many revisions had been made per node. The root cause was identified and addressed. (PS-302232)
  • When the Retrieve Requestable Open Shifts (POST /v1/scheduling/employee_open_shift_requests/open_shifts/multi_read) API operation was called with an invalid request subtype, the error response included unnecessary and unclear information. The API now returns the invalid request subtype as part of the error response. (PS-300843)
  • When the Retrieve Employee Schedule (GET /v1/scheduling/employee_schedule) API operation was called with an invalid symbolic period, the error response included unnecessary and unclear information. The API now returns the invalid symbolic period as part of the error response. (PS-295534)
  • The Retrieve Employee Schedule (GET /v1/scheduling/employee_schedule) API operation incorrectly threw an HTTP status code 500 Internal Server Error when an invalid order_by query parameter value was passed. (PS-295522)
  • When updating a shift in a schedule, the Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update) API operation did not correctly resolve job paths when a date range was not specified and a qualifier was used in orgJobRef. The API now correctly resolves such references without an explicitly specified date range. (PS-283276)
  • Several API operations could throw an HTTP status code 500 Internal Server Error when extremely large numbers of employees were inadvertently loaded by a backend service. The root cause was identified and corrected. (PS-277362)
  • The Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation's availabilityPattern property is deprecated because the Availability Template data access profile no longer exists. The Developer Hub documentation for this property has been updated to note the deprecated status. (PS-275918)
  • Improved performance of the Post or Unpost Schedule (POST /v1/scheduling/schedule_management_actions/apply_update) API operation, which sometimes timed out and returned an HTTP status code 504 Gateway Timeout error. (PS-274705)
  • Enhanced the Developer Hub documentation for the Retrieve Employee Schedule Changes (POST /v1/scheduling/schedule/changes/multi_read) API operation to clarify behavior. (PS-241505)
  • When creating a schedule pattern with a future-dated orgJob using the Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create) API operation, the call would fail with an error message of "could not be found, or you do not have access rights to it." The API now supports creating schedule patterns with future-dated orgJobs. (PS-222754)
  • The following API operations now have enhanced validation to ensure they correctly enforce rules around various behaviors that should only be executed by employees or managers: (PS-174027)
  • The Delete Labor Category Entries (POST /v1/commons/labor_entries/multi_delete) API operation did not allow objects to be specified in the request payload by qualifier as described in the documentation. The API now supports deleting by qualifier. (PS-301891)
  • Enhanced the Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation to return timezone qualifiers as well as IDs for workedSpans properties. (PS-301058)
  • The Retrieve Paycodes as Manager (Deprecated) (GET /v1/timekeeping/setup/pay_codes) API operation sometimes incorrectly returned duplicate pay code objects in the response. The root cause was identified and corrected. (PS-295798)
  • The Export Payroll Asynchronously (POST /v1/commons/payroll/export/async) API operation threw an HTTP status code 500 Internal Server Error when too many requests were in process on the same tenant simultaneously. The root cause was identified and corrected. (PS-240620)
  • The Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation sometimes timed out while processing very large request payloads. Implemented a service limit on new tenants and performance monitoring on existing tenants to preserve backwards compatibility. (PS-223221)
  • The Create or Update Hyperfind Queries (POST /v1/commons/hyperfind/multi_upsert) API operation threw errors when certain combinations of nested filters were specified in the request payload. The root cause was identified and corrected. (PS-282568)
  • The Retrieve Batch Job Statuses (POST /v1/platform/batch_processing/batch_job_status/multi_read) API operation threw HTTP status code 500 Internal Server Errors when the launchDate property was not specified in the correct format or the createdBy property was null in the request payload. The API now returns actionable and descriptive 400 error messages. (PS-271547)
  • The Execute Hyperfind Query (POST /v1/commons/hyperfind/execute) API operation failed to allow a full-year timespan when executed against a leap year. The API has been updated to support leap year-length timespans. (PS-271387)
  • The definition in the Developer Hub of the mfaRequired property has been enhanced as follows: "A Boolean indicator of whether or not Multi-Factor Authentication (MFA) is required by an employee extension. Note: You can enable or disable MFA for managers only if the global property global.authentication.mfa.manager.override is true. By default, MFA is enabled for basic authentication of new users and managers." (PS-297413)
  • Enhanced the Retrieve All Generic Categories or by Name (Deprecated) (GET /v1/forecasting/generic_categories) API operation to include the name property in the response. The value of this string will always be the same as the value of the categoryPath property. (PS-276662)
  • Enhanced the following API operations to include the primaryLaborCategory property in the workedSpans array: (PS-311742)
  • Enhanced the following API operations with new behavior that is enabled with the new global property: global.payrule.single.entry.history.enabled. When false, the API operations maintain the existing behavior. The existing behavior is such that when only one pay rule exists, assigning a new pay rule through the API with no effective date sets the effective date of the new assignment to the beginning of time and removes the previous pay rule assignment from history. When set to true, assigning a new pay rule through the API with no effective date (when only one pay rule already exists) sets the effective date of the new assignment to today's date in UTC and retains the history of the previous assignment. This new behavior is similar to the existing behavior when more than one pay rule already exists. (PS-330388)
  • The Developer Hub documentation for the following API operations sometimes included an incorrect request or response model. The root cause was identified and the correct model is now displayed.
  • Enhanced the Retrieve All Display Profiles (GET /v1/commons/display_profiles) API operation with the data_import_tool optional Boolean query parameter, which allows the API to return a smaller Display Profile object in the response body. (PS-288415)
  • Enhanced the following API operations with the optional Boolean query parameter validation_only, which allows users to preview and validate labor categories or labor category entries before performing insertions or updates: (PS-319461, PS-319462)
  • Enhanced the Retrieve Locations by External IDs (POST /v1/commons/locations/external_ids/multi_read) API operation with the optional Boolean request payload property returnAllMatches, which enables the new behavior, along with the new property endDate, which determines the date span for the external_ids returned. This new functionality allows multiple mappings to be returned whenever multiple revisions exist during a given date span and whenever multiple different locations use the same external_id. (PS-315683, PS-316148)
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation's response body to include the following new properties: (PS-310099)
    • vestedDurationInSeconds
    • probationDurationInSeconds
    • takingToDateInSeconds
    • availableBalanceInSeconds
    • secondsAmount
    • probationSecondsAmount
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation to allow filtering based on the payCodeType specified in the request payload. When COMBINED is specified, all combined paycodes totals are returned, and when REGULAR is specified, all regular paycodes totals are returned. (PS-291411)
  • Enhanced the Bulk Accrual Suspensions or Reinstatements (POST /v1/timekeeping/accruals/suspensions) API operation to support the position object in the request payload and response body. Adding position object support allows this API operation to support position-aware accrual codes. (PS-179219)
  • Updated the Retrieve Employee Rule Violations (POST /v1/scheduling/violations) API operation to mark the following two properties as deprecated: beforeViolations and validateBeforeViolation. (PS-204303)
  • Enhanced the following API operations to include HTTP status code 207 Partial Success responses when activated with an optional query parameter partial_success or request payload property partialSuccess: (PS-268060)
    • Retrieve Schedule (POST /v1/scheduling/schedule/multi_read) accepts request payload property partialSuccess
    • Create Shifts (POST /v1/scheduling/schedule/shifts/multi_create) accepts query parameter partial_success
    • Create Shifts from Patterns (POST /v1/scheduling/schedule/shifts/apply_create) accepts request payload property partialSuccess
    • Update Shifts (POST /v1/scheduling/schedule/shifts/multi_update) accepts query parameter partial_success
    • Delete Shifts (POST /v1/scheduling/schedule/shifts/multi_delete) accepts request payload property partialSuccess
  • Enhanced the following API operations to add the exclusionComments property to the effectivePredictiveSchedulingRules object, which identifies the Comments that have been selected for exclusion: (PS-222151)
  • Enhanced the Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation such that, when the Brazil Compliance feature switch is enabled, the response body includes the brazilDevice object reference and the nsrId property. (PS-276235)
  • Enhanced the Retrieve Data (POST /v1/commons/data/multi_read) API operation with the editable Boolean property, which, when true, allows a custom filter to be edited by a user. (FS-41366)
  • Enhanced the following API operations to include shift details in the response: (PS-268057)
    • Retrieve Shift Swap Requests as Manager (POST /v1/scheduling/manager_swap/multi_read)
    • Retrieve Shift Swap Requests (POST /v1/scheduling/employee_swap/multi_read)
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation to include the following new select options: (PS-233872)
    • CONTRACT_TOTALS
    • SHIFT_CONTRACT_TOTAL_SUMMARY
    • DAILY_CONTRACT_TOTAL_SUMMARY
  • In certain situations, the Bulk Import Paycode Edits (POST /v1/timekeeping/pay_code_edits/import) API operation threw an HTTP status code 500 Internal Server Error. The root cause was identified and a solution implemented. (PS-254026)
  • In certain situations, the Add Rule Version to Percentage Allocation Rule by ID (POST /v1/timekeeping/setup/percentage_allocation_rules/{id}) API operation threw an unhelpful transaction assistant error. The API now returns a more helpful error condition in those scenarios. (PS-225534)
  • Enhanced the response body of the following API operations to include the Activity processed segment ID within every processedSegments object: (PS-352309)
  • Enhanced the Retrieve Shift Swap Request Information (POST /v1/scheduling/employee_swap/apply_read) API operation to add the includeEmployeeDetails Boolean property to the request payload. When true, this property allows the response body to include the employeeName property. (PS-199001)
  • Enhanced the following API operations to support the request payload and response body property externalId: (PS-286971)
  • Enhanced the following API operations with a timeZoneName response body property: (PS-283343)
  • Enhanced the following API operations with a new request payload and response body property skillRequirementsProfile: (PS-276726)
  • Enhanced the Update Adjustment Rule by ID (PUT /v1/timekeeping/setup/adjustment_rules/{id}) API operation with a new error message that is thrown when a duplicate request is submitted to update the adjustment rule and a previous request is still in progress. (PS-177476)
  • Enhanced the Create Work Rule (POST /v1/timekeeping/setup/full_work_rule) and Create Work Rules (POST /v1/timekeeping/setup/full_work_rules/multi_create) API operations with additional validation and a new error message that validates the expiration date specified during the creation of a new work rule by duplication of an existing workrule. This validation ensures that only valid work rules within the intended timeframe (beginning of time to forever) are created. (PS-240323)
  • Enhanced the following API operations to support returning the lastModified property: (PS-241610)
  • Enhanced the Retrieve Employee Schedule (GET /v1/scheduling/employee_schedule) API operation with the Boolean query parameter include_formatted_path, which, when true, returns the formatted job path as part of the OrgJob information. (PS-199611)

2024.R1

The following changes were made to the API and Developer Hub in 2024.R1.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The following API operations will no longer process the accountLocked boolean property in the request payload. If accountLocked is specified, it will be ignored by the system. (PS-178224)
  • Added the new Access Control Point (ACP) VIEW_MY_INTEGRATION_RUNS_ONLY to the following API operations: (PS-178225)
  • The Retrieve Activity Totals for Multiple Employees (POST /v1/work/activity_totals/multi_read) API operation incorrectly threw an HTTP status code 500 Internal Server Error when a symbolic period was specified within the dateRange object. Support was added to allow specifying a symbolic period. (PS-175824)
  • Enhanced the following API endpoints to accept or return the positions object reference when the Multiple Positions feature switch is enabled. The Fill Open Shifts API operation also now accepts an employeePositions object in the request payload as part of Multiple Positions support. (PS-162553)
  • Enhanced the response model of the Retrieve Attestation Daily Details (POST /v1/timekeeping/attestation/multi_read) API operation with the createdByUser object reference, which refers to the user who created the attestation process. (PS-180783)
  • Enhanced the request payload of the Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) API operation with the customFields array, which allows you to specify custom fields to return in the response. (PS-179659)
  • Enhanced the following API operations with a position object reference in the request payload and response body that only appears or is applicable when the Multiple Assignments feature is enabled. (DIM-591444)
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation incorrectly threw an HTTP status code 500 Internal Server Error when a infinite base wage was passed for the hourlyRate property. (PS-177949)
  • The Execute Hyperfind Query (POST /v1/commons/hyperfind/execute) API operation incorrectly threw an HTTP status code 500 Internal Server Error when pagination was enabled and no employees were returned in the result set. (PS-177864)
  • Enhanced the Create Rule Set (POST /v1/scheduling/schedule_rule_sets) and Update Rule Set by ID (PUT /v1/scheduling/schedule_rule_sets/{ruleSetId}) API operations to support Employee Rule Sets. (PS-175466)
  • The Developer Hub documentation for the Update Timecard as Manager (POST /v1/timekeeping/timecard) API operation ommitted the sourceTransfer and targetTransfer properties within the moveAmounts object in the request model. (PS-216322)
  • The Update Timecard as Manager (POST /v1/timekeeping/timecard) API operation incorrectly threw an HTTP status code 500 Internal Server Error when specifying a labor category transfer without an explicit job transfer and the specified date was prior to the employee's primary job effective date. (PS-208180)
  • In some cases, the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation did not return the correct response data when the FTPTDATA_ALL option was specified. (PS-178031)

2023.R2.1

The following changes were made to the API and Developer Hub in 2023.R2.1.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation stopped successfully updating certain Activity-related properties due to new, incompatible defaults for the affected properties. The "Enable Effective dated Defaults and Idle percentage allocation" setting has been introduced with a default value of false, which resolves the error. If the setting is set to true, the old behavior is enforced. (PS-173424)
  • When the Retrieve Activity Shifts (POST /v1/work/activity_shifts/multi_read) API operation was used with the SEGMENTS_WITH_TOTALS option, it incorrectly returned only whole hour amounts instead of the amounts reflected in the Timecard and reports. (PS-169312)
  • The Developer Hub entry for the Retrieve Labor Tasks by Name and Department (GET /v2/forecasting/tasks) API operation incorrectly documented an ability to retrieve all labor tasks if no query parameters were specified. The documentation has been updated to correctly describe the operation's behavior, which requires query parameters to be passed. (PS-175191)
  • When delete actions were included in the request payload, the Import Labor Standards, Tasks, and Task Groups (POST /v2/forecasting/labor_standard_tasks/import) API operation returned HTTP status code 200 but, in some cases, did not delete all of the specified entities. (PS-172054)
  • When passing multiple locations in the request payload, the Import Volume Forecast (POST /v2/forecasting/volume_forecast/import) API operation sometimes returned an incorrect error message. The incorrect error message was: "Provided categories should belong to same parent category per given date span." The corrected error message is: "The categories must be in the same organizational node as the parent site for the date span. Only one site is allowed for each request." (PS-169237)
  • The Developer Hub documentation for the following API operations did not display the correct response model: (PS-168714)
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation returned an unhelpful error message when bad data was passed in the request payload for the license type object. (PS-176303)
  • The Modify Assignments for Multiple People (POST /v1/commons/persons/assignments/multi_upsert) API operation threw a Null Pointer Exception instead of a validation error when Attendance Profile Name was omitted from the request payload of certain calls. (PS-169052)
  • The Update Multiple Persons (POST /v1/commons/persons/multi_update) API operation incorrectly threw an HTTP status code 500 'Internal Server Error' when NaN was passed as the Base Wage in the request payload. (PS-169022)
  • The Retrieve Photos for Multiple Employees (POST /v1/commons/persons/profile_photos/multi_read) API operation would not allow a logged-in employee with the correct permssions to retrieve their own photo unless that employee had the Manager role. (PS-166635)
  • Improved performance of the Retrieve Data (POST /v1/commons/data/multi_read) API operation, which sometimes timed out when aggregating Timecard Attestation data. (PS-165757)
  • Improved cache handling of the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation to prevent unexpected transaction assistant errors, especially when called by an integration. (PS-162306)
  • The Developer Hub documentation for the Update Generic Job by ID (POST /v1/commons/jobs/{jobId}) API operation did not display the correct request model. (PS-173316)
  • The Retrieve Schedule (POST /v1/scheduling/schedule/multi_read) API operation failed when both symbolic periods and Hyperfind queries were included in the request payload and the excludeOvernightShiftsOnStartDate boolean was set to true. (PS-173178)
  • Under certain circumstances, the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation produced an incorrect schedule after a schedule group update. (PS-172769)
  • Enhanced the performance of the Retrieve Timecard as Manager (GET /v1/timekeeping/timecard) API operation. (PS-171426)
  • The Retrieve Data (POST /v1/commons/data/multi_read) API operation was unable to filter response data on the SCH_SCHEDULE_EVENT_CALENDAR_DATE Data Dictionary key. (PS-171045)
  • Enhanced the Retrieve Employee Schedule Changes (POST /v1/scheduling/schedule/changes/multi_read) API operation's Developer Hub documentation to explain that startDateTime and endDateTime values are always evaluated using UTC. (PS-167556)
  • The Bulk Create or Update Workload Patterns (POST /v1/scheduling/workload_patterns/multi_upsert) API operation returned an unhelpful error message when duplicate properties were present in the request payload. (PS-167026)
  • The Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create) API operation returned an incorrect error message when the pattern template reference in the request payload did not match any pattern templates in the system. (PS-167012)
  • The Retrieve Schedule Audits (POST /v1/scheduling/audits/multi_read) API operation failed to return any audit data when a Skill Certification Profile was not found for any reference in the request payload. The API now gracefully handles such requests and returns audit data. (PS-166929)
  • Enhanced the performance of the Post or Unpost Schedule (POST /v1/scheduling/schedule_management_actions/apply_update) API operation. (PS-154585)
  • In rare cases, the data returned by the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation did not apply an adjustment rule to a payrate consistent with the full precision of the adjusted rate in the timecard. (PS-176442)
  • The Update Timecard as Manager (POST /v1/timekeeping/timecard) API operation sometimes returned an incorrect error message. The incorrect error message was: "For duration paycode edit, amount value must be blank." The corrected error message is: "For duration paycode edit, amount is not a valid input; you must enter a symbolic value or an In time and Out time." (PS-176298)
  • In rare cases, the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation did not return all historical corrections in the specified timeframe. (PS-175430)
  • Under certain specific circumstances, the Retrieve Timecard as Manager (GET /v1/timekeeping/timecard) API operation returned employees with a totalizationStatus of require_totalization even when those employees were already totalized. (PS-174935)
  • The Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) API operation returned all employees regardless of date range and active or terminated status within the range. The operation now returns only active employees within the specified date range. (PS-174851)
  • Enhanced the performance of the Update Attestation Profile Assignments by Person Number (POST /v1/commons/persons/attestation_profile_assignments/multi_update) API operation. (PS-163193)
  • The Developer Hub entry for the Retrieve Payroll Staging Asynchronous Request Status by ID (GET /v1/commons/payroll/staging/{requestId}/status) API operation did not describe all possible statuses in the response. (PS-165901)
  • The following API operations did not return the proper array of validated punches when validateAsTimestamp was set to true: (PS-166119)
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation did not throw an error when the order for a position was not passed as 1 but Is Primary was set to true. (PS-166695)
  • The Developer Hub entry for the Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) API operation included an incorrect dateRange object in the request schema. (PS-167088)
  • The Export Small Batch Payroll (POST /v1/commons/payroll/export) and the Export Payroll Asynchronously (POST /v1/commons/payroll/export/async) API operations returned an unhelpful error message when tables were not defined after data was refreshed. (PS-167455)
  • The Apply Updates to Accrual Balances for Multiple Employees (POST /v1/timekeeping/accruals/updates) API operation sometimes returned an incorrect accrual code name in the response. (PS-167703)
  • In some cases, the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation did not return combined pay codes. (PS-173993)
  • The Retrieve Pay Period Timespans (GET /v1/commons/pay_period) API operation incorrectly threw an error when a default tenant timezone was not set. (PS-173800)
  • The Retrieve Pay Period Timespans (GET /v1/commons/pay_period) API operation returned an incorrect spanStartDate and spanEndDate. (PS-173169)
  • The Retrieve Data (POST /v1/commons/data/multi_read) API operation returned incorrect data in the response when calling Timecard Export data. (PS-171409)
  • The Update Timecard as Manager (POST /v1/timekeeping/timecard) API operation returned an HTTP status code 500 Internal Server Error in certain situations when the required id property was omitted. (PS-170319)
  • The Update Cost Centers (POST /v1/commons/cost_centers/multi_update) API operation returned an unhelpful error message when updating LaborCategoryEntry (including CostCenter) and the version was omitted from the request payload. (PS-168345)
  • The following API operations have been enhanced with the new properties employmentName and employmentLink, which are used only when the multipleemployments feature switch is enabled: (DIM-612917)
  • The following API operations have been enhanced with the new properties positionAccrualProfile and positionCascadeProfile, which are used only when the Multiple Assignments feature switch is enabled: (DIM-602846)
  • The following API operations have been enhanced with the new property positionAware, which is used only when the Multiple Assignments feature switch is enabled: (DIM-591392, DIM-612980)
  • The following Persons API operations have been enhanced with positionFullTimeEquivalencies assignments, with the accrualProfileAssignments object, which are used only when the Multiple Assignments feature switch is enabled, with the new property cascadingProfile in the positionDetails object, with the new Boolean property accountLocked, and with the optional, effective-dated property hrPositionCodes,: (DIM-591416, DIM-600215, DIM-591408, DIM-605844, DIM-571113)
  • The following API operations have been enhanced with the new custom tile type PERSONINSIGHTS and to support multiple URLs on a custom tile: (DIM-564810, DIM-614798)
  • The following API operations have been enhanced with the new Boolean properties shiftMovedSameDay and shiftMovedDifferentDay: (DIM-584957)
  • The following API operations have enhanced the Absence Calendar with the new availabilityItems object and the new properties dataView, selectedDataViewColumnNameAliasPairs, maxDataViewColumnsAmount, absenceCalendarItems, absenceCalendarLabel, availabilityTypes, and the Boolean showTeamAbsenceDetails: (PS-165708, DIM-567194, DIM-587957)
  • Enhanced the Retrieve Current User (GET /v1/commons/persons/current_user_info) API operation with the include_contact_information query parameter. (DIM-572423)
  • Enhanced the Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) API operation with the new properties includeCommentsForPayCodes and includeCommentsForPayCodes. (DIM-590904)
  • Enhanced the Employee Cover Requests and Manager Cover Requests API resources to include backwards-compatible support for the Multiple Assignments feature. (DIM-581584)
  • Enhanced all operations against the Coverage Counting Profiles API resource with the new property excludedSegmentTags. The property indicates whether or not to exclude segment tags that are added to shift segments; those hours are not counted towards the coverage. (WFD-169822)
  • Enhanced the following API operations with the Boolean property includeUnprocessedPaycodeEdits, which applies only when the select property is PAYCODE_EDITS: (WFD-171278)
  • The Create or Update Wage and Work Rule Overrides (POST /v1/commons/persons/wage_work_rules/multi_upsert) API operation threw an HTTP status code 500 Internal Server Error when the specified Job expired prior to the wage and work rules effective date. Additional validation has been added and the API now returns a useful error message. (PS-169707)
  • Enhanced the following API operations to support the Multiple Assignments feature: (DIM-566397)
  • Enhanced the following API operations with the ability to perform schedule eule overrides on the parameter Break Length Threshold of the rule Shifts Conform to Break Rules. The display of this new parameter is controlled by the Enable Break Length Threshold rule parameter feature switch. (DIM-570273, DIM-570272)
  • Added the feature switch scheduling.shift.delete.verifyOrgMaps to control validation of all shift segment jobs or transfer jobs for the following API operations: (PS-169436)
  • Enhanced the following API operations with two new response properties: coverageDetails and otherRequestorsSortingProcedureSet. (DIM-568339)

R9 Update 4

The following changes were made to the API and Developer Hub in R9 Update 4.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Retrieve Historical Net Changes for Activity Shifts (POST /v1/work/activity_shifts/historical_net_changes/multi_read) API operation displayed an incorrect request and response model on the Developer Hub. (WFD-165763)
  • The Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation always returned activity segments with a dayDivideState property value of 0 - No Day Divide even when an activity spanned a day divide. (WFD-161148)
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation logged a generic 'Internal server error' error message in the Transaction Assistant when the preserveTrackingStatus property was passed as true in the personInformation.accessAssignment object while either not providing or providing an invalid timeEntryTypeName property. The error message now identifies the API call and the missing or invalid property. (WFD-160910)
  • Improved performance of the Retrieve Data (POST /v1/commons/data/multi_read) API operation, which sometimes timed out when aggregating Attendance data. (WFD-159197)
  • The Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation incorrectly included a fingerScan object in the response model on the Developer Hub. (WFD-161448)
  • The Retrieve Schedule (POST /v1/scheduling/schedule/multi_read) API operation incorrectly returned the following error: 'cannot execute UPDATE in a read-only transaction'. (WFD-147805)
  • The Retrieve All Assignments for Multiple People (POST /v1/commons/persons/assignments/multi_read) API operation incorrectly returned an error when attempting to retrieve JobPreferences. (WFD-165001)
  • Under certain conditions, the Modify Assignments for Multiple People (POST /v1/commons/persons/assignments/multi_upsert) API operation threw an 'Internal server error'. (WFD-162464)
  • The Apply Updates to Accrual Balances for Multiple Employees (POST /v1/timekeeping/accruals/updates) API operation threw an HTTP status code 403 error and invalid error response details when a future-dated TERMINATED ONLY EMPLOYEE was included in the request payload. (WFD-165045)
  • The Bulk Import Paycode Edits (POST /v1/timekeeping/pay_code_edits/import) API operation incorrectly accepted combined paycodes in the request payload which generated a Callable Totalizer error. This operation now throws a descriptive error when combined paycodes are included in the request payload. (WFD-166217)
  • Under certain conditions, the Retrieve Employee Visibility Periods (POST /v1/scheduling/setup/employee_visibility_periods/multi_read) API operation failed to return the employeesHyperFindPeriods object in the response body when it should have been present. (WFD-152578)
  • The Retrieve Locations (POST /v1/commons/locations/multi_read) API operation did not accept a qualifier as an identifer for locationRef. This operation now takes a qualifier for locationRef, but note that you must also pass a revisionDate when qualifier is used to identify a location. (WFD-157694)
  • Under certain conditions, the Retrieve Locations (POST /v1/commons/locations/multi_read) API operation did not return up-to-date cost center information when that information had been recently updated. (WFD-157486)
  • Enhanced the WFM Foundations topic by clarifying the behavior of effective and expiration dates. (WFD-156038)
  • Under certain conditions, the Create or Update Generic Data Access Profiles (POST /v1/commons/generic_data_access_profiles/apply_upsert) API operation failed to save valid updates and threw errors. (WFD-154468)
  • The Retrieve Sorted or Eligible Employees (POST /v1/scheduling/staffing_assistant/apply_read) API operation sometimes timed out when includeTransferEmployees was passed as true. (WFD-157122)
  • The following API operations incorrectly threw errors when the Multiple Start Days per Week (MSDW) feature was enabled: (Note: the deprecated V1 versions of these operations were not updated with this fix. We recommend you update your implementations to utilize version 2 operations as they provide better security, performance, and functionality.) (WFD-164673)
    • Retrieve Forecast Week Start Day by ID (GET /v2/forecasting/forecast_week/start_day)
    • Retrieve Forecast Week Start Days (POST /v2/forecasting/forecast_week/start_days)
  • The Retrieve Labor Standards (POST /v1/forecasting/labor_standards/multi_read) API operation returned start and end dates that were inconsistent with the dates presented in the UI. (WFD-162689)
  • Enhanced the Retrieve Labor Standards (POST /v1/forecasting/labor_standards/multi_read) API operation to accept only labor standard IDs in the request payload. Previously the associated generic departments were also required. (WFD-160020)
  • Under certain conditions and as part of very large data transactions, the Retrieve Data (POST /v1/commons/data/multi_read) API operation threw a null pointer exception or timed out. (WFD-163042)
  • Under certain conditions, the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation timed out or took a very long time to return a response. (WFD-164330)
  • The Retrieve Locale Date Span (POST /v1/commons/symbolicperiod/read) API operation returned an incorrect error message when the caller specified more than one mutually exclusive properties in the request payload. (WFD-164157)
  • The Modify Assignments for Multiple People (POST /v1/commons/persons/assignments/multi_upsert) API operation incorrectly listed the service limit as 400 instead of the correct value, 200, in the Developer Hub. (WFD-163650)
  • The Send Notification by ID (POST /v1/platform/messaging/generic_notifications/{id}/notify) API operation stopped and did not send any email notifications if the request contained an inactive employee. An error is now logged instead of the API throwing an exception when the operation encounters inactive employees in the recipients list. (WFD-162036)
  • The Retrieve Generic Data Access Profiles (POST /v1/commons/generic_data_access_profiles/multi_read) API operation did not show the correct request payload model in the Developer Hub. (WFD-159659)
  • The Create and Assign Adjustment Rule Version by ID (POST /v1/timekeeping/setup/adjustment_rules/{id}) API operation did not correctly apply the reporting service limit of 365 days, which caused time outs and performance issues when multi-year spans were passed. (WFD-159221)
  • Updated the documentation for the following API operations to indicate that they take the accept-translation header: (WFD-157549)
    • Retrieve Accrual Codes (GET /v1/timekeeping/setup/accrual_codes)
    • Retrieve Accrual Codes by ID (GET /v1/timekeeping/setup/accrual_codes/{id})
    • Retrieve Timecard Add-On Columns (GET /v1/timekeeping/setup/timecard_addon_columns)
    • Retrieve Bonus and Deduction Rules (GET /v1/timekeeping/setup/deduct_rules)
    • Retrieve Bonus or Deduction Rule by ID (GET /v1/timekeeping/setup/deduct_rules/{id})
    • Retrieve Break Rules (GET /v1/timekeeping/setup/break_rules)
    • Retrieve Break Rule by ID (GET /v1/timekeeping/setup/break_rules/{id})
    • Retrieve Comments (GET /v1/commons/comments)
    • Retrieve Comments as Employee (GET /v1/commons/comments/employee_comments)
    • Retrieve All Mapping Category Types or by Name (GET /v1/platform/analytics/mapping_category_types)
    • Retrieve Mapping Category Type by ID (GET /v1/platform/analytics/mapping_category_types/{id})
    • Retrieve Paycode by ID as Manager (GET /v1/timekeeping/setup/pay_codes/{id})
    • Retrieve Paycodes—Manager (GET /v1/timekeeping/setup/pay_codes)
    • Retrieve Full Paycode by ID—Manager (GET /v1/timekeeping/setup/paycodes/{id})
    • Retrieve Full Paycodes—Manager (GET /v1/timekeeping/setup/paycodes)
    • Retrieve Paycodes—Employee (GET /v1/timekeeping/setup/employee_pay_codes)
    • Retrieve Paycode by ID—Employee (GET /v1/timekeeping/setup/employee_pay_codes/{id})
    • Retrieve Paycodes (POST /v1/timekeeping/setup/pay_codes/multi_read)
    • Retrieve Work Rules—Manager (GET /v1/timekeeping/setup/work_rules)
    • Retrieve Work Rule by ID—Manager (GET /v1/timekeeping/setup/work_rules/{id})
    • Retrieve Work Rule by ID—Employee (GET /v1/timekeeping/setup/employee_work_rules/{id})
    • Retrieve Work Rules—Employee (GET /v1/timekeeping/setup/employee_work_rules)
  • The Execute Hyperfind Query (POST /v1/commons/hyperfind/execute) API operation did not return re-hired employees accurately when the date range specified in the request payload overlapped with the terminated-and-rehired timeframe. (WFD-157022)
  • The Create Employee Time Off Request (POST /v1/scheduling/employee_timeoff) API operation returned an overly verbose rendering of the JSON object in an error response rather than simply specifying the name of the incorrect qualifier. (WFD-166589)
  • The Retrieve Staffing Matrices (POST /v1/scheduling/staffing_matrices/multi_read) API operation returned an overly verbose rendering of the JSON object in an error response rather than simply specifying the name of the incorrect qualifier. (WFD-165872)
  • Under certain circumstances, the Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create) API operation returned a vague and unhelpful error message. (WFD-164945)
  • The Retrieve Schedule (POST /v1/scheduling/schedule/multi_read) API operation failed when the excludeOvernightShiftsOnStartDate property was set to true and the request payload also referenced a symbolic period. (WFD-164603)
  • The Retrieve Data (POST /v1/commons/data/multi_read) API operation would occasionally return a floating point value instead of an integer for 'PayPeriodWeek' under Data Dictionary key 'TK_ACTUAL_PAYPERIOD_WEEK'. (WFD-158389)
  • The Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation threw an HTTP status code 500 error when importing employee records with an expired or undefined end date in any node in the job organizational path. Now, the API throws an HTTP status code 400 error and supports partial success. (WFD-160589)
  • Certain multi_read API operations, such as Retrieve Persons (POST /v1/commons/persons/extensions/multi_read), return wage information despite wage access not being enabled in the calling user's FAP. A new ACP, HIDE_WAGES, has been added that defaults to disabled. When enabled, these API operations do not return wage information. (WFD-145461, WFD-154043)
  • The Retrieve Location Profiles Option Set Assignments (POST /v1/scheduling/location_profiles_option_set/assignments/multi_read) and Retrieve All Location Profiles Option Sets or by Name (GET /v1/scheduling/location_profiles_option_set) API operations only returned a 'null' value for each Procedure's qualifier property. (WFD-162611)
  • The Update Multiple Persons (POST /v1/commons/persons/multi_update) and Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operations returned an HTTP status code 200 success response but failed to update the professionalShiftCodeName, also known as the Shift Template Profile. (WFD-160756)
  • The Create Employment Term Schedule Pattern (POST /v1/scheduling/employment_term_schedule_patterns/apply_create) API operation returned a vague and unhelpful error message when the mandatory startDate property was omitted from the request payload. (WFD-156848)
  • The Retrieve Pay Period Timespans (GET /v1/commons/pay_period) API operation would incorrectly throw an error when valid pay periods existed and should have been returned in the response. (WFD-156839)
  • The Update Timecard as Manager (POST /v1/timekeeping/timecard) API operation threw an HTTP status code 500 Internal Server Error when an invalid Labor Category string was passed in the request payload. The operation now throws the correct HTTP status code 400 error. (WFD-160831)
  • The Retrieve Absence Spans (POST /v1/timekeeping/absence_spans/multi_read) API operation did not properly filter spans from the response and, as a result, unexpected spans were being returned in response data. (WFD-161227)

R9 Update 3

The following changes were made to the API and Developer Hub in R9 Update 3.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • Enhanced the following API operations such that, when the Use Shift Start Times feature is enabled, the 'Use Shift Start Times' (ERPARAM_USE_SHIFT_START_TIMES) option is available as a ruleParameterType. (DIM-469577)
    • Retrieve Schedule with Criterion (GET /v1/scheduling/schedule)
    • Retrieve Rule Sets (POST /v1/scheduling/schedule_rule_sets/multi_read)
    • Retrieve All Schedule Rules or by Name (GET /v1/scheduling/schedule_rules)
    • Retrieve Schedule Rule by ID (GET /v1/scheduling/schedule_rules/{id})
    • Retrieve Schedule Rules (POST /v1/scheduling/schedule_rules/multi_read)
    • Retrieve All Schedule Rule Overrides or by Person Number (GET /v2/commons/persons/schedule_rule_overrides)
    • Retrieve Schedule Rule Overrides (Deprecated) (POST /v1/commons/persons/schedule_rule_overrides/multi_read)
    • Create Schedule Rule Overrides (POST /v1/commons/persons/schedule_rule_overrides/multi_create)
    • Create Schedule Rule Override (POST /v1/commons/persons/schedule_rule_overrides)
    • Update Schedule Rule Override (PUT /v1/commons/persons/schedule_rule_overrides)
    • Retrieve All Schedule Rule Overrides or by Person Number (Deprecated) (GET /v1/commons/persons/schedule_rule_overrides)
    • Retrieve Schedule Rule Overrides (POST /v2/commons/persons/schedule_rule_overrides/multi_read)
    • Retrieve Schedule Rule Override by ID (Deprecated) (GET /v1/commons/persons/schedule_rule_overrides/{person_id})
    • Retrieve Schedule Rule Override by ID (GET /v2/commons/persons/schedule_rule_overrides/{person_id})
    • Update Schedule Rule Overrides (POST /v1/commons/persons/schedule_rule_overrides/multi_upsert)
  • Enhanced the following API operations to return a detailed error message when the length of certificationNumber is greater than maximum allowed length. (WFD-155880)
    • Update Certification Assignments (POST /v1/commons/persons/certifications/multi_upsert)
    • Update Certification Assignment by ID (PUT /v1/commons/persons/certifications/{personId})
    • Modify Assignments for Multiple People (POST /v1/commons/persons/assignments/multi_upsert)
  • Enhanced the following API operations to support the markRelatedExceptionsAsReviewed boolean in the request payload and-or response body, as appropriate. (DIM-454191)
    • Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read)
    • Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read)
    • Update Timecard as Employee (POST /v1/timekeeping/employee_timecard)
    • Update Timecard as Manager (POST /v1/timekeeping/timecard)
    • Bulk Import Punches (POST /v1/timekeeping/punches/import)
  • Enhanced the following API operations with an automaticBreakPlacement response property for the following Request Subtypes: CoverRequestSubType, OpenShiftRequestSubType, SelfScheduleRequestSubType, and SwapRequestSubType. (WFD-153251)
    • Retrieve Request Subtype by Name (GET /v1/scheduling/setup/request_subtypes)
    • Retrieve Request Subtypes (POST /v1/scheduling/setup/request_subtypes/multi_read)
    • Retrieve Request Subtype by ID (GET /v1/scheduling/setup/request_subtypes/{id})
  • Deprecated the following two API operations: (WFD-155228)
    • Retrieve Report History (GET /v1/platform/scheduled_reports) is deprecated and has been replaced by Retrieve Report History by Criteria (POST /v1/platform/scheduled_reports/apply_read)
    • Retrieve Scheduled Report Requests (GET /v1/platform/report_executions) is deprecated and has been replaced by Retrieve Paginated List of Scheduled Report Requests (POST /v1/platform/report_executions/apply_read)
  • Enhanced the following API operations to change the validation of dayCount from a hard-coded value of 364 days to maximum defined in the setting com.kronos.scheduling.pattern.maximumpatternlength, schedule rollout days, and 364 days. (WFD-138351)
    • Create Schedule Pattern (POST /v1/scheduling/schedule_pattern_templates)
    • Create Schedule Patterns (POST /v1/scheduling/schedule_pattern_templates/multi_create)
    • Update Schedule Pattern by Name (PUT /v1/scheduling/schedule_pattern_templates)
    • Update Schedule Patterns (PUT /v1/scheduling/schedule_pattern_templates/multi_update)
    • Update Schedule Pattern by ID (PUT /v1/scheduling/schedule_pattern_templates/{id})
  • The following API operations have been corrected to ensure the API returns an HTTP status code 400 error response instead of an HTTP status code 200 success response when using preview mode for a paycode edit creation operation on a locked day: (WFD-155130)
    • Create Paycode Edits with Options (Deprecated) (POST /v1/scheduling/schedule/pay_code_edits/import)
    • Create Paycode Edits with Options (POST /v1/scheduling/schedule/pay_code_edits/apply_import)
    • Create PCE with Options (POST /v1/scheduling/schedule/pay_code_edits/apply_create)
  • The Create or Update Wage and Work Rule Overrides (POST /v1/commons/persons/wage_work_rules/multi_upsert) API operation has been updated to throw an error when the employee-level Wage and Work Rule Override value is updated and the employee has multiple positions. (WFD-152261)
  • Enhanced the following Timecard API operations with a new ACP SA_PCE_WITH_HIDDEN_PAYCODES that, when applied, allows the caller to retrieve paycode edits with hidden paycodes. (WFD-147747)
    • Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read)
    • Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read)
    • Retrieve Timecard as Manager (GET /v1/timekeeping/timecard)
  • Enhanced the following API endpoints to accept or return the positions object reference when the Multiple Positions feature switch is enabled. When a position is not specified, the API defaults to the employee's primary assignment to ensure backwards compatibility. (DIM-57502)
    • /v1/scheduling/employee_open_shift_requests
    • /v1/scheduling/employee_open_shift_requests/{id}
    • /v1/scheduling/employee_open_shift_requests/multi_read
    • /v1/scheduling/employee_open_shift_requests/apply_update
    • /v1/scheduling/open_shift_requests/{id}
    • /v1/scheduling/open_shift_requests/apply_update
    • /v1/scheduling/open_shift_requests/similar_requests
    • /v1/scheduling/open_shift_requests/multi_read
    • /v1/scheduling/employee_self_schedule_requests
    • /v1/scheduling/employee_self_schedule_requests/{id}
    • /v1/scheduling/employee_self_schedule_requests/apply_update
    • /v1/scheduling/employee_self_schedule_requests/multi_read
    • /v1/scheduling/self_schedule_requests/multi_read
  • Enhanced the following API endpoints to add position_id and position_name as optional query parameters. When a position is not specified, the API defaults to the employee's primary assignment to ensure backwards compatibility. (DIM-57502)
    • /v1/scheduling/employee_open_shift_requests/open_shifts/multi_read
    • /v1/scheduling/employee_open_shift_requests/jobs?subtype_id={subtype_id}&subtype_name={subtype_name}&date={date}&position_id={position_id}&position_name={position_name}
    • /v1/scheduling/employee_open_shift_requests/employees?subtype_id={subtype_id}&subtype_name={subtype_name}&position_id={position_id}&position_name={position_name}
    • /v1/scheduling/employee_open_shift_requests/request_subtypes&position_id={position_id}&position_name={position_name}
    • /v1/scheduling/employee_open_shift_requests/submission_periods?subtype_id={subtype_id}&subtype_name={subtype_name}&position_id={position_id}&position_name={position_name}
    • /v1/scheduling/employee_self_schedule_requests/open_shifts/multi_read
    • /v1/scheduling/employee_self_schedule_requests/shift_templates/multi_read
    • /v1/scheduling/employee_self_schedule_requests/jobs?subtype_id={subtype_id}&subtype_name={subtype_name}&date={date}&position_id={position_id}&position_name={position_name}
    • /v1/scheduling/employee_self_schedule_requests/employees?subtype_id={subtype_id}&subtype_name={subtype_name}&position_id={position_id}&position_name={position_name}
    • /v1/scheduling/employee_self_schedule_requests/request_subtypes&position_id={position_id}&position_name={position_name}
    • /v1/scheduling/employee_self_schedule_requests/submission_periods?subtype_id={subtype_id}&subtype_name={subtype_name}&position_id={position_id}&position_name={position_name}
  • Enhanced the following Persons API operations with either an include_base_wages query parameter or includeBaseWages request payload property, as appropriate. (WFD-145461)
    • Retrieve Person by Extension (GET /v1/commons/persons/{extensionType}?person_number={personNumber}&&include_base_wages=true)
    • Retrieve All Extensions (GET /v1/commons/persons/extensions?person_number={personNumber}&&include_base_wages=true)
    • Retrieve Persons (POST /v1/commons/persons/extensions/multi_read)
  • Enhanced the Retrieve Generic Data Access Profiles (POST /v1/commons/generic_data_access_profiles/multi_read) API operation to return the following two boolean properties in the response, but only when the values are true: deleted, workRuleAssociated. (DIM-210188)
  • Enhanced the Update Timecard as Employee (POST /v1/timekeeping/employee_timecard) API operation to add support for a udmDevice object reference to the request payload. (DIM-450874)
  • Enhanced the Start Attestation Process (POST /v1/timekeeping/attestation_process) API operation with the managerAttestation boolean property in the request payload to support the new Manager Attestation feature. (DIM-459515)
  • Enhanced the Update Timecard Change Status (PUT /v1/timekeeping/timecard/changes/{id}) and the Update Timecard Change Statuses (POST /v1/timekeeping/timecard/changes/multi_update) API operations with the FAP 'Bypass permissions for approving pending timecard changes' which is located under 'Manager - Department Manager -> Timecard Editor for Managers' When enabled, managers who do not have the ability to approve Timecard Change Requests without the ability to edit the timecard itself are now able to execute these API operations. (DIM-435190)
  • Enhanced the Retrieve All Employment Terms (GET /v2/timekeeping/setup/employment_terms) and the Retrieve All Employment Terms (Deprecated) (GET /v1/timekeeping/setup/employment_terms) API operations with the version_dates boolean query parameter. When all_details is false and version_dates is true, the response returns all employment term version dates along with each lightweight employment term version. (WFD-148089)
  • Enhanced the Retrieve Schedule Scores (POST /v1/scheduling/schedule_score/multi_read) API operation's documentation with service limit details. (DIM-449104)
  • Enhanced the following Forecast Planner Settings API operations with a readOnlyVolumeDrivers object in the request and response models, which contains a list of non-editable volume drivers for the Forecast Planner. (DIM-413792)
    • Retrieve a Forecast Planner Setting by ID (GET /v1/forecasting/forecast_planner_settings/{id})
    • Retrieve All Forecast Planner Settings or by Name (GET /v1/forecasting/forecast_planner_settings)
    • Retrieve Forecast Planner Settings (POST /v1/forecasting/forecast_planner_settings/multi_read)
    • Create Forecast Planner Settings (POST /v1/forecasting/forecast_planner_settings/multi_create)
    • Create a Forecast Planner Setting (POST /v1/forecasting/forecast_planner_settings)
    • Update a Forecast Planner Setting by ID (PUT /v1/forecasting/forecast_planner_settings/{id})
    • Update Forecast Planner Settings (POST /v1/forecasting/forecast_planner_settings/multi_update)
  • Enhanced the Retrieve Locale Date Span (POST /v1/commons/symbolicperiod/read) API operation to accept id in the request payload. While symbolicPeriodId is a string value such as 'Next_SchedPeriod', id is the numeric ID of the symbolic period. (DIM-453968)
  • Enhanced all operations against the Adjustment Rules (/v1/commons/persons/adjustment_rule) and Attestation Profile Assignments (/v1/commons/persons/attestation_profile_assignments) API resources to include the following ACPs, which default to Allowed in existing environments to ensure backwards compatibility: EMPLOYEE_ASSIGNMENTS_EDIT and EMPLOYEE_ASSIGNMENTS_READ. (DIM-450953)
  • Enhanced the Retrieve Hours of Operation Assignments for One Location (GET /v1/commons/hours_operation_assignments) and the Retrieve Hours of Operation Assignments for Multiple Locations (POST /v1/commons/hours_operation_assignments/multi_read) API operations to return an overrideInherited boolean when the request payload contains a date span. (DIM-436665)
  • Enhanced the Update Multiple Persons (POST /v1/commons/persons/multi_update) and the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operations to include a preserveTrackingStatus boolean in the request payload that, when true, preserves the original Tracking Status value when the operation is executed without including any value for Tracking Status in the request payload. (WFD-150803)
  • Enhanced all API operations that accept the symbolicPeriod property in the request payload or the symbolic_period query parameter to include the MONTH_TO_DATE (Month to Date) symbolic time period. This period resolves to the first day of the month as the start date and the current calendar date as the end date. (DIM-450440)
  • Enhanced the following API operations with the automaticBreakPlacementForQuickActionsAndGlances boolean in the request payload and response body, which indicates whether or not to adjust breaks automatically for quick actions and glances in the Schedule Planner. (WFD-150215)
    • Retrieve Staffing Dashboard Settings by ID (GET /v1/scheduling/setup/staffing_dashboard_settings/{id})
    • Retrieve All Staffing Dashboard Settings or by Name (GET /v1/scheduling/setup/staffing_dashboard_settings?name={name})
    • Retrieve Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_read)
    • Update Staffing Dashboard Settings by ID (PUT /v1/scheduling/setup/staffing_dashboard_settings/{id})
    • Update Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_update)
    • Create Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings)
    • Create Multiple Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_create)
  • Enhanced the following API operations to include the professionalShiftCodeName property in the request payload and response body, as appropriate. This property contains the name of the shift template profile that is assigned to a position. This update also introduces the following two ACPs to control access to the new property: POSITIONS_GENERAL_VIEW and SCHEDULER_MANAGER_ROLE_VIEW. (DIM-420375)
    • Retrieve Person by ID (GET /v1/commons/persons/{personId})
    • Create Person (POST /v1/commons/persons)
    • Update Person by ID (PUT /v1/commons/persons/{personId})
    • Create Multiple Persons (POST /v1/commons/persons/multi_create)
    • Create or Update Persons (POST /v1/commons/persons/multi_upsert)
    • Update Multiple Persons (POST /v1/commons/persons/multi_update)
  • The Retrieve Comments as Manager (GET /v1/commons/comments) API operation did not always refresh cached values after an import, resulting in delays when attempting to retrieve translated values. (WFD-154816)
  • Improved performance of the Update Average Pay Rate Sets (POST /v1/commons/average_pay_rate_sets/multi_update) API operation, which sometimes timed out and returned an HTTP status code 504 error. (WFD-154758)
  • The superuser account could not delete terminated employees by using the Delete Person by ID (DELETE /v1/commons/persons/{personId}) API operation. A condition was added that finds inactive and terminated employees outside of the current pay period and allows the API to delete the terminated employees. (WFD-154391)
  • The Accrual Balance Reset integration failed because the Retrieve Base Person (POST /v1/commons/persons/base_persons/multi_read) API operation did not always honor the onlyActivePerson boolean property. (WFD-127600)
  • The Retrieve Target Thresholds (POST /v1/platform/target_thresholds/multi_read) API operation did not contain a correct request payload in the Developer Hub. (WFD-153927)
  • The Create Leave Edits (POST /v1/leave/leave_edits) API operation did not correctly add comments even when correctly specified in the request payload. (WFD-155687)
  • The Update Batch Task by ID (PUT /v1/platform/batch_processing/batch_tasks/{id}) API operation did not recognize backslash as an escape character in the request payload. (WFD-156139)
  • The Submit Business Process Form Data (POST /v1/platform/workflow/business_processes/tasks/forms) API operation did not correctly process integer offsets and threw an error when they were specified in the request payload. (WFD-149395)
  • Updated the Retrieve Employee Schedule Changes (POST /v1/scheduling/schedule/changes/multi_read) Developer Hub documentation to include the service limit. (WFD-156335)
  • The Update Manager Role Assignments (POST /v1/commons/persons/manager_role_assignments/multi_update) API operation sometimes returned an HTTP status code 500 Internal Server Error when attempting to update role assignments. (WFD-155918)
  • Enhanced Labor Standards create and update API operations with validation that ensures labor standards have a version that starts at the Beginning of Time (1900-01-01). (WFD-149343)

R9 Update 2

The following changes were made to the API and Developer Hub in R9 Update 2.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Retrieve Adjustment Rules (GET /v1/timekeeping/setup/adjustment_rules) API operation was enhanced to add an all_details query parameter that allows you to specify if you want to retrieve all details of the returned adjustment rules or only the ID and name. Defaults to true to preserve backwards compatibility. (WFD-149840)
  • Enhanced the following API operations with an optional asOfDate request property. When asOfDate is specified, the borrow and lender jobs in the group are validated against the specified date. When asOfDate is null or absent, it defaults to today's date. (WFD-150876)
    • Create Labor Distribution Group (POST /v1/forecasting/labor_distribution_groups)
    • Update Labor Distribution Group by ID (PUT /v1/forecasting/labor_distribution_groups/{id})
    • Create Labor Distribution Groups (POST /v1/forecasting/labor_distribution_groups/multi_create)
    • Update Labor Distribution Groups (POST /v1/forecasting/labor_distribution_groups/multi_update)
  • Enhanced the following API operations with two new Access Control Points (ACPs) that allow you to disable an employee or a manager's ability to select an employee's assignments on the employee's timecard. The new ACPs default to disallowed, which preserves the existing behavior (and allows employees and managers to select employee assignments). The ACP keys are EA_DISABLE_POSITION_SELECTION (employee) and SA_DISABLE_POSITION_SELECTION (manager). (DIM-434743)
    • Update Timecard as Employee (POST /v1/timekeeping/employee_timecard)
    • Update Timecard as Manager (POST /v1/timekeeping/timecard)
    • Bulk Import Paycode Edits (POST /v1/timekeeping/pay_code_edits/import)
    • Bulk Import Punches (POST /v1/timekeeping/punches/import)
    • Create Leave Edits (POST /v1/leave/leave_edits)
  • The following API operations have been corrected to prevent shifts from being assigned to non-job locations, which could create invalid shifts. (WFD-150938)
    • Create Shift (POST /v1/scheduling/schedule/shifts)
    • Create Shifts (POST /v1/scheduling/schedule/shifts/multi_create)
    • Create Shifts from Patterns (POST /v1/scheduling/schedule/shifts/apply_create)
    • Update Shift by ID (POST /v1/scheduling/schedule/shifts/{shiftId})
    • Update Shifts (POST /v1/scheduling/schedule/shifts/multi_update)
    • Update Shifts with Criteria (POST /v1/scheduling/schedule/shifts/apply_update)
    • Update Schedule (POST /v1/scheduling/schedule)
    • Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update)
  • Enhanced the following API operations with the fullAccess property, which is a Boolean indicator of whether or not all items in a particular category of a Setup Item are selected under a particular GDAP. (DIM-386348)
    • Create or Update Generic Data Access Profiles (POST /v1/commons/generic_data_access_profiles/apply_upsert)
    • Retrieve Generic Data Access Profiles (POST /v1/commons/generic_data_access_profiles/multi_read)
    • Retrieve Setup Category Available Items for Generic Data Access Profile (GET /v1/commons/generic_data_access_profiles/setup/gdap_items)
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) to add the position object reference and the uniqueId string in the response model. (DIM-430705)
  • Enhanced the following API operations with the genericLocationRef object reference in the response model. (DIM-428323)
    • Retrieve Location by Path (GET /v1/commons/locations)
    • Retrieve Locations (POST /v1/commons/locations/multi_read)
    • Retrieve Location by ID (GET /v1/commons/locations/{id})
  • Enhanced the Retrieve Adjustment Rules (GET /v1/timekeeping/setup/adjustment_rules) API operation to support adjustment rule versions. (DIM-434113)
  • Enhanced the Bulk Import Punches (POST /v1/timekeeping/punches/import) API operation with a device-id header that represents the unique ID associated with a device, such as a tablet. (DIM-406737)
  • Enhanced the Move Location (POST /v1/commons/locations/apply_update) API operation with an undoMove object that allows you to undo a previous move applied to a given node over a date range. (DIM-420106)
  • Enhanced the Retrieve Net Changes for Activity Shifts (POST /v1/work/activity_shifts/net_changes/multi_read) API operation to include a location object reference with the activity totals. (WFD-149031)
  • Enhanced the following API operations with a managerSchoolCalendarProfile object in the response model: (WFD-147286)
    • Retrieve All Assignments by Person ID (GET /v1/commons/persons/assignments/{id})
    • Retrieve All Assignment Names (GET /v1/commons/persons/assignments/names)
    • Retrieve All Assignments for Multiple People (POST /v1/commons/persons/assignments/multi_read)
    • Retrieve All Assignments by Criteria (GET /v1/commons/persons/assignments)
    • Modify Assignments for Multiple People (POST /v1/commons/persons/assignments/multi_upsert)
  • Enhanced the Retrieve Activity Shifts (POST /v1/work/activity_shifts/multi_read) API operation with two new select options: SEGMENTS_WITH_TOTALS and SEGMENTS_WITH_RESULTS_AND_TOTALS. (WFD-149039)
  • Enhanced the following API operations to support bonus deductions and the add/deduct action: (DIM-413004)
    • Retrieve All Activity Actions or by Name (GET /v1/work/pay_code_actions)
    • Create Activity Action (POST /v1/work/pay_code_actions)
    • Update Activity Action by ID (PUT /v1/work/pay_code_actions/{id})
    • Delete Activity Action by ID (DELETE /v1/work/pay_code_actions/{id})
    • Retrieve Activity Actions (POST /v1/work/pay_code_actions/multi_read)
    • Create Activity Actions (POST /v1/work/pay_code_actions/multi_create)
    • Update Activity Actions (POST /v1/work/pay_code_actions/multi_update)
    • Delete Activity Actions (DELETE /v1/work/pay_code_actions/multi_delete)
  • Enhanced the following API operations to accept or return the positions object reference when the Multiple Positions feature switch is enabled. (DIM-414931)
    • Retrieve Shift Swap Request by ID as Manager (GET /v1/scheduling/manager_swap/{swapRequestId})
    • Retrieve Rule Violations for Shift Swap Request (POST /v1/scheduling/manager_swap/apply_read)
    • Retrieve Shift Swap Requests as Manager (POST /v1/scheduling/manager_swap/multi_read)
    • Retrieve Shift Swap Request by ID (GET /v1/scheduling/employee_swap/{swapRequestId})
    • Retrieve Shift Swap Request Information (POST /v1/scheduling/employee_swap/apply_read)
    • Retrieve Shift Swap Requests (POST /v1/scheduling/employee_swap/multi_read)
  • Enhanced the Retrieve Work Unit Hyperfinds (GET /v1/hca/work_unit_hyperfinds) API operation to return standard as well as custom Work Unit Hyperfinds by adding optional type and work_unit_details query parameters. (DIM-414165)
  • Enhanced the Schedule Integration by ID (POST /v1/platform/integrations/{id}/schedule) API operation to return the scheduleId property in the response model. (DIM-425001)
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation to return the absenceExceptionsWithPosition array in the response model when the Multiple Positions feature switch is enabled. (WFD-146569)
  • Enhanced the following API operations with a new select option: SCHEDULED_TOTALS. (WFD-133468)
    • Retrieve Timecard as Manager (GET /v1/timekeeping/timecard)
    • Retrieve Timecard as Employee (GET /v1/timekeeping/employee_timecard)
    • Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read)
    • Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read)
  • Enhanced the Retrieve Locations (POST /v1/commons/locations/multi_read) API operation with the ancestorsOfDuring object. Previously only the ancestorsOf property was available, which returns ancestors of a node for a specific date. The new property allows you to specify a date range. (DIM-421380)
  • Enhanced the following API operations with the following optional properties: scheduleGroupAssignments in the jobAssignment object of the request payload, employmentTermAssignmentSpan and scheduleGroupAssignmentSpan in the jobAssignment and positions objects, and removeFromOtherGroups in the scheduleGroupAssignments object (where it already exists as part of positions). (DIM-413097)
    • Retrieve Person by ID (GET /v1/commons/persons/{personId})
    • Create Person (POST /v1/commons/persons)
    • Update Person by ID (PUT /v1/commons/persons/{personId})
    • Create Multiple Persons (POST /v1/commons/persons/multi_create)
    • Create or Update Persons (POST /v1/commons/persons/multi_upsert)
    • Update Multiple Persons (POST /v1/commons/persons/multi_update)
  • Enhanced the following API operations with a context_date query parameter or contextDate request property, as appropriate, to correct an issue when totals_roll_by is PERIOD_TO_DATE. (WFD-130735)
    • Retrieve Timecard as Manager (GET /v1/timekeeping/timecard)
    • Retrieve Timecard as Employee (GET /v1/timekeeping/employee_timecard)
    • Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read)
    • Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read)
  • Enhanced the following API operations to return a description string for labor categories in the response model: (DIM-400865)
    • Retrieve Hyperfind Query by ID (GET /v1/commons/hyperfind/{id}?all_details=true)
    • Retrieve Hyperfind Queries for Current User (GET /v1/commons/hyperfind/?all_details=true)
  • Enhanced the Retrieve Locations (POST /v1/commons/locations/multi_read) API operation with an includeInheritedCurrency Boolean within multiReadOptions that, when true, changes the logic of the currencyRef property in the response from only sending a value if a location has an explicitly set currency to always sending a value, and if a location's currency is inherited, it is resolved from the inheriting parent. (WFD-144579)
  • Enhanced the following API operations with a dataView object reference in the response model, which is present when the applicable user can see additional employee information in a tooltip in the Staffing Dashboard. (WFD-144583)
    • Retrieve Staffing Dashboard Settings by ID (GET /v1/scheduling/setup/staffing_dashboard_settings/{id})
    • Retrieve All Staffing Dashboard Settings or by Name (GET /v1/scheduling/setup/staffing_dashboard_settings)
    • Retrieve Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_read)
    • Update Staffing Dashboard Settings by ID (PUT /v1/scheduling/setup/staffing_dashboard_settings/{id})
    • Update Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_update)
    • Create Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings)
    • Create Multiple Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_create)
  • Enhanced the following Minor Rule Sets API operations with a maximumLegalAge property in the response model. (WFD-138572)
    • Retrieve Minor Rule by ID (GET /v1/scheduling/minor_rule_sets/{id})
    • Retrieve All Minor Rules or by Name (GET /v1/scheduling/minor_rule_sets)
    • Retrieve Minor Rules (POST /v1/scheduling/minor_rule_sets/multi_read)
  • Enhanced the Update Schedule (POST /v1/scheduling/schedule) and the Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update) API operations with a bypassPredictiveScheduling Boolean that allows the caller to bypass Predictive Scheduling logic and a new Access Control Point (ACP) that controls access to the bypassPredictiveScheduling Boolean: IGNORE_PREDICTIVE_SCHEDULING_PROCESSING. (WFD-136917)
  • Updated the Retrieve Integration Executions (POST /v1/platform/integration_executions/multi_read) API operation to display the full request payload model on the Developer Hub. (WFD-151838)
  • Updated the Evaluate Metrics for Scheduling (POST /v1/scheduling/schedule_metrics/multi_read) API operation to list the enumerations accepted by the SELECT property on the Developer Hub. (WFD-144568)
  • Updated the Retrieve All Work Rules (GET /v1/timekeeping/setup/full_work_rules) API operation to display the full response model on the Developer Hub. (WFD-151139)
  • Improved cache performance and logging for the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation to prevent a rare condition where incorrect errors could be returned. (WFD-144923)
  • The Bulk Accrual Payout (POST /v1/timekeeping/accruals/payouts) API operation returned an HTTP status code 500 Internal Server Error due to a null pointer exception. (WFD-144926)
  • The Create Employment Term (POST /v1/timekeeping/setup/employment_terms) API operation incorrectly converted percentages passed in the payload to seconds when viewed in the UI. (WFD-147198)
  • Improved performance of the Retrieve Data (POST /v1/commons/data/multi_read) API operation when returning results that include Timekeeping audit data. (WFD-148390)
  • Updated the Bulk Timecard Signoffs (POST /v1/timekeeping/signoffs/import) API operation to add missing HTTP status codes 207 and 403 and to include all possible error messages in error code details on the Developer Hub. (WFD-148917)
  • The Retrieve Comments as Manager (GET /v1/commons/comments) API operation did not return Comments for Super Access users. (WFD-148138)
  • Enhanced the Update Workload Weights or Update, Lock, or Unlock Workload Volumes (POST /v1/scheduling/volume/apply_update) API operation to process the location path as case insensitive. (WFD-152230)
  • Added the Delete Certification Assignments (POST /v1/commons/persons/certifications/apply_delete) API operation to address functionality available in the UI but missing in the API. (WFD-145284)
  • Improved performance for the following API operations to prevent possible timeouts when invoked from Activiti: (WFD-133410)
    • Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update)
    • Update Shift by ID (POST /v1/scheduling/schedule/shifts/{shiftid})
    • Delete Paycode Edits by ID (POST /v1/scheduling/schedule/pay_code_edits/multi_delete)
    • Create Paycode Edits (POST /v1/scheduling/schedule/pay_code_edits/multi_create)
    • Update Paycode Edits (POST /v1/scheduling/schedule/pay_code_edits/multi_update)
  • The Create or Update Result Codes (POST /v1/work/result_codes/multi_upsert) API operation incorrectly threw an HTTP status code 500 Internal Server Error when an existing result code name was passed in using a letter case that did not match the actual name's case. The API operation no longer treats result code names as case-sensitive. (WFD-147807)
  • Improved performance of the Update Volume Forecast (PUT /v1/forecasting/volume_forecast) API operation. (WFD-149319)
  • Under certain conditions, the Create or Update Hours of Operation Assignments (POST /v1/commons/hours_operation_assignments/multi_upsert) API operation threw an illegal state exception error. (WFD-148947)
  • The Machine Learning Models API operations were listed as released but were not actually accessible. (WFD-148813)
  • Enhanced the Update Task Groups (POST /v2/forecasting/task_groups/multi_update) API operation to increase the Number of Jobs Assigned to a Single Task Group service limit from 1,000 to 4,000. (WFD-146117)
  • The Create or Update Category Profile Assignment (PUT /v1/commons/persons/forecasting_category_profiles) and Update Category Profile Assignments (POST /v1/commons/persons/forecasting_category_profiles/multi_update) API operations did not correctly unassign Forecasting Category Profiles. (WFD-148619)
  • Updated the Retrieve Payroll Staging Asynchronous Request Status by ID (GET /v1/commons/payroll/staging/{requestId}/status) API operation to display the correct response model on the Developer Hub. (WFD-150129)
  • The Retrieve Payroll Export Asynchronous Response Payload by Key (GET /v1/commons/payroll/export/async/{executionKey}/response) API operation did not include the worked job in the response. (WFD-147787)
  • All of the Persons API operations, such as Update Multiple Persons (POST /v1/commons/persons/multi_update), that allow the caller to update a person's password stopped allowing password updates by means of the API. (WFD-149518)
  • Updated the Update Group Memberships for Multiple Employees (POST /v1/commons/persons/schedule_groups/multi_upsert) API operation to be case-sensitive, as Schedule Group names are case-sensitive. (WFD-147429)
  • Updated the Create Adjustment Rule (POST /v1/timekeeping/setup/adjustment_rules) API operation to use the same decimal precision as the UI. (WFD-151858)
  • Updated the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation to consider the WAGES Access Control Point (ACP) when returning wages in the response. ( WFD-151366)

Docs updates

The following changes were made to the conceptual documentation:

  • Updated the Certificate Assignments topic to include instructions for using the new Delete Certification Assignments (POST /v1/commons/persons/certifications/apply_delete) API operation.
  • Updated the Skill Assignments topic to include instructions for using the new Delete Skill Assignments (POST /v1/commons/persons/skills/apply_delete) API operation.
  • Updated the HTTP status codes topic to include more details about HTTP status code 413, which is returned for service limit violations and for request payload JSONs that exceed the size limit. By default, request payload JSONs are limited to 1 megabyte in size. Some operations allow for a larger request payload. The increased size is documented in the operation's description. For example, see the Import Labor Budgets (POST /v1/forecasting/labor_budget/import) API operation.

API updates

The following changes were made to the reference documentation:

  • Renamed the Healthcare Analytics domain to Healthcare Productivity. This change only affects branding and is backwards compatible--URIs, ACP key names, and other such entities are unchanged.
  • Many of the new features that accept request payloads now feature detailed example request and responses in each API operation's description. These examples are of actual sample calls to a test environment, not merely the complete request and response model already provided as part of the reference documentation.

R9 Update 1

The following changes were made to the API and Developer Hub in R9 Update 1.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Update Job Preferences for Multiple Employees (POST /v1/commons/persons/job_preferences/multi_update) API operation could fail with an HTTP status code 504 Gateway Timeout error when 100 or more records were passed in the request payload. (WFD-142980)
  • The Retrieve Locations (POST /v1/commons/locations/multi_read) API operation did not always return the same business structure shown in the UI. (WFD-141624)
  • The Create or Update Location Set (POST /v1/commons/location_sets/apply_upsert) API operation returned improperly formatted JSON in the response bodies of HTTP status code 207 Partial Success responses. (WFD-138917)
  • The Create Batch Tasks (POST /v1/platform/batch_processing/batch_tasks/multi_create) API operation did not correct resolve object references using a qualifier instead of an ID and did not honor the required properties in the request payload, which could result in bad data saved to the system. (WFD-137642)
  • The Retrieve Schedule Rule Overrides (POST /v2/commons/persons/schedule_rule_overrides/multi_read) API operation incorrectly reported the time amount in seconds rather than HH:MM format in the HTTP status code 207 Partial Success response body. (WFD-144696)
  • The Retrieve Schedule Audits (POST /v1/scheduling/audits/multi_read) API operation would not accept the EMPLOYEES option within the select array. (WFD-142563)
  • The Create Time Off Request as Manager (POST /v1/scheduling/timeoff) API operation threw a null pointer exception when attempting to apply a time off request with auto approval. (WFD-142467)
  • After R8 Update 3, the Update Employment Term Assignments (POST /v1/commons/persons/employment_terms/multi_upsert) API operation became case sensitive to values in certain request payload properties. Those properties are no longer case sensitive. (WFD-138644)
  • The Create Time Off Request as Manager (POST /v1/scheduling/timeoff) API operation intermittently threw optimistic locking errors. (WFD-138468)
  • Enhanced the Retrieve Schedule (POST /v1/scheduling/schedule/multi_read) API operation's documentation to clarify the behavior of the excludeBreaks property in the request payload. (WFD-138344)
  • The Create or Update Labor Category Lists (POST /v1/commons/labor_category_lists/multi_upsert) API operation incorrect threw an HTTP status code 500 Internal Server Error when the laborCategory object was omitted from the request payload. The operation now returns a correct and informative error. (WFD-145073)
  • The Update Timecard as Manager (POST /v1/timekeeping/timecard) API operation incorrect threw an HTTP status code 500 Internal Server Error when passing a pay code edit object reference without also passing a paycode object reference in the request payload. The operation now returns a correct and informative error. (WFD-144024)
  • The Create Adjustment Rule (POST /v1/timekeeping/setup/adjustment_rules) API operation incorrectly used the locale policy to determine the number of decimal places to round certain employee data. This operation no longer uses the locale policy to make this determination and now behaves exactly like the UI. (WFD-142590)
  • The Bulk Import Punches (POST /v1/timekeeping/punches/import) API operation did not correct resolve object references to comments that used a qualifier instead of an ID.(WFD-141760)
  • The Bulk Accrual Reset (POST /v1/timekeeping/accruals/resets) API operation unnecessarily made a CT call during execution that could generate an error. This operation no longer makes an unnecessary CT call when executed. (WFD-141250)
  • Updated the Update Timecard as Manager (POST /v1/timekeeping/timecard) API operation's documentation to note that the do > moveAmounts > updated entity in the request payload is not supported. (WFD-139894)
  • Enhanced the Retrieve Percentage Allocation Rules (POST /v1/timekeeping/setup/percentage_allocation_rules/multi_read) API operation's performance to handle environments where the performance of the Retrieve All Percentage Allocation Rules (GET /v1/timekeeping/setup/percentage_allocation_rules) operation is not sufficient. (WFD-138724)
  • Enhanced the Retrieve Timecard as Manager (GET /v1/timekeeping/timecard) and the Retrieve Timecard as Employee (GET /v1/timekeeping/employee_timecard) API operations to add two new query parameters: (DIM-389665, WFD-132534)
    • retrieve_full_labor_categories: when true, the API returns a significantly more detailed labor category object. This parameter is optional, and the default value is false.
    • return_true_cost_center_id: when true, the API returns the correct cost center ID. This parameter is optional, and the default value is false.
  • Enhanced the Retrieve Timecards as Manager (GET /v1/timekeeping/timecard/multi_read) and the Retrieve Timecards as Employee (GET /v1/timekeeping/employee_timecard/multi_read) API operations to add two new request properties: (DIM-389665, WFD-132534)
    • retrieveFullLaborCategories: when true, the API returns a significantly more detailed labor category object. This property is optional, and the default value is false.
    • returnTrueCostCenterId: when true, the API returns the correct cost center ID. This property is optional, and the default value is false.
  • Enhanced the Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) API operation with a new processBasedOn type of POSITION_ASSIGNMENT. All associated conceptual documentation and examples have been updated with examples of the new functionality. (DIM-394054)
  • Enhanced the Create Scheduling Leave Edits with Options (POST /v1/scheduling/schedule/leave_edits/apply_create) API operation with a new assignBreaks Boolean property in the request payload. When true, breaks are automatically adjusted. This property is optional, and the default value is false. (WFD-133966)
  • Enhanced the Retrieve Locations (POST /v1/commons/locations/multi_read) API operation with a new childrenOfDuring request property, which allows the caller to retrieve first level child nodes of a specific parent node within a specified date range. This property is optional. (WFD-143883)
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation to support the upcoming Multiple Assignments feature by adding a new position property to the response payload that only appears when the Multiple Assignments feature is enabled. Refer to the operation's description for more details and an example request and response. (DIM-390428)
  • Enhanced the following Request Subtype API operations with the enableDurationSelectionInTile Boolean property in the response body, which defaults to false: (DIM-375226)
    • Retrieve Request Subtype by ID (GET /v1/scheduling/setup/request_subtypes/{id})
    • Retrieve Request Subtype by Name (GET /v1/scheduling/setup/request_subtypes?name="")
    • Retrieve Request Subtypes (POST /v1/scheduling/setup/request_subtypes/multi_read)
  • Enhanced the following Labor Category Profiles API operations with a date query parameter or request property, which allows the caller to retrieve versions on specific dates: (DIM-378061)
    • Retrieve All Labor Category Profiles (GET /v1/commons/labor_category_profiles)
    • Retrieve Labor Category Profile by ID (GET /v1/commons/labor_category_profiles/{id})
    • Retrieve Labor Category Profile for Current User (GET /v1/commons/labor_category_profiles/current_user)
    • Retrieve Labor Category Profiles (POST /v1/commons/labor_category_profiles/multi_read)
    • Retrieve Paginated List of Labor Category Profiles (POST /v1/commons/labor_category_profiles/apply_read)
  • Enhanced the following API Labor Standards API operations with Access Control Point (ACP) validation when the following system setting is set to true: site.forecasting.labor.standard.components.acp.enabled (backwards compatibility on existing tenants is maintained): (DIM-342171)
    • Create Labor Standard (POST /v1/forecasting/labor_standards)
    • Create Labor Standards (POST /v1/forecasting/labor_standards/multi_create)
    • Update Labor Standard (POST /v1/forecasting/labor_standards/apply_update)
    • Update Labor Standards (POST /v1/forecasting/labor_standards/multi_update)
  • Enhanced the Retrieve Payroll Export Asynchronous Request Status by Key (GET /v1/commons/payroll/{executionKey}/status) API operation to add the queued and queued_failed statuses. (DIM-385345)
  • Enhanced the following Labor Standards API operations to include the laborStandardAdjustments object in the response body: (DIM-372219)
    • Retrieve Labor Standard by ID (GET /v1/forecasting/labor_standards/{id})
    • Retrieve All Labor Standards or by Specification (GET /v1/forecasting/labor_standards)
    • Retrieve Labor Standards (POST /v1/forecasting/labor_standards/multi_read)
    • Create Labor Standard (POST /v1/forecasting/labor_standards)
    • Create Labor Standards (POST /v1/forecasting/labor_standards/multi_create)
    • Update Labor Standard (POST /v1/forecasting/labor_standards/apply_update)
    • Update Labor Standards (POST /v1/forecasting/labor_standards/multi_update)
  • Enhanced the following Group Schedule Membership API operations with an optional property refs inside the employeeRefs object in the request payload: (DIM-386734)
    • Add Group Membership (POST /v1/scheduling/group_schedule/assignments/apply_create)
    • Remove Group Membership (POST /v1/scheduling/group_schedule/assignments/apply_delete)
  • Enhanced the following Activities API operations with an optional property dayDivideState inside the processedSegments object in the request payload, which has the following options: 0=No Day Divide, 1=Before Day Divide, 2=After Day Divide, -1=Undetermined (WFD-141786)
    • Retrieve Activity Shifts (POST /v1/work/activity_shifts/multi_read)
    • Retrieve Net Changes for Activity Shifts (POST /v1/work/activity_shifts/net_changes/multi_read)
    • Retrieve Activity Transactions (POST /v1/work/activity_transactions/multi_read)
  • Enhanced the Create Employment Term Schedule Pattern (POST /v1/scheduling/employment_term_schedule_patterns/apply_create) API operation with a formatForTransactionAssistant Boolean property in the request payload that, when true, formats the response so that it can be resubmitted by the Transaction Assistant in the event of an error. (WFD-140781)
  • Enhanced the following API operations with an updatePartial property in the request payload that, when set to true, changes most mandatory request parameters to optional, allowing activities to be created or updated with only a name and a description: (DIM-376093, WFD-140902)
    • Create or Update Activities (POST /v1/work/activities/multi_upsert)
    • Create Activity (POST /v1/work/activities)
    • Create Activities (POST /v1/work/activities/multi_create)
    • Update Activity by ID (PUT /v1/work/activities/{id})
    • Update Activities (POST /v1/work/activities/multi_update)
  • Enhanced the following Staffing Dashboard Settings API operations with an automaticBreakPlacement property in the request payload, which allows breaks to be adjusted automatically when shifts are added to the Staffing Dashboard: (WFD-133966)
    • Retrieve Staffing Dashboard Settings by ID (GET /v1/scheduling/setup/staffing_dashboard_settings/{id})
    • Retrieve All Staffing Dashboard Settings or by Name (GET /v1/scheduling/setup/staffing_dashboard_settings?name={name})
    • Retrieve Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_read)
    • Update Staffing Dashboard Settings by ID (PUT /v1/scheduling/setup/staffing_dashboard_settings/{id})
    • Update Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_update)
    • Create Staffing Dashboard Settings (POST /v1/scheduling/setup/staffing_dashboard_settings/multi_create)
  • Enhanced the following Paycode Edits for Scheduling API operations with an assignBreaks property in the request payload, which allows breaks to be adjusted automatically when pay code edits are added: (WFD-133966)
    • Create PCE with Options (POST /v1/scheduling/schedule/pay_code_edits/apply_create)
    • Create Paycode Edits with Options (Deprecated) (POST /v1/scheduling/schedule/pay_code_edits/import)
    • Create Paycode Edits with Options (POST /v1/scheduling/schedule/pay_code_edits/apply_import)
  • Enhanced the following Request Subtypes API operations with an automaticBreakPlacement query parameter or property in the request payload, which allows breaks to be adjusted automatically when pay code edits are added: (WFD-133966)
    • Retrieve Request Subtype by ID (GET /v1/scheduling/setup/request_subtypes/{id})
    • Retrieve Request Subtype by Name (GET /v1/scheduling/setup/request_subtypes/?name={name})
    • Retrieve Request Subtypes (POST /v1/scheduling/setup/request_subtypes/multi_read)
  • Altered the following Activity Profiles API operations to make the multiStopVariance property read-only in the request payload and always returns a fixed value of 3 in the response body. Backwards compatibility is maintained as the operation still accepts multiStopVariance in the request payload, but it continues to have no effect. (WFD-132346)
    • Create Activity Profile POST (/v1/work/activity_profiles)
    • Retrieve Activity Profile by ID (GET /v1/work/activity_profiles/{id})
    • Update Activity Profile by ID (PUT /v1/work/activity_profiles/{id})
    • Retrieve Activity Profiles (POST /v1/work/activity_profiles/multi_read)
    • Create Activity Profiles (POST /v1/work/activity_profiles/multi_create)
    • Update Activity Profiles (POST /v1/work/activity_profiles/multi_update)
  • Enhanced the Retrieve Asynchronous Computed Pending Historical Corrections by Key (GET /v1/timekeeping/pending_historical_corrections/compute/{id}/results) API operation with a position object reference in the response body that appears only when the Multiple Assignments feature is enabled. (DIM-335522)
  • Enhanced the Retrieve Open Shift Requests as Manager (POST /v1/scheduling/open_shift_requests/multi_read) API operation to add an optional statuses parameter to the employees array that contains a list of statuses that filter the open shift requests. (WFD-137444)
  • Enhanced the Retrieve Generic Jobs by Reference (POST /v1/commons/jobs/multi_read) API operation with a modifiedSince property in the multiReadOptions object to filter generic jobs and location types that were changed after the date specified in the new property. (DIM-363726)
  • Enhanced the following API operations with support for the persistentId property in their request and/or response bodies: (DIM-375015)
    • Retrieve Cost Centers (POST /v1/commons/cost_centers/multi_read)
    • Create Cost Centers (POST /v1/commons/cost_centers/multi_create)
    • Update Cost Centers (POST /v1/commons/cost_centers/multi_update)
    • Retrieve Paginated List of Cost Centers (POST /v1/commons/cost_centers/apply_read)
    • Retrieve All Cost Centers (GET /v2/commons/cost_centers)
    • Retrieve Cost Center by ID (GET /v2/commons/cost_centers/{id})
    • Retrieve Labor Category Entries (POST /v1/commons/labor_entries/multi_read)
    • Create Labor Category Entries (POST /v1/commons/labor_entries/multi_create)
    • Update Labor Category Entries (POST /v1/commons/labor_entries/multi_update)
    • Retrieve Labor Category Entry by ID (GET /v2/commons/labor_entries/{id})
    • Retrieve Labor Category Entries by Category ID (GET /v2/commons/labor_entries?categoryId)
  • Enhanced the Retrieve All Labor Categories or by Criteria (GET /v2/commons/labor_categories) API operation with a modified_since query parameter to filter labor categories that were changed after the date specified in the new property. (DIM-375015)
  • Enhanced the following Display Profiles API operations with an optional hidePunchTileMobile Boolean property in the request payload that defaults to false: (DIM-369188)
    • Create Display Profile (POST /v1/commons/display_profiles)
    • Create Display Profiles (POST /v1/commons/display_profiles/multi_create)
    • Update Display Profile by ID (PUT /v1/commons/display_profiles/{id})
    • Update Display Profiles (POST /v1/commons/display_profiles/multi_update)
  • Enhanced the following Schedule Builder Settings API operations with an optional blockingShiftRolloutType property in the request payload and response body: (DIM-371647)
    • Retrieve Schedule Builder Settings (GET /scheduling/schedule_builder_settings)
    • Retrieve Schedule Builder Settings by ID (GET /v1/scheduling/schedule_builder_settings/{id})
    • Update Schedule Builder Settings by ID (PUT /v1/scheduling/schedule_builder_settings/{id})
  • Enhanced the following Labor Forecast Limits API operations with an optional optimizeMinHeadCount Boolean property in the request payload and response body: (DIM-371630)
    • Retrieve Labor Forecast Limit by Name (GET /v2/forecasting/labor_forecast_limits)
    • Retrieve Labor Forecast Limit by ID (GET /v2/forecasting/labor_forecast_limits/{id})
    • Create Labor Forecast Limit (POST /v2/forecasting/labor_forecast_limits)
    • Create Labor Forecast Limits (POST /v2/forecasting/labor_forecast_limits/multi_create)
    • Update Labor Forecast Limits (POST /v2/forecasting/labor_forecast_limits/multi_update)
    • Retrieve Labor Forecast Limits by Criteria (POST /v2/forecasting/labor_forecast_limits/apply_read)
    • Delete Labor Forecast Limits (POST /v2/forecasting/labor_forecast_limits/multi_delete)
    • Delete Labor Forecast Limit Effective Version (POST /v2/forecasting/labor_forecast_limits/versions/apply_delete)
    • Update Labor Forecast Limit by ID (PUT /v2/forecasting/labor_forecast_limits/{id})
  • Enhanced the following Report Data Objects API operations with a timeframeType property in the request payload and response body: (DIM-348894)
    • Retrieve All Report Data Objects or by Name (GET /v1/platform/report_dataobjects)
    • Retrieve Report Data Object by ID (GET /v1/platform/report_dataobjects/{id})
    • Update Report Data Object by ID (PUT /v1/platform/report_dataobjects/{id})
    • Create Report Data Object (POST /v1/platform/report_dataobjects)
    • Delete Report Data Object by ID (DELETE /v1/platform/report_dataobjects/{id})
  • Enhanced the following Timecard Changes API operations with position and userEnteredPosition properties in the request payload and response body when the Multiple Assignments feature is enabled: (DIM-318018)
    • Retrieve Timecard Changes (GET /v1/timekeeping/timecard/changes)
    • Retrieve Timecard Changes for Reports (POST /v1/timekeeping/timecard/changes/reports/multi_read)
  • Enhanced the following API operations to accept a new Perform-Translation header that, when true, adds localized objects such as localizedName, localizedDescription, localizedQualifier, and localizedValue to the response body as appropriate and where supported: (DIM-339761, DIM-342060)
    • Retrieve Open Shift Request by ID (GET /v1/scheduling/open_shift_requests/{openShiftRequestId})
    • Retrieve Employee Open Shift Request by ID (GET /v1/scheduling/employee_open_shift_requests/{openShiftRequestId})
    • Retrieve Request Submission Periods (GET /v1/scheduling/employee_open_shift_requests/submission_periods)
    • Retrieve Open Request Subtypes (GET /v1/scheduling/employee_open_shift_requests/request_subtypes)
    • Retrieve Similar Open Shift Requests by ID (GET /v1/scheduling/open_shift_requests/similar_requests)
    • Update Open Shift Request (POST /v1/scheduling/open_shift_requests/apply_update)
    • Retrieve Open Shift Requests as Manager (POST /v1/scheduling/open_shift_requests/multi_read)
    • Create Employee Open Shift Request (POST /v1/scheduling/employee_open_shift_requests)
    • Retrieve Employee Open Shift Requests (POST /v1/scheduling/employee_open_shift_requests/multi_read)
    • Update Employee Open Shift Request (POST /v1/scheduling/employee_open_shift_requests/apply_update)
    • Create Self-Schedule Request (POST /v1/scheduling/employee_self_schedule_requests)
    • Update Self-Schedule Request by ID (PUT /v1/scheduling/employee_self_schedule_requests/{id})
    • Retrieve Self-Schedule Request by ID (GET /v1/scheduling/employee_self_schedule_requests/{id})
    • Retrieve Self-Schedule Requests (POST /v1/scheduling/employee_self_schedule_requests/multi_read)
    • Retrieve Open Self-Scheduling Request Subtypes (GET /v1/scheduling/employee_self_schedule_requests/request_subtypes)
    • Retrieve Self-Scheduling Request Submission Periods (GET /v1/scheduling/employee_self_schedule_requests/submission_periods)
    • Create Shift Swap Request (POST /v1/scheduling/employee_swap)
    • Retrieve Shift Swap Request by ID (GET /v1/scheduling/employee_swap/{id})
    • Update Shift Swap Request (POST /v1/scheduling/employee_swap/apply_update)
    • Retrieve Shift Swap Requests (POST /v1/scheduling/employee_swap/multi_read)
    • Create Shift Cover Request (POST /v1/scheduling/employee_cover_requests)
    • Retrieve Shift Cover Request by ID (GET /v1/scheduling/employee_cover_requests/{id})
    • Update Shift Cover Request (POST /v1/scheduling/employee_cover_requests/apply_update)
    • Retrieve Shift Cover Requests (POST /v1/scheduling/employee_cover_requests/multi_read)
    • Retrieve Shift Cover Request Subtypes (GET /v1/scheduling/employee_cover_requests/request_subtypes)
    • Retrieve Submission Periods (GET /v1/scheduling/employee_cover_requests/submission_periods)
    • Retrieve Self-Schedule Requests as Manager (POST /v1/scheduling/self_schedule_requests/multi_read)
    • Retrieve Shift Swap Request by ID as Manager (GET /v1/scheduling/manager_swap/{id})
    • Update Shift Swap Request as Manager (POST /v1/scheduling/manager_swap/apply_update)
    • Retrieve Shift Swap Requests as Manager (POST /v1/scheduling/manager_swap/multi_read)
    • Retrieve Shift Cover Request by ID as Manager (GET /v1/scheduling/cover_requests/{id})
    • Update Shift Cover Request as Manager (POST /v1/scheduling/cover_requests/apply_update)
    • Retrieve Shift Cover Requests as Manager (POST /v1/scheduling/cover_requests/multi_read)
    • Retrieve Employee Time Off Request by ID (GET /v1/scheduling/employee_timeoff/{timeOffRequestId})
    • Retrieve Time Off Request by ID as Manager (GET /v1/scheduling/timeoff/{timeOffRequestId})
    • Retrieve Employee Request Subtype (GET /v1/scheduling/employee_timeoff/request_subtypes)
    • Retrieve Request Subtype as Manager (GET /v1/scheduling/timeoff/request_subtypes)
    • Update Employee Time Off Request (POST /v1/scheduling/employee_timeoff/apply_update)
    • Update Time Off Request as Manager (POST /v1/scheduling/timeoff/apply_update)
    • Create Employee Time Off Request (POST /v1/scheduling/employee_timeoff)
    • Create Time Off Request as Manager (POST /v1/scheduling/timeoff)
    • Retrieve Employee Time Off Requests (POST /v1/scheduling/employee_timeoff/multi_read)
    • Retrieve Time Off Requests as Manager (POST /v1/scheduling/timeoff/multi_read)
    • Update Time Off Request by ID as Manager (PUT /v1/scheduling/timeoff/{timeOffRequestId})
    • Create Availability Request (POST /v1/scheduling/employee_availability_requests)
    • Retrieve Availability Request by ID (GET /v1/scheduling/employee_availability_requests/{id})
    • Retrieve Request Subtypes by Availability Type (GET /v1/scheduling/employee_availability_requests/request_subtypes)
    • Retrieve Submission Periods by Availability Type or Subtype (GET /v1/scheduling/employee_availability_requests/submission_periods)
    • Update Availability Request State as Manager (POST /v1/scheduling/manager_availability_requests/apply_update)
    • Retrieve Availability Requests as Manager (POST /v1/scheduling/manager_availability_requests/multi_read)
    • Create Availability Pattern Request (POST /v1/scheduling/employee_availability_pattern_requests)
    • Retrieve Availability Pattern Request by ID (GET /v1/scheduling/employee_availability_pattern_requests/{id})
    • Retrieve Request Subtypes by Availability Type for Pattern Requests (GET /v1/scheduling/employee_availability_pattern_requests/request_subtypes)
    • Retrieve Submission Periods for Pattern Requests (GET /v1/scheduling/employee_availability_pattern_requests/submission_periods)
    • Update Availability Pattern Request State as Manager (POST /v1/scheduling/manager_availability_pattern_requests/apply_update)
    • Retrieve Availability Pattern Requests as Manager (POST /v1/scheduling/manager_availability_pattern_requests/multi_read)
    • Retrieve Employee Visibility Period by ID (GET /v1/scheduling/setup/employee_visibility_periods/{id})
    • Retrieve All Employee Visibility Periods or by Name (GET /v1/scheduling/setup/employee_visibility_periods)
    • Retrieve Employee Visibility Periods (POST /v1/scheduling/setup/employee_visibility_periods/multi_read)

Docs updates

The following changes were made to the conceptual documentation:

  • Added a new Integers tip to the Best practices topic explaining that you must provide integers for request properties with the integer data type. If you provide floating point numbers then the fractional portion of the number is silently discarded and only the integer is submitted.
  • Updated and enhanced A Guide to Running Payroll to incorporate all of the latest changes. The Stage Payroll topic contains the most updates.

API updates

The following changes were made to the reference documentation:

  • Enhanced the Retrieve Schedule (POST /v1/scheduling/schedule/multi_read) API operation with greatly expanded documentation for the scheduleDayList response property. (WFD-135947)
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation's documentation to include new select parameters and to describe support for the upcoming Multiple Assignments feature.
  • Edits throughout to enhance clarity, add detail, and correct errors and omissions. Refer to the Corrections and enhancements section for more details.

R9

The following changes were made to the API and Developer Hub in R9.

General

Announcements

New authentication method for federated users

The Authenticate with federated user accounts topic has been updated to reflect the new, improved federated authentication process. The legacy federated authentication method described in the Authenticate with federated user accounts topic has been deprecated.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Create or Update Activities (POST /v1/work/activities/multi_upsert) API operation sometimes failed with an HTTP status code 500 Internal Server Error due to a race condition. (WFD-135957)
  • Various Persons API operations did not correctly process the changed license name from "Work" to "Activities." All affected operations can now consume both naming conventions for this license. (WFD-132608)
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation incorrectly returned an HTTP status code 500 Internal Server Error when the employeeLaborCategoryProfileName property was not passed with a valid value in the request payload. The operation now throws a descriptive error. (WFD-136090)
  • Scheduling API operations could return an incorrect errorCode for certain unknown errors. These operations now return an errorCode of WFS-100000 when unknown errors occur. (WFD-135566)
  • Enhanced the Retrieve Job Preferences by Person Number (GET /v1/commons/persons/job_preferences) API operation to add a new query parameter full_job_path, which is a Boolean indicator of whether or not the response returns the full job path for each job. (WFD-136319)
  • The Create Locations (POST /v1/commons/locations/multi_create) API operation could fail with an error claiming that the newly created revision lacked a unique externalId. (WFD-132447)
  • The Retrieve Locations (POST /v1/commons/locations/multi_read) API operation returned old Business Structure node names even after the names were successfully updated. The logic now properly updates the locations cache when a nodeType is changed. (WFD-131397)
  • The Import Labor Standards, Tasks, and Task Groups (Deprecated) (POST /v1/forecasting/labor_standard_tasks/import) API operation allowed a user to alter generic departments in a harmful way. The operation now throws an error message if an API caller attempts to alter a generic department. (WFD-136858)
  • The Retrieve All Labor Standards or by Specification (GET /v1/forecasting/labor_standards) API operation would time out and throw an HTTP status code 504 error message if too many labor standards existed on a tenant. This operation has been deprecated. If you have a large number of labor standards, use POST /v1/forecasting/labor_standards/multi_read instead. (WFD-135769)
  • Enhanced the Retrieve Custom Drivers (POST /v1/forecasting/custom_drivers/multi_read) API operation to return all custom drivers if an empty object is passed in the request payload. (WFD-125423)
  • The Submit Bulk Download (POST /v1/commons/exports/async) API operation incorrectly required a Timekeeping license. (WFD-131561)
  • Enhanced the model property documentation for the following operations against the Leave Case Defaults API resource to include the following: Note: Scheduled shifts are overridden when overrideShiftType is defined. If overrideShiftType is not defined then scheduled shifts are not overridden. This property is only applicable when commitTo is set to schedule. (WFD-134150)
    • Update Leave Case Defaults (PUT /v1/leave/leave_cases/defaults)
    • Retrieve Leave Case Defaults (GET /v1/leave/leave_cases/defaults)
    • Retrieve Leave Case Defaults by ID (GET /v1/leave/leave_cases/{id}/defaults)
  • Enhanced the Update Leave Admin for Multiple Employees (POST /v1/commons/persons/leave_admin/multi_update) API operation to return a more descriptive and accurate error message when assigning leave administrators to employees in invalid scenarios. (WFD-133446)
  • The Create Batch Tasks (POST /v1/platform/batch_processing/batch_tasks/multi_create) API operation did not accept qualifiers when creating batch tasks and did not require some of the elements that are actually required to successfully create batch tasks. (WFD-137642)
  • The Retrieve All Batch Events (GET /v1/platform/batch_processing/batch_events) API operation did not return all of the batch events configured in the system. (WFD-136949)
  • Enhanced the documentation for the Retrieve Notifications (GET /v1/commons/notifications) API operation to clarify that the notifications returned are limited to the access privileges of the logged-in user even when specifying a list of users by including a Hyperfind as a query parameter. (WFD-136384)
  • In rare circumstances, a user could encounter an authentication error when attempting to access the Developer Hub from the UI. (WFD-135654)
  • The Update Batch Events (POST /v1/platform/batch_processing/batch_events/apply_update) API operation did not accept qualifiers when updating batch events. (WFD-135425)
  • The Update Multiple Persons (POST /v1/commons/persons/multi_update) API operation incorrectly returned an HTTP status code 401 error when submitting an incorrectly formatted request payload. (WFD-135095)
  • The Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update) API operation incorrectly returned a WCO-115003 error when creating multiple scheduled pay code edits. (WFD-135412)
  • The Update Schedule (POST /v1/scheduling/schedule) API operation intermittently threw incorrect errors when adding pay codes to the schedule. (WFD-134551)
  • After R8 Update 2, the Update Schedule (POST /v1/scheduling/schedule) API operation intermittently threw a WFS-102409 error when updating a pay code edit. (WFD-133834)
  • Enhanced the Retrieve Time Off Requests as Manager (POST /v1/scheduling/timeoff/multi_read) API operation to allow the caller to pass a Hyperfind query in the request payload. (WFD-121441)
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation to add ISR_DAILY and ISR_SUMMARY as possible values for the select request property. (WFD-139148)
  • The Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation threw an HTTP status code 404 error when it encountered certain improperly configured pay codes. (WFD-137833)
  • Enhanced the snapshotDate and snapshotDateTime property descriptions to clearly state which API operations accept these properties in their request payloads. (WFD-137657)
  • In rare circumstances, the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation would omit the Accrual Summary and the Daily Summary from the response. (WFD-136861)
  • In certain circumstances, the Retrieve Punches in Real Time (POST /v1/timekeeping/punches/apply_read) API operation did not return the correct override type for a punch. (WFD-136762)
  • The Create Time Off Request as Manager (POST /v1/scheduling/timeoff) API operation responded slowly when the request payload did not include a pay code edit from Schedule. (WFD-129520)
  • The Update Employment Term Versions (POST /v1/timekeeping/setup/employment_terms/versions/apply_upsert) API operation incorrectly threw an error when a valid but null pay code was included in the request payload. (WFD-132150)
  • The orderBy property was incorrectly displayed in the following API operations' request payloads: (WFD-134629)
    • Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read)
    • Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read)
    • Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read)
  • Enhanced the Apply Updates to Accrual Balances for Multiple Employees (POST /v1/timekeeping/accruals/updates) API operation to include a formatForTransactionAssistant request property to allow the transaction assistant to better parse this operation's partial success responses. (WFD-134877)
  • The Retrieve All Work Rules (GET /v1/timekeeping/setup/full_work_rules) API operation did not return Rest Between Shift rules in the response. (WFD-135421)
  • The Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation did not return overtime details when the request payload select property contained OVERTIME_DETAILS. (WFD-136166)
  • Enhanced the following API operations to support the following entities: laborCategories, costCenter, workRule, orgJob, and emptyTransfer: (DIM-282613)
    • Retrieve Timecard as Manager (GET /v1/timekeeping/timecard) (applicable only when the select query parameter is ACTIVITY_SEGMENTS or ACTIVITY_SHIFTS)
    • Retrieve Timecard as Employee (GET /v1/timekeeping/employee_timecard) (applicable only when the select query parameter is ACTIVITY_SEGMENTS or ACTIVITY_SHIFTS)
    • Update Timecard as Manager (POST /v1/timekeeping/timecard)
    • Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read)
    • Update Timecard as Employee (POST /v1/timekeeping/employee_timecard)
    • Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read)
  • Enhanced the Create Team Definition (POST /v1/scheduling/setup/team_definition) API operation to allow null values to be passed for either the entire absenceQuotas object or for the quota object within absenceQuotas. Also enhanced the Retrieve Guided Recommendations (POST /v1/scheduling/time_off_request_guided_recommendations/apply_read) API operation to allow the thresholdStatus property to accept a value of NO_COLOR. (DIM-334021)
  • Enhanced the Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update) API operation to allow you to create paycode edits with options using the new createWithOptions request array. (DIM-322789)
  • Enhanced the following Forecast Planner Settings API operations to add the defaultVolumeForecastInterval property to the request and response models: (DIM-371376)
    • Retrieve a Forecast Planner Setting by ID (GET /v1/forecasting/forecast_planner_settings/{id})
    • Retrieve All Forecast Planner Settings or by Name (GET /v1/forecasting/forecast_planner_settings)
    • Retrieve Forecast Planner Settings (POST /v1/forecasting/forecast_planner_settings/multi_read)
    • Create a Forecast Planner Setting (POST /v1/forecasting/forecast_planner_settings/)
    • Create Forecast Planner Settings (POST /v1/forecasting/forecast_planner_settings/multi_create)
    • Update a Forecast Planner Setting by ID (PUT /v1/forecasting/forecast_planner_settings/{id})
    • Update Forecast Planner Settings (POST /v1/forecasting/forecast_planner_settings/multi_update)
  • Enhanced the Create Team Definition (POST /v1/scheduling/setup/team_definition) and Update Team Definition by ID (PUT /v1/scheduling/setup/team_definition/{id}) API operations to add a quotaAsPercentage Boolean request property that determines whether or not the team definition defines the quota as a percentage or a whole number. (DIM-155638)
  • Enhanced the Import Volume Forecast (POST /v2/forecasting/volume_forecast/import) API operation by adding the intervalAmounts property to the volumeForecasts array. This optional property contains a string of up to 96 comma-separated values representing each 15 minute interval in a day. (DIM-318085)
  • Enhanced the following multi_upsert and the apply_upsert API operations with an include_version query parameter and the multi_read operation with an includeVersion property within multiReadOptions in the request payload. These new properties, when set to false, allow you to omit the version property from the request payload. (WFD-136715)
    • Update Custom Driver Values (POST /v1/forecasting/custom_driver_values/apply_upsert)
    • Update Values for Multiple Custom Drivers (POST /v1/forecasting/custom_driver_values/multi_upsert)
    • Retrieve Custom Driver Values (POST /v1/forecasting/custom_driver_values/multi_read)
  • Enhanced the following API operations with a new badgeLoginMask Boolean property to the request payload. This property allows you to mask the Kiosk display of badge ID in the same way a password is masked. (DIM-333097)
    • Create Kiosk Configuration (POST /v1/timekeeping/setup/kiosks)
    • Retrieve Kiosk Configuration by ID (GET /v1/timekeeping/setup/kiosk/{id})
    • Retrieve All Kiosk Configurations (GET /v1/timekeeping/setup/kiosks)
    • Update Kiosk Configuration by ID (PUT /v1/timekeeping/setup/kiosks/{id})
  • Enhanced the following API operations with a new overtimeRule object reference in the work hour definition: (DIM-330417)
    • Create Employment Term (POST /v1/timekeeping/setup/employment_terms)
    • Update Employment Term Versions (POST /v1/timekeeping/setup/employment_terms/versions/apply_upsert)
    • Retrieve Employment Terms (POST /v1/timekeeping/setup/employment_terms/multi_read)
    • Update Employment Term by ID (PUT /v1/timekeeping/setup/employment_terms/{id})
    • Retrieve All Employment Terms (GET /v2/timekeeping/setup/employment_terms)
    • Retrieve Employment Term by ID (GET /v2/timekeeping/setup/employment_terms/{id})
  • Enhanced the Stage Payroll Asynchronously (POST /v1/commons/payroll/staging/async) API operation with a new filterBy property within the processBasedOn object. This property accepts JOB, LABOR_CATEGORY, or COST_CENTER when the processBasedOn type is WORKED. (DIM-334906)
  • Enhanced the following API operations with a new licenseTypeName property within employeeExtension > licenseTypeList: (DIM-332112)
    • Retrieve Persons (POST /v1/commons/persons/extensions/multi_read)
    • Retrieve Person by Extension (GET /v1/commons/persons/{extensionType})
    • Retrieve All Extensions (GET /v1/commons/persons/extensions)
  • Updated the following API operations to correctly return only the data for the specified date range (and to no longer include flanking days). These operations now behave consistently with the UI and the Activity Totals API operations: (WFD-132427)
    • Retrieve Timecard as Manager (GET /v1/timekeeping/timecard?select=ACTIVITY_TOTALS)
    • Retrieve Timecard as Employee (GET /v1/timekeeping/employee_timecard?select=ACTIVITY_TOTALS)
    • Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read)
    • Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read)
  • Enhanced the following API operations such that the scheduleTagColor property is now optional and, when omitted, inherits the color from the tag definition: (WFD-130158)
    • Create Schedule Tag (POST /v1/scheduling/schedule/schedule_tags)
    • Update Schedule Tag by ID (PUT /v1/scheduling/schedule/schedule_tags/{id})

Docs updates

The following changes were made to the conceptual documentation:

API updates

The following changes were made to the reference documentation:

R8 Update 3

The following changes were made to the API and Developer Hub in R8 Update 3.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Retrieve All Timekeeping Pay Rules (Deprecated) (GET /v1/timekeeping/setup/payrules) API operation incorrectly threw an error when the number of pay rules in the system exceeded 1,500. (WFD-129144)
  • Added additional validation to the Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation to prevent rare combinations of request parameters from causing unusual behavior. (WFD-128997)
  • When a historical correction's historical date was the same as its effective date, the Save Pending Historical Corrections (POST /v1/timekeeping/pending_historical_corrections/save/async) API operation would incorrectly generate duplicate historical corrections. (WFD-130614)
  • In certain rare circumstances, the Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation returned the incorrect work rule associated with a pay rule. (WFD-130864)
  • A code error caused the Developer Hub to display an incorrect JSON schema for the Update Employment Term Version (POST /v1/timekeeping/setup/employment_terms/versions/apply_upsert) API operation. (WFD-131957)
  • Enhanced the performance of processing large request batches in the Create Schedule Tags (POST /v1/scheduling/schedule/schedule_tags/multi_create) API operation. (WFD-128742)
  • Enhanced the performance of the Retrieve Schedule Audits (POST /v1/scheduling/audits/multi_read) API operation. (WFD-128088)
  • The Retrieve Locations (POST /v1/commons/locations/multi_read) API operation returned a generic error message when certain backend services failed. This operation now has enhanced logging to return more descriptive errors. (WFD-130616)
  • The Create or Update Known Places (POST /v1/commons/known_places/multi_upsert) API operation would indicate success even when some transactions failed when transactions failed due to improperly formatted JSON in the request payload. (WFD-130680)
  • The Update Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_update) API operation incorrectly threw a generic error message when certain validation errors occurred. (WFD-131181)
  • The Retrieve Punches in Real Time (POST /v1/timekeeping/punches/apply_read) API operation now has a datasource qualifier property that shows where punches originate. (WFD-123904, DIM-317898)
  • Enhanced all operations against the Schedule Change Criteria API resource by adding the shiftLocationChanged and locationType properties to their request and response models. (DIM-207671)
  • Enhanced the following API operations' partial success validation such that partial success is only processed for expected errors (locked day, expired job, and so on). If an unexpected error occurs during business validation, the entire operation fails and partial success is not processed. (WFD-128015)
    • Create Employment Terms PCEs (POST /v1/scheduling/employment_terms_schedule/pay_code_edits/apply_create)
    • Update Employment Terms PCEs (POST /v1/scheduling/employment_terms_schedule/pay_code_edits/apply_update)
    • Create Group Shifts (POST /v1/scheduling/schedule/groups/shifts/apply_create)
    • Update Group Shifts (POST /v1/scheduling/schedule/groups/shifts/apply_update)
    • Create Group PCEs (POST /v1/scheduling/schedule/groups/pay_code_edits/apply_create)
    • Update Group PCEs (POST /v1/scheduling/schedule/groups/pay_code_edits/apply_update)
  • Enhanced the Update Open Shift Request (POST /v1/scheduling/open_shift_requests/apply_update) API operation's event property to add a new enumeration, comment_by_manager, which allows a manager to add a comment to an open shift request. (DIM-300115)
  • Enhanced the Execute Hyperfind Query (POST /v1/commons/hyperfind/execute) API operation to add the includeTerminatedInRangeForLocations request property, which is a Boolean indicator of whether or not to include terminated employees in the date range for locations. (DIM-276188)
  • Enhanced the Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation to add the filterByAnchorDate request property. When false, this Boolean allows an employee's Accrual Summary to be returned in a manner consistent with the existing report format. (WFD-128765)
  • Enhanced the Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) and Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read) API operations by adding the totalsRollupBy request property, which allows you to specify the level by which totals are rolled up. Supported values are ALL, SHIFT, TIMEITEM, DAILY, PERIOD_TO_DATE, ACTIVITY_EVENT, and RAW. (WFD-131316)
  • Enhanced the Retrieve Payroll Data for HCM (POST /v1/hcm/payroll/data/apply_read) API operation by adding the includeWorkedCostCenter request property, which allows you to include the worked cost center in the aggregation key and in the cost center array. (DIM-279226)
  • Enhanced all API operations that return the punchGeoLocation object (such as Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) by adding geofenceMethod and knownPlaceName to the punchGeoLocation object. (DIM-277503)
  • Enhanced the Retrieve Net Changes for Activity Shifts (POST /v1/work/activity_shifts/net_changes/multi_read) API operation to include full object references for each of the following objects in the response: (WFD-129646)
    • laborCategory
    • costCenter
    • orgJob
    • payCode
    • workRule
  • Enhanced the following API operations by increasing the JSON payload size from the default of 1 megabyte to 5 megabytes: (WFD-130391)
    • Update Results Templates (POST /v1/work/results_templates/multi_update)
    • Create Results Templates (POST /v1/work/results_templates /multi_create)
    • Update Results Template by ID (PUT /v1/work/results_templates/{id})
    • Create Results Template (POST /v1/work/results_templates)
  • Enhanced the following API operations by adding the PROCESSED_SEGMENTS option to the select query parameter and property: (DIM-326168)
    • Retrieve Timecard as Employee (GET /v1/timekeeping/employee_timecard)
    • Retrieve Timecard as Manager (GET /v1/timekeeping/timecard)
    • Retrieve Timecards as Employee (POST /v1/timekeeping/employee_timecard/multi_read)
    • Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read)

Docs updates

The following changes were made to the conceptual documentation:

API updates

The following changes were made to the reference documentation:

Important New Content

  • The Payroll Staging, Payroll Tables, and Payroll Export subdomains have been added to the API, greatly enhancing your ability to extract payroll and accruals from the system.

R8 Update 2

The following changes were made to the API and Developer Hub in R8 Update 2.

General

Announcements

FAQ about deprecated API operations

This release introduces a topic defining the way we use the term Deprecated and answering a number of frequently asked questions about our deprecated API operations and their replacement operations.

Important updates in the API updates section

Check out the API updates section for important notes on the new top-level organization of the API reference documentation, significant new content, and for notes regarding our move to document service limits at the operation level whenever it is possible to do so.

Introducing a Hyperfind Query timeout limit

Hyperfind queries that consistently take more than 5 minutes to execute will be prevented from executing.

  • If a query group is deactivated for this reason, the following error message will display:
Execution of this Hyperfind query has been disabled. Simplify the query and try again.
  • If a query group is consistently resulting in queries that take over 5 minutes, the following error message will display:
Execution of your Hyperfind query will exceed the limit of 5 minutes. Simplify the query and try again.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • Enhanced the Bulk Enable Edits (POST /v1/timekeeping/enable_edits/import) and Bulk Timecard Signoffs (POST /v1/timekeeping/signoffs/import) API operations to add the employeeResponseType property inside the options object. When detailedPartialSuccess is true, this property controls whether to return IDs, qualifiers, or refs in partial success responses.
    • If employeeResponseType is null, the operation behaves as before and always returns IDs in partial success responses.
    • If employeeResponseType is original, the partial success response mimics what was passed in the originating request payload. For example, if employees were specified in the request payload using refs, the partial success response returns refs. If they are specified using qualifiers, the partial success response returns qualifiers.
    • If employeeResponseType is ids, qualifiers, or refs, the partial success response returns ids, qualifiers, or refs, respectively.
  • Enhanced the Retrieve All Accrual Profiles (GET /v2/timekeeping/setup/accrual_profiles) API operation to add the include_accrual_policies query parameter, which is a Boolean indicator of whether or not to include accrual policies in the response.
  • Enhanced the Update Timecard as Manager (POST /v1/timekeeping/timecard) and Update Timecard as Employee (POST /v1/timekeeping/employee_timecard) API operations to add the onlyReturnChangedEntities property inside the do object, which is a Boolean indicator of whether or not to only return changed entities in the response.
  • Enhanced the following API operations to be consistent with the following UI behavior: when licenses are assigned to terminated employees, the employment status of the employee changes from terminated to active as of the current date and the license is assigned to the employee. The employee's user account status is set to Active and a user role is assigned (employee or manager). Previously, when attempting to assign licenses to terminated employees, these API operations returned an HTTP status code 200 success response but did not actually assign the license or perform any of the actions described above.
    • Create or Update Persons (POST /v1/commons/persons/multi_upsert)
    • Update Multiple Persons (POST /v1/commons/persons/multi_update)
    • Update Person by ID (PUT /v1/commons/persons/{personId})
    • Create Person (POST /v1/commons/persons)
  • The Retrieve Activity Totals for Multiple Employees (POST /v1/work/activity_totals/multi_read) API operation's response body did not always include the processSegmentId property, which caused integrations to fail.
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation returned "an unexpected non-SQL system error" in certain rare circumstances. The root cause was identified and corrected.
  • In rare circumstances, the Retrieve Comments as Manager (GET /v1/commons/comments) API operation would return duplicate comment entries. The root cause was identified and corrected.
  • Enhanced the Move Location (POST /v1/commons/locations/apply_update) API operation to add the showDescendants Boolean, which ensures the response always returns descendant nodes.
  • Resolved a null pointer exception for the Create Locations (POST /v1/commons/locations/multi_create) API operation.
  • The Update Multiple Adjustment Driver Settings (POST /v1/forecasting/adjustment_driver_settings/multi_update) API operation incorrectly threw an "ERROR-1007" during certain validation scenarios. The root cause was identified and corrected.
  • The Retrieve Static Driver Assignments (POST /v1/forecasting/static_driver_assignments/multi_read) API operation's error messaging has been enhanced to more clearly inform the user when they specify a timeframe that includes locations that are divided in the middle of the week, which is considered a 'broken week.'
  • The Retrieve Data (POST /v1/commons/data/multi_read) API operation failed with a "400 Bad Request" error when terminated employees were included in a Hyperfind in the request payload. The root cause was identified and validation logic was corrected.
  • The Create PCE with Options (POST /v1/scheduling/schedule/pay_code_edits/apply_create) API operation did not write employee IDs to the transaction assistant when it encountered an error. The root cause was identified and corrected.
  • The Apply Updates to Accrual Balances for Multiple Employees (POST /v1/timekeeping/accruals/updates) API operation did not write employee IDs to the transaction assistant when it encountered an error. The root cause was identified and corrected.
  • When a null value caused an import of person records to fail, the Transaction Assistant and the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation showed a generic, uninformative error message. The new message is "This field does not allow a null value. Field name: User Name."
  • The Create Paycode Edits with Options (POST /v1/scheduling/schedule/pay_code_edits/apply_import) API operation incorrectly returned a text string for the durationInMinutes property instead of the numerical duration value.
  • The Retrieve Open Shift Requests as Manager (POST /v1/scheduling/open_shift_requests/multi_read) API operation did not properly execute the statuses array in the request payload. The root cause was identified and corrected.
  • In certain circumstances, the Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create) API operation would delete a previous day's shift when applying a schedule pattern to a portion of a week. The root cause was identified and corrected.
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation was incorrectly generating a Hyperfind service limit error even though the number of employees processed in the request payload was under the service limit. The root cause was identified and corrected.
  • The Update Shift Template Profile Assignments (POST /v1/commons/persons/shift_template_profiles/multi_update) API operation threw a null pointer exception error when ShiftTemplateProfile was null. The root cause was identified and corrected.
  • The Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update) API operation threw null pointer exceptions under certain conditions, which were identified and corrected.
  • The Update Schedule (POST /v1/scheduling/schedule) API operation incorrectly required the employee node when specifying a paycode edit. The operation no longer requires the employee node when specifying a paycode edit.
  • The Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update) API operation threw an error when multiple availabilities were created for the same employee on the same day in a single request payload. The API now gracefully handles such requests.
  • The Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create) API operation incorrectly accepted values for the anchorStartDay property, which has always been documented and intended to be a read-only property. The API now correctly ignores this property in the request payload and instead reads the anchorStartDay in the locale policy.
  • The Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation incorrectly returned an HTTP 500 Internal Server Error when the request payload included terminated employees that met certain rare conditions. The API now gracefully handles these conditions.
  • The Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation did not correctly return end-dated but active jobs for historical corrections. The root cause was identified and corrected.
  • Enhanced the Create Percentage Allocation Rule (POST /v1/timekeeping/setup/percentage_allocation_rules) and Update Percentage Allocation Rule (PUT /v1/timekeeping/setup/percentage_allocation_rules/{id}) API operations to validate the properties passed within the allocations array.
  • The Update Paycode by ID (PUT /v1/timekeeping/setup/pay_codes/{id}) API operation did not correctly update the system with the data specified in the scheduledHoursType property. The API now correctly updates the scheduled hours type.
  • The Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation returned two worked shifts with the same ID when the shift was split at the day divide. The API now returns a single worked shift that crosses the divide and spans on each side of the divide.
  • The Retrieve All Accrual Profiles (GET /v2/timekeeping/setup/accrual_profiles) API operation returned the accrual profile name and the accrual code but did not return the accrual policy details. Accrual policy details are now correctly returned.
  • The Retrieve Punches in Real Time (POST /v1/timekeeping/punches/apply_read) API operation did not return punches created with a legacy timezone ID that concatenated a real timezone ID with a Daylight Savings Time flag. The API now gracefully handles punches created with a legacy timezone ID.
  • Under rare conditions, the Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation returned an HTTP status code 500 Internal Server Error. The root cause was identified and corrected via additional validation steps.
  • The Create, Update, or Delete Manager Role Assignments (POST /v1/commons/persons/manager_role_assignments/apply_upsert) API operation did not correctly mirror the request payload in the input property of its HTTP Status Code 207 Partial Success response body, which caused issues when the response was consumed by the Transaction Assistant. The input property now correctly reflects the sequence provided in the request payload.
  • The Bulk Accrual Reset (POST /v1/timekeeping/accruals/resets) API operation did not correctly process only the latest reset when multiple resets for the same employee, accrual code, and date were specified in the same request payload.

Docs updates

The following changes were made to the conceptual documentation:

  • Added A Guide to Attestations to the Guides section.
  • Removed operation-level service limits across all domains from the Service limits topic. Those limits now exist in the reference documentation at the operation level.
  • Added information about the Business Structure jobs service limit to the Service limits topic.

API updates

The following changes were made to the reference documentation:

New Organization

  • Moved the Forecasting setup operations into a new domain named Forecasting Setup.
  • Moved the Timekeeping timecards operations into a new domain named Timekeeping Timecards.
  • Moved the Timekeeping bulk operations into a new domain named Timekeeping Bulk Operations.
  • Moved the person assignments operations out of the Persons domain and into a new domain named Person Assignments.

Other Updates

  • Added service limits across all domains to each operation as applicable. Now, only general service limits that apply to whole domains or groups of operations are contained in the Service limits topic in the conceptual documentation.
  • The Change Indicators subdomain has been added to the API, greatly enhancing your ability to extract change-over-time data from the system.

R8 Update 1

The following changes were made to the API and Developer Hub in R8 Update 1.

General

Announcements

Version 2 API operations

The API has introduced the first set of version 2 API operations. We recommend you update your implementations to utilize version 2 operations as they provide better security, performance, and functionality.

End-of-life API operations

The following API operations have reached end-of-life and have been removed entirely from the system:

  • GET /v1/forecasting/hours_operation
  • POST /v1/forecasting/hours_operation
  • GET /v1/forecasting/hours_operation/{id}
  • PUT /v1/forecasting/hours_operation/{id}
  • DELETE /v1/forecasting/hours_operation/{id}
  • POST /v1/forecasting/hours_operation/multi_create
  • POST /v1/forecasting/hours_operation/multi_update
  • POST /v1/forecasting/hours_operation/multi_read
  • POST /v1/forecasting/hours_operation/multi_delete

If you are currently using any of these operations, the following now-deprecated replacements work in exactly the same way and can be used immediately as-is, aside from updating the URL:

  • GET /v1/commons/hours_operation
  • POST /v1/commons/hours_operation
  • GET /v1/commons/hours_operation/{id}
  • PUT /v1/commons/hours_operation/{id}
  • DELETE /v1/commons/hours_operation/{id}
  • POST /v1/commons/hours_operation/multi_create
  • POST /v1/commons/hours_operation/multi_update
  • POST /v1/commons/hours_operation/multi_read
  • POST /v1/commons/hours_operation/multi_delete

Note: As of R8 Update 1, you can update your implementations more fully to use the version 2 Hours of Operation resource. Refer to the Version 2 resources and operations topic for more information.

Introducing effective dating support in version 2 Forecasting API operations

The following version 2 Forecasting API resources introduce effective dating support:

  • Labor Forecast Limits (/v2/forecasting/labor_forecast_limits)
  • Hours of Operation (/v2/commons/hours_operation)
  • Labor Tasks (/v2/forecasting/tasks)
  • Task Groups (/v2/forecasting/task_groups)

Note: The deprecated version 1 operations against these API resources (for example, operations against /v1/commons/hours_operation) only work with entities containing a single effective version.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • Enhanced the documentation for the Import Labor Standards, Tasks, and Task Groups (POST /v1/forecasting/labor_standard_tasks/import) API operation to better describe how to compress or truncate traffic pattern distribution using the StandardDistributionSettings.standardDistributionType property.
  • Enhanced the Guides > A Guide to People Information > Person Assignments > Skill Assignments topic to indicate that only skill assignments with an effective date in the future can be deleted.
  • The Retrieve Activity Transactions (POST /v1/work/activity_transactions/multi_read) API operation reported activity totals in whole hours only, which did not match the UI. This operation now reports activity totals at the same level of granularity provided by the UI.
  • Enhanced certain operations against the Timecards API resource (/v1/timekeeping/employee_timecard and /v1/timekeeping/timecard) to include full object references to associated "activity" objects.
  • The Create or Update Location Set (POST /v1/commons/location_sets/apply_upsert) API operation did not gracefully handle certain request payloads when passing the "removeNodeRefs" property. The operation will now correctly perform a removal of specified nodes or pass an explanatory error message.
  • The Update Values for Multiple Adjustment Drivers (POST /v1/forecasting/adjustment_drivers/multi_upsert) API operation in some cases passed an HTTP status code 400 error code with an HTTP status code 207 response body. Also, this operation did not allow the caller to specify a version of the Adjustment Driver object. The operation now returns the correct HTTP status code for 207 "Partial Success" errors and has been enhanced with an "includeVersion" property that allows the caller to specify the version.
  • The Retrieve Volume Driver Assignments (POST /v1/forecasting/volume_driver_assignments/multi_read) API operation would sporadically time out due to a caching issue. The caching issue has been corrected.
  • Updated numerous Forecasting API operations to support the standard "end of time" date in request payload specifications.
  • The Retrieve Hyperfind Queries for Current User (GET /v1/commons/hyperfind) API operation did not return the home Hyperfind query when the "usage_type" query paramater was passed with "Home" specified. The operation now returns the correct results for all enumerations of the "usage_type" query parameter.
  • The Create or Update Delegate Profiles (POST /v1/commons/delegate_profiles/multi_upsert) API operation would incorrectly return an HTTP status code 200 response even when some of the specified delegates were not assigned to a profile. The operation now correctly passes an HTTP status code 207 "Partial Success" response when some delegate assignments failed and others succeeded.
  • The Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create) API operation returned an incorrect error message when the "timePeriodType" property was not specified. The operation now returns the correct error message.
  • The Update Group Memberships for Multiple Employees (POST /v1/commons/persons/schedule_groups/multi_upsert) API operation did not correctly honor the "removeFromOtherGroups" Boolean property. The property now behaves as intended.
  • The Create Shift Template (POST /v1/scheduling/shift_templates) API operation would sometimes take an unusually long time to complete. The root cause was identified and corrected.
  • In rare circumstances, the Create PCE with Options (POST /v1/scheduling/schedule/pay_code_edits/apply_create) API operation could throw a nullPointerException error. The root cause was identified and corrected.
  • The Modify Assignments for Multiple People (POST /v1/commons/persons/assignments/multi_upsert) API operation could not end-date a currently active, effective-dated Schedule Group assignment when that assignment's name matched an effective-dated assignment that already ended in the past. The root cause was identified and corrected.
  • The Bulk Create or Update Workload Patterns (POST /v1/scheduling/workload_patterns/multi_upsert) API operation incorrectly returned a nullPointerException when an empty string or 'null' was passed into the "count" key of a workload object. The root cause was identified and corrected.
  • Corrected an issue where the actions specified in a Create Group Schedule Pattern (POST /v1/scheduling/group_schedule_patterns/apply_create) API operation would not fully complete if it was immediately followed by an Update or Remove Group Schedule Patterns (POST /v1/scheduling/group_schedule_patterns/apply_update) API operation.
  • Due to a caching issue, the Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation could return incorrect Schedule Group assignments. The root cause was identified and corrected.
  • The Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation did not correctly filter the results based on the accrual code passed in the request payload. The operation now passes all results if no accrual code is specified or filters the result set by the specified accrual code.
  • The Retrieve All Overtime Rules (GET /v1/timekeeping/setup/overtime_rules) API operation displayed an incorrect response model on the Developer Hub. The root cause was identified and the Developer Hub now displays the correct response model.
  • The Retrieve All Work Rules (GET /v1/timekeeping/setup/full_work_rules) API operation would sometimes return incorrect information when the majority or zone rules were changed in the UI. The root cause was identified and corrected.
  • The Create Shift Templates (POST /v1/scheduling/shift_templates) API operation returned an incorrect error message when passing a read-only property in the request payload. The operation now gracefully handles such errors and has been enhanced with more descriptive error messaging.

Docs updates

The following changes were made to the conceptual documentation:

API updates

The following changes were made to the reference documentation:

  • Deprecated the version 1 resources and operations that have been replaced by version 2 resources and operations. Deprecated operations note that they are deprecated and point to their replacements. Refer to the Version 2 resources and operations topic for more information.
  • Enhanced the Import Labor Standards, Tasks, and Task Groups (POST /v2/forecasting/labor_standard_tasks/import) and Import Labor Standards, Tasks, and Task Groups (Deprecated) (POST /v1/forecasting/labor_standard_tasks/import) API operations to support combined labor distribution.
  • Restored the R7 Update 4 enhancements that dropped out of the first R8 release.
  • Updated the Employee Availability Requests and Manager Availability Requests resources to correct the allowable values for the "event" property in the request payload and to provide more details about how the states behave for create and update state operations.
  • Enhanced the Predictive Scheduling Rules (operations against /v1/scheduling/setup/predictive_scheduling_rules) API resource to include a "priority" property. This field defaults to a value of 10 when not specified in the payload.
  • Updated the documentation for several operations against the Timecards resource to clearly state that the dateRange object is required, and, for the GET operations, to note that either a symbolic period or a date range consisting of a start date and end date is required.
  • Enhanced the Retrieve Data (POST /v1/commons/data/multi_read) API operation to support Healthcare Analytics data retrieval.
  • To support primary job assignment by providing a Business Structure location's full name or persistent ID, added a new request payload property "orgPathByCriteria" to the following API operations:
    • Create or Update Persons (POST /v1/commons/persons/multi_upsert)
    • Create Multiple Persons (POST /v1/commons/persons/multi_create)
    • Update Multiple Persons (POST /v1/commons/persons/multi_update)
    • Create Person (POST /v1/commons/persons)
    • Update Person by ID (PUT v1/commons/persons/{personId})
  • Enhanced the following API operations to allow retrieving employee and manager punches and approvals by the Associate Object ID (AOID) or a combination of the AOID and the Client Object ID (COID):
    • Retrieve Timecard as Employee (GET /v1/timekeeping/employee_timecard)
    • Retrieve Timecard as Manager (GET /v1/timekeeping/timecard)
    • Retrieve Timecard Approvals as Manager (GET /v1/timekeeping/timecard_approvals)

R8

The following changes were made to the API and Developer Hub in R8.

General

Announcements

Enhanced Timecard Metrics Responses with Starting Balance For Accrual Periods

The Retrieve Timecard Data for Multiple Employees (POST v1/timekeeping/timecard_metrics/multi_read) API operation has been enhanced with an additional object in the response body: startingBalanceForPeriod:

  "startingBalanceForPeriod": {
    "balanceDate": "2020-07-19T00:00:00",
    "vestedHoursAmount": 53.0667,
    "probationHoursAmount": 0
  }

Corrections and enhancements

The following conditions were corrected or enhanced:

  • Enhanced the documentation for the Create Labor Category Entries (POST /v1/commons/labor_entries/multi_create) API operation to note that entries are created as inactive by default unless the 'inactive' Boolean is set to 'false' for each entry.
  • The Retrieve Location Sets by List (POST /v1/commons/location_sets/multi_read) API operation only supported the expandJobs Boolean when searching by types and did not support this Boolean when searching by locationSets. The expandJobs Boolean is now supported when searching by either types or locationSets.
  • The Retrieve Locations (POST /v1/commons/locations/multi_read) API operation's example response model on the Developer Hub was missing the orgPath property. This property is now correctly reflected in the JSON model.
  • The Retrieve All Hyperfind Profiles (GET /v1/commons/hyperfind_profiles) API operation did not return the correct list of Hyperfind queries assigned to each of the Hyperfind profiles in the response body. The response now correctly lists the hyperfind queries assigned to each Hyperfind profile.
  • The Retrieve Engine Statuses (POST /v1/forecasting/engine_statuses/apply_read) API operation's documentation on the Developer Hub has been enhanced to clarify the type of date range needed for the request.
  • The Submit Bulk Download (POST /v1/commons/exports/async) API operation returned an incorrect and misleading error message when the Hyperfind specified in the request body contained an empty employee set. The error message returned in this scenario now correctly describes the cause of the error state.
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation would intermittently fail when processing large batches of employees. The root cause was identified and corrected.
  • The Retrieve User Preferences (GET /v1/commons/user_preferences) and Retrieve User Preferences for Current User (GET /v1/commons/user_preferences/locale_policy) API operations did not correctly return a user's locale policy when it differed from the tenant's default policy. These API operations now correctly return a user's default locale policy.
  • Ensured a default display profile is present in the system to prevent the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation from generating a nullPointerException error when passing persons with no defined preferenceProfileName in the request payload.
  • The Update Rule Set Assignments for Multiple Employees (POST /v1/commons/persons/schedule_rule_sets/multi_upsert) API operation returned an HTTP status code 500 Internal Server Error when either effectiveDate or expirationDate was missing from the request payload. The operation now returns an error message with the details needed to correct the request.
  • The Retrieve Schedule (POST /v1/scheduling/schedule/multi_read) API operation incorrectly triggered a service limit when requesting open shifts. The service limit no longer applies to calls against this operation that only request open shifts.
  • Enhanced the Shift Template Profile Assignments and Pattern Template Profile Assignments API resources (operations against /v1/commons/persons/shift_template_profiles and /v1/commons/persons/pattern_template_profiles) to allow the caller to specify "Empty" as well as "Empty Profile" to remove assignments. This allows the caller to use the same word shown in the UI when unassigning Shift Template Profiles and Pattern Template Profiles.
  • Due to a caching issue, the Create Time Off Request as Manager (POST /v1/scheduling/timeoff) API operation incorrectly returned an error when certain valid calls were made. The root cause was identified and corrected.
  • Bulk operations against the Labor Category Profiles API resource (POST /v1/commons/labor_category_profiles/multi_create, /v1/commons/labor_category_profiles/multi_update, and /v1/commons/labor_category_profiles/multi_delete) have been enhanced to include HTTP status code 207 Partial Success responses when activated with an optional query parameter.
  • Enhanced the Update Multiple Persons (POST /v1/commons/persons/multi_update) API operation to allow the caller to specify "Empty" as well as "Empty Profile" to remove the manager work rule. This allows the caller to use the same word shown in the UI when unassigning manager work rules.
  • The Bulk Delete Paycode Edits (POST /v1/timekeeping/pay_code_edits/multi_delete) API operation would sometimes fail when passing a very large number of IDs. The root cause was identified and corrected.
  • The Update Timecard as Manager (POST /v1/timekeeping/timecard) API operation incorrectly returned an HTTP status code 403 response even when certain calls successfully executed. The root cause was identified and corrected.
  • In certain circumstances, the Create Employee Time Off Request (POST /v1/scheduling/employee_timeoff) API operation would take much longer than intended to process. The root cause was identified and steps were taken to enhance response times.
  • Enhanced the following API operations to include a timeout query parameter:
    • Create Time Off Request as Manager (POST /v1/scheduling/timeoff)
    • Update Time Off Request as Manager (POST /v1/scheduling/timeoff/apply_update)
    • Update Employee Time Off Request (POST /v1/scheduling/employee_timeoff/apply_update)
  • Due to a caching issue, the Update Certification Assignments (POST /v1/commons/persons/certifications/multi_upsert) API operation would intermittently fail and throw an error. The root cause was identified and corrected.

Docs updates

The following changes were made to the conceptual documentation:

API updates

The following changes were made to the reference documentation:

  • Edits throughout to enhance clarity, add detail, and correct errors and omissions

R7 Update 4

The following changes were made to the API and Developer Hub in R7 Update 4.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Retrieve Activities (POST /v1/work/activities/multi_read) API operation's request payload model in the Developer Hub was missing the required 'where' property. The process used to generate this model has been corrected to ensure the missing property is now included.
  • Enhanced the Submit Bulk Download (POST /v1/commons/exports/async) API operation's documentation to include a full request model as well as example requests and responses.
  • Enhanced the Schedule Group Profile Assignments API resource (operations against /v1/commons/persons/schedule_group_profiles) to allow the caller to specify "Empty" as well as "Empty Profile" to remove assignments. This allows the caller to use the same word shown in the UI when unassigning Schedule Group Profiles.
  • The Bulk Accrual Reset (POST /v1/timekeeping/accruals/resets) API operation would intermittently fail with an HTTP status code 400 error. The root cause was identified and corrected.
  • The Create or Update Persons (POST v1/commons/persons/multi_upsert) API operation did not accept employee hours between 0.01 and 1.0. This operation now accepts all employee hours greater than 0.01.
  • The Create or Update Persons (POST v1/commons/persons/multi_upsert) API operation intermittently threw an "Illegal invocation of method" error. The root cause was identified and corrected.
  • In certain circumstances, the Retrieve Schedule (POST /v1/scheduling/schedule/multi_read) API operation returned a Null Pointer Exception error. The root cause was identified and corrected.
  • The Create or Update Wage and Work Rule Overrides (POST /v1/commons/persons/wage_work_rules/multi_upsert) API operation did not properly validate that the job passed for a wage override was a job and not a location on the Business Structure. The operation now properly validates that the nodes passed in this property are in fact jobs.
  • The Update Shift Cover Request (POST /v1/scheduling/employee_cover_requests/apply_update) API operation incorrectly generated an 'invalid where parameter' error with certain request subtype configurations.
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation would sometimes incorrectly fail when including the 'predictiveSchedulingEligibilityList' property for a new person record. The root cause of the failure has been identified and corrected.
  • The Retrieve Sorted or Eligible Employees (POST /v1/scheduling/staffing_assistant/apply_read) API operation has been enhanced with an optional parameter 'includeTransferEmployees' that allows this operation to include transfer employees as part of its search criteria.
  • The Update Schedule for Multiple Employees (POST /v1/scheduling/schedule/multi_update) API operation would not generate a correct partial success response body (when the optional partial_success Boolean was set to 'true') when an incorrect shift segment type was specified in the request payload.
  • The Create Labor Category Entries (POST /v1/commons/labor_entries/multi_create) API operation was updated to normalize trailing space handling between the UI and the API.
  • The Retrieve All Percentage Allocation Rules (GET /v1/timekeeping/setup/percentage_allocation_rules) API operation was enhanced to improve performance for calls that return a large number of results.

Docs updates

The following changes were made to the conceptual documentation:

API updates

The following changes were made to the reference documentation:

  • Enhanced the documentation for the Submit Bulk Download (POST /v1/commons/exports/async) API operation to include additional enumerations, an example request body, to point out that the payLoad property wraps a Retrieve Data (POST /v1/commons/data/multi_read) request payload, and to point to the new conceptual topic Submit Bulk Download examples, which provides request and response schemas and example request and response bodies.
  • Enhanced the documentation for the Retrieve Currency Definition by ID (GET /v1/commons/currency/definitions/{id}) and Retrieve All Currency Definitions (GET /v1/commons/currency/definitions) API operations to add response body examples.
  • Enhanced the documentation for the Retrieve Employee Schedule Changes (POST /v1/scheduling/schedule/changes/multi_read) API operation to add Best Practices and an example call.
  • Deprecated the Import Labor Forecasts (POST /v1/forecasting/labor_forecast/import) API operation. Instead, use Create Labor Forecasts (POST /v1/forecasting/labor_forecast/multi_create).
  • Enhanced the documentation of and added Best Practices to the following Forecasting operations:
    • Import Labor Standards, Tasks, and Task Groups (POST /v1/forecasting/labor_standard_tasks/import)
    • Create Labor Forecasts (POST /v1/forecasting/labor_forecast/multi_create)
    • Update Adjustment Drivers (POST /v1/forecasting/adjustment_drivers/multi_upsert)
    • Import Volume Forecast (POST /v1/forecasting/volume_forecast/import)
    • Import Labor Budgets (POST /v1/forecasting/labor_budget/import)
    • Import Volume Budgets (POST /v1/forecasting/volume_budget/import)
    • Import Actual Volume (POST /v1/forecasting/actual_volume/import)

R7 Update 3

The following changes were made to the API and Developer Hub in R7 Update 3.

General

Announcements

Spike arrest feature

We are enhancing API authentication to improve service reliability in R7 Update 3.

API operations are controlled by a throttling limit which prevents clients from making too many requests in a short time. API authentication is not currently constrained by these mechanisms, which has negatively impacted service reliability. When a customer application requests a new authentication token for every API call, it can overload the authentication servers and prevent authentication tokens from being issued to other customers.

We are implementing a REST-compliant spike arrest feature which temporarily blocks authentication requests when too many requests are received too quickly.

How will this affect your applications?

If your applications are coded to REST standards, they should correctly handle the spike arrest feature without any changes.

How will the API behave when a spike arrest occurs?

The API will return an HTTP status code 503 "Service Unavailable" error when a spike arrest occurs.

HTTP 503
{
              "errorCode": "GTW-ERROR-012",
              "message": "The request was rejected due to a spike in requests for access tokens. Resubmit your request after a brief wait.”
}

This 503 response will include a “Retry-After” header that indicates the number of seconds to wait before resubmitting the request.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Create or Update Hours of Operation Assignments API operation (POST /v1/commons/hours_operation_assignments/multi_upsert) would allow a new assignment to overlap and erase an existing assignment. Added a new Boolean 'allowOverlappingOverride' request parameter that, when set to false, allows the operation to behave like the UI and throw an error if the assignment specified in the request overlaps an existing assignment.
  • The Delete Leave Edits API operation (POST /v1/leave/leave_edits/multi_delete) could cause the system to slow down when processing a Leave Case with no defined end date. Protections were added to ensure such leave cases are processed quickly.
  • Enhanced the Minor Rule Sets API operations (GET /v1/scheduling/minor_rule_sets, GET /v1/scheduling/minor_rule_sets{id}, and POST /v1/scheduling/minor_rule_sets/multi_read) to return more information via an optional query parameter 'all_details' or request body property 'allDetails'.
  • The Bulk Retrieve Workload Patterns API operation (POST /v1/scheduling/workload_patterns/multi_read) would sometimes fail with an unknown error. The root cause of these errors was identified and corrected.
  • Enhanced the Update Certification Assignments API operation (POST /v1/commons/persons/certifications/multi_upsert) to add a 'preserve_existing_assignments' query parameter, which allows the caller to optionally send only new and updated assignments rather than a full list of all assignments.
  • Enhanced the Retrieve Time Off Requests as Manager and the Retrieve Time Off Request by ID as Manager API operations (POST /v1/scheduling/timeoff/multi_read and GET /v1/scheduling/timeoff/{timeOffRequestId}) to add an 'includeOverriddenShifts' request property and an 'include_overridden_shifts' query parameter, respectively. These new Booleans allows the caller to include overridden shifts in the response.
  • The Update Attestation Profile Assignments by Person Number API operation (POST /v1/commons/persons/attestation_profile_assignments/multi_update) would incorrectly throw a 500 Internal Server Error response if an effective date after the system-default "forever date" of 3000-01-01 was specified, preventing 207 Partial Success processing. The operation now provides graceful error handling of "after forever" effective dates.
  • The Bulk Accrual Reset API operation (POST /v1/timekeeping/accruals/resets) returned a successful response body containing 'null' when an incorrect date format was supplied in the request payload. The operation now throws a detailed error message when an invalid date format is specified.
  • The Retrieve Timecard Data—Multiple Employees API operation (POST /v1/timekeeping/timecard_metrics/multi_read) would, in certain circumstances, incorrectly apply transfer continuation logic, causing schedule totals that did not match the employee's schedule.
  • In certain circumstances, changing the name of a primary labor category would not correctly populate the new name in People Information and the response body of the Retrieve Persons API operation (POST /v1/commons/persons/extensions/multi_read).
  • Enhanced the Adjustment Rule Assignments API resource and all associated operations (all methods against /v1/commons/persons/adjustment_rule/*) to accept -1 as an ID representing an Empty Profile, and added the property 'adjustmentRule' to the request bodies of POST operations that also accepts the new ID for Empty Profile.

Docs updates

The following changes were made to the conceptual documentation:

  • Added a Create open shifts Tip to the Best practices and tips topic demonstrating an efficient way to create multiple open shifts with a single API operation.

R7 Update 2

The following changes were made to the API and Developer Hub in R7 Update 2.

General

Announcements

  • The Create Paycode Edits with Options (POST /v1/scheduling/schedule/pay_code_edits/import) API operation has been deprecated and replaced by the POST /v1/scheduling/schedule/pay_code_edits/apply_import operation.
  • Updated the Retrieve Timecard Data—Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation to add a new, optional 'rollUpByJobId' Boolean to the request body. When set to true, job totals are rolled up based only on the job ID and the operation will not take into account changes in the job path across the specified date range. This property defaults to false and is fully backwards compatible.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • Several Forecasting API operations, including Retrieve Labor Budgets (POST /v1/forecasting/labor_budget/apply_read), incorrectly threw a null pointer exception rather than a detailed error message when a location's expiration date occurred before the end date of the period specified in the request payload. These API operations now provide a descriptive error message.
  • Enhanced the Retrieve Timezone (GET /v1/commons/setup/timezones) API operation to add the 'fullDisplayName' property to the response body. This property returns a longer timezone name format that is consistent with the timezone naming convention used elsewhere in the API.
  • Enhanced the Retrieve Comments for Manager (GET /v1/commons/comments) and Retrieve Comments for Employee (GET /v1/commons/comments/employee_comments) API operations to support returning all category types when the user calling the API has the correct permissions.
  • The Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation did not return home cost center information along with primary job and labor category information. This operation has been enhanced to include cost center information.
  • The Create Paycode Edits (POST /v1/scheduling/schedule/pay_code_edits/multi_create) API operation did not correctly mark days as unavailable when using an appropriate paycode, such as "Time Off Unavailable." The operation now correctly marks such days as unavailable.
  • When reviewing an employee's audit tab in Schedule Planner or calling the Retrieve Schedule Audits (POST /v1/scheduling/audits/multi_read) API operation, a "work rule not found" error could be incorrectly returned instead of valid audit data. The system now gracefully handles audit queries that include deleted work rules.
  • In certain situations, the Bulk Accrual Reset (POST /v1/timekeeping/accruals/resets) API operation would return a CT Call error message that did not correctly replace the 'Message' variable with detailed error information. CT Call error messaging is now generated correctly.
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation did not have a parameter that allows a caller to unassign "Labor Category Profile - Manager Additions". The new parameter 'unassignMgrEmplLaborCategoryProfile' was added to enable this functionality.
  • The Bulk Delete Paycode Edits (POST /v1/timekeeping/pay_code_edits/multi_delete) API operation incorrectly allowed edits to signed-off periods. Such edits are no longer allowed.

Docs updates

The following changes were made to the conceptual documentation:

  • Updated product language to conform to new naming guidelines for our products.
  • Documented a significant number of new service limits for assignments, common resources, and Timekeeping operations. Refer to the Service limits topic for more information.

R7 Update 1

The following changes were made to the API and Developer Hub in R7 Update 1.

General

Announcements

Global Multiple Manager Role Switching Support

A logged-in manager who has two or more Multi-Manager Roles (Role Assignments) can switch between assigned roles using any API operation by adding the global, optional query parameter roleId. For example:

POST /v1/commons/persons/51?roleId=221
POST /v1/scheduling/schedule/pay_code_edits/multi_create?roleId=221

Refer to the Global Multiple Manager Role Switching topic for more information.

Predictive Scheduling and the Persons API resource

In R7, the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation began validating the Predictive Scheduling System Setting when the predictiveSchedulingEligibilityList property was passed in the request payload. Prior to R7, this validation did not occur. To ensure backwards compatibility, the validation introduced in R7 has been removed, and request payloads with this property included will not fail when the Predictive Scheduling system is not enabled.

Enhanced Accrual Warning Support in the Create Paycode Edits with Options operation

The Create Paycode Edits with Options () API operation has been enhanced with a new optional Boolean request property: errorOnAccrualWarning. This Boolean defaults to false.

When this property is true, the operation throws an error if an accrual warning occurs. Note that this property interacts with the existing property: bypassAccrualValidation. If bypassAccrualValidation is true, the errorOnAccrualWarning property is ignored.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Create Employment Terms PCEs (POST /v1/scheduling/employment_terms_schedule/pay_code_edits/apply_create) API operation incorrectly required a primary job to be specified in the request even when the employee already had a valid primary job.
  • The Update Attendance Profile for Multiple Employees (POST /v1/commons/persons/attendance_profile/multi_update) API operation incorrectly generated an error when the consumer attempted to assign an Empty Profile. The ability to assign an Empty Profile has been restored.
  • When the Update Values for Multiple Custom Drivers (POST /v1/forecasting/custom_driver_values/multi_upsert) API operation encountered an error while processing a record and generated an HTTP status code 400 or 207 Partial Success response, the error offsets were not specified in the response body. Error offsets are now included.
  • In certain circumstances, the Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation failed to correctly return valid, existing employees. The operation now correctly returns all valid employees.
  • In rare circumstances, the Submit Bulk Download (POST /v1/commons/exports/async) API operation could become stranded during execution of the asynchronous request and incorrectly respond with an HTTP status 413 error. The operation now handles these circumstances gracefully.
  • The Create or Update Known Places (POST /v1/commons/known_places/multi_upsert) and Create Known Places (POST /v1/commons/known_places/multi_create) API operations incorrectly required the location ID to be specified when a valid qualifier for that location was included in the request payload. Calls specifying locations with valid qualifiers (and no IDs) now execute correctly.
  • In R7, the Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation began validating the Predictive Scheduling System Setting when the predictiveSchedulingEligibilityList property was passed in the request payload. Prior to R7, this validation did not occur. To ensure backwards compatibility, the validation introduced in R7 has been removed, and request payloads with this property included will not fail when the Predictive Scheduling system is not enabled.
  • The Retrieve Requestable Open Shifts (POST /v1/scheduling/employee_open_shift_requests/open_shifts/multi_read) API operation now returns a clear error message instead of a null pointer exception when a resource is not found.
  • The Update Workload Weights or Update, Lock, or Unlock Workload Volumes (POST /v1/scheduling/volume/apply_update) API operation now handles certain error conditions gracefully and no longer throws a null pointer exception.
  • The Retrieve Shift Cover Requests (POST /v1/scheduling/employee_cover_requests/multi_read) API operation incorrectly returned a null value for the recipient qualifier. The operation now returns the correct value.
  • The Update Rule Set Assignments for Multiple Employees (POST /v1/commons/persons/schedule_rule_sets/multi_upsert) API operation incorrectly returned an error when the start of an assignmentSpan was equal to the effectiveDate.
  • The Create Employment Term Schedule Pattern (POST /v1/scheduling/employment_term_schedule_patterns/apply_create) and the Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create) API operations did not provide resubmittable request payloads inside HTTP status code 207 Partial Success response bodies. These operations have been enhanced with an optional query parameter that allows fully resubmittable request payloads to be passed inside 207 responses.
  • Harmonized behavior between the UI and the Update Certification Assignments (POST /v1/commons/persons/certifications/multi_upsert) API operation such that they both accept an end date of 3000-01-01.
  • The Retrieve Schedule Audits (POST /v1/scheduling/audits/multi_read) API operation has been enhanced to include HTTP status code 207 Partial Success responses when activated with an optional query parameter.
  • The Person API operations, such as Create or Update Persons (POST /v1/commons/persons/multi_upsert), incorrectly allowed inactive Labor Category Entries to be used as Primary Job assignments. Attempting to specify an inactive Labor Category Entry as a Primary Job assignment now results in a error.
  • The Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation now correctly rounds hoursAmount inside the actualTotals array.
  • The Paycodes for Timekeeping API resource (including operations such as Retrieve Paycodes as Manager (GET /v1/timekeeping/setup/pay_codes)) did not return the analyticCategoryAssignments object in the response even though this object appeared in the response model on the Developer Hub. Operations against this API resource now correctly return this object.
  • The Bulk Import Paycode Edits (POST /v1/timekeeping/pay_code_edits/import) API operation did not allow paycode edits to be imported without associating a time of day with the edit. This operation has been enhanced to allow the following:
    1. specify applyDate only
    2. specify startDateTime only
    3. specify both startDateTime and applyDate
    • If both startDateTime and applyDate are specified, they must be the same date or the request results in an error.
  • The Retrieve Timecard as Employee (GET /v1/timekeeping/employee_timecard) and Retrieve Timecard as Manager (GET /v1/timekeeping/timecard) API operations incorrectly threw HTTP status code 500 Internal Server Error responses when an invalid selection was specified in the "select" query parameter. These API operations now throw the correct error.
  • The Retrieve Employee Groups (POST /v1/commons/employee_groups/multi_read) API operation did not return the laborCategoryProfileRef and orgMapGroupRef properties in the response even though they appear in the response model on the Developer Hub. Operations against this API resource now correctly return these properties.
  • Operations against the Timecard API resource, such as Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read), were not always correctly handling auto-resolved exceptions, and the operations would fail. These operations now correctly handle auto-resolved exceptions.
  • The Create Labor Category List Assignments (POST /v1/commons/labor_category_list_assignments/multi_create) API operation incorrectly threw "An Internal Error Has Occurred" when the specific orgNode qualifier was not valid. The operation now responds with a specific error description.
  • The Update Labor Category Lists (POST /v1/commons/labor_category_lists/multi_update) API operation incorrectly threw "An Internal Error Has Occurred" when the entryList array was ommitted from the request payload. The operation now responds with a specific error description.
  • The Bulk Accrual Payout (POST /v1/timekeeping/accruals/payouts) API operation did not allow increments of less than 1, which does not match the way the Accrual Policy behaves. The API behavior now allows incremements of less than 1.
  • The Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation would refuse to return paycode edit data that involved end-dated business structure locations. The operation now correctly returns the data.
  • The Retrieve Activity Totals for Multiple Employees (POST /v1/work/activity_totals/multi_read) API operation did not always return all valid Work activity totals. Totals are now returned correctly.

Docs updates

The following changes were made to the conceptual documentation:

  • Changed the format of the Important Notes and Version History topics. The releases are now sorted from newest to oldest.
  • Added the Global Multiple Manager Role Switching topic, which allows any logged-in manager with more than one manager role to switch between those roles in any API call.
  • Added A Guide to Timekeeping to the Guides section.
  • We are reworking the Quick Start tutorial to better serve the more mature API platform. More information will be available soon!

R7

The following changes were made to the API and Developer Hub in R7.

General

Announcements

An Important Note on Correcting Insecure Token Generation

An undocumented, insecure method for generating tokens for API calls has been identified and will be removed in a future release.

If you have any apps that are generating tokens for API calls by passing the required details as query parameters, you must update them to pass those details as form data in the request payload using the secure process described in the Authentication and security topic.

An Important Note Concerning a Deprecated Boolean in Review Notifications by ID

In the request payload model for the Review Notifications by ID (POST /v1/commons/notifications/multi_review) API operation, the Boolean property reviewForAll has been deprecated and no longer performs any function. Previously, this property could be used to review notifications for other managers. After review it was determined that this was not working as designed and posed a potential security issue, so the functionality has been removed.

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Update Attendance Admin—Multiple Employees (POST /v1/commons/persons/attendance_admin/multi_update) API operation incorrectly returned an HTTP status code 500 Internal Server Error when an invalid Person Number is specified in the request. The API response now returns an informative error message that explicitly tells the caller than the passed Person Number is invalid.
  • The Retrieve Persons (POST /v1/commons/person/extensions/multi_read) API operation incorrectly returned an HTTP status code 400 error mentioning an "Internal Server Error" in the message body when an employee is set to inactive for both the user account and employee status and the "onlyActivePerson" Boolean is set to true. This error prevented the API from continuing to process other employees in the request (if other valid employees exist) and producing an HTTP status code 207 Partial Success response. This API operation now correctly processes this error condition and allows HTTP status code 207 or 400 responses, as appropriate.
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) and Update Person by ID (PUT /v1/commons/persons/{personId}) API operations incorrectly allowed a call to set the expiration date to a date before the effective date for the primary job. These API operations now throw an error if the caller attempts to set an expiration date prior to the effective date.
  • The Retrieve Schedule Zone Set Assignments (POST /v1/scheduling/schedule_zone_sets/assignments/multi_read) API operation failed to return updated versions of certain location paths after those paths changed. The API operation now correctly returns updated location paths.
  • The Update Location by ID (POST /v1/commons/locations/{id}) and Update Locations (POST /v1/commons/locations/multi_update) API operations did not always update the externalId property. This API operation now correctly updates the externalId when specified in an update request.
  • The Update Schedule—Multiple Employees (POST v1/scheduling/schedule/multi_update/?partial_success=true) API operation with Partial Success enabled passed an incorrect error message when the call failed due to an overdrawn leave balance. The API now returns a correct and meaningful error.
  • The Retrieve Tag Definitions with Criterion (POST /v1/scheduling/setup/tag_definitions/multi_read) API operation incorrectly returned deleted tags in the response. Deleted tags are no longer returned.
  • The Create Employee Time Off Request (POST /v1/scheduling/employee_timeoff) API operation in certain rare conditions would prevent an employee's time-off requests submitted via the API from displaying in a manager's control center notifications. Time off requests submitted through the API now consistently display in the control center.
  • The Update Labor Forecasts (POST /v1/forecasting/labor_forecast/multi_update) API operation has been enhanced to include support for Partial Success responses when activated by means of a new query parameter.
  • The Retrieve Unapproved Timecard Data (GET /v1/timekeeping/attestation_unapproved_timecard_data) API operation returned no data for an employee during any period approved by the employee's manager. The API operation now correctly returns relevant data when the timecard has not been approved by the employee.
  • The Update Attestation Profile Assignments by Person Number (POST /v1/commons/persons/attestation_profile_assignments/multi_update) API operation incorrectly returned an HTTP status code 500 Internal Server Error in certain situations when an employee's attestation profile assignment is updated. The updated assignments not process correctly.
  • The Move Accrual Balances—Multiple Employees (POST /v1/timekeeping/accruals/moves) API operation understands time in terms of minutes, not decimal values, and in situations where the passed decimal value of the accrual move amount does not correspond precisely to a minute value, the passed value is rounded down to the nearest decimal that corresponds to a minute. However, the API response was incorrectly returning the decimal value passed in the request body, not the rounded-down value actually processed by the system. The response body now correctly returns the rounded value, as appropriate.
  • Updated the Retrieve Percentage Allocation Rules-Multiple Employees (POST /v1/commons/persons/percentage_allocation_rules/multi_read) API operation to add the Boolean property 'failOnNoAssignment'. When set to false, the operation does not send an HTTP status 400 error when the person queried has no assignments.
  • In the unlikely event that you exceed throttling limits or the system is too busy to process a request, a Retry-After header has been added to HTTP status code 429 and 503 responses.
    • When Retry-After is returned with an HTTP status code 503 (Service Too Busy) response, the header indicates how long the service is expected to be unavailable. Your app should only make an automatic attempt to retry if the Retry-After is present in the response; if it is absent, your app should not automatically retry.
    • When Retry-After is returned with an HTTP status code 429 (Too Many Requests) response, the header indicates how long to wait before making a new request.
  • When a user's locale policy was set to Mexican Spanish, the following API operations did not accept localized strings for the "contactTypeName" property within the "emailAddresses" array. This property was updated to accept "Trabajo" or "Work".
    • Update Person by ID (PUT /v1/commons/persons/{personId})
    • Create Person (POST /v1/commons/persons)
    • Create or Update Persons (POST /v1/commons/persons/multi_upsert)
    • Create Multiple Persons (POST /v1/commons/persons/multi_create)
    • Update Multiple Persons (POST /v1/commons/persons/multi_update)
  • The Update Availability Request State as Manager (POST /v1/scheduling/manager_availability_requests/apply_update), Update Shift Swap Request as Manager (POST /v1/scheduling/manager_swap/apply_update), and Update Open Shift Request (POST /v1/scheduling/open_shift_requests/apply_update) API operations now allow a manager to approve an employee's availability, shift swap, or open shift requests when that employee is part of that manager's Employee Group unless a reviewer list is set up for the applicable request subtype, in which case the manager must be part of the reviewer list.
  • The Update Skill Assignments (POST /v1/commons/persons/skills/multi_upsert) API operation incorrectly generated an error when adding a skill to an employee who had been terminated but is configured in the system to be re-hired on the date that the configured termination time span ends. Such skill assignments can now be applied without error.
  • When using the Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create) API operation to create a schedule pattern with an override ("override" : true), the system incorrectly returned an HTTP status 200 success response code but a JSON body containing an error, and did not apply the pattern. The system now returns a correct response body and successfully applies the pattern.
  • Added partial success support to the following API operations:
    • Retrieve Timecard Data–Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read)
    • Retrieve Timecards–Manager (POST /v1/timekeeping/timecard/multi_read)
    • Retrieve Timecards–Employee (POST /v1/timekeeping/employee_timecard/multi_read)
  • The Update Employment Term Assignments (POST /v1/commons/persons/employment_terms/multi_upsert) API operation generated an incorrect error message when the employment term referenced in the request payload did not exist. The API now passes a correct error message.
  • Under certain conditions, the Retrieve Timecard Data–Multiple Employees (POST v1/timekeeping/timecard_metrics/multi_read) API operation would not correctly pass a vacation pay code edit even when that edit is visible on the timecard in the UI. The API now correctly displays such pay code edits.
  • The Create or Update Location Set (POST /v1/commons/location_sets/apply_upsert) API operation incorrectly returned an HTTP status 400 instead of HTTP status 207 for a Partial Success response. This API operation now returns an HTTP status code 207 for Partial Success responses.
  • In certain circumstances, the Revoke a Token (POST /authentication/token/revoke) API operation did not invalidate the specified token. This API operation now correctly invalidates tokens in all circumstances.
  • The Evaluate Workload (POST /v1/scheduling/workload_coverage/workload/multi_read) API operation incorrectly returned an HTTP status 400 error when the number of processed IDs exceeded 32,768.
  • The Retrieve Schedule Pattern by Name (GET /v1/scheduling/schedule_pattern_templates) and Retrieve Schedule Patterns (POST /v1/scheduling/schedule_pattern_templates/multi_read) API operations occasionally returned HTTP status 200 SUCCESS with an empty array even when valid data existed. These API operations now consistently return the correct data.
  • When creating or updating a report using the following API operations, the reportOutputFormat property did not correctly validate and use the passed ID before validating and using the qualifier. The API now correctly validates the ID and, if valid, the qualifier is not validated or used in any way.
    • Save Report (POST /v1/platform/reports)
    • Update Report by ID (POST /v1/platform/reports/{id})
  • The Update Timecard—Manager (POST /v1/timekeeping/timecard) API operation did not recognize the property "reviewed". The API now accepts either "reviewed" or "isReviewed" in the request payload.
  • The Create Labor Category Profiles (POST /v1/commons/labor_category_profiles/multi_create) API operation incorrectly returned an HTTP status code 404 response when a labor category that does not exist is specified in the request. Added a query parameter that, when set to true, converts HTTP status response code 404 to 400 when the error is a result of a missing labor category.
  • The Retrieve Absence Spans (POST /v1/timekeeping/absence_spans/multi_read) API operation would not return the correct duration in certain cases.
  • The Create Employment Term (POST /v1/timekeeping/setup/employment_terms) API operation would incorrectly require a paycode to be specified in the request payload when the same operation performed through the UI did not require a paycode.

Docs updates

The following changes were made to the conceptual documentation:

  • Added the Aggregated Person Assignments topic to A Guide to People Information. Don't miss this powerful new API resource.
  • Added the Manage UI sessions topic to the Authentication and security section, including a new API that allows you to log out a specified UI session.
  • Updated the person assignment API topics to note that, for effective-dated person assignment updates, you must pass in the request payload any current forever-dated assignment with an explicit end date along with the new assignment with a defined start date. If you pass a new forever-dated assignment and a different forever-dated assignment already exists, the new assignment will replace the existing assignment. Refer to the Person assignments topic and subtopics for more information.
  • Various edits and changes to improve usability of the Developer Hub content.

API updates

The following changes were made to the reference documentation:

New Organization

  • Moved the Timekeeping Setup API operations into a new top-level domain named Timekeeping Setup.
  • Split the Common Resources top-level domain into two new top-level domains named Common Resources I and Common Resources II.
    • Common Resources I contains all of the API resources that used to have Common Resources as their direct parent in the navigation tree.
    • Common Resources II contains all of the subdomains within Common Resources that have API resources as children in the navigation tree.

Important New Content

  • Be sure to check out the powerful new Aggregated Person Assignments API resource under People, which allows you to consolidate the management of most person assignments. You can retrieve one or more person's assignments, update, add, or delete assignments for multiple people, and retrieve the names of all available aggregated assignments.

Other Updates

  • Updated the list of enumerations for the Retrieve Timecards select property. This update affects:
    • Retrieve Timecards-Manager (POST /v1/timekeeping/timecard/multi_read)
    • Retrieve Timecards-Employee (POST /v1/timekeeping/employee_timecard/multi_read)
  • Added the full list of enumerations for the Retrieve Timecard select query parameter. This update affects:
    • Retrieve Timecard-Manager (GET /v1/timekeeping/timecard)
    • Retrieve Timecard-Employee (GET /v1/timekeeping/employee_timecard)
  • Updated the Timecard Metrics resource by enhancing Retrieve Timecard Data—Multiple Employees API operation documentation and by adding descriptions of each possible select parameter.
  • Enhanced the Process Leave Requests (POST /v1/leave/leave_requests/multi_action) and Process Leave Request by ID (POST /v1/leave/leave_requests/{id}) documentation to explicitly list all possible actions.
  • Enhanced the Retrieve Location Sets by List (POST /v1/commons/location_sets/multi_read) documentation to explicitly list all available org map group types.
  • Enhanced the Update Employee Open Shift Request (POST /v1/scheduling/employee_open_shift_requests/apply_update) documentation with all valid enumerations for the event property.
  • Enhanced the documentation for the following two API operations to mention the new Test Mode feature, implemented by passing an ID of -1:
    • Update Integration Execution Details (POST /v1/platform/integrations/update_status)
    • Submit Integration Execution Additional Details (POST /v1/platform/integration_executions/{id}/additional_details)

R6 Update 4

The following changes were made to the API and Developer Hub in R6 Update 4.

General

Announcements

An Important Note on startTime and endTime in Employee Extensions

In the first public R6 Release of (06.04.00), an enhancement was made to add startTime and endTime to the effective-dated entries for the badgeDetails object in the Retrieve Person by Extension (GET /v1/commons/persons/{extensionType}) operation.

As part of this work, a defect was introduced which caused startTime and endTime to be added to the response for all effective-dated entries across many of the extensions.

The invalid startTime and endTime returned are always "00:00:00" and "23:59:59" respectively. These values do not actually exist on the effective-dated properties in the employee extensions. They are erroneously added to the response body's JSON. They have no effect on any of the affected extension properties.

In R6 Update 4 (06.08.00), we are removing the invalid startTime and endTime values from all extensions (with the exception of badgeDetails, where they are valid).

Any effective-dated entries included in these extensions will have these erroneous startTime and endTime properties removed.

Important: The badgeDetails object in deviceExtension is the only property where startTime and endTime are valid. startTime and endTime will not be removed from the badgeDetails object.

The invalid instances of startTime and endTime should not be consumed by any API-based application. These values should be ignored and any applications that have begun consuming these new values should be modified to ignore them.

Affected API operations:

  • Retrieve Persons (POST /v1/commons/persons/extensions/multi_read)
  • Retrieve Person by Extension (GET /v1/commons/persons/{extensionType})
  • Retrieve All Extensions (GET /v1/commons/persons/extensions)

Extensions Impacted:

  • accountStatusDataExtension
  • accrualProfilesDataExtension
  • accrualProfilesDataExtensionNew
  • accrualProfilesDataExtensionNew
  • baseWageDataExtension
  • dataAccessExtension
  • employmentAnalyticsLaborTypeDataExtension
  • employmentStatusDataExtension
  • employmentTermDataExtension
  • fullTimeEquivalencyDataExtension
  • groupAssignmentDataExtension
  • jobTransferDataExtension
  • payRuleDataExtension
  • predictiveSchedulingEligibilityDataExtension
  • primaryJobAccountDataExtension

Example of Erroneous Entries:

  "employeeExtension": {
    "effDatedAccountStatuses": [
      {
        "accountStatus": "Active",
        "accountStatusTypeId": 1,
        "effectiveDate": "2016-08-13",
        "endTime": "23:59:59",    // invalid endTime
        "expirationDate": "3000-01-01",
        "startTime": "00:00:00"    // invalid startTime
      }
    ],
    "effDatedPrimaryJobAccountEntries": [
      {
        "effectiveDate": "2016-08-13",
        "endTime": "23:59:59",    // invalid endTime
        "expirationDate": "2019-01-01",
        "primaryJob": "Organization/United States/Metropolitan Plant/Machine Shop/Apprentice Welder",
        "primaryLaborCategory": ",,Shift 1,,,",
        "primaryLaborCategoryId": 2,
        "primaryOrganizationId": 35,
        "startTime": "00:00:00"    // invalid startTime
      }
    ],
    "employmentStatuses": [
      {
        "effectiveDate": "2016-08-13",
        "employmentStatus": "Active",
        "employmentStatusTypeId": 1,
        "endTime": "23:59:59",    // invalid endTime
        "expirationDate": "3000-01-01",
        "startTime": "00:00:00"    // invalid startTime
      }
    ]
  }

Corrections and enhancements

The following conditions were corrected or enhanced:

  • Calling the Create or Update Volume Driver Assignments (POST /v1/forecasting/volume_driver_assignments/multi_upsert) API operation multiple times completed successfully for most of the specified records, but sporadically failed with a NullPointerException error. Repeated operations against this resource should now succeed without error.
  • The Submit Bulk Downloads (POST /v1/commons/exports/async) API operation was incorrectly restricted by service limits implemented by other domains, but is now only restricted by the proper Information Access service limits. Refer to the Service limits topic for more information.
  • When a Leave of Absence case was configured to commit the leave time to the schedule, the Create Leave Edits (POST /v1/leave/leave_edits) API operation still committed leave time in the timecard.
  • The Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation would sometimes return records without the firstName and lastName properties. The operation now consistently returns these properties.
  • The Retrieve Locations API operation (POST /v1/commons/locations/multi_read) sometimes returned an error message instead of the requested root location.
  • The Evaluate Metrics for Scheduling API operation (POST /v1/scheduling/schedule_metrics/multi_read) sometimes returned a value of 0 instead of the correct value.
  • When the Bulk Import Punches API operation (POST /v1/timekeeping/punches/import) was called with an override specified only by qualifier, the call would fail. The call now works with either ID or qualifier for the override.
  • The Update Attestation Profile Assignments by Person Number API operation (POST /v1/commons/persons/attestation_profile_assignments/multi_update) was not correctly processing request payloads in a way that allowed for partial successes when multiple entities were passed.
  • During some calls to the Retrieve Data API operation (POST /v1/commons/data/multi_read), a multi-threading error occurred.
  • The Create Employment Term API operation (POST /v1/timekeeping/setup/employment_terms) was not correctly validating properties in the request payload.
  • The Create Employment Term and Update Employment Term API operations (POST /v1/timekeeping/setup/employment_terms and PUT /v1/timekeeping/setup/employment_terms/{id}) were missing three modifiable properties in the request body schema:
    • Minimum Wage
    • Contributing Pay Codes
    • Pay Code for Adjustment

Docs updates

The following changes were made to the conceptual documentation:

API updates

The following changes were made to the reference documentation:

  • Removed the invalid startTime and endTime values from all Person extensions (with the exception of badgeDetails, where they are valid). Refer to the Announcements for more details.
  • Added the extend_all_activities_query query parameter to Retrieve Activity by Name (GET /v1/work/activities)
  • The existing Timekeeping > Paycodes—Timekeeping operations have been enriched with additional properties.

R6 Update 3

The following changes were made to the API and Developer Hub in R6 Update 3.

General

Announcements

An Important Note on startTime and endTime in Employee Extensions

In the first public R6 Release of (06.04.00), an enhancement was made to add startTime and endTime to the effective-dated entries for the badgeDetails object in the Retrieve Person by Extension (GET /v1/commons/persons/{extensionType}) operation.

As part of this work, a defect was introduced which caused startTime and endTime to be added to the response for all effective-dated entries across many of the extensions.

The invalid startTime and endTime returned are always "00:00:00" and "23:59:59" respectively. These values do not actually exist on the effective-dated properties in the employee extensions. They are erroneously added to the response body's JSON. They have no effect on any of the affected extension properties.

In R6 Update 4 (06.08.00), we are removing the invalid startTime and endTime values from all extensions (with the exception of badgeDetails, where they are valid).

Any effective-dated entries included in these extensions will have these erroneous startTime and endTime properties removed.

Important: The badgeDetails object in deviceExtension is the only property where startTime and endTime are valid. startTime and endTime will not be removed from the badgeDetails object.

The invalid instances of startTime and endTime should not be consumed by any API-based application. These values should be ignored and any applications that have begun consuming these new values should be modified to ignore them.

Affected API operations:

  • Retrieve Persons (POST /v1/commons/persons/extensions/multi_read)
  • Retrieve Person by Extension (GET /v1/commons/persons/{extensionType})
  • Retrieve All Extensions (GET /v1/commons/persons/extensions)

Extensions Impacted:

  • accountStatusDataExtension
  • accrualProfilesDataExtension
  • accrualProfilesDataExtensionNew
  • accrualProfilesDataExtensionNew
  • baseWageDataExtension
  • dataAccessExtension
  • employmentAnalyticsLaborTypeDataExtension
  • employmentStatusDataExtension
  • employmentTermDataExtension
  • fullTimeEquivalencyDataExtension
  • groupAssignmentDataExtension
  • jobTransferDataExtension
  • payRuleDataExtension
  • predictiveSchedulingEligibilityDataExtension
  • primaryJobAccountDataExtension

Example of Erroneous Entries:

  "employeeExtension": {
    "effDatedAccountStatuses": [
      {
        "accountStatus": "Active",
        "accountStatusTypeId": 1,
        "effectiveDate": "2016-08-13",
        "endTime": "23:59:59",    // invalid endTime
        "expirationDate": "3000-01-01",
        "startTime": "00:00:00"    // invalid startTime
      }
    ],
    "effDatedPrimaryJobAccountEntries": [
      {
        "effectiveDate": "2016-08-13",
        "endTime": "23:59:59",    // invalid endTime
        "expirationDate": "2019-01-01",
        "primaryJob": "Organization/United States/Metropolitan Plant/Machine Shop/Apprentice Welder",
        "primaryLaborCategory": ",,Shift 1,,,",
        "primaryLaborCategoryId": 2,
        "primaryOrganizationId": 35,
        "startTime": "00:00:00"    // invalid startTime
      }
    ],
    "employmentStatuses": [
      {
        "effectiveDate": "2016-08-13",
        "employmentStatus": "Active",
        "employmentStatusTypeId": 1,
        "endTime": "23:59:59",    // invalid endTime
        "expirationDate": "3000-01-01",
        "startTime": "00:00:00"    // invalid startTime
      }
    ]
  }

Corrections and enhancements

The following conditions were corrected or enhanced:

  • The Retrieve Date Span Grouped by Symbol Type (POST /v1/commons/symbolicperiod/multi_read) API operation did not always return the start and end dates for the symbolic period.
  • The Submit Bulk Download (POST /v1/commons/exports/async) asynchronous API operation would in rare situations remain in the Pending state until deleted.
  • The Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation returned custom field properties that did not always match the ordinal position of the custom field, resulting in a JSON response body with a "customDataTypeId" that did not match the numerical sequence of each custom field.
  • The Retrieve Timecard as Manager (GET /v1/timekeeping/timecard) API operation caused rare performance issues.
  • The Create or Update Location Set (POST /v1/commons/location_sets/apply_upsert) API operation sometimes caused performance issues that resulted in a timeout error.
  • Enhanced the following API operations with a query parameter that adds Partial Success error handling:
    • Create Employment Term Schedule Pattern (POST /v1/scheduling/employment_term_schedule_patterns/apply_create)
    • Update or Remove Employment Term Schedule Patterns (POST /v1/scheduling/employment_term_schedule_patterns/apply_update)
    • Create Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_create)
    • Update Employee Schedule Pattern (POST /v1/scheduling/employee_schedule_patterns/apply_update)
    • Create Schedule Group Pattern (POST /v1/scheduling/schedule_group_patterns/apply_create)
    • Update or Remove Schedule Group Patterns (POST /v1/scheduling/schedule_group_patterns/apply_update)
  • Also added Partial Success support to the following soon-to-be-deprecated API operations:
    • Create Group Schedule Pattern (POST /v1/scheduling/group_schedule_patterns/apply_create)
    • Update or Remove Group Schedule Patterns (POST /v1/scheduling/group_schedule_patterns/apply_update
  • The Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation did not always return the correct value in the "managerSignoffThruDate" property.
  • The Retrieve Data (POST /v1/commons/data/multi_read) API operation did not return the full name for the AUDIT_DATASOURCE Data Dictionary key.
  • The Retrieve Timecard Data for Multiple Employees (POST /v1/timekeeping/timecard_metrics/multi_read) API operation did not correctly allow pay code qualifiers to be used as filters.
  • The Retrieve Persons (POST /v1/commons/persons/extensions/multi_read) API operation did not return a value for the "managerSignoffThruDate" property for newly created employees.
  • The Create or Update Persons (POST /v1/commons/persons/multi_upsert) API operation returned an incorrect error when the value passed in "managerEmployeeGroupName" did not exist and a "homeHyperFindQueryName" was passed in the same call.
  • The Bulk Accrual Reset (POST /v1/timekeeping/accruals/resets) API operation returned a null response for records with an accrual code name that did not exactly match the case of the accrual code name passed in the request body.
  • The Retrieve Timecards as Manager (POST /v1/timekeeping/timecard/multi_read) API operation did not return all of the same time-related data as the Retrieve Timecard as Manager (GET /v1/timekeeping/timecard) API operation.

Docs updates

The following changes were made to the conceptual documentation:

  • Added this Important notes topic, which captures updates to the Developer Hub that fall outside of the new API operations listed in the Version history
  • Added the Best practices and tips topic along with new and edited subtopics
  • Moved the Service limits topic to the top level of the conceptual documentation
  • Updated the Service limits topic to include service limits for the Work domain
  • Various edits and changes to improve usability of the Developer Hub content

API updates

The following change was made to the reference documentation:

  • Added the extend_all_activities_query query parameter to Retrieve Activity by Name (GET /v1/work/activities)

Updated 3 months ago