Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use.

Version Information

Template Name	Extension Name	Version	Status
dbt Cloud Jobs	ue-dbt-cloud-jobs	1 (Current 1.0.1)	Fixes and new Features are introduced.

Refer to Changelog for version history information.

Overview

dbt Cloud is a scalable data transformation platform that helps data teams build, deploy, monitor, and discover data assets, providing a browser-based UI for developing, testing, scheduling, documenting, and investigating data models. dbt Cloud Jobs are collections of dbt commands executed within a dbt environment that allow users to run transformations on a schedule or trigger, eliminating the need for manual command execution and providing detailed run history, logs, and monitoring capabilities.

Universal Automation Center (UAC) can trigger dbt Cloud jobs by making API requests to the dbt Cloud API endpoint with appropriate authentication, enabling automated execution of your data transformation workflows based on your orchestration requirements.

Key Features

Feature	Description
Job Triggering	Trigger and monitor a dbt Cloud Job with the capability to provide optional configuration Job Run settings.
Job Run Information Streaming	Live stream updates about dbt Job Run and Run steps.
Tunable Output Options	STDOUT: Capability to show “Run Summary” and “Job Monitoring” EXTENSION OUTPUT: Capability to show “Run Steps” and “Run Results”

Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Area	Details
Python Version	Requires Python 3.11, Tested with Agent bundled python distribution.
Universal Agent Compatibility	Compatible with Universal Agent for Windows x64 and version >= 7.6.0.0. Compatible with Universal Agent for Linux and version >= 7.6.0.0.
Universal Controller Compatibility	Universal Controller Version >= 7.6.0.0.
Network and Connectivity	Connectivity to DBT Cloud Rest APIs is required.
dbt Cloud	Compatible with dbt Cloud API V2.

Supported Actions

Action: Run Job

The “Run Job” action provides the following capabilities.

Trigger or Trigger and Monitor a dbt Cloud Job waiting to reach a final state, providing the required input parameters for execution.
Control the information to be displayed on STDOUT, or on EXTENSION Output, to bring visibility on the executed Steps.

Action Output

Output Type Description Examples

EXTENSION

The extension output provides the following information:

exit_code, status_description: General info regarding the task execution. For more information users can refer to the exit code table.
invocation.fields: The task configuration used for this task execution.
result.basic_info: Shows basic information about the Job Run, regardless of the Extension output Options.
- result.job_run_id
- result.status
- result.job_run_href
- result.dbt_version
result.job_run_info: Shows information about Job Run. Information shown, depends on the configuration of field Extension Output Options and only if Wait For Success Or Failure field is checked. Child Objects
- result.job_run_info.run_steps
- result.job_run_info.run_results
result.errors: List of errors that might have occurred during execution. That does not include dbt job run internal errors.

Success: Job Triggering without Monitoring

{
    "exit_code": 0,
    "status_description": "Task executed successfully, job 'sample_default_models' run on dbt Cloud triggered successfully",
    "invocation": {
        "extension": "ue-dbt-cloud-jobs",
        "version": "1.0.0",
        "fields": {
        "action": "Run Job",
        "dbt_cloud_credentials": {
            "user": "70471823471492",
            "password": "****",
            "token": "****",
            "key_location": null,
            "passphrase": "****"
        },
        "base_url": "https://wv602.us1.dbt.com",
        "job_name": "sample_default_models",
        "wait_for_success_or_failure": true,
        "reason": "Test Reason For Running The Job",
        "use_optional_params": "-- None --",
        "optional_params": null,
        "polling_interval": 60,
        "stdout_options": null,
        "extension_output_options": null,
        "job_run_id": null,
        "job_run_http_link": null,
        "job_run_status": null,
        "job_run_duration": null,
        "last_updated_on": null
    }
},
    "result": {
        "basic_info": {
            "job_run_id": 70471839270866,
            "status": "Success",
            "job_run_href": "https://wv602.us1.dbt.com/deploy/70471823471492/projects/70471823480824/runs/70471839270866/",
            "dbt_version": "latest"
        }
    }
}

