Connectors / Helper / List Helper

List Helper

List Helper

Perform quick manipulations to an array of data.


The Tray 'List Helpers' connector allows you to quickly create and manipulate lists based on arrays of data generated by other services and connectors in your workflows.

Amongst other things, this allows you to combine data from multiple sources, sort it, extract certain values, find common items, create batches for processing...

Note some list actions you wish to carry out will require use of the Append to List operation found in the Data Storage connector. This is illustrated in the first example below.

'Concatenate' and 'Sort Objects' Example - combining and sorting lists of project tasks

This example will take you through how to use the Concatenate and Sort Objects operations.

What we will be achieving here is:

  1. Get lists of tasks from two separate Asana projects
  2. Combine (using concatenate) these into one list
  3. Sort (using sort objects) these tasks in date order - with earliest due at the top
  4. Use the loop collection, data storage and text helpers connectors to format these into a batch message which lists the tasks and their due date one-by-one
  5. Send this batch message to a Slack channel so as to notify about the tasks which are due, with the earliest tasks listed first

The end result in Slack will look something like:

In Tray, the complete workflow looks like this:

Step 1 - List the Asana tasks by project

For each of the Asana steps above you will need to set the operation to List Tasks and choose the project.

This will create the two lists that we want to combine. When a workflow has been run and you are inspecting the debug output of a listing of Asana tasks, you will see that there is a lot of data associated with each task:

Step 2 - combine the lists

Set the first list helpers step to Concatenate and choose the two Asana steps as Lists 1 and 2.

Step 3 - sort list by date

Set the second list helpers step to sort objects, the list to $.steps.list-helpers-1.result and choose due_on as the key. We know to use due_on because the output schema from either of the Asana steps lists it for us (you can also see it in the above list task output screenshot from Step 1):

Step 4 - loop through each task to create individual messages

Add a loop connector and set the input list as $.steps.list-helpers-2.result

Get Asana project

For each result you should get the Asana project name using the Asana Get Project operation, using $.steps.loop-1.value.projects[0].id to get the id for the project which the current task comes from:

Create message

The Create messsages step uses a data storage connector to create and store the indvidual message for that task. Do this by using the Append to List operation and make sure the Create if missing box is ticked:

Keep the scope as 'Current Run' and set the Key as 'message' (this means you will be creating a list of 'messages')

Note that the Value is kept as 'string' type and uses { } to allow for use of jsonpaths to grab the necessary data for each message:

The '{$}' task from the '{$}' project is due on {$.steps.loop-1.value.due_on}

This would create a message such as "The 'Deploy to Production' task from the 'Shareable Workflows' project is due on 2018-08-05"

Step 5 - Get messages

The final stage is to batch the individual messages together.

The Get messages step uses a data storage connector to get all the stored messages:

These are returned as an array:

Step 6 - format the batch message with a Text Helper

We can then pick these up and format them using the Text Helpers (Create batch message) connector. This uses the Concatenate operation and grabs $ to go through the individual messages.

The key step to formatting the message correctly here is, in the Separator box, hit the 'Enter' key on your keyboard to add an empty line. This will ensure that each message takes a new line.

Step 7 - send the message to Slack

The final stage is to choose a Slack channel to send the message to:

The message is grabbed from the previous step with $.steps.text-helpers-1.result

And the final message sent to Slack should look something like this:

'Delete items from list' example

The Delete items from list operation can be used to create a list and delete certain items from it which match certain conditions:

The above example shows how you could remove a project with a particular title from a list of Asana projects.

Another way to use this might be to change the Comparison type to 'Contains' and the Value to 'test' in order to filter out any projects which are only test projects.

'Join' example - converting a list into a string

In some cases, you may want to combine every item in your list into one string, for example, for it to read well in a sentance. The Join operation allows you to do just that.

In this example, we have a Google Sheets file where people can sign themselves up to a fun run. We want to take the names and compose an email that tells the organizers who has signed up.

The above workflow takes every name in the 'First Name' column from a Google Sheets file and stores them under a list called 'members' that is stored in the data storage connector. We will take those names and use them to compose an email.

This example will pick up from the second data storage connector, storage-2 which 'gets' the list (using the Get Value operation). If you would like more information on the steps before this point, please refer to the Google Sheets connector, Loop connector and the Data Storage connector documentation pages.

We currently have a list of first names from the Google Sheet, that looks like the below:

We want these names to be bullet points in an email that will be sent to the organizers. We can use the List Helpers Join operation, which will turn every item inside the list into one long string. Firstly, using the connector snake select the output of the previous data storage step to reference the list - this will produce a jsonpath like $

We can now assign a separator, that will appear between every item once the string has been created. As we would like for them to be in a bullet point format, in the separator input, we will need to enter the following:

enter, hyphen, space

which looks like (the whitespace has been highlighted for easier reference):

This will give every name it's own line and precede every name with a hyphen. The output looks like:

We can see that Mike is not preceded with a hyphen, so this will need to be taken into consideration when composing the email.

Using the Send Email connector, set up the input to send the email to the desired recipient. The 'content' section is where the body of the email is composed. We can use interpolation to inject the output of the List Helper into the email. Remembering that Mike doesn't have a hyphen before it, we can add that in here:

When the workflow is now triggered, the following email is sent:

'Remove Duplicates', 'Count Items', 'Add Item To List', and 'Last' example - Counting the number of names in a document

In this example, we will be receiving a Google Sheets document that contains a list of names, then adding a final row with the number of unique names within the sheet, as some names will appear more than once.

The first steps of this workflow (that are not shown above) gets the row data from a Google Sheets file that has names listed in column A:

