Skip to main content

Needle Workflows

Needle Workflows is a platform for creating and managing workflows for creating automations and data processing.

For example, on Needle you can create a workflow that can automate the process of labeling emails as they come. For that purpose, you can use the following nodes:

  • Scheduled Trigger Node (runs the workflow every day at 8pm)
  • Gmail Find Email Node (finds emails from last 24 hours)
  • AI Node (analyze email content and suggest labels)
  • Gmail Add Label to Email Node (attach labels to Gmail emails)

With such a workflow you can organize your email inbox without manual effort.

Imagine having a workflow for most common and tedious tasks you work on. This allows you work in auto-pilot so that you can amplify your productivity greatly.

The nice thing is, workflows can be incredibly flexible since they work with any data source. Whether you want to enrich leads, monitor changes in websites or automate content creation, you can create a Needle workflow for it.

Sounds good?

Let's get you familiar with the core concepts of Needle Workflows.

Core concepts

Nodes are the building blocks of workflows and they represent specific operations. Workflows are then organized as a network of connected nodes, which are executed in order. Nodes are executed starting from the trigger node. If a node is connected to the network that starts from the trigger node, it will be executed, otherwise it will not be executed.

In Needle:

  1. You add nodes and configure them
  2. Make connections between nodes
  3. Make sure your workflow works as expected by testing it

Important! Since the nodes are executed in order, workflow must not contain any cycles - instead connections must flow in one direction. There is one exception to this rule: Loop Node (more on that later).

1. Workflow Nodes​

Node are the single unit of processing in Needle workflows. A node receives input data via the incoming connection, run and output data. Input and output of the nodes can have any shape and size. They can be an array, an object, a string, a number, etc.

Important! Nodes can have only one incoming connection, representing the input data to the node. There is one exception Node to this rule: Merge Node can have multiple incoming connections (more on that later).

Connections going out of the node represent the output data from the node. These can be connected to other nodes to pass the data as input to them. Effectively, the data flows from one node to the next in the workflow according to connections between nodes. There are various types of nodes in Needle Workflows. Two important categories of nodes are Trigger Nodes and Action Nodes.

Trigger nodes are special type of nodes that are responsible for starting the workflow run. Action Nodes are responsible for performing an operation. See some examples:

    1. Trigger Nodes
    • Scheduled Trigger Node
    • Webhook Trigger Node
    • etc.
    1. Action Nodes
    • AI Agent Node
    • Transform Node
    • Filter Node
    • Gmail Find Email Node
    • Google Sheets Upser Rows Node
    • etc.

Important! Every workflow must striclty start with a single trigger node.

Node Configuration​

If a node fails to run, it will error and the workflow execution will stop.

Alongside some standard parameters, every node has their set of specific configuration parameters that is relevant for the operation. See documentation of a given node to learn more about it.

Now we will focus on the standard parameters of every node since they control how exactly a node is run.

1. Node Run Mode (runMode)​

Every node has a standard parameter called run mode. It controls whether the node runs in parallel or not.

  1. If run mode is set to input, the node will be run only once for the entire input. Entire input data will be fed to the node and input variable will refer to the entire input data.
  2. If run mode is set to item and the input data of the node is an array, then the node will be run for every item in the input array, allowing processing data in parallel. Each item in the input array will be fed to the node and item variable will refer to the that individual data.

Important! If run mode is set to item but the input data of the node is not an array, then the entire input data will be considered a single item and node will run only once. Entire input will be fed to the node and item variable will refer to the entire input data.

2. Node Parameter Mode​

Most nodes have a standard parameter called "parameter mode". It controls how the value of the parameters are decided during a workflow run. It can have 3 possible values or be unset for a given parameter. See an example below

"parameterMode": {
  "paramName2": "expression",
  "paramName3": "fixed",
  "paramName4": "ai-decide",
}

In this example
- `paramName1` (which is unset) and `paramName4`'s values will be decided by AI.
- `paramName2` value will be evaluated as Javascript expression
- `paramName3` value will be a fixed value.

Let's learn more about each of these modes.

1. AI Decide (ai-decide)​

AI views the input data and instructions parameter to decide on a plausible value for the parameter.

2. Expression (expression)​

User enters a Javascript expression to resolve the parameter value. This expression can refer to input or item variable, based on the chosen runMode in order to read data from the input data.

Important! When run mode is input, expression can use input variable to read data from Otherwise, when run mode is item, expression can use item variable to read data from Therefore parameters configured with expressions must use the appropriate variable.

3. Fixed (fixed)​

Provide a fixed value is for the parameter during the workflow run.

3. Node Instructions​

Most nodes have a standard parameter called instructions. In Needle workflows, for many nodes it's not necessary to configure node parameters manually. Instead you can delegate choosing parameter values to AI by

  1. Selecting parameter mode as ai-decide
  2. Entering instructions on how to choose value for the parameter.

2. Connectors​

Available at https://needle.app/dashboard/connectors?workflow_id=[workflow-id]

In Needle workflows, many nodes are used to read or write data from external tools such as Google Sheets, Airtable etc. There are more than 8000+ external tool nodes. These nodes require a connector to establish a connection and run correctly.

You can create connectors for your workflow either in node configuration screen or in the Connectors page of your workflow.

3. Workflow Builder​

Available at: https://needle.app/dashboard/workflows/[workflow-id]

Your first stop in Needle Workflows will be the Workflow Builder page. In this interactive editor, you can add, configure and connect nodes, trigger test runs to build your workflow.

You can also use our embedded chat assistant to get help by simply describing the workflow you need. The chat assistant will make changes and test the workflow for you so that you can get your first successful run easier.

Start by adding a trigger node, the simplest is the manual trigger, and keep adding the relevant nodes for the task you want to automate. Prefer writing instructions over manually configuring nodes to hit the ground running. Click on Test button to trigger a "test run" and see the data flowing through the nodes. Make adjustments to your node configuration according to the input data.

Once you are happy with how your workflow works you are ready to publish your workflow.

4. Publishing Workflows​

Available at: https://needle.app/dashboard/workflows/[workflow-id]/versions

When you publish your workflow, Needle will create a production version of your workflow and activate it. You can see it in the Workflow Versions page. Depending on the trigger type your published workflow will run when triggered. For example, a published workflow with a scheduled trigger will automatically run on a regular basis. Other types of triggers such as Gmail New Email Received will start a run whenever you receive a new email.

If you wish, you can deactivate a published version to stop running it automatically. Or if you'd like to modify the workflow, you can do so in the Workflow Builder and publish a new version of it.

Important! Since a workflow can have only 1 active version, whenever you publish a workflow it will deactivate the previously published version.

5. Workflow Runs​

Available at: https://needle.app/dashboard/workflows/[workflow-id]/runs

As you see, your process of creating workflows first involves using the Workflow Builder to configure your workflow. During this time you will trigger many test runs and once you publish a version production runs will be automatically triggered.

You can list and view the details of all the runs of a workflow in the Workflow Runs page.