Workspace-level parameters let you define a key-value pair once and reuse it across all tasks in a workspace—rather than setting the same value repeatedly on individual tasks. Use them when multiple tasks share a common configuration value, such as a database connection string or a shared date range.
Workspace-level parameters are distinct from task-level scheduling parameters. Task-level parameters apply to one task; workspace-level parameters apply to every task in the workspace.
Prerequisites
Before you begin, ensure that you have:
-
A workspace. See Manage workspaces
-
The Workspace Administrator role in that workspace. Only Workspace Administrators can create workspace-level parameters. See Add a RAM user to a workspace as a member and assign roles to the member
-
DataWorks Professional Edition or a higher edition. See Differences among DataWorks editions
-
An exclusive resource group for scheduling. The shared resource group does not support this feature
If your exclusive resource group was created before January 1, 2024, contact technical support to upgrade the resource group configuration before using workspace-level parameters.
How it works
When a task runs, DataWorks replaces each variable in the task's code with the value of the assigned workspace-level parameter. The replacement follows the same rules as task-level scheduling parameters—see Supported formats of scheduling parameters.
In a workspace in standard mode, you can set different values for the same parameter in the development and production environments. For example, you can point a db.endpoint parameter to a test database in development and a production database in production—without changing any task code.
Create workspace-level parameters
-
Log on to the DataWorks console. In the top navigation bar, select the target region.
-
In the left-side navigation pane, choose Data Development and O&M > Operation Center. Select the target workspace from the drop-down list and click Go to Operation Center.
-
In the left-side navigation pane of the Operation Center page, choose Other > Tenant Schedule Setting, then click the Workspace-level Parameters tab.
-
Click Create Workspace-level Parameter.
NoteTo create multiple parameters at once, click Batch Create Workspace-level Parameters instead.
-
In the Create Workspace-level Parameter dialog box, configure the following fields.
NoteParameter values can include specific special characters. Check the DataWorks console for the supported character set. A workspace-level parameter value cannot reference another workspace-level parameter.
Field Description Parameter name A unique name for the parameter. Names are prefixed with workspace.by default.Owner The workspace member who owns this parameter. A Workspace Administrator can assign any member as owner. Only a Workspace Administrator can modify or delete any parameter, regardless of ownership. Workspace The workspace where the parameter is available. All tasks in this workspace can reference the parameter. Each parameter is scoped to a single workspace. The drop-down list shows only workspaces where you are the Workspace Administrator. Parameter type Controls how the value is stored and displayed. See the table below. Parameter value (development environment) The value used in the development environment. Only available in workspaces in standard mode. Parameter value (production environment) The value used in the production environment. Only available in workspaces in standard mode. Parameter types:
Type Behavior Example Constant (Plaintext) The value is stored and displayed as-is, visible to all workspace members. cn-hangzhou.oss.aliyuncs.comConstant (Ciphertext) The value is masked as ******in the console. Use this for sensitive configuration values such as passwords or access keys.A password displayed as ******Variable The value is dynamically replaced at run time based on a scheduling expression. $[yyyy-mm-dd]resolves to the task's scheduled run time;${yyyy-mm-dd}resolves to the task's data timestamp. See Supported formats of scheduling parameters.$[yyyy-mm-dd] -
Click OK.
Use workspace-level parameters in a node
-
In the node's code editor, define a variable using the standard scheduling parameter syntax.
-
On the node's configuration tab, click Properties in the right-side panel. In the Scheduling Parameter section, assign the workspace-level parameter to that variable.
-
Preview the resolved parameter value to confirm it meets your expectations.
-
Save and submit the node configuration using the top toolbar.
For details on scheduling parameter syntax and usage, see Configure and use scheduling parameters and Supported node types.
Manage workspace-level parameters
On the Workspace-level Parameters tab, you can view, modify, compare versions, and delete workspace-level parameters.
Role permissions:
| Action | Required role |
|---|---|
| View parameter details, referenced tasks, and versions | Development, O&M, or Workspace Administrator |
| Modify or delete parameters | Workspace Administrator only |
To add a RAM user to a workspace and assign roles, see Add a RAM user to a workspace as a member and assign roles to the member.
View
Click a parameter to see its details, the workspace it applies to, and the tasks that reference it. Click a task ID to go directly to that node's configuration tab.
Modify
Only the owner, value, and description of a parameter can be modified. Each modification creates a new version. Changes take effect within 10 minutes.
Modifying a workspace-level parameter affects all tasks that reference it. Review dependent tasks before making changes.
Compare versions and roll back
View the full version history of a parameter, compare any two versions side by side, and roll back to a previous version if needed.
Delete
Deleting a workspace-level parameter causes all tasks that reference it to fail. The deletion takes effect immediately. Within 10 minutes after deletion, referencing tasks may still resolve the parameter's value. A parameter referenced by active tasks cannot be deleted.