The names continue for 152 rows.

We have put every name into a list, which has been saved to a list stored in a Data Storage connector, under the key marketingResponses. If you want guidance on how we got this point, please see the relevant connector documents, linked to above.

We pick up on this workflow where we get the list of the names on the Google Sheets file, from the Data Storage connector. We then use four List Helper steps, which will use the operations we are focusing on.

First off, we will need to make sure any duplicate names are not counted. The first step will use the Remove duplicates operation. The list input will be the list of names from the data storage step.

This output will give us the same list as the data storage connector of the list of names from the Google Sheet, but each name will appear only once, any duplicates, as the name suggests, have been removed.

Note: A limitation of the Remove Duplicates function is that it can only remove simple items from an array, and it can't remove objects based on a particular field in that object being unique. Please see the Useful scripts page for a simple script-based way of doing this.

Now that we have a list of names that only appear once, we can count them to see how many individuals we have. The next step uses the Count items operation. This list input will refer to the output of the previous remove duplicates step.

The output of this step will give us the number of items (names) in the list.

We can add the number of unique names to the end of the list for easy reference later or in another workflow if needed. To do this, we use the Add item to list operation. The input is built using the list from the output of the remove duplicates step and the item from the output of the count items step.

Now, the final item in the list is the number of names in it.

As we know where the number of unique names is found within the list, we can use the last operation to add it to the Google Sheet.

In this case, the output will give us 139, which we can use to update the Google Sheet with interpolation. We build the input of the Google Sheet step with the following:

Where the Value input is set to text so we can add more detail Unique names: {$.steps.list-helpers-1.result}, which will update the Google Sheet with the number of unique names on the final row:

'Pluck' and 'Difference' example - retrieve and compare list of properties from objects

With the Pluck operation we can take a property from each object in a list and return a new list of those properties. In this example we'll retrieve the list of fields from 2 different objects in Salesforce, Account and Lead. Then we'll compare those two lists and be given the missing fields for the Lead object.

Step 1 - Set up your workflow

Here's a screenshot of what your complete workflow will look like.

We'll start off by creating a new workflow with a manual trigger.

Step 2 - Retreive Salesforce objects

Next we'll place a Salesforce connector after the trigger. We'll use the Describe object(advanced) operation and select our Record Type. In this case it will be Account.

Then we can duplicate this step by hovering over the Salesforce connector and selecting the 3 dots button. Inside that menu click on Duplicate. Within the newly created connector change the Record type to Lead

Here's a screenshot of just some of the output schema from the Describe object operation. As you can see it contains a lot of information. However we only care about the fields list and even inside of that we only want the property label from each field.

Step 3 - Pluck label

Now we can add our list helpers connector so that we can get a list of the field labels for each object. Select the Pluck operation. Using the connector snake set the List value to that of the first Salesforce connector fields list.

Then set the Key value to label.

You can then duplicate this connector the same way we did for the Salseforce connector. For the second list helper we want to keep the Key value as label but set the List value to the second Salesforce connector fields list.

Here's a sample output of the pluck step. As you can see we now have a tidy list of field labels.

Step 4 - Find differences

The last step in this example is to use both of the field label lists we created and find any differences between them. That way we can see if our Lead object has any missing fields that exist in our Account object.

Start by placing another list helper connector on to your workflow. In this list helper we'll be using the Difference operation. Set the Main list value to the result of the first list helper and the Second list to filter with value to the result of the second list helper. Your property panel for this connector should look something like this.

The output of this will vary depending on your Salesforce objects but will look similar to the screenshot below. A list of field values that exist in Account but not in Lead.

'Filter' example - Retrieve objects from a list based on filter criteria

In this example we have a list of account objects that are delivered from another workflow for processing. We need to find any objects that have null values in certain fields so that we can send those objects off to another workflow to be processed and enriched.

Here's what the final workflow will look like.

Step 1 - Set up Callable trigger

Start building your workflow with a callable trigger. This will allow our workflow to be sent data from another workflow which in our case is sending us a sample file of customer records.

Here's a sample of what the trigger is receiving

You can see that the data is stored in an array called 'records'.

In some of these records the fields will have null values as shown below. We can use the filter operation to search for any objects that have properties with certain values. In our example we'll be looking for any objects with either 'BillingState' or 'Type' set to null.

Step 2 - Add list helper

Add in the list helper right after the trigger. Select the Filter operation from the operation dropdown list. Next, using the connector snake, set the value of List to the output records of the trigger.

Set the Filter type to Inclusive. This will give us a list of objects that include our filter criteria which in our case would mean any object with either 'BillingState' or 'Type' set to null.

The Conjunction value will be set to Satisfy ANY condition. We us this because some of our objects will have either 'BillingState' or 'Type' set to null but might not have both and we want any objects that have either or both of those null values.

Here's a screenshot of the properties panel so far.

Filter list is where we set our filter objects. The screenshot below shows how we set up the filter objects. Each filter object has a property and a value. So our property is BillingState and the value is (null). The null value is set up by selecting the type menu to the right of the property as seen in the screenshot.

Here's the result of the our list helper. As you can see we've found two objects that match our filter criteria.

Step 4 - Call workflow

Now all we need to do is send our filtered data to another workflow to be processed. Add a call workflow connector after the list helper.

Set the Workflow value to whichever workflow you want the filtered data to be sent to. For the Data property click 'Add Property to Data' and label the new property null_objects. We will the set the value of null_objects, using the connector snake, to the result of the list helper. Now this workflow will filter the incoming data and send it to the next workflow to be processed.

All Operations

Latest version: