Workflows Overview
A Workflow is an internal tool that executes a set of steps across your business systems: APIs, Databases and business logic in code.
What is a Workflow?
Example use cases
- Send a slack message to #user-signups every time a signup happens in your app, after enriching it with database info, triggered by your code
- Update your reporting database every time a user clicks "Checkout" on your website via Webhook in Segment
- Return geocoding data on a given address and use it as a "Platform API" from other Superblocks Workflows, Superblocks Applications or your existing Admin Tooling
For detailed examples that include steps for calling external or internal APIs, running custom Python functions, and notifying users via email, check out the Workflow Library.
info
Workflows are modular and can be used as "Reusable Platform APIs" across all your internal Applications, Workflows and Scheduled Jobs. Consume Workflows like any REST API.
Set up Workflow
On the Superblocks Home page, click Create New followed by Create Workflow.
We receive confirmation that the workflow was successfully created and are prompted to setup an optional workflow body.
Workflow Body
Workflows can extract request query parameters and body values from the calling request. For example, imagine the service that calls our workflow passes along a ?key
query parameter in the URL and a request_id
in the POST request body. We can reference the values assigned to these in subsequent workflow steps using params.key
and body.request_id
, respectively.
Note, the values defined here are for testing the in-development workflow. In the example below, anytime we test run the workflow, key=value
will be added as a URL query parameter along with "request_id":123
in the request body. By comparison, the deployed workflow will use the actual values contained in the calling request.
Workflow Test
With the workflow URL and test body configured, we can run a test using cURL, Postman, or via code.
info
When testing, the query param ?test=true
tells Superblocks to run your in-development workflow. Remove this parameter in order to call your deployed workflow.
In a terminal, execute the curl command above to see that the workflow returns a successful response to the request.
Similarly, we can call the workflow from Postman by importing the curl command there.
After issuing the request, the workflow setup UI also confirms the request was received successfully.
Workflow Steps
Next, choose from any Superblocks integration to get started adding steps to the workflow.
info
Adding steps in Workflows is exactly the same as defining Superblocks APIs within Applications or Scheduled Jobs.
Let's add steps for the following:
- Call an internal GraphQL API that handles refunds
- Send an email to the user with confirmation of their refund
Since these workflow steps will take an order id and email, let's add those as test variables to the request body in the workflow configuration.
Now we can add the GraphQL API step with the URL and Query for refunding an order, referencing the order id with {{body.order_id}}
. A test run shows the API returns the data for the order id.
With a successful response to our refund API, we'll send the user an email to let them know their order was refunded successfully. The order id is populated in the subject and HTML templated message via {{body.order_id}}
.
After running a test, the email is received.
With the workflow steps configured and tested, we can now deploy the workflow.
Deploy Workflow
Before running a workflow outside of the development mode, it must first be deployed.
info
When sending requests to the Workflow, use the query parameter ?profile
to specify which Profile configuration to use when executing. If not specified, the default Profile configured for that Workflow will be used. Learn more about Superblocks Profiles.
After deploying the workflow, it is available externally to 3rd party services or other Superblocks apps.
Run Workflow from 3rd Party
Workflows are great for automating tasks to connect data from 3rd party systems:
In order to set up an external tool to automatically trigger a Superblocks workflow, you need to pass in the authorization token. There are two ways to pass the authorization token to the Superblocks workflow:
- As a header:
Authorization: Bearer <TOKEN>
- As a URL query parameter:
sb-auth=<TOKEN>
(requires agent version > v0.31.0 if using the OPA)
Example Configuration for URL query parameters
In order to identify your account's authorization token and workflow ID, open up an existing workflow and locate them from the workflow test section. Using these parameters, you can pass them via header, or URL query parameters as follows: https://app.superblocks.com/agent/v1/workflows/workflow-id?sb-auth=<AUTH_TOKEN>
caution
When specifying your auth token as a URL query parameter, be sure to URL encode any special characters.
For examples of triggering workflows as webhooks from 3rd parties, check out the Intercom to Zendesk and GitHub to Slack use cases in the Workflow Library.
Run Workflow within Superblocks
Let's say our teams have multiple apps within Superblocks that all require querying the same database for customer orders, and enriching that data with shipping information from another source. Rather than recreating these steps for all apps, we can create a workflow once and plug it in anywhere. Here is our final workflow that takes an order_id
, queries data from Postgres and Snowflake, and returns the merged datasets with Python.
Now when we're building Superblocks apps, scheduled jobs, or even other workflows, we can reference this workflow as one of the API steps. For example, we have an app that contains an Input component for a user to specify the order ID, and a Table to display the order details and shipping status.
To dynamically populate these components with data, we can create an API that simply calls the workflow we already built. We can pass data from the app components to the workflow request body, as seen with the order_id
taken from an Input component here.
In the User Interface, we can trigger the EnrichOrders
API upon submitting an Input, and bind the Table data to the API response.
When building other Superblocks apps, scheduled jobs, and workflows that require the same data, we can save time by reusing this workflow and transforming the data as needed for each use case.
Workflow response
By default, the response of a workflow contains metadata along with the actual data returned to the user. For example:
curl --location \
--request POST 'https://app.superblocks.com/agent/v1/workflows/<WORKFLOW-ID>?sb-auth=<AUTH_TOKEN>'
{
"responseMeta": {
"status": 200,
"message": "",
"success": true,
"timing": {
"fetchStart": 1673638872500,
"fetchEnd": 1673638872553,
"fetchDurationMs": 53,
"executeStart": 1673638872553,
"executeEnd": 1673638872594,
"executeDurationMs": 41,
"requestStart": 1673638872500,
"requestEnd": 1673638872594,
"requestDurationMs": 94
}
},
"data": {
"value": "Hello Superblocks!"
}
}
To return only your workflow's data, without extra response metadata, add raw=true
as a URL query parameter when invoking the workflow. For example:
curl --location \
--request POST 'https://app.superblocks.com/agent/v1/workflows/<WORKFLOW-ID>?sb-auth=<AUTH_TOKEN>&raw=true'
{
"value": "Hello Superblocks!"
}