fix(ui): advise users on correct chron syntax for scheduling

Author: kevinkarchacryl

datahub-web-react/src/app/ingest/source/builder/CreateScheduleStep.tsx

@@ -5,7 +5,7 @@ import { Cron } from 'react-js-cron';
 import 'react-js-cron/dist/styles.css';
 import styled from 'styled-components';
 import cronstrue from 'cronstrue';
-import { CheckCircleOutlined, WarningOutlined } from '@ant-design/icons';
+import { CheckCircleOutlined, WarningOutlined, InfoCircleOutlined } from '@ant-design/icons';
 import { SourceBuilderState, StepProps } from './types';
 import { TimezoneSelect } from './TimezoneSelect';
 import { ANTD_GRAY, REDESIGN_COLORS } from '../../../entity/shared/constants';
@@ -81,6 +81,26 @@ const StyledWarningOutlined = styled(WarningOutlined)`
     margin-top: 12px;
 `;
 
+const HashmarkNotice = styled.div`
+    margin-top: 8px;
+    padding: 8px;
+    background-color: #e6f7ff;
+    border: 1px solid #91d5ff;
+    border-radius: 4px;
+    display: flex;
+    align-items: flex-start;
+`;
+
+const InfoIcon = styled(InfoCircleOutlined)`
+    color: #1890ff;
+    margin-right: 8px;
+    margin-top: 3px;
+`;
+
+const containsHashmark = (cronExpression: string): boolean => {
+    return cronExpression.includes('#');
+};
+
 const ItemDescriptionText = styled(Typography.Paragraph)``;
 
 const DAILY_MIDNIGHT_CRON_INTERVAL = '0 0 * * *';
@@ -93,6 +113,7 @@ export const CreateScheduleStep = ({ state, updateState, goTo, prev }: StepProps
     const [advancedCronCheck, setAdvancedCronCheck] = useState(false);
     const [scheduleCronInterval, setScheduleCronInterval] = useState(interval);
     const [scheduleTimezone, setScheduleTimezone] = useState(timezone);
+    const hasHashmark = useMemo(() => containsHashmark(scheduleCronInterval), [scheduleCronInterval]);
 
     const cronAsText = useMemo(() => {
         if (scheduleCronInterval) {
@@ -183,6 +204,19 @@ export const CreateScheduleStep = ({ state, updateState, goTo, prev }: StepProps
                             />
                         </AdvancedSchedule>
                     </Schedule>
+                    {advancedCronCheck && hasHashmark && (
+                        <HashmarkNotice>
+                            <InfoIcon />
+                            <div>
+                                <Typography.Text strong>Special schedule syntax detected</Typography.Text>
+                                <Typography.Paragraph style={{ marginBottom: 0 }}>
+                                    Your schedule uses special syntax (# character) to run on a specific occurrence of a day each month.
+                                    Please combine the day of the month with the day of the week to achieve this schedule.
+                                    For example use '0 0 8-14 0 1' instead of '0 0 0 0 1#2' for the 2nd Monday of the month 
+                                </Typography.Paragraph>
+                            </div>
+                        </HashmarkNotice>
+                    )}
                     <CronText>
                         {cronAsText.error && <>Invalid cron schedule. Cron must be of UNIX form:</>}
                         {!cronAsText.text && (

ingestion-scheduler/src/test/java/com/datahub/metadata/ingestion/IngestionSchedulerTest.java

@@ -299,4 +299,59 @@ public void testUnscheduleAll() throws Exception {
     // And that the future is cancelled
     Assert.assertTrue(future.isCancelled());
   }
+
+  @Test
+  public void testDayRangeAndHashmarkSyntax() throws Exception {
+    assertEquals(_ingestionScheduler.nextIngestionSourceExecutionCache.size(), 1);
+
+    // Create two ingestion sources with different cron syntax methods
+    // need to affirm both '0 0 1-7 * 0' and the equivalent '0 0 0 * 0#2' work
+    final Urn dayRangeUrn = Urn.createFromString("urn:li:dataHubIngestionSourceUrn:day-range");
+    final DataHubIngestionSourceInfo dayRangeInfo = new DataHubIngestionSourceInfo();
+    dayRangeInfo.setSchedule(
+        new DataHubIngestionSourceSchedule().setInterval("0 0 1-7 * 0").setTimezone("UTC"));
+    dayRangeInfo.setType("mysql");
+    dayRangeInfo.setName("Day Range Syntax Test Source");
+    dayRangeInfo.setConfig(
+        new DataHubIngestionSourceConfig()
+            .setExecutorId("default")
+            .setRecipe("{ type: \"type\" }")
+            .setVersion("0.8.18"));
+
+    final Urn hashmarkUrn = Urn.createFromString("urn:li:dataHubIngestionSourceUrn:hashmark");
+    final DataHubIngestionSourceInfo hashmarkInfo = new DataHubIngestionSourceInfo();
+    hashmarkInfo.setSchedule(
+        new DataHubIngestionSourceSchedule().setInterval("0 0 * * 0#1").setTimezone("UTC"));
+    hashmarkInfo.setType("mysql");
+    hashmarkInfo.setName("Hashmark Syntax Test Source");
+    hashmarkInfo.setConfig(
+        new DataHubIngestionSourceConfig()
+            .setExecutorId("default")
+            .setRecipe("{ type: \"type\" }")
+            .setVersion("0.8.18"));
+
+    // Schedule both sources
+    _ingestionScheduler.scheduleNextIngestionSourceExecution(dayRangeUrn, dayRangeInfo);
+    _ingestionScheduler.scheduleNextIngestionSourceExecution(hashmarkUrn, hashmarkInfo);
+
+    // Verify both were scheduled successfully
+    assertEquals(_ingestionScheduler.nextIngestionSourceExecutionCache.size(), 3);
+    assertTrue(_ingestionScheduler.nextIngestionSourceExecutionCache.containsKey(dayRangeUrn));
+    assertTrue(_ingestionScheduler.nextIngestionSourceExecutionCache.containsKey(hashmarkUrn));
+
+    // Get both scheduled futures
+    ScheduledFuture<?> dayRangeFuture =
+        _ingestionScheduler.nextIngestionSourceExecutionCache.get(dayRangeUrn);
+    ScheduledFuture<?> hashmarkFuture =
+        _ingestionScheduler.nextIngestionSourceExecutionCache.get(hashmarkUrn);
+
+    // Both should be valid futures
+    assertFalse(dayRangeFuture.isCancelled());
+    assertFalse(hashmarkFuture.isCancelled());
+
+    // Clean up
+    _ingestionScheduler.unscheduleNextIngestionSourceExecution(dayRangeUrn);
+    _ingestionScheduler.unscheduleNextIngestionSourceExecution(hashmarkUrn);
+    assertEquals(_ingestionScheduler.nextIngestionSourceExecutionCache.size(), 1);
+  }
 }

metadata-ingestion/schedule_docs/cron.md

@@ -25,4 +25,8 @@ We can use crontab to schedule ingestion to run five minutes after midnight, eve
 5 0 * * * datahub ingest -c /home/ubuntu/datahub_ingest/mysql_to_datahub.yml
 ```
 
+:::tip
+For scheduling on a specific occurrence of a weekday (e.g., 2nd Monday), use day ranges like 8-14 * 1 instead of hashmark syntax like * * 1#2. While both work, the the hashmark syntax is unsupported in the UI scheduler.
+:::
+
 Read through [crontab docs](https://man7.org/linux/man-pages/man5/crontab.5.html) for more options related to scheduling.