# Define runtime parameters

> Define runtime parameters - Add runtime parameters to a custom job, making the custom job code
> easier to reuse.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-06T18:17:10.043490+00:00` (UTC).

## Primary page

- [Define runtime parameters](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-jobs-workshop/nxt-runtime-parameters-custom-jobs.html): Full documentation for this topic (HTML).

## Sections on this page

- [Runtime parameter definitions](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-jobs-workshop/nxt-runtime-parameters-custom-jobs.html#runtime-parameter-definitions): In-page section heading.

## Related documentation

- [NextGen UI documentation](https://docs.datarobot.com/en/docs/workbench/index.html): Linked from this page.
- [Registry](https://docs.datarobot.com/en/docs/workbench/nxt-registry/index.html): Linked from this page.
- [Jobs](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-jobs-workshop/index.html): Linked from this page.
- [Create custom jobs](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-jobs-workshop/nxt-create-jobs/index.html): Linked from this page.
- [API reference documentation for credentials](https://docs.datarobot.com/en/docs/api/reference/public-api/credentials.html#schemacredentialsbody): Linked from this page.

## Documentation content

Define environment variables to supply different values to scripts and tasks used by a custom job at runtime by including them as runtime parameters, making your custom job easier to reuse. Define runtime parameters in code or through the UI:

- Code: Provide ametadata.yamlfile in the custom job. Define this file when creating or editing a custom job in theJobsworkshop, or use the template available in theJobsworkshop through a custom job'sFiles >Createdropdown. The YAML structure is definedon this page.
- UI: Define runtime parameters in theRuntime parameterssection of the custom job in theJobsworkshop. For more information, see theCreate custom jobsdocumentation.

Runtime parameters are injected into containers as environment variables (accessible through `os.getenv`). Parameters [created via theJobsworkshop UI](https://docs.datarobot.com/en/docs/workbench/nxt-registry/nxt-jobs-workshop/nxt-create-jobs/index.html) persist and merge when you upload new code versions, ensuring a seamless development flow.

**Runtime parameter considerations**

The system uses a blocklist of reserved patterns (e.g., `DRUM_*`, `MLOPS_*`, `KUBERNETES_*`), managed in the dynamic configuration. Matching supports the `*` wildcard (not full regular expression syntax). Reserved names aren't blocked entirely: if a runtime parameter uses a reserved name, the UI displays a warning. How the variable is exposed depends on the context:

- Custom models: Only in prefixed ( MLOPS_RUNTIME_PARAM_* ) and JSONified format—not as a raw (unprefixed) environment variable, to prevent system conflicts.
- Custom apps: Prefixed, but values are not packed into a JSON payload (except for credentials).
- Custom jobs: No prefix and no JSON payload (except for credential types); the variable is available as a raw environment variable.

For credential-type runtime parameters, the system automatically unpacks JSON fields into separate environment variables rather than a single string. For example, a credential named `MAIN_AWS_CREDENTIAL` with the following JSON structure:

```
{"awsAccessKeyId": "<your-key-id>", "awsSecretAccessKey": "<your-access-key>"}
```

is unpacked into the following environment variables, combining the parameter name + JSON key, in uppercase:

```
MAIN_AWS_CREDENTIAL_AWS_ACCESS_KEY_ID="<your-key-id>"
MAIN_AWS_CREDENTIAL_AWS_SECRET_ACCESS_KEY="<your-access-key>"
```

> [!TIP] Access runtime parameters in containers
> For programmatic access to runtime parameters in containers, use `DataRobotAppFrameworkBaseSettings` as documented in the SDK API reference.

## Runtime parameter definitions

To define runtime parameters, you can add the following `runtimeParameterDefinitions` in `metadata.yaml`:

| Key | Description |
| --- | --- |
| fieldName | Define the name of the runtime parameter. |
| type | Define the data type the runtime parameter contains: string, boolean, numeric, credential, deployment, modelPackage. |
| defaultValue | (Optional) Set the default string value for the runtime parameter (the credential type doesn't support default values). If you define a runtime parameter without specifying a defaultValue, the default value is None. |
| minValue | (Optional) For numeric runtime parameters, set the minimum numeric value allowed in the runtime parameter. |
| maxValue | (Optional) For numeric runtime parameters, set the maximum numeric value allowed in the runtime parameter. |
| credentialType | (Optional) For credential runtime parameters, set the type of credentials the parameter must contain. |
| allowEmpty | (Optional) Set the empty field policy for the runtime parameter.True: (Default) Allows an empty runtime parameter.False: Enforces providing a value for the runtime parameter before deployment. |
| description | (Optional) Provide a description of the purpose or contents of the runtime parameter. |

```
# Example: metadata.yaml
name: runtime-parameter-example

runtimeParameterDefinitions:
- fieldName: my_first_runtime_parameter
  type: string
  description: My first runtime parameter.

- fieldName: runtime_parameter_with_default_value
  type: string
  defaultValue: Default
  description: A string-type runtime parameter with a default value.

- fieldName: runtime_parameter_boolean
  type: boolean
  defaultValue: true
  description: A boolean-type runtime parameter with a default value of true.

- fieldName: runtime_parameter_numeric
  type: numeric
  defaultValue: 0
  minValue: -100
  maxValue: 100
  description: A boolean-type runtime parameter with a default value of 0, a minimum value of -100, and a maximum value of 100.

- fieldName: runtime_parameter_for_credentials
  type: credential
  allowEmpty: false
  description: A runtime parameter containing a dictionary of credentials.
```

The `credential` runtime parameter type supports any `credentialType` value available in the DataRobot REST API. The credential information included depends on the `credentialType`, as shown in the examples below:

> [!NOTE] Note
> For more information on the supported credential types, see the [API reference documentation for credentials](https://docs.datarobot.com/en/docs/api/reference/public-api/credentials.html#schemacredentialsbody).

| Credential Type | Example |
| --- | --- |
| basic | basic: credentialType: basic description: string name: string password: string user: string |
| azure | azure: credentialType: azure description: string name: string azureConnectionString: string |
| gcp | gcp: credentialType: gcp description: string name: string gcpKey: string |
| s3 | s3: credentialType: s3 description: string name: string awsAccessKeyId: string awsSecretAccessKey: string awsSessionToken: string |
| api_token | api_token: credentialType: api_token apiToken: string name: string |