Callable response

Overview

When using the Tray Platform there will be ocassions when you need to send data to a callable workflow, and you wish that workflow to respond - perhaps with a confirmation message, or with some data retrieved via a processing mechanism - before continuing with the main workflow.

The Callable Workflow response connector can help you manage these situations.

The steps involved in using callable workflow response are:

1. Create a workflow with a callable trigger (operation set to Trigger and respond) and a callable workflow response step (when using 'Fire and wait for response' this workflow will now be available to select from the drop-down of callable workflows)

2. Create a main workflow which generates data (via interaction with service connectors and core/helper connectors) and pulls the data into a Call workflow (operation set to 'Fire and wait for response') step which calls the workflow created in step 1

3. Return to the workflow created in step 1 to configure the processing actions and set the data to be sent back to the main workflow via the callable workflow response step

Note: for more advanced requirements please also see our tutorial on Workflow threads. This talks you through how to deal with processing batches of data whereby the processing itself is heavy and time-consuming and so you will need to set up a system to notify when all the instances or 'threads' of the callable workflow have finished.

1 - Set up the callable workflow

We need to make a callable workflow available so we can create an empty callable workflow, with the trigger operation set to Trigger and respond:

2 - Set up the main workflow

Now we can create the main workflow which will pass the data to the callable workflow.

In this example we start with a manual trigger and use an Object Helpers step to create some dummy JSON data with the JSON Parse operation (one feature of this operation is that it allows you to enter JSON data into a text box and 'parse' it so it is available to be pulled by any subsequent steps).

This mimicks a scenario whereby you have pulled data from a particular service and want to send it to another workflow to be processed in some way.

The final step in the main workflow pulls all of this demo customer data using the $.steps.object-helpers-1 jsonpath and sends it with the Call Workflow connector and the Fire and Wait for Response operation:

A run of the workflow will then send off a list of customers to the callable workflow to be processed:

3 - Fully configure the callable workflow

You can now return to the callable workflow and set up the processing routine, before sending back a response to the main workflow.

In this example, in order to compile a list of all the tags that have been used across all customers in the list, we have:

1. Looped through the customer data received by the trigger using a Loop connector

2. For each customer used an Object Helper 'Get value by key' operation to pull the tags for that customer

3. Added the tags for each customer to a complete tagsList using a Data Storage 'Append to list' operation

4. After all customers are looped through, got the tagsList using a Data Storage 'Get Value' operation

5. Sent the complete tagsList back to the main workflow using a Callable Workflow Response 'Format response' operation

4 - Check the response being sent back to the main workflow

When the main workflow is triggered the call and response sequence will be set off.

Inspection of the debug panel will clarify that the Call Workflow step shows the data it passed (the dummy customer data) as Input and the data received back (the tag list) as Output which can then be used by any subsequent steps in the main workflow:

Setting input and output schema to control data structure

In order to make sure that the data being passed between your main and callable workflow adheres to a strict structural format, in the workflow being called you can:

1. Set the Input Schema for the Trigger. This links back to the main workflow and can force the structure and properties of the data being gathered and passed by the main workflow

2. Set the Output Schema for the Callable Workflow Response step. This can be used to make sure that you always send back the requisite data to the original workflow, in the correct structure

Taking the above example of customer data, we could imagine a scenario where the data for a single customer is being sent and we wish to make sure that only certain data is sent, and only certain data is sent back.

Setting the input schema

First off, for the Callable trigger we can click on Edit input schema:

And then add the properties to the schema and set the data type (short-text, array etc.):

Each property has an Advanced settings drop-down whereby you can specify that it is 'required':

If you return to the main workflow this will be reflected in the properties panel for the Call workflow step:

Setting the output schema

Then for the Callable workflow response step we can click on Edit output schema. In this example it may be that we want to use the customer's email to find their entry in a Google Sheet which has a list of customers' emails and favorite colors.

In this example it is done by pulling in the email from the trigger and using the Google Sheets 'Find row' operation:

Then we can click on Edit output schema for the callable workflow response step:

And we can use the dialog to set the required data structure to be sent back each time the workflow is called:

As for the input schema each can be set as required using the advanced settings.

Returning to the workflow you can then see that the schema is reflected in the required fields: