Building your first workflow
A step-by-step guide to building your first Middle workflow
So, it's finally time for you to build your first workflow. Well, you're in the right place!
To summarize, building a new workflow from scratch will require the following:
- Make any needed changes
A fully built out workflow
If you do not already have an account created to build your workflow in, you'll want to create a new account. To do this, go to the account portal and click "+ New Account" in the upper-right corner. You will then be taken to a brand new Middle account in your instance.
Accounts can be toggled on or off. When you are ready to begin syncing data and/or automating an account's workflows, you'll want to activate it by clicking "Enable Syncs" on the account's main page.
It's safe to assume that your workflow will need to touch systems external to Middle. Typically, workflows begin on data that has been synced into Middle and then perform an API call to another system, such as a PUT statement. You'll need to connect the apps that the workflow will need. To do this click "+ New App Connection" in the left-hand menu under "APP CONNECTIONS." You will get a list of available apps in your organization. You are able to select any one of these to connect.
If you don't see an app you need, reach out to the Middle team at [email protected]. They will either need to set up your organization with access to this app or it's an integration that has not been developed yet in Middle. You can add as many apps as you need to an account.
When you connect a new app to an account, you will be taken to the Connection Details page to authenticate. The Connection Details page features an authorization form that you will need to complete to connect. Middle is able to handle a variety of authentications, including OAuth and API keys. Within the Connection Details page, you'll have the ability to select which version of an app you'd like to use. Middle's developer portal allows for versioning as an app is updated. In general, you will want to have the most up-to-date version selected.
You can access the App Connection page anytime by clicking on the app and then "Edit Connection Details."
An app's syncs can be toggled on and off as you see fit. When determining the function of your workflow, you'll need to consider what data needs to be synced into Middle for the workflow to operate. Typically, workflows begin on a root record. Imagine a workflow that runs everytime Middle sees a purchase. That workflow will begin on a purchase record; therefore you'll want to turn on the sync for purchases. That being said, purchases have related records, such as the user making the purchase. You will likely also want to turn on a sync for users and any other related data so that the workflow has all the data it needs to work on.
For apps that you are only performing actions with, you most likely don't need to turn on any syncs
You are able to toggle on or off any syncs you want
There are three types of syncs:
- Complete transfers - Grab all the data available from an endpoint or external resource. This sync is common for smaller datasets.
- Primary key lookups - Request data for a specific record using a primary identifier. For example, if Middle grabs a record, such as an invoice, and sees a user ID associated with that sale, Middle will perform a sync to grab that user's data.
- Recent record lookups - Syncs data from a datetime range. For example, grabbing all sales that have occurred in the past hour, every 20 minutes. The datetime scope and frequency of these syncs are configurable from the developer portal.
You should consider how each sync operates, interacts with other syncs, and how that affects the operation of your workflow. You should also consider the implications of API limits when turning on syncs.
To create a new workflow click "+ New Workflow" in the account sidebar under "WORKFLOWS." You will then be given a blank draft for your new workflow. You can also paste a workflow from an existing workflow in your installation using Middle's copy and paste function.
It's helpful to name the workflow to indicate what function it's achieving and provide any additional documentation in the description.
Providing sufficient documentation for the workflow description and node descriptions is helpful to track what a workflow is meant to do and the reasoning behind why a workflow is built the way it is
A brand new workflow
Most workflows will begin with an input record. This is the data that's being passed into the workflow to be performed on. Your data inputs can be flexible. With Middle, you are able to not only input the most up-to-date version of a record but also the previous version of a record as well. Generally, you'll most likely just want to select a single record type. This is done by simply clicking the "Key to?" dropdown. You'll see all the record types for all the apps connected to the account. Select the one you'll like the workflow to perform on.
Select the data inputs for a workflow via the begin node
To exit any node click above the pop-up pane
You will likely want to next step in your workflow to be a decision node.
Either true or false, decision nodes route to one of two branches depending on whether their criteria is met. Within decision nodes, you will construct these criteria, using Middle's parameter system. You will essentially build a list of true or false statements, where you can compare one variable against another. Say if you are trying to determine if a client has an outstanding balance on their account, you can select a field on their profile for
account_balanceand then select "not equal to" 0. If that criterion is true, then Middle will move on to the next criteria in the decision node. Middle operates from top to bottom. If the criteria in the decision node are met, Middle will send the workflow on its way, either along the true or the false branch.
Decision nodes allow you to filter data and branch workflow logic
Once you've filtered your workflow or need to grab additional data that requires an API call, you are going to want to add an action to your workflow.
Actions are a powerful tool that generally push out of Middle and hit another system's endpoint, to do anything from sending user data, to triggering an event, to fetching data from a system. Actions are also able to provide an internal service to your workflow. With actions, you are able to input static values or dynamic data that are dependent on your input record. While actions are generally the final destination for a workflow, they can also be a waypoint, as actions can have outputs that can be referenced later on in the workflow via global variables.
Actions are generally setup as forms where you can map data from Middle to another system
Whether it be creating booleans in a decision node or inputting data into an action, Middle's parameters are the building blocks of your workflow nodes. When you create a new parameter you will be provided with a large menu of options to select from. For in-depth details on the different parameters you can use please refer to the workflow parameters article.
As a beginner, you'll want to understand IF statements and global variables. All decision nodes are composed of true or false statements. For a decision node to pass, the logic you build must be true. To create a boolean (true or false) statement you'll want to select IF from the parameter dropdown. You can build out logic as you see fit by using AND (all IF statements must be true) or OR (any IF statement needs to be true). These can be layered on top of each other as you see fit.
Layer AND and OR groupings on top of each other to build out highly specific logic
The beginning of an IF statement
You will then need to build some comparison logic. You'll likely want to compare data in the input record with another variable or static value. To select data to perform the comparison on, click "+ Add child parameter" and then select the global variable. Global variables are your primary key to using data in your workflows. In the global variable, you'll see the begin node. If you select the begin node you'll be able to select the input record and see all the data points in that record and any related records.
User global variables to select data for boolen comparisons and mapping in actions
Once you've selected a data attribute, you'll need to make a comparison. First, decide the type of comparison you'd like to make and the variable or static value you're comparing against. Once you've completed this, you have a full IF statement for Middle to perform logic with.
Two complete IF statements linked together with an AND
Using global variables to construct action inputs along with a switch statment that provides additional mapping logic
To promote a workflow to live, this is essentially saving your workflow draft and making it the primary version, click "Lock this version and make Active" at the top of the page.
If you ever need to make changes to a locked in workflow simply click "Copy" at the top of the page. You should then be able to make changes to your workflow. If you need to go back to a previous draft of a workflow, Middle has workflow versioning. You can select any previous draft of a workflow via the "View Another Version" dropdown at the top of the page.
Discarding a draft when you have previous workflow versions will not delete the entire workflow, it will only delete the draft you are currently working on unless the workflow has a single draft and no live versions.
Once you've locked in your workflow you can test it. To test a workflow, click on the app for the data input, click "Records" next to the record type the workflow is built to perform on, check the box next to a record you'd like to test with, click the execute workflow dropdown to select your newly constructed workflow, and click execute.
Select data to run a manual workflow execution on
Middle also has an experimental feature that allows you to enter a JSON object of test data. This feature can be found at the top of your workflow page with the "Run workflow" button.
If you need to make any subsequent changes to your workflow, make a new draft, complete your changes, and then promote the new draft to live.
For a workflow to be truly automated you'll need to create a trigger for a workflow. Triggers are what snap a workflow into action. There are two types of triggers: activity-based triggers and scheduled triggers. Triggers are created and managed on your account's main page. Most likely your first workflow trigger will be an activity-based trigger. For more information on how to construct triggers please refer to the Workflow triggers article.
Once you have an operational trigger connected to a tested workflow you are all set! From here it's good to monitor workflow executions via the workflow history page and observe end-destination results to ensure the workflow is achieving what you'd like it to do.