Skip to main content

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.

Create a new workflow from the 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

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.

Using curl to test and validate workflow configuration

Similarly, we can call the workflow from Postman by importing the curl command there.

Using postman to test and validate workflow configuration

After issuing the request, the workflow setup UI also confirms the request was received successfully.

Successfully posting to a workflow results in a success message within UI

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

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.

Test variables can be added within the workflow configuration to provide test data for workflows

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.

Graphql step using the test body variable and return output to the user

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}}.

The Superblocks email integration can send emails with customized bodies to lists of recipients

After running a test, the email is received.

Final formatted report received via email

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.

Workflows are developed in development mode and can be made publicly available via deploying

info

When invoking the workflow URL use the query parameter ?environment to specify which environment to call. Otherwise the workflow executes against the production environment. For more info, see Staging & Prod Environments.

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

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:

  1. As a header: Authorization: Bearer <TOKEN>
  2. 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>

Use Authentication tokens to authenticate with third party services

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.

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 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.

Application framework with an Input and Table component

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.

Bind UI elements with event handlers for responsive applications

In the User Interface, we can trigger the EnrichOrders API upon submitting an Input, and bind the Table data to the API response.

Trigger the EnrichOrders API on submitting the input text

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!"
}