Callable recipes

How often have you created a recipe where you have had to repeat logic? For e.g.

        You want to create an account if an account with same name does not exist, and update

the account if it already exists

        If an account or contact is not found you want to send an email and notify the admin

Workato recipes help you create a recipe that can house repeated logic, so it can be called from another recipe. Callable recipes are great for

        Instead of having really long recipes, break it out into smaller recipes that can be called

        If you have a standard error notification policy, you can create a recipe and then have all

recipes call this recipe for error notification

        If you wish to share your logic segment with others, you can enable REST enable it to

allow people to call your endpoint/callable recipe from their Workato accounts or through

standard REST

Brief overview of how callable recipes work

  1. A main recipe containing a ‘Call recipe’ action from the ‘Workato recipe’ connector is triggered.
  2. This main recipe will pause at the ‘Call recipe’ step while the recipe called upon will trigger.
  3. The called recipe would have a ‘Receive request’ trigger, as well as a ‘Send reply’ action wherever the recipe ends, from the ‘Workato recipe’ connector. The called recipe runs the job and completes the recipe (either successfully or unsuccessfully).
  4. When the callable recipe ends successfully, the main recipe will continue from where it paused.
  5. If the callable recipe job failed, the main recipe will display a failed job as well.

Detailed walkthrough

Example scenario: Salesforce closed-won opportunity creates a Quickbooks Online invoice (and creates a customer if the customer doesn’t already exist)

For example, let’s say that we wish to build the following recipe. We can turn steps 3-4 into a callable recipe so that we can reuse the (Search QBO customer, create if doesn’t exist) logic in any recipe we want. Hence we won’t have to rebuild these 3 steps and retest them and their mappings over and over again.

  1. Create callable recipe with ‘Receive request’ trigger and final ‘Send reply’ action

We first need to create a callable recipe that the above original recipe can call on. Create a new recipe and set the trigger as the ‘Receive request’ trigger from the ‘Workato recipe’ connector.

Name

The name you wish to give this callable recipe. This will show up on the picklist of callable recipes you wish to call when you select the action ‘Call recipe’ from the main recipes.

Request JSON schema

The data structure you define for the data that will be passed to this callable recipe from the main recipe. We try to pass only data that is relevant for the recipe.

In the main recipe, shows up as input fields for ‘Call recipe’ action for user to pass data into callable recipe.

In the callable recipe, shows up in trigger datatree for user to use data from main recipe in the callable recipe.

Reply JSON schema

The data structure you define for the data that will be passed back to the main recipe from the callable recipe. We try to pass only data that is relevant for the main recipe.

In the callable recipe, shows up as input fields for ‘Send reply’ action for user to pass data back into main recipe.

In the main recipe, shows up in datatree of ‘Call recipe’ action for user to use data from callable recipe in the main recipe.

Enable REST endpoint

Yes if we wish to let others have access to this callable recipe. This means that you allow them to trigger the recipe and pass in data to this recipe while it’s connected to your apps, i.e. to create/update/search/delete objects in your connected applications

For this scenario, I’ve filled in the trigger fields as follows. I have defined that I only wish to pass in display name, and, optionally, company name into the callable recipe (for it to use to search for my customer or create my customer by), and that I wish to only send back the customer ID. The actual mappings will be done later - I’m only defining what I would like to receive (request) from and reply to the main recipe now:


The request JSON will show up in the trigger datatree as values available for use, as it’s data coming from the main recipe:

While the reply JSON schema will show up in the send reply step as data to be sent back to the main recipe:

We can build our recipe that consists of the actions we had wanted to decouple from the main recipe as such:

And in order to send a valid reply back to our main recipe, we would need to map a proper value into the reply data structure. If you recipe consists of multiple branches where the recipe may end and return to the main recipe, every branch needs to have its own ‘Send reply’ action to send its reply data back to the main recipe.

I will map the Quickbooks customer ID from the search as well as from the create actions - in that way, we return a customer ID no matter if we found that the customer already existed, or if we had to create the customer. The main recipe only needs to know the Quickbooks customer ID it should create the invoice under:


  1. Adding the ‘Call recipe’ action in the main recipe

Now that we have a callable recipe to call from the main recipe, we can replace steps 1-3 in our main recipe with the ‘Call recipe’ action step from the ‘Workato recipe’ connector. Our original recipe can be seen below:

And our new, shorter recipe will be:

In the request parameters section, you see the data structure you had previously defined in the callable recipe’s request JSON schema field. This is the data we need to pass to the callable recipe for it to execute its steps. You would need to provide the mapping for the actual variables to be passed into the callable recipe. In the following, I passed in the account name associated with the Salesforce opportunity. This is the name which the callable recipe will use to do a search customer action/create customer action with:

And in subsequent steps, you can see that the ‘Call recipe’ datatree has the data structure we defined in the callable recipe’s reply JSON schema field. This is the data our callable recipe returns to the main recipe that would be useful for the main recipe. In this case, it would be to use the Quickbooks customer ID to create the invoice under the customer:


REST endpoint

Enabling a REST endpoint allows you to expose your callable recipes and allow it to be called, not just by all your other recipes, but also by others, as a REST endpoint. Enabling an endpoint doesn’t mean that it’s automatically available to everyone, however - you would still need to give access to people via API tokens that you can generate and give out.

If you had marked the ‘Enable REST endpoint’ as yes earlier, there would be additional fields generated in the ‘Receive request’ trigger:

HTTP method

The type of endpoint you would like this callable recipe to be: GET, PUT or POST.

Service path

The unique name of the endpoint, across all the endpoints you have, that should be descriptive of what the endpoint does

You would need to fill in these additional fields. We select GET here, as we are passing in only the Salesforce account name and possibly retrieving multiple variables back from the callable recipe. We can just give a suitably descriptive service path, like  /check_quickbooks_customer.

To manage these callable recipes’ endpoints, bring up the menu when you hover over your username, and go to Service Catalog. You should be able to view your endpoints on this page:

And you can test out your endpoints simply by expanding the endpoint - there’s an interactive panel where you can pass in the expected request JSON schema values (such as DisplayName and CompanyName below)

And simply click on the button ‘try it out!’ - the request URL should be generated for you and the request made. If all goes well, your callable recipe should return you data in the reply JSON schema you defined previously.

In order to give access to your endpoints to people, you need to provide them with a unique API token they should use via the ‘Manage API tokens’ link as above. You should create a unique token for every user you wish to share your endpoints with. Take note that whoever has access to this token will have access to your callable recipes.