Why connect to dbt Cloud?
When you connect your Workstream.io instance with dbt Cloud, we will detect data incidents, alert your team of them in Slack, and streamline your data incident management from end to end.
This includes knowing when your dbt models and sources fail, registering associated incidents for your team to investigate and manage, alerting your team via Slack, and populating a status page for any asset that is configured as an exposure in dbt.
Workstream also presents failing dashboards and data incidents in our environment insights page. This gives your team a centralized place to monitor data quality trends, and more easily identify urgent issues with your assets.
How do I connect to dbt Cloud?
To connect dbt Cloud, you must generate and provide us with a service token.
We recommend you provide us a service token with account admin permissions so that we can create webhooks on your behalf. If you are uncomfortable with this level of access, you can use a member, job admin or read only token.
Please note: users may have different roles in dbt Cloud that determine access to their API. To properly access the api, and generate service tokens, you must:
Be a dbt Team or Enterprise customer
Be a user with a valid a developer license. You can read more about these roles in dbt's documentation.
You can read below for step by step instructions, or use this video.
Step 1: Generating a Service Token
These steps document using a service token with Account Admin permissions in dbt Cloud to connect to Workstream. We ask for an account admin token so we can create webhooks on your behalf.
For instructions on using a Read-Only, Job Admin, or Member token instead, see the Advanced Setup guide below.
Service tokens allow secure system-to-system communication between dbt Cloud and Workstream. To generate this token, please take the following steps within dbt Cloud:
Login as an owner
Click on the gear icon in the top right corner and select "Account Settings"
On the Account Settings screen, go to "API tokens" in the left nav and select "Service Tokens"
Click "Create service token" on the right side above the table.
Enter a name for the service token. We recommend including Workstream in the name, so the token is easily identifiable.
After you enter a name, add a permission set in the list and select "Account Admin."
Note: we request this so that we can create and manage webhooks. To integrate with a Read-Only token instead, follow the Advanced Setup, below.
Click "Save" in the bottom right.
You will have successfully created your service token, and can see the details in the righthand slide out. Before closing the slide out, make sure to save it in a secure location, or keep the page available in a separate browser tab when connecting your account to Workstream.
Step 2: Providing required information to Workstream
Your connections are created and managed under the "Settings" section, available by clicking on your workspace's name in the top left corner of the screen.
Find the dbt Cloud card and click "Connect".
The only required piece of information is your service token. Enter the service token you just created, and click "Connect" to create the connection.
Once you've connected, Workstream will begin importing information about your dbt Cloud sources, models, and exposures. Please allow a few minutes for this initial import to complete.
Advanced Setup: Using a Read-Only Token
If you do not want to create a service account token with Account Admin access, you will have to perform some extra steps in the dbt Cloud UI, relative to the setup described above.
Creating a Read-Only Service Token
On the Account Settings screen, go to "API tokens" in the left nav and select "Service Tokens"
Click "Create service token" on the right side above the table.
Enter a name for the service token. We recommend including Workstream in the name, so the token is easily identifiable.
After you enter a name, add a permission set in the list and select one of the following:
Member, Job Admin, Read Only
DO NOT select Metadata Only, or Semantic Layer only. These will not work and will error out.
Optionally, you can select "All Projects" or reduce the scope of the token to specific dbt Projects that you would like to manage with Workstream.
Click "Save" in the bottom right.
You will have successfully created your service token, and can see the details in the righthand slide out. Before closing the slide out, make sure to save it in a secure location, or keep the page available in a separate browser tab when connecting your account to Workstream.
Providing required information to Workstream
Follow the tutorial above, under Step 2, to provide the service token credentials to Workstream in the Workstream web app.