Scheduling parameters are a core DataWorks feature that dynamically replaces time-based values in your code during automated task runs. This eliminates the need to hardcode dates in recurring tasks, allowing your workflows to automatically adapt to different business dates and execution times. This topic describes the supported formats for parameter values of scheduling parameters and their usage.
Before reading this topic, make sure you understand how to configure scheduling parameters. For more information, see Configure and use scheduling parameters.
Core concepts: Time baselines
All dynamic time parameters in DataWorks are based on the following two core time baselines.
Concept | Definition | Parameter value | Custom format | Time precision |
Business date | The date of the data being processed, usually the day before the task's scheduled run date. In T+1 batch processing scenarios (where today's task processes yesterday's data), this represents the date when the business data occurred. For example, if you're calculating yesterday's sales revenue today, yesterday is the date when the transactions occurred, which is the business date. |
|
| Year, month, day |
Scheduling time | The scheduling time configured in Scheduling for the task. When an instance is created, this value is set and remains fixed. It's accurate to the second and independent of the task's actual run time. This represents the expected execution time of the task and may not be identical to the actual start time. The actual start time is affected by multiple factors. |
|
| Year, month, day, hour, minute, second |
Concept summary:
Business date ≈ Yesterday (the date of the data)
Scheduling time ≈ Today (when the task runs)
A typical T+1 task starts in the early morning of today (scheduling time) to process data from yesterday (business date).
Principles
You can configure parameters and assign values in , and preview replacement values for future task instances using the parameter preview feature. For more information about the parameter configuration process, see Configure and use scheduling parameters.
You can use built-in system parameters
$bizdateand$cyctimeto directly assign values for business date and scheduling time. In terms of values,$bizdateis equivalent to${yyyymmdd}, and$cyctimeis equivalent to$[yyyymmddhh24miss].
The figures show the parameter definitions and preview results when the business date is October 16, 2025 for
$bizdatevs.${yyyymmdd}and$cyctimevs.$[yyyymmddhh24miss].If the baseline time parameter return values don't meet your requirements, you can create custom time parameters using
${...}and$[...]. Custom time parameters are transformations based on the two time baselines and support the following methods:
When assigning values to scheduling parameters using custom methods, note the difference between the two bracket formats {...} and [...]. The two formats use different baseline values and produce completely different parameter values. Mixing them up can cause data errors in production.
Value assignment types
Scheduling parameters support several assignment types, including:
Built-in system parameters: Such as
$bizdate,$bizmonth, and$jobid, which can be used to obtain business date, business month, workflow ID, and more. They are not limited to time-based values. For more information, see Built-in system parameters.Custom time parameters: Such as
${...}and$[...], which can be transformed based on the two time baseline values. For details, see Custom time parameters.Constants: Such as
'123'or'abc'.
Custom time parameters
DataWorks supports using ${...} and $[...] to retrieve business date and scheduling time. It also supports transformations to adjust the time. The following examples assume the node is configured with daily scheduling and a scheduling time of 02:30:45. Assuming the business date is October 31, 2025, here are the baseline times:
Business date: ${yyyymmdd}, which is 20251031 in this example.
Scheduling time: $[yyyymmddhh24miss], which is 20251101023045 in this example.
ImportantThe scheduling time is a preset value that is fixed when a task instance is generated. If an instance is delayed due to factors like resource constraints or the status of upstream nodes, its scheduling time does not change; it is independent of the actual run time.
Core differences between ${...} and $[...]
Understanding the core differences between the ${...} and $[...] formats is crucial, as they have fundamental differences in their time baselines and calculation capabilities. Mixing them up can lead to data errors.
Comparison |
|
|
Time baseline | Business date (T-1) | Scheduling time (T) |
Time precision | Day (year, month, day) | Second (year, month, day, hour, minute, second) |
Offset calculation capability | Supports offsets for years, months, weeks, and days. | Supports offsets for days, hours, and minutes. |
Core limitations | Does not support formatting or offset calculations for smaller units like hours, minutes, or seconds. | Does not support direct year or month offsets using syntax like |
Default equivalence |
|
|
Time formatting
You can format the two time baselines by using ${...} or $[...] combined with time format specifiers such as yyyy, mm, and dd.
Code | Description |
|
| ||
Assignment | Result | Assignment | Result | ||
| 4-digit year |
|
|
|
|
| 2-digit month |
|
|
|
|
| 2-digit day |
|
|
|
|
| Hour in 24-hour format | Not supported (day precision) | - |
|
|
| Hour in 12-hour format | - |
|
| |
| Minute | - |
|
| |
| Second | - |
|
| |
| Get year and month |
|
|
|
|
| Format with hyphens |
|
|
|
|
| Format with hyphens | Not supported (day precision) | - | See String Concatenation: Case 2 for supported methods. | |
Offset calculations
Offset calculations are the core of dynamic parameters, allowing you to add or subtract time from either the business date or scheduling time. For example, retrieve dates N years, months, or days before or after the baseline, or N hours or minutes (hours and minutes only supported for scheduling time). ${...} and $[...] support different ranges due to their different time baseline precisions.
Offset calculation in
${...}modeCore capability: Supports integer offsets for years, months, weeks, and days.
ImportantDoes not support hour or minute offsets. Syntax like
${yyyy-mm-dd-1/24}is not supported.Syntax:
${<time_format><±N>}, where N corresponds to the smallest unit of the time format. For example, if the format isyyyymm, N represents months (mm); if the format isyyyymmdd, N represents days (dd).Date offset period
Offset unit
Method
Example
N years before/after
Year
${yyyy±N}or${yy±N}Previous year:
${yyyy-1}N months before/after
Month
${yyyymm±N}Previous month:
${yyyymm-1}N weeks before/after
Week
${yyyymmdd±7*N}Previous week:
${yyyymmdd-7*1}N days before/after
Day
${yyyymmdd±N}Previous day:
${yyyymmdd-1}
Offset calculation in
$[...]modeCore capability: Supports fractional offsets for days, hours, and minutes.
ImportantThe
$[...]format does not support year or month offsets using formats like$[yyyy-N]or$[mm-N]. To perform offset calculations on years or months, use theadd_monthsfunction instead.Syntax:
$[<time_format><±N>], where an hour offset is specified asN/24and a minute offset is specified asN/24/60.Nis the number of hours or minutes for the offset.Requirement
Offset unit
Method
Example
N years before/after
Year
$[add_months(yyyymmdd, 12*N)](N years after)$[add_months(yyyymmdd, -12*N)](N years before)Previous year:
$[add_months(yyyymmdd, -12*1)]N months before/after
Month
$[add_months(yyyymmdd, N)](N months after)$[add_months(yyyymmdd, -N)](N months before)Previous month:
$[add_months(yyyymmdd, -1)]N weeks before/after
Week
$[yyyymmdd±7*N]Previous week:
$[yyyymmdd-7*1]N days before/after
Day
$[yyyymmdd±N]Yesterday:
$[yyyymmdd-1]N hours before/after
Hour
Use formats such as
$[hh24miss±N/24],$[hh24±N/24], and$[<custom_time_format>±N/24].Previous hour in different formats:
$[mm-1/24],$[yyyy-1/24],$[yyyymm-1/24],$[yyyymmdd-1/24],$[yyyymmdd-1-1/24].N minutes before/after
Minute
Use formats such as
$[hh24miss±N/24/60],$[yyyymmddhh24miss±N/24/60],$[mi±N/24/60], or$[<custom_time_format>±N/24/60].15 minutes before the scheduling time in different formats:
$[yyyy-15/24/60],$[yyyymm-15/24/60],$[yyyymmdd-15/24/60],$[hh24-15/24/60],$[mi-15/24/60].Complex combined offset
Day + Hour
$[yyyymmdd±N±M/24], where N is the day offset and M is the hour offset.Example: Get the previous day and previous hour →
$[yyyymmdd-1-1/24]NoteWhen you perform offset calculations for hours and minutes, a cross-day issue may occur. For details on how to handle cross-day parameter replacements, see How do I handle cross-day parameter replacement when I subtract one hour from a scheduling parameter?.
Secondary transformations using engine functions
If the built-in features cannot generate the value you need (for example, getting the last day of the previous month), use the built-in functions of the target node's compute engine or an assignment node to perform a secondary transformation on the time parameter when calling it.
For more information, see Typical scenarios for secondary processing of scheduling parameter return values.
String concatenation
This method is used to construct specific date strings that are not supported by the built-in syntax. It combines the date part generated by a scheduling parameter with a fixed constant string.
Example 1: Dynamically retrieve the first day of every month.
Case: Regardless of which day a task runs, you need a string representing the first day of the current month in
yyyymm01format.Implementation:
Extract the year and month: Use
${yyyymm}to get the year and month of the current business date (for example, if the business date is20231027, the result is202310).Concatenate the extracted year and month with the string
'01'.Parameter assignment:
first_day_of_month=${yyyymm}01
Result: When the task runs, a call to
${first_day_of_month}returns20231001.
Example 2: Retrieve a time in yyyy-mm-dd hh24:mi:ss format.
Case: Retrieve a time in
yyyy-mm-dd hh24:mi:ssformat, such as2023-11-01 02:30:45.Implementation:
Set two parameters:
datetime1anddatetime2, and assign them valuesdatetime1=$[yyyy-mm-dd]anddatetime2=$[hh24:mi:ss-1/24/60], respectively.Concatenate the parameters: Define a third parameter that concatenates
datetime1anddatetime2with a space.Parameter assignment:
pt=${datetime1} ${datetime2}.
Result: When the task runs, a call to
${pt}returns2023-11-01 02:29:45.
Built-in system parameters
DataWorks supports the system parameters listed in the table below, which can be used to set the values of scheduling parameters. However, this method offers less flexibility and uses fixed time formats. We recommend using custom time parameters, which support flexible transformations.
Built-in parameter | Definition |
$bizdate | The business date, in This parameter is widely used. In daily scheduling, the business date defaults to the day before the task's expected run time. |
$cyctime | The task's scheduling time, in |
$gmtdate | The current date, in This parameter defaults to the current day. When you perform a data backfill operation, the value is the |
$bizmonth | The business month, in
|
$jobid | The ID of the workflow to which the task belongs. |
$nodeid | The node ID. |
$taskid | The instance ID generated by the node. |
Appendix
Parameter replacement during data backfill
After you commit a task to Operation Center, you can perform a data backfill to batch generate and run historical task instances for a specified date range to complete data fixes, backfills, or retrospective analysis.
Business date: The business date selected for data backfill is consistent with the replacement result of $bizdate. If a scheduling parameter uses the
${...}custom format, its baseline is the selected date, transformed by the specified time expression.Scheduling time: When you perform a data backfill, the replacement result for $cyctime is the
selected business date + 1day. For example, if the business date selected for the data backfill is20250315, the value for the$cyctimeparameter will be20250316000000. If a scheduling parameter uses the$[...]format, its baseline is theselected business date + 1day, transformed by the specified time expression.
Relationship between scheduling parameters, business date, scheduling time, and actual run time
Relationship | Description and example |
Relationship between scheduling parameters and actual run time | A scheduling parameter's value is set when its instance is generated and does not change if the instance's actual run time is delayed. |
Relationship between scheduling parameters and the task's scheduling time | When a scheduling parameter is set to  For example, if a node is scheduled hourly from |
Relationship between scheduling parameters, business date, and scheduling time |  |
About daylight saving time
DataWorks ensures that tasks run correctly on days when daylight saving time (DST) begins and ends. For details on how the product handles the DST transition, see Scenario: Impact of daylight saving time transitions on scheduled task execution. If you're in a region that observes DST, review this document to avoid confusion during the transition period.