Skip to main content

​
What is a Workflow?

Workflows are modular, reusable platform APIs that can be used across all your internal Applications, Workflows, and Scheduled Jobs. Consume Workflows like any REST API.

​
Workflow setup

On the Superblocks Home page, click Create New followed by Create Workflow. Create workflow from home page 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. Define variables for both query parameters and request body during configuration of Superblocks Workflows

​
Workflow test

With the workflow URL and test body configured, we can run a test using cURL, Postman, or via code. Test your workflows with either curl, javascript or python
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. Using curl to test and validate workflow configuration

​
Workflow steps

Next, choose from any Superblocks integration to get started adding steps to the workflow. Workflow steps allow you to query data sources or execute code and return a result

​
Workflow deployment

Before running a workflow outside of the development mode, it must first be deployed. To deploy a workflow, click the blue Deploy button. Workflows are developed in development mode and can be made publicly available via deploying This prompts you to add a commit message and deploy your changes. Commit and deploy changes to workflow Workflow deploy confirmation and trigger instructions
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: Workflows can be triggered by third party services and systems and can also post to third party systems and services Since a workflow is a REST API, it can be triggered with an HTTP POST request (e.g., a 3rd party webhook or HTTP client libraries in code). A workflow URL follows this structure: 
https://agent.superblocks.com/v2/execute/<WORKFLOW-ID>
For example requests, scroll down to the Trigger Workflow section of your workflow. The request requires passing in your account’s authorization token using either of these methods:
  1. As a header: Authorization: Bearer <TOKEN>
Authorization token in header
  1. As a URL query parameter: sb-auth=<TOKEN>
Authorization token in URL
When specifying your auth token as a URL query parameter, be sure to URL encode any special characters.

​
Async workflows

By default, a client calling a workflow must wait for the workflow to complete before it receives a response. Alternatively, if you do not need to wait for the response of a workflow, you can trigger it to run asynchronously by adding async=true as a URL query parameter to the workflow request (For customers self-hosting the data plane, this is available as of v1.2.1).

​
Run Workflow within Superblocks

If there is a set of common API steps needed in multiple apps, we can create a single workflow and reference that anywhere in Superblocks. For example, 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. To reuse this logic anywhere, we have created a workflow that takes an order_id, queries data from Postgres and Snowflake, and returns the merged datasets with Python. Example workflow that reads data from Postgres and Snowflake then uses Python to merge the data and return it Now when we’re building Superblocks Applications, Scheduled Jobs, or even other Workflows, we can reference this workflow as one of the API steps. Bind UI elements with event handlers for responsive applications When building other Superblocks Applications, 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

When calling a workflow, the response returned to the client contains information about the execution, output, and errors. For example, below is the result of a successful workflow that completed with no errors. 
{
  "execution": "018df715-5fd0-7cdd-8a51-ef2faf95a33f",
  "output": {
    "result": "hello world",
    "stdout": [
      "example printed log",
      "another log"
    ]
  },
  "status": "STATUS_COMPLETED"
}
In comparison, a workflow that hits any errors returns these in an errors array. 
{
  "execution": "018dfadd-d817-767e-abe8-cb1a00d8b8c0",
  "errors": [
    {
      "name": "IntegrationError",
      "message": "Error on line 1: name 'time' is not defined ",
      "blockPath": "Step2"
    }
  ],
  "status": "STATUS_COMPLETED"
}
For an async workflow, the response is returned immediately, and only contains the execution id along with the status. 
{
  "execution": "018dfade-6724-77de-a7d9-60365ad9486a",
  "status": "STATUS_EXECUTING"
}