fix(oracle-hcm): expose deliberate element value clearing

Author: Bill Leoutsakos

apps/docs/content/docs/integrations/oracle_fusion_hcm.mdx

@@ -47,6 +47,8 @@ Salary creation and correction support **user-entered salary bases only**. Creat
 
 Payroll run-result values, balance slots, and goal completion percentages remain their documented strings. Balance `value1`–`value10`, definition IDs, and context/dimension labels are preserved without inventing net-pay or year-to-date meanings.
 
+When updating an element input value, supply its text value or explicitly enable `clearScreenEntryValue`. Clearing writes Oracle's documented null value; a missing value alone never clears it. Direct execution also accepts an explicit null. The clear flag follows the established integration pattern for model interfaces that cannot express nullable scalar parameters.
+
 Operation contracts: [assigned payroll creation](https://docs.oracle.com/en/cloud/saas/human-resources/farws/op-payrollrelationships-payrollrelationshipsuniqid-child-payrollassignments-payrollassignmentsuniqid-child-assignedpayrolls-post.html), [element entry creation](https://docs.oracle.com/en/cloud/saas/human-resources/farws/op-elemententries-post.html), [salary creation](https://docs.oracle.com/en/cloud/saas/human-resources/farws/op-salaries-post.html), [salary correction](https://docs.oracle.com/en/cloud/saas/human-resources/farws/op-salaries-salaryid-patch.html), and [salary bases](https://docs.oracle.com/en/cloud/saas/human-resources/farws/op-salarybasislov-get.html). Required fields follow the formal operation schemas even where abbreviated examples omit them.
 
 ## Talent and performance
@@ -670,7 +672,8 @@ Update Element Entry Value using documented Oracle fields. Requires administrati
 | `elementEntryValueId` | string | Yes | Element entry value ID, as a positive decimal string |
 | `effectiveDate` | string | Yes | Effective date in YYYY-MM-DD format |
 | `rangeMode` | string | Yes | CORRECTION changes the historical row; UPDATE starts an effective-dated change |
-| `screenEntryValue` | string | No | Element input value as text, preserving decimal precision; null clears a nullable value |
+| `screenEntryValue` | string | No | Element input value as text, preserving decimal precision. To clear it, use clearScreenEntryValue. Direct execution also accepts explicit null. |
+| `clearScreenEntryValue` | boolean | No | Explicitly clear the element input value; omit screenEntryValue when true |
 
 #### Output
 

apps/sim/blocks/blocks/oracle_fusion_hcm.ts

@@ -1119,9 +1119,15 @@ export const OracleFusionHcmBlock: BlockConfig = {
       title: 'Screen Entry Value',
       type: 'short-input',
       condition: { field: 'operation', value: ['update_element_entry_value'] },
-      required: { field: 'operation', value: ['update_element_entry_value'] },
       description:
-        'Element input value as text, preserving decimal precision; null clears a nullable value',
+        'Set a text value or enable Clear Entry Value. Direct execution also accepts explicit null.',
+    },
+    {
+      id: 'clearScreenEntryValue',
+      title: 'Clear Entry Value',
+      type: 'switch',
+      condition: { field: 'operation', value: ['update_element_entry_value'] },
+      description: 'Explicitly clear the value. Leave Screen Entry Value blank when enabled.',
     },
     {
       id: 'objectActionId',
@@ -1432,15 +1438,34 @@ export const OracleFusionHcmBlock: BlockConfig = {
       type: 'short-input',
       canonicalParamId: 'profileId',
       mode: 'advanced',
-      condition: { field: 'operation', value: ['get_talent_profile', 'list_talent_profile_sections', 'list_talent_profile_skills', 'list_talent_profile_certifications'] },
-      required: { field: 'operation', value: ['get_talent_profile', 'list_talent_profile_sections', 'list_talent_profile_skills', 'list_talent_profile_certifications'] },
+      condition: {
+        field: 'operation',
+        value: [
+          'get_talent_profile',
+          'list_talent_profile_sections',
+          'list_talent_profile_skills',
+          'list_talent_profile_certifications',
+        ],
+      },
+      required: {
+        field: 'operation',
+        value: [
+          'get_talent_profile',
+          'list_talent_profile_sections',
+          'list_talent_profile_skills',
+          'list_talent_profile_certifications',
+        ],
+      },
       placeholder: 'Enter profile id',
     },
     {
       id: 'sectionKind',
       title: 'Section Kind',
       type: 'dropdown',
-      options: [{ id: 'skill', label: 'skill' }, { id: 'certification', label: 'certification' }],
+      options: [
+        { id: 'skill', label: 'skill' },
+        { id: 'certification', label: 'certification' },
+      ],
       value: () => 'skill',
       condition: { field: 'operation', value: ['list_talent_profile_sections'] },
       required: { field: 'operation', value: [] },
@@ -1450,15 +1475,24 @@ export const OracleFusionHcmBlock: BlockConfig = {
       id: 'profileSectionId',
       title: 'Profile Section Id',
       type: 'short-input',
-      condition: { field: 'operation', value: ['list_talent_profile_skills', 'list_talent_profile_certifications'] },
-      required: { field: 'operation', value: ['list_talent_profile_skills', 'list_talent_profile_certifications'] },
+      condition: {
+        field: 'operation',
+        value: ['list_talent_profile_skills', 'list_talent_profile_certifications'],
+      },
+      required: {
+        field: 'operation',
+        value: ['list_talent_profile_skills', 'list_talent_profile_certifications'],
+      },
       description: 'Profile section ID, as a positive decimal string',
     },
     {
       id: 'startTime',
       title: 'Start Time',
       type: 'short-input',
-      condition: { field: 'operation', value: ['list_time_records', 'list_time_cards', 'create_time_entry', 'update_time_entry'] },
+      condition: {
+        field: 'operation',
+        value: ['list_time_records', 'list_time_cards', 'create_time_entry', 'update_time_entry'],
+      },
       required: { field: 'operation', value: ['list_time_records', 'list_time_cards'] },
       description: 'Start timestamp in ISO 8601 with explicit time-zone offset',
       wandConfig: {
@@ -1472,7 +1506,10 @@ export const OracleFusionHcmBlock: BlockConfig = {
       id: 'stopTime',
       title: 'Stop Time',
       type: 'short-input',
-      condition: { field: 'operation', value: ['list_time_records', 'list_time_cards', 'create_time_entry', 'update_time_entry'] },
+      condition: {
+        field: 'operation',
+        value: ['list_time_records', 'list_time_cards', 'create_time_entry', 'update_time_entry'],
+      },
       required: { field: 'operation', value: ['list_time_records', 'list_time_cards'] },
       description: 'Stop timestamp in ISO 8601 with explicit time-zone offset',
       wandConfig: {
@@ -1486,8 +1523,14 @@ export const OracleFusionHcmBlock: BlockConfig = {
       id: 'timeRecordId',
       title: 'Time Record Id',
       type: 'short-input',
-      condition: { field: 'operation', value: ['get_time_record', 'update_time_entry', 'delete_time_entry'] },
-      required: { field: 'operation', value: ['get_time_record', 'update_time_entry', 'delete_time_entry'] },
+      condition: {
+        field: 'operation',
+        value: ['get_time_record', 'update_time_entry', 'delete_time_entry'],
+      },
+      required: {
+        field: 'operation',
+        value: ['get_time_record', 'update_time_entry', 'delete_time_entry'],
+      },
       description: 'Time record ID, as a positive decimal string',
     },
     {
@@ -1507,8 +1550,14 @@ export const OracleFusionHcmBlock: BlockConfig = {
       serviceId: 'oracle_fusion_hcm',
       dependsOn: ['oauthCredential'],
       mode: 'basic',
-      condition: { field: 'operation', value: ['list_time_attribute_data_sources', 'list_time_attribute_criteria_binds'] },
-      required: { field: 'operation', value: ['list_time_attribute_data_sources', 'list_time_attribute_criteria_binds'] },
+      condition: {
+        field: 'operation',
+        value: ['list_time_attribute_data_sources', 'list_time_attribute_criteria_binds'],
+      },
+      required: {
+        field: 'operation',
+        value: ['list_time_attribute_data_sources', 'list_time_attribute_criteria_binds'],
+      },
       placeholder: 'Select time attribute id',
       description: 'Time attribute ID, as a positive decimal string',
     },
@@ -1518,23 +1567,43 @@ export const OracleFusionHcmBlock: BlockConfig = {
       type: 'short-input',
       canonicalParamId: 'timeAttributeId',
       mode: 'advanced',
-      condition: { field: 'operation', value: ['list_time_attribute_data_sources', 'list_time_attribute_criteria_binds'] },
-      required: { field: 'operation', value: ['list_time_attribute_data_sources', 'list_time_attribute_criteria_binds'] },
+      condition: {
+        field: 'operation',
+        value: ['list_time_attribute_data_sources', 'list_time_attribute_criteria_binds'],
+      },
+      required: {
+        field: 'operation',
+        value: ['list_time_attribute_data_sources', 'list_time_attribute_criteria_binds'],
+      },
       placeholder: 'Enter time attribute id',
     },
     {
       id: 'dataSourceUsageId',
       title: 'Data Source Usage Id',
       type: 'short-input',
-      condition: { field: 'operation', value: ['list_time_attribute_criteria_binds', 'list_time_attribute_values', 'create_time_entry', 'update_time_entry'] },
-      required: { field: 'operation', value: ['list_time_attribute_criteria_binds', 'list_time_attribute_values'] },
+      condition: {
+        field: 'operation',
+        value: [
+          'list_time_attribute_criteria_binds',
+          'list_time_attribute_values',
+          'create_time_entry',
+          'update_time_entry',
+        ],
+      },
+      required: {
+        field: 'operation',
+        value: ['list_time_attribute_criteria_binds', 'list_time_attribute_values'],
+      },
       description: 'Data source usage ID, as a positive decimal string',
     },
     {
       id: 'timeAttributeUsageId',
       title: 'Time Attribute Usage Id',
       type: 'short-input',
-      condition: { field: 'operation', value: ['list_time_attribute_values', 'create_time_entry', 'update_time_entry'] },
+      condition: {
+        field: 'operation',
+        value: ['list_time_attribute_values', 'create_time_entry', 'update_time_entry'],
+      },
       required: { field: 'operation', value: ['list_time_attribute_values'] },
       description: 'Time attribute usage ID, as a positive decimal string',
     },
@@ -1577,7 +1646,13 @@ export const OracleFusionHcmBlock: BlockConfig = {
       canonicalParamId: 'payrollTimeType',
       selectorKey: 'oracle_fusion_hcm.payrollTimeTypes',
       serviceId: 'oracle_fusion_hcm',
-      dependsOn: ['oauthCredential', 'assignmentId', 'effectiveDate', 'dataSourceUsageId', 'timeAttributeUsageId'],
+      dependsOn: [
+        'oauthCredential',
+        'assignmentId',
+        'effectiveDate',
+        'dataSourceUsageId',
+        'timeAttributeUsageId',
+      ],
       mode: 'basic',
       condition: { field: 'operation', value: ['create_time_entry', 'update_time_entry'] },
       required: { field: 'operation', value: [] },
@@ -1805,6 +1880,11 @@ export const OracleFusionHcmBlock: BlockConfig = {
             rest[key] = undefined
           }
         }
+        if (rest.clearScreenEntryValue === 'true') rest.clearScreenEntryValue = true
+        if (rest.clearScreenEntryValue === 'false') rest.clearScreenEntryValue = false
+        if (rest.screenEntryValue === '') {
+          rest.screenEntryValue = undefined
+        }
         for (const key of ['limit', 'offset', 'salaryAmount', 'measure', 'timeRecordVersion'] as const) {
           if (typeof rest[key] === 'string') rest[key] = Number(rest[key])
         }
@@ -1845,7 +1925,11 @@ export const OracleFusionHcmBlock: BlockConfig = {
     entryType: { type: 'string', description: 'Oracle element-entry type code supported by the tenant' },
     entryValues: { type: 'json', description: 'Up to 100 typed objects: inputValueId (positive decimal string) and screenEntryValue (string up to 60 characters or null). Input IDs serialize exactly as JSON integers' },
     elementEntryValueId: { type: 'string', description: 'Element entry value ID, as a positive decimal string' },
-    screenEntryValue: { type: 'string', description: 'Element input value as text, preserving decimal precision; null clears a nullable value' },
+    screenEntryValue: {
+      type: 'string',
+      description: 'Element input value as text; use clearScreenEntryValue to explicitly clear it',
+    },
+    clearScreenEntryValue: { type: 'boolean', description: 'Explicitly clear the element input value' },
     objectActionId: { type: 'string', description: 'Object action ID, as a positive decimal string' },
     salaryId: { type: 'string', description: 'Salary ID, as a positive decimal string' },
     salaryBasisId: { type: 'string', description: 'Salary basis ID, as a positive decimal string' },

apps/sim/lib/internal/oracle-fusion-hcm/execute-tool.test.ts

@@ -82,6 +82,25 @@ function invokeHcmTool(overrides: Partial<InternalToolOperationCall>) {
 }
 
 describe('Oracle Fusion HCM tool dispatch', () => {
+  it('turns an explicit model clear flag into a nullable element value before execution', async () => {
+    const response = await invokeHcmTool({
+      toolId: 'oracle_fusion_hcm_update_element_entry_value',
+      input: {
+        ...auth,
+        elementEntryId: '1',
+        elementEntryValueId: '2',
+        effectiveDate: '2026-01-01',
+        rangeMode: 'CORRECTION',
+        clearScreenEntryValue: true,
+      },
+    })
+    expect(response.status).toBe(200)
+    expect(mocks.updateElementEntryValue).toHaveBeenCalledWith(
+      expect.objectContaining({ screenEntryValue: null }),
+      undefined
+    )
+  })
+
   it('marks ambiguous mutation failures non-retryable without exposing provider details', async () => {
     mocks.createSalary.mockRejectedValueOnce(
       new OracleFusionProviderError('Oracle Fusion HCM request timed out', 504)

apps/sim/lib/internal/oracle-fusion-hcm/operations.test.ts

@@ -1181,6 +1181,21 @@ describe('Oracle Fusion HCM payroll, compensation, talent, and time', () => {
         method: 'POST',
         body: {
           processInline: 'N',
+          processMode: 'TIME_ENTER',
+          timeRecordEvent: [
+            expect.objectContaining({
+              operationType,
+              reporterIdType: 'PERSON',
+              reporterId: '0007',
+            }),
+          ],
+        },
+      })
+      expect(result.output.timeRecordRequest.timeRecordEventRequestId).toBe('9007199254740993')
+      expect(result.output.timeRecordRequest).not.toHaveProperty('status')
+      expect(mocks.requestOracleFusionJson).toHaveBeenCalledOnce()
+    }
+  )
 
   it('sends only a changed stop time for a versioned time-entry update', async () => {
     mocks.requestOracleFusionJson.mockResolvedValueOnce({

apps/sim/lib/internal/oracle-fusion-hcm/schema.test.ts

@@ -914,11 +914,29 @@ describe('Oracle Fusion HCM payroll and time input contracts', () => {
   })
 
   it('preserves documented string-valued result, goal, flag, and message fields', () => {
-    expect(projectors.projectPayrollRunResult({ RunResultId: '1', ResultValue: '123456789012345.6700' }).resultValue).toBe('123456789012345.6700')
-    expect(projectors.projectPayrollBalance({ Value10: '0.0000', TotalValue1: null }).value10).toBe('0.0000')
-    expect(projectors.projectPerformanceGoal({ GoalId: '2', PercentComplete: '25' }).percentComplete).toBe('25')
-    expect(projectors.projectSalary({ SalaryId: '3', PendingTransactionExists: 'N' }).pendingTransactionExists).toBe('N')
-    expect(projectors.projectTimeRecordEventMessage({ timeRecordEventMessageId: '4', allowException: 'N' }).allowException).toBe('N')
-    expect(projectors.projectTimeRecordRequestEvent({ timeRecordEventId: '5', reporterId: '0007' }).reporterId).toBe('0007')
+    expect(
+      projectors.projectPayrollRunResult({ RunResultId: '1', ResultValue: '123456789012345.6700' })
+        .resultValue
+    ).toBe('123456789012345.6700')
+    expect(projectors.projectPayrollBalance({ Value10: '0.0000', TotalValue1: null }).value10).toBe(
+      '0.0000'
+    )
+    expect(
+      projectors.projectPerformanceGoal({ GoalId: '2', PercentComplete: '25' }).percentComplete
+    ).toBe('25')
+    expect(
+      projectors.projectSalary({ SalaryId: '3', PendingTransactionExists: 'N' })
+        .pendingTransactionExists
+    ).toBe('N')
+    expect(
+      projectors.projectTimeRecordEventMessage({
+        timeRecordEventMessageId: '4',
+        allowException: 'N',
+      }).allowException
+    ).toBe('N')
+    expect(
+      projectors.projectTimeRecordRequestEvent({ timeRecordEventId: '5', reporterId: '0007' })
+        .reporterId
+    ).toBe('0007')
   })
 })

apps/sim/lib/internal/oracle-fusion-hcm/schema.ts

@@ -1641,13 +1641,27 @@ export type OracleFusionHcmCreateElementEntryResponse = z.output<
   typeof oracleFusionHcmCreateElementEntryResponseSchema
 >
 
-export const oracleFusionHcmUpdateElementEntryValueBodySchema = oracleFusionHcmBaseBodySchema.extend({
-  elementEntryId: oracleFusionHcmDecimalIdSchema,
-  elementEntryValueId: oracleFusionHcmDecimalIdSchema,
-  effectiveDate: dateSchema,
-  rangeMode: z.enum(['CORRECTION', 'UPDATE']),
-  screenEntryValue: z.string().max(60).nullable(),
-})
+export const oracleFusionHcmUpdateElementEntryValueBodySchema = oracleFusionHcmBaseBodySchema
+  .extend({
+    elementEntryId: oracleFusionHcmDecimalIdSchema,
+    elementEntryValueId: oracleFusionHcmDecimalIdSchema,
+    effectiveDate: dateSchema,
+    rangeMode: z.enum(['CORRECTION', 'UPDATE']),
+    screenEntryValue: z.string().min(1).max(60).nullable().optional(),
+    clearScreenEntryValue: z.boolean().optional(),
+  })
+  .superRefine((input, context) => {
+    if (input.screenEntryValue === undefined && input.clearScreenEntryValue !== true) {
+      context.addIssue({ code: 'custom', message: 'Supply screenEntryValue or explicitly clear it' })
+    }
+    if (input.clearScreenEntryValue && input.screenEntryValue != null) {
+      context.addIssue({ code: 'custom', message: 'Cannot set and clear screenEntryValue together' })
+    }
+  })
+  .transform((input) => ({
+    ...input,
+    screenEntryValue: input.clearScreenEntryValue ? null : (input.screenEntryValue ?? null),
+  }))
 
 export const oracleFusionHcmUpdateElementEntryValueResponseSchema = successResponse(
   z.object({