Fail: Invalid Task Configuration

{
    "exit_code": 20,
    "status_description": "Data Validation Error: Invalid optional parameters, data.dbt_version_override must be string",
    "invocation": {
        "extension": "ue-dbt-cloud-jobs",
        "version": "1.0.0",
        "fields": {
          ....
        }
}
},
    "result": {
        "errors": [
            "Data Validation Error: Invalid optional parameters, data.dbt_version_override must be string"
        ]
    }
}

STDOUT

Provides useful information depending on the configuration of STDOUT Options (only if Wait For Success Or Failure is checked).

Job Monitor

Job Monitor
================================
Observation Timestamp: 2025-07-11 10:43:07 +0300
Job: 'sample_default_models' with Run ID: <run_id>
Job Status: Running
Job Run Steps Count: 1
Job Run Steps (changes since last observation):
+-----+----------------------+----------------------------------+----------------------------------+----------+------------+
| # | Name | Started | Finished | Status | Duration |
+=====+======================+==================================+==================================+==========+============+
| 1 | Clone git repository | 2025-07-11 07:43:02.798946+00:00 | 2025-07-11 07:43:03.211042+00:00 | Success | 0 minutes |
+-----+----------------------+----------------------------------+----------------------------------+----------+------------+


Observation Timestamp: 2025-07-11 10:43:12 +0300
Job: 'sample_default_models' with Run ID: <run_id>
Job Status: Running
Job Run Steps Count: 4
Job Run Steps (changes since last observation):
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+
| # | Name | Started | Finished | Status | Duration |
+=====+========================================================+==================================+==================================+==========+============+
| 2 | Create profile from connection ue-aws-athena-dbt-cloud | 2025-07-11 07:43:08.464531+00:00 | 2025-07-11 07:43:08.489448+00:00 | Success | 0 minutes |
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+
| 3 | Invoke dbt with `dbt deps` | 2025-07-11 07:43:08.561205+00:00 | 2025-07-11 07:43:10.937632+00:00 | Success | 2 seconds |
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+
| 4 | Invoke dbt with `dbt run` | 2025-07-11 07:43:11.028896+00:00 | | Running | 1 second |
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+


Observation Timestamp: 2025-07-11 10:43:34 +0300
Job: 'sample_default_models' with Run ID: <run_id>
Job Status: Running
Job Run Steps Count: 4
Job Run Steps (changes since last observation):
+-----+---------------------------+----------------------------------+----------------------------------+----------+------------+
| # | Name | Started | Finished | Status | Duration |
+=====+===========================+==================================+==================================+==========+============+
| 4 | Invoke dbt with `dbt run` | 2025-07-11 07:43:11.028896+00:00 | 2025-07-11 07:43:33.125809+00:00 | Success | 22 seconds |
+-----+---------------------------+----------------------------------+----------------------------------+----------+------------+

Job Summary

Job Summary
================================
+-----------------------+----------------+----------+------------+
| Job Name | Job Run ID | Status | Duration |
+=======================+================+==========+============+
| sample_default_models | <job_run_id> | Success | 37 seconds |
+-----------------------+----------------+----------+------------+

Step Summary
================================
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+
| # | Name | Started | Finished | Status | Duration |
+=====+========================================================+==================================+==================================+==========+============+
| 1 | Clone git repository | 2025-07-11 07:41:26.966921+00:00 | 2025-07-11 07:41:27.433595+00:00 | Success | 0 minutes |
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+
| 2 | Create profile from connection ue-aws-athena-dbt-cloud | 2025-07-11 07:41:32.727554+00:00 | 2025-07-11 07:41:32.757405+00:00 | Success | 0 minutes |
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+
| 3 | Invoke dbt with `dbt deps` | 2025-07-11 07:41:32.777336+00:00 | 2025-07-11 07:41:35.184978+00:00 | Success | 2 seconds |
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+
| 4 | Invoke dbt with `dbt run` | 2025-07-11 07:41:35.241742+00:00 | 2025-07-11 07:41:57.516962+00:00 | Success | 22 seconds |
+-----+--------------------------------------------------------+----------------------------------+----------------------------------+----------+------------+

