Scheduling parameters dynamically replace time-based values in your code each time a task runs, eliminating the need to hard-code dates in recurring workflows. This topic covers the supported formats for parameter values and how to construct them.
Before reading this topic, make sure you understand how to configure scheduling parameters. For more information, see Configure and use scheduling parameters.
Key concepts
All dynamic time parameters in DataWorks are based on two time baselines.
| Concept | Definition | Default parameter | Custom format | Time precision |
|---|---|---|---|---|
| Business date | The date of the data being processed — the day before the task's scheduled run date. In T+1 offline computing, this is the date when the business data occurred. For example, if a task calculates yesterday's sales revenue today, yesterday is the business date. | ${yyyymmdd} |
${...} |
Year, month, day |
| Scheduling time | The scheduling time set in the task's scheduling configuration. When the instance runs, this resolves to the task's theoretical run date — today. It does not shift due to resource queuing or actual execution delays. | $[yyyymmddhh24miss] |
$[...] |
Year, month, day, hour, minute, second |
In short:
-
Business date = Yesterday (the date of the data being processed)
-
Scheduling time = Today (the date the task runs)
A typical T+1 task starts in the early morning of today (scheduling time) to process data from yesterday (business date).
Parameter value types
Scheduling parameters support three types of values.
| Type | Examples | Description |
|---|---|---|
| Custom time parameters | ${...}, $[...] |
Time values derived from the two baselines, with optional formatting and offset transformations. |
| Built-in system parameters | $bizdate, $cyctime, $jobid |
Predefined variables that return the business date, scheduling time, workflow ID, and other values. |
| Constants | '123', 'abc' |
Fixed string values assigned directly. |
Parameter expressions do not support spaces or the = character.
How it works
Define a parameter by setting a parameter name and a parameter value in Scheduling > Scheduling Parameters. Reference the parameter in your code using ${parameter_name}.
The two built-in shortcuts — $bizdate and $cyctime — map directly to the default baseline formats:
-
$bizdate=${yyyymmdd}(business date) -
$cyctime=$[yyyymmddhh24miss](scheduling time)
For details on configuring parameters, see Configure and use scheduling parameters.
Custom time parameters
Use ${...} for business-date-based values and $[...] for scheduling-time-based values. Both support format codes and offset calculations, but with different precisions and constraints.
The examples in this section assume: daily scheduling, scheduling time = 02:30:45, business date = 20251031. Under these conditions:
-
${yyyymmdd}→20251031 -
$[yyyymmddhh24miss]→20251101023045
Choosing between ${...} and $[...]
${...} (business date) |
$[...] (scheduling time) |
|
|---|---|---|
| Time baseline | Business date (T-1) | Scheduling time (T) |
| Time precision | Day (year, month, day) | Second (year, month, day, hour, minute, second) |
| Supported offsets | Years, months, weeks, days | Days, hours, minutes |
| Limitations | Hour, minute, and second offsets are not supported. ${yyyy-mm-dd-1/24} is invalid. |
Direct year or month offsets such as $[yyyy±N] or $[mm±N] are not supported. Use add_months instead. |
| Equivalent built-in | ${yyyymmdd} = $bizdate |
$[yyyymmddhh24miss] = $cyctime |
Time format codes
Combine yyyy, yy, mm, dd, hh24, mi, and ss to build the time format you need.
| Code | Description | ${...} example |
Result | $[...] example |
Result |
|---|---|---|---|---|---|
yyyy |
4-digit year | ${yyyy} |
2025 |
$[yyyy] |
2025 |
mm |
2-digit month | ${mm} |
10 |
$[mm] |
11 |
dd |
2-digit day | ${dd} |
31 |
$[dd] |
01 |
hh24 |
Hour (24-hour) | Not supported — ${...} has day precision |
— | $[hh24] |
02 |
hh / hh12 |
Hour (12-hour) | Not supported | — | $[hh] |
02 |
mi |
Minute | Not supported | — | $[mi] |
30 |
ss |
Second | Not supported | — | $[ss] |
45 |
yyyymm |
Year and month | ${yyyymm} |
202510 |
$[yyyymm] |
202511 |
yyyy-mm-dd |
Date with hyphens | ${yyyy-mm-dd} |
2025-10-31 |
$[yyyy-mm-dd] |
2025-11-01 |
yyyy-mm-dd hh24:mi:ss |
Date and time with hyphens | Not supported — use string concatenation | — | See string concatenation | — |
Offset calculations
Add or subtract time from the baseline using the syntax ${<format>±N} or $[<format>±N]. N corresponds to the smallest unit in the format — for example, yyyymm±N offsets by months, and yyyymmdd±N offsets by days.
`${...}` offsets (business date)
| Offset | Syntax | Example |
|---|---|---|
| N years | ${yyyy±N} or ${yy±N} |
Previous year: ${yyyy-1} |
| N months | ${yyyymm±N} |
Previous month: ${yyyymm-1} |
| N weeks | ${yyyymmdd±7*N} |
Previous week: ${yyyymmdd-7*1} |
| N days | ${yyyymmdd±N} |
Day before yesterday: ${yyyymmdd-1} |
| Hours or minutes | Not supported | ${yyyy-mm-dd-1/24} is invalid. |
`$[...]` offsets (scheduling time)
For hour offsets, use N/24. For minute offsets, use N/24/60.
| Offset | Syntax | Example |
|---|---|---|
| N years | $[add_months(yyyymmdd,12*N)] (forward) / $[add_months(yyyymmdd,-12*N)] (back) |
Previous year: $[add_months(yyyymmdd,-12)] |
| N months | $[add_months(yyyymmdd,N)] (forward) / $[add_months(yyyymmdd,-N)] (back) |
Previous month: $[add_months(yyyymmdd,-1)] |
| N weeks | $[yyyymmdd±7*N] |
Previous week: $[yyyymmdd-7*1] |
| N days | $[yyyymmdd±N] |
Yesterday: $[yyyymmdd-1] |
| N hours | $[hh24miss±N/24], $[hh24±N/24], or $[<custom format>±N/24] |
Previous hour in different formats: Month: $[mm-1/24]; Year: $[yyyy-1/24]; Year and month: $[yyyymm-1/24]; Year, month, and day: $[yyyymmdd-1/24]; Previous day and previous hour: $[yyyymmdd-1-1/24] |
| N minutes | $[hh24miss±N/24/60], $[yyyymmddhh24miss±N/24/60], $[mi±N/24/60], or $[<custom 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] |
| Combined day + hour | $[yyyymmdd±N±M/24] |
Previous day and 1 hour ago: $[yyyymmdd-1-1/24] |
| Direct year or month offset | Not supported — use add_months |
$[yyyy-1] and $[mm-1] are invalid. |
Direct year or month offsets such as $[yyyy-N] or $[mm-N] are not supported. Use add_months instead.
Usage notes for offsets:
-
Cross-day handling: Hour and minute offsets can produce cross-day results. For guidance, see How do I handle cross-day parameter replacement when I subtract one hour from a scheduling parameter?
-
Month-end calibration: When subtracting months from a month-end date, if the target month is shorter, the result is automatically adjusted to the last day of that month. For example,
2025-03-31minus one month resolves to2025-02-28.
Secondary transformations using engine functions
When the built-in format codes and offsets cannot produce the value you need — for example, the last day of the previous month — apply a secondary transformation using the built-in functions of the node's compute engine or an assignment node.
For examples, see Typical scenarios for secondary processing of scheduling parameter return values.
String concatenation
Combine a scheduling parameter with a fixed string to construct date formats that built-in syntax does not directly support.
Example 1: First day of every month
Goal: Get a string in yyyymm01 format regardless of which day the task runs.
first_day_of_month=${yyyymm}01If the business date is 20231027, ${first_day_of_month} resolves to 20231001.
Example 2: Full timestamp in `yyyy-mm-dd hh24:mi:ss` format
Goal: Get a timestamp like 2023-11-01 02:30:45.
datetime1=$[yyyy-mm-dd]
datetime2=$[hh24:mi:ss-1/24/60]
pt=${datetime1} ${datetime2}${datetime1} ${datetime2} resolves to 2023-11-01 02:30:45.
Built-in system parameters
DataWorks provides the following predefined parameters. Where a custom time parameter equivalent exists, prefer the custom format — it supports flexible formatting and offset transformations that built-in parameters do not.
| Parameter | Format | Definition | Recommended alternative |
|---|---|---|---|
$bizdate |
yyyymmdd |
Business date. In daily scheduling, defaults to the day before the task's expected run time. | ${yyyymmdd} — supports custom formatting and offsets |
$cyctime |
yyyymmddhh24miss |
Scheduling time of the task instance. | $[yyyymmddhh24miss] — supports custom formatting and offsets |
$gmtdate |
yyyymmdd |
Current date. During a data backfill, the value equals business date + 1. | — |
$bizmonth |
yyyymm |
Business month. If the business date month equals the current month, $bizmonth = business date month − 1. If they differ, $bizmonth = business date month. |
— |
$jobid |
— | ID of the workflow the task belongs to. | — |
$nodeid |
— | Node ID. | — |
$taskid |
— | Instance ID generated by the node. | — |
Parameter replacement in practice
A parameter's replacement value is locked when the instance is generated and does not change based on the instance's actual start time.
Normal scheduling
In normal automated scheduling, each parameter resolves against the instance's own baselines:
-
${...}resolves against the instance's business date. -
$[...]resolves against the instance's scheduling time.
Example: A daily task scheduled at 00:00 with parameters yesterday=${yyyymmdd} and today=$[yyyymmddhh24miss].
| Instance scheduling time | Instance business date | yesterday=${yyyymmdd} |
today=$[yyyymmddhh24miss] |
|---|---|---|---|
2025-03-15 00:00:00 |
2025-03-14 |
20250314 |
20250315000000 |
Data backfill
When you run a data backfill manually, the baselines shift based on the manually selected business date:
-
${...}resolves against the manually selected business date. -
$[...]resolves against the manually selected business date + 1 day.
Example: Data backfill with business date 2025-03-15 selected.
| Manually selected business date | yesterday=${yyyymmdd} |
today=$[yyyymmddhh24miss] |
|---|---|---|
2025-03-15 |
20250315 |
20250316000000 (baseline = 2025-03-15 + 1 day) |
FAQ
For answers to common questions, see Scheduling parameters FAQ.