Overview
While Recipe Builder enables you to quickly deploy integrations between GUIDEcx and a wide range of popular applications within minutes through our collection of pre-built recipes, its true value lies in its versatility and customizability. Whether you're a seasoned integration chef or just starting out in the world of automation, Recipe Builder empowers you to create customized recipes tailored to your specific integration needs.
Working with APIs: Recipe Builder relies on APIs to determine what can be retrieved from and sent to systems. To effectively leverage the included functionality, users should have a basic understanding of how APIs work and how they can test and validate APIs.
User Access
Only Admins can access Recipe Builder.
How to Build a Recipe
Follow these steps to create a recipe:
Within the project where you would like to create the recipe, click the Create Dropdown and select Recipe.
Name the Recipe.
Select the trigger type you’d like to use for the recipe. Refer to the table below for an explanation of the most common triggers used.
Click Start building.
Typically adding the final app action in a recipe first assists in determining any logic actions that need added to the recipe.
Save the Recipe.
Start the Recipe.
Ensure that all progress is saved.
Exit the Editing Environment by clicking the Exit button at the top-right.
Click Start recipe.
The Editing Environment
The Editing Environment is your workspace for creating and editing recipes. There are 4 main components of the editing environment, each explained below, they are The Recipe (highlighted in yellow), The Data Pane (highlighted in blue), The Top Bar (highlighted in white), and the Configuration Pane (highlighted in green).
The Recipe
Here the steps a recipe takes are numbered, starting with the trigger, and proceeding through the all of the actions. Warning icons indicate that action needs to be taken for that step.
The Data Pane
Data from steps within the recipe can be used to populate fields of later steps as datapills. They are found here. The Data Pane can be minimized or expanded by clicking the icon in the top-right corner.
The Top Bar
The Top Bar has tools available throughout the recipe building process. Here you can name the project; view previous test jobs; and Save, Test, Refresh, and Exit the Recipe
The Configuration Pane
Clicking on a step (including the Trigger) in Recipe Builder opens the Configuration Pane on the right hand side of the editing environment. Here you can adjust settings for the individual step. Depending on the action selected, the contents of the pane will differ.
Types of Triggers and Their Common Use Cases
Option | Use |
Trigger from app | If a source application has the ability to trigger a run (typically facilitated via a webhook), this can be used for real-time triggering. For example, when a task updates, a recipe can be triggered to automatically push an update to another application.
This approach tends to be useful for small data multiple times per day. |
Run on schedule | If an ideal application-based trigger isn’t available, a schedule is normally the viable option. This also comes into play for bulk administration, batch updates, or afterhours runs. For example, at midnight, the recipe can run to pull all project updates to push to another application.
This approach tends to be useful for large data movement on a cadenced basis. |
Trigger from a webhook | If a source application has the ability to send data to a webhook, this can be used for real-time triggering. For example, a change happens in the CRM and an update is automatically pushed to GUIDEcx.
This approach tends to be useful for external systems and workflows that require quick, small updates. |
Adding an Action
Follow these steps to Add an action to the recipe:
Click the plus icon at the bottom of the editing environment.
Select the action you would like the recipe to take.
There are 7 types of actions available in Recipe Builder.
Option | Use |
Action in an app | Used to send data to an application. If the application you are hoping to integrate with does not exist in the library, the generic HTTP option can be used for most APIs. |
IF condition | Used to determine whether a recipe should complete some corresponding steps. If the condition is not satisfied, the recipe moves on without entering the condition. |
IF/ELSE condition | Used to determine which path a recipe should follow. If the condition is not satisfied, the recipe takes the ELSE path. |
Repeat action | Used to loop through a list of data and repeat the same action for each record. |
Call function | Used to call a function containerized in another recipe. |
Stop job | Used to stop a job. This is typically useful if the recipe has met the desired outcome and future tasks should not be run. |
Handle errors | Used to catch errors that may occur in your run and take action based on what is defined for handling errors. |
Configuring Triggers and Actions in Recipe Builder
Configuring the Trigger
Recipe Triggered From An App
Within the configuration pane, follow these steps to configure the trigger action for recipes triggered from an app.
Select the Application you would like to trigger the recipe.
Apps that you have already created connections for will be listed in the Configuration Pane.
You can search for for an app by name in the search bar.
Select the Trigger event that you would like to use. Triggers will have a name and a description to help determine how it works. Depending on the connector, Recipe Builder may recommend triggers available for the app.
Connect to the Application.
If you already have a connection made that you want to use, select it from the list.
or
Follow the steps outlined in Creating a New Connection in Recipe Builder to create a new connection.
Set up the Trigger.
Depending on the trigger, the fields in this step will differ. Fields marked with a red asterisk are required.
(Optional) Toggling Set trigger condition will allow you to add additional rules to the trigger event, reducing the number of jobs. For example, you can specify that a job only runs if a row added to a Google Sheet has a keyword in a specified column.
Recipe Ran on a Schedule
Within the configuration pane, follow these steps to configure the trigger action for recipes ran on a schedule.
Select the unit of time to use for the recipe. Options include: minutes, hours, days, weeks, months, and custom schedule.
Specify how often you want the recipe to run. In this example the recipe will run every 5 minutes:
Depending on the unit of time selected, you may have additional fields to fill out. For example selecting days as the unit of time will add a field where you specify what time you want the recipe to run.
Custom Schedules requires a cron expression. Cron expressions are written as: [minute] [hour] [day of month] [month] [day of week]. Learn More.
NOTE: If you initially selected a different trigger method, you can switch to a scheduled trigger in the configuration pane by clicking on the App step of the configuration pane and searching for "Scheduler by Workato."
Recipe Triggered From A Webhook
If a source application has the ability to send data to a webhook, Recipe Builder can create a webhook URL that triggers the recipe when it receives a payload.
Within the configuration pane, follow these steps to configure the trigger action for recipes triggered from a webhook.
Click the Start guided setup button.
Name the Webhook.
Naming the webhook adds the name to the generated URL, making it easier to identify what recipe it's for.
Copy the webhook address.
Within the source application that will send data to Recipe Builder, configure the webhook using the generated address.
Within Recipe Builder, click Next at the bottom of the modal.
Within the source application that will send data to Recipe Builder, trigger the webhook.
Within Recipe Builder, review the data received by the webhook.
Click Setup webhook.
(Optional) Toggling Set trigger condition will allow you to add additional rules to the trigger event, reducing the number of jobs.
NOTE: If you initially selected a different trigger method, you can switch to a scheduled trigger in the configuration pane by clicking on the App step of the configuration pane and searching for "Webhooks."
Configuring Actions
App Actions
Actions carry out an operation in your target app, such as a create, update, or search operation.
Follow these steps to configure an action in app.
Select the Application you would like to perform the action in.
Apps that you have already created connections for will be listed in the Configuration Pane.
You can search for for an app by name in the search bar.
Select the action that you would like to take. Actions will have a name and a description to help determine how it works.
Connect to the Application.
If you already have a connection made that you want to use, select it from the list.
or
Follow the steps outlined in Creating a New Connection in Recipe Builder to create a new connection.
Set up the Action
Depending on the action, the fields in this step will differ. Fields marked with a red asterisk are required.
You can enter text into the fields to create a constant. Every time the recipe runs, it will use the text entered in the action.
The Recipe Data Pane lets you insert Datapills from previous steps as variables in these fields. Every time the recipe runs, it will check to see what data is in the specified field and use it in the action.
For example, in the following picture, the data in the Next column from Step 1 is being used to populate part of the project's name and the data in the Email column from Step 1 is being used to populate the Project Manager's Email.
In addition to text input, you can use formulas to populate the field. To toggle from text mode into formula mode, click formula on the top-right of the input field. This changes the background color to indicate that you are in formula mode.
For example, in the following picture, the data entered into the Due Date field will be 2 days from the date of the job.
Logic Actions
Take advantage of conditional logic to add decision branches to your recipe.
IF Conditions
An IF condition step enables a recipe to execute an action or a series of actions if the specified condition is satisfied.
These steps act as a fork in the path that a recipe can take. If the condition is met, it will continue down the Yes path, if it isn't met, it will continue down the No Path.
The following recipe has two IF conditions:
IF the Zendesk External ID is Present, Get the GUIDEcx Task with that ID.
IF the Zendesk Ticket and GUIDEcx task have the same status, stop the job.
Follow these steps to configure an IF Condition:
Setup your condition.
Click the step labeled Setup your condition.
In the configuration pane, enter a datapill from a previous step into the first field.
Select the condition from the dropdown. A full list of available conditions can be found here.
Specify the value that the action will check against.
(Optional) Add another condition.
Click the + icon below the first condition.
Select either AND or OR. Selecting AND will require events to satisfy all conditions in order to proceed. Selecting OR will require events to only satisfy one of the conditions in order to proceed.
Follow steps a-d above for the new condition.
Configure the action(s) you wish to take if the condition is met.
Click on the step labeled Select app and action to do when condition is met.
Follow the steps in Configuring an App Action to add an action.
(Optional) Add additional steps to the Yes branch of the recipe.
IF/ELSE Conditions
An IF/ELSE condition step adds the ability to provide a seperate set of instructions for the recipe to follow if the condition is not met.
The following recipe has an IF/ELSE condition:
IF the Row number from Step 7 equals 7, Update Row 2 to "y".
ELSE Update the next row to "y".
The recipe then will update the original row form Step 7 to "n".
Follow these steps to configure an IF/ELSE Condition:
Follow the steps for configuring an IF condition.
Configure the action(s) you wish to take if the condition is not met.
Under the step labeled ELSE do the following actions, click on the step labeled Select app and action to do when condition not is met.
Follow the steps in Configuring an App Action to add an action.
(Optional) Add additional steps to the branch of the recipe.
Repeat Action
When working with a list of items, it is often necessary to perform a specific set of actions for each item in the list. Actions placed within the repeat block will be executed for every item in a provided list.
Follow these steps to configure a Repeat action:
Setup the List.
Click on the step labeled Setup a list. Repeat following action(s) for each item in list.
Select a list datapill from a previous step to act as the input.
Select whether to repeat the steps for one item at a time, or for a batch of items.
If repeating for a batch of items select the batch size.
Configure the action(s) you wish to take for each item in the list.
Click on the step labeled Select an app and action in the repeat block.
Follow the steps in Configuring an App Action to add an action.
(Optional) Add additional steps to the repeat block of the recipe.
Call Function
The call function allows you to trigger another recipe allowing you to quickly and easily re-use recipe logic.
Refer to Workato's Recipe Functions documentation for more info.
Stop Job
The Stop Job step ends the job. Preventing further steps from being run. It is typically used as part of the logic in an IF condition.
Handle Errors
The Handle Errors Action allows you to provide steps for the recipe to take if a step errors. Actions placed in the Monitor block will be monitored for errors and if an error occurs the recipe will follow the steps in the On Error block.
Follow these steps to configure a Handle Errors action:
Configure the Monitor block.
Add any steps to the block that you want to monitor for errors.
Configure the On Error Block.
Select whether you want to retry the actions in Monitor Block.
Click the action labeled ON ERROR.
Select how many times you want to retry the actions in the dropdown.
Add steps that you want the recipe to take if there is still an error after retrying the action.
Testing Recipes
Follow these steps to test the recipe:
Click on Test at the top of the screen.
While Recipe Builder looking for a new event, recreate the trigger condition.
To manually stop the test, click on Stop test to end the test.
Review the resulting Test Job.
Click on any task you would like to analyze (failed tasks will show up in red with a warning symbol).
Review the Inputs, Outputs, Error, and Debug information (sections vary depending on the state of the task) and navigate to the information you would like to review.
If there aren't any errors in the test job, check that the expected behavior happened in the applications the recipe uses.
Best Practices
Develop in test environments: Please perform testing in a development or sandbox environment or against objects or records that will not affect production processes. In your testing, validate critical flows to ensure that once the integration is live it will not negatively impact your business flows or data accuracy.
User trigger conditions: User conditions can be set on the triggers to determine whether or not a recipe should run. Leverage this to reduce the volume of tasks your account consumes.
Be strategic about data timeliness and volume: Set your trigger events to align with your business need and not necessarily the fastest update or largest volume of data.
FAQs
In recipe builder, is there a way to pull the value from a custom field on a project?
In recipe builder, is there a way to pull the value from a custom field on a project?
You can return the custom field values for a Project with Get Project by ID Action. Set it up as a formula using the "Output" of that GET Project by ID Action. Example:
Record ID is the name of the Custom Field in this Example.
['customFields'].where("name":"Record ID").pluck('value').smart_join("")
How to "comment out" on recipe builder?
How to "comment out" on recipe builder?
Use the three dots option on the item and select "skip" on the step in question or you can use the shortcut that it shows.