https://example.dbt.com/deploy/704718234*****/projects/70471823****/runs/704718392****/

STDERR

Shows the logs from the Task Instance execution. The verbosity is controlled by the Task configuration Log Level.

Info Logs

2025-07-11 10:51:54,991 - 139711821620992 AsyEvent[EXTENSION_START] - utils.py[109] INFO: Extension Information: ue-dbt-cloud-jobs-1.0.0-beta
2025-07-11 10:51:54,992 - 139711821620992 AsyEvent[EXTENSION_START] - utils.py[114] INFO: System Information: Python Version: 3.11.6 (main, Nov 9 2023, 08:01:02) [GCC 8.5.0 20210514 (Red Hat 8.5.0-4)], system: Linux, release: ue-agt-lin-dev, version: #1 SMP Tue Feb 21 19:25:54 UTC 2023, machine type: x86_64, ue-commons Version: 0.4.3
2025-07-11 10:51:54,992 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[35] INFO: Fetching all dbt Cloud Jobs
2025-07-11 10:51:55,770 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[71] INFO: Triggering job run on job with ID: 1123411****
2025-07-11 10:51:56,265 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[107] INFO: Job monitoring started...
2025-07-11 10:51:56,265 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[91] INFO: Retrieving job run on job with Run ID: 9991923****
2025-07-11 10:52:01,681 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[91] INFO: Retrieving job run on job with Run ID: 9991923****
2025-07-11 10:52:02,370 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[155] INFO: Updating STDOUT with Job Monitor.
2025-07-11 10:52:07,372 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[91] INFO: Retrieving job run on job with Run ID: 9991923****
2025-07-11 10:52:07,798 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[155] INFO: Updating STDOUT with Job Monitor.
2025-07-11 10:52:12,800 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[91] INFO: Retrieving job run on job with Run ID: 9991923****
2025-07-11 10:52:13,218 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[155] INFO: Updating STDOUT with Job Monitor.
2025-07-11 10:52:18,219 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[91] INFO: Retrieving job run on job with Run ID: 9991923****
2025-07-11 10:52:18,645 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[155] INFO: Updating STDOUT with Job Monitor.
2025-07-11 10:52:23,646 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[91] INFO: Retrieving job run on job with Run ID: 9991923****
2025-07-11 10:52:24,076 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[155] INFO: Updating STDOUT with Job Monitor.
2025-07-11 10:52:29,076 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[91] INFO: Retrieving job run on job with Run ID: 9991923****
2025-07-11 10:52:29,520 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[155] INFO: Updating STDOUT with Job Monitor.
2025-07-11 10:52:34,522 - 139711821620992 AsyEvent[EXTENSION_START] - dbt_cloud_job_manager.py[91] INFO: Retrieving job run on job with Run ID:9991923****
2025-07-11 10:52:35,229 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[155] INFO: Updating STDOUT with Job Monitor.
2025-07-11 10:52:35,229 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[202] INFO: Updating STDOUT with Job Summary.
2025-07-11 10:52:35,231 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[136] INFO: Building extension result.
2025-07-11 10:52:35,231 - 139711821620992 AsyEvent[EXTENSION_START] - utility.py[57] INFO: Getting Run Information.

Configuration Examples

Example: Trigger a dbt Cloud Job

The dbt Cloud Jobs task triggers a dbt Cloud job with the name “sample_job” with no monitoring. The task will end when it triggers the job run on dbt Cloud, and the task will not wait for it to finish. If the Job is triggered successfully, the task instance completes with success, else with failure.

Example: Trigger and Monitor a dbt Cloud Job

The dbt Cloud Jobs task will trigger a dbt Cloud Job with the name “sample_job” with monitoring. All STDOUT and EXTENSION OUTPUT options are selected. The task will remain running until the job run on dbt Cloud reaches a terminal state.

The task will check if the job run has reached a terminal state on each poll interval. Additionally, the task will perform job monitoring on each poll interval and will print the results on the STDOUT. Once the task reaches a terminal state, it will print the Job Summary to STDOUT and include the “Run Steps” information and “Run Results” artifact in the EXTENSION output. Then the task will end with success or failure, depending on the terminal state of the Job Run.

Input Fields

Name	Type	Description	Version Information
Action	Choice	The action performed upon the task execution. Run Job (default)	Introduced in 1.0.0
Base URL	Text	The base URL of your service (e.g., `https://ab123.us1.dbt.com` )	Introduced in 1.0.0
dbt Cloud Credentials	Credentials	Credentials for the interaction with dbt Cloud API. The Credential definition should be as follows: DBT Cloud Account ID as "Runtime User". Personal Access Token (PAT) as "Runtime Password".	Introduced in 1.0.0
Job Name	Dynamic Choice	Dynamic Choice field for retrieval and selection of the Job to be executed.	Introduced in 1.0.0
Reason	Text	A text description of the reason for running the Job	Introduced in 1.0.0
Provide Additional Optional Parameters	Choice	Used to select whether Additional Optional Configuration needs to be provided for the Job to Run. The following run configuration options are available -- None -- As JSON Text As JSON UAC Script	Introduced in 1.0.0
Optional Parameters	Large Text	Additional Optional Configuration as Text (in JSON format). The following run configuration options are available: Example Expand source { "git_sha": "string - The git sha to checkout before running", "git_branch": "string - The git branch to checkout before running", "azure_pull_request_id": 0, "github_pull_request_id": 0, "gitlab_merge_request_id": 0, "non_native_pull_request_id": 0, "schema_override": "string - Overrides the destination schema in the configured target", "dbt_version_override": "string - Overrides the version of dbt", "threads_override": 0, "target_name_override": "string - Overrides the target.name context variable", "generate_docs_override": true, "timeout_seconds_override": 0, "steps_override": [ "string - Overrides the list of dbt commands" ] } The default value is a placeholder value meant to serve as a way to inform the user of what the available options are. It is not meant to be used directly as a default value for an execution of the task. Task authors can use the default value provided as a template; however, it needs to be modified according to their needs. For more information on how it can be filled, consult the dbt Cloud official API documentation. Required when Provide Additional Configuration As = “As JSON Text”
Optional Parameters	Script	Provides the same functionality as Additional Configuration (JSON) option with the added benefit of being reusable by saving the configuration as a UAC script. Required when Provide Additional Configuration As = “As JSON UAC Script”	Introduced in 1.0.0
Wait For Success Or Failure	Checkbox	When checked, the Task Instance waits until the executed Job reaches a final State. Otherwise, the Task Instance completes when the Job is simply triggered, without waiting to finish.	Introduced in 1.0.0
Polling Interval (sec)	Integer	This field is required when Wait For Success Or Failure is checked and represents the time interval between retries for getting the status of the dbt Cloud Job Run. As a best practice, if the Task Execution expected completion duration is long, set the polling Interval to a larger value. A short value will trigger frequent checks towards dbt Cloud, which is inefficient in terms of resources in the case of long-duration Tasks. The default value is 60.
STDOUT Options	Multiple Choice	Controls what information is displayed on the STDOUT. Allowed values Include Run Summary Include Job Monitoring Related outputs will be shown on the STDOUT only if Wait For Success Or Failure is checked.	Introduced in 1.0.0
Extension Output Options	Multiple Choice	Controls what information is displayed on the Extension Output. Allowed values Include Run Steps Include Run Results Run Results is a dbt Cloud artifact.	Introduced in 1.0.0

Output Fields

Name	Type	Description	Version Information
Job Run ID	Text	The Job Run ID of the Triggered Job.	Introduced in 1.0.0.
Job Run HTTP Link	Text	The dbt Cloud Console HTTP link that shows information on this Job Run.	Introduced in 1.0.0.
Job Run Status	Text	The last retrieved Job Run Status.	Introduced in 1.0.0.
Job Run Duration	Text	The last retrieved Job Run Duration in human format. Gets value only if Wait For Success Or Failure is checked.	Introduced in 1.0.0.
Last Updated On	Text	The last local date and time the agent updated the Output Fields.	Introduced in 1.0.0.

Environment Variables

Environment Variables can be set from Environment Variables task definition table. The following environment variables can affect the behavior of the extension.

Environment Variable	Description	Version Information
UE_HTTP_TIMEOUT	Specifies the timeout (in seconds) for HTTP requests made by the Task Instance. A higher value allows for slower responses, while a lower value enforces stricter time constraints. If not set, a default of 60 seconds is used. When a timeout happens, the Task Instance ends in failure.	Introduced in 1.0.0.

Cancelation and Rerun

In case of cancellation of Task Instance, the Job Run remains intact on dbt Cloud.
In case of re-run of the Task Instance a new Job Run is created.

Exit Codes

Exit Code	Status	Status Description	Meaning
0	Success	If Wait For Success Or Failure input field is checked, “Task executed successfully, job monitoring finished. The job run on dbt Cloud finished successfully“ If Wait For Success Or Failure input field is not checked, “Task executed successfully, job '<<Job Name>>' run on dbt Cloud triggered successfully“	Successful Execution. If Wait For Success Or Failure input field is checked, It means that the Job Run ended up in a Success State. If Wait for Success or Failure input field is not checked, It means that the Flow Run has been successfully triggered.
1	Failure	“Execution Failed: <<Error Description>>”	Failed Execution. If Wait For Success Or Failure input field is checked, it means that the Flow Run ended up in a Failed State. This error code also acts as a generic error code. Raised when an error does not fall into the other error scenarios.
2	Cancelled	“Task instance cancelled successfully”	Cancelled Execution. If the task is cancelled via the Cancel button in the right click menu of the task instance.
20	Failure	“Data Validation Error: <<Error Description>>“	Input fields validation error.

STDOUT and STDERR

STDOUT is used for displaying Job information and its controlled by STDOUT Options (only when Wait For Success Or Failure is checked).

STDERR provides additional information to the user, the verbosity of which is controlled by Log Level Task Definition field.

Backwards compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice

How To

Import Universal Template

To use the Universal Template, you first must perform the following steps.

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
Import the Universal Template into your Controller:
1. Extract the zip file, you downloaded from the Integration Hub.
2. In the Controller UI, select Services > Import Integration Template option.
3. Browse to the “export” folder under the extracted files for the ZIP file (Name of the file will be unv_tmplt_*.zip) and click Import.
4. When the file is imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

Python code modifications should not be done.
Template Modifications
- General Section
  - "Name", "Extension", "Variable Prefix", and "Icon" should not be changed.
- Universal Template Details Section
  - "Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.
- Result Processing Defaults Section
  - Success and Failure Exit codes should not be changed.
  - Success and Failure Output processing should not be changed.
- Fields Restriction Section
  The setup of the template does not impose any restrictions. However, concerning the "Exit Code Processing Fields" section.
  1. Success/Failure exit codes need to be respected.
  2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining the success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents:

Document Link	Description
Universal Templates	User documentation for creating, working with and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.
dbt Developer Hub	The dbt Cloud API v2 Documentation

Changelog

ue-dbt-cloud-jobs-1.0.1 (2025-11-07)

Fixed: Issue where job fetching did not support pagination, which could cause incomplete data retrieval for large job sets.

ue-dbt-cloud-jobs-1.0.0 (2025-08-01)

Initial Version