Collection Outputs

Collections are groups of outputs that can contain many items.  It's much easier to explain with an example, so that's what we'll do here.

You'll know you have a collection when you see the [  ] icon:

You can also treat any array item within a data output as a collection.

Here, we're using a method that allows us to get invoices that have been sent to a customer.  Of course, a single customer could have 1, 2, 5 or actually any number of invoices.

Let's assume our customer has 3 invoices:

Now, a few things to note.  This is a simplified example; you're likely to see a lot more outputs in real life but that won't change how you use them!

You'll also notice that invoice 3 only has a single product, which is something you might come across when using collections for real.  Where important, we'll explain how missing values are treated in the use cases below.

Using the first item of a collection

The simplest thing you can do with a collection, and probably the most common way of using collections, is to use the first item.

Collections are often found in the outputs of search methods.  Think about searching for customers in your CRM.  You might want to search for a customer by email address and add a note.  In this case, you want a single customer to add a note to.

By default, collection outputs always give you the first item.  So just pick your output and use it in your field, easy!

So thinking back to our invoices example, this is what the input field will look like if we pick the outputs straight from the list:

This is what the task receives:

The most recent invoice is 123, for amount $20 and the first product is PAPER.

If you refer to a value that's missing, it will be replaced with nothing (an empty string), just like when using an output that's not from a collection.

Using a numbered item in the collection

Maybe you want to use the second item in the collection?  You can do that by adding a 2 at the end of each output tag:

So {{output}} becomes {{output 2}}.  This is what the task now receives:

The most recent invoice is 456 , for amount $80 and the first product is INK.

Of course, if you wanted to use the third invoice, make it  {{output 3}} (this works for any index of the collection).  You can also get the last item in the collection by using {{output n}}.

If you refer to a value that's missing, it will be replaced with nothing (an empty string), just like when using an output that's not from a collection.

Listing items in a collection

Another common thing you'll want to do is list all the values for a single output in a collection.  For example, you might want to list all the invoice totals for this customer ($20, $80 & $10).

You can do that simply by modifying {{output}} to  {{output &&}}.  So lets see this in action:

This gives us the input:

This customer has invoice totals $20, $80 & $10.

If you'd prefer a list separated only by spaces, you can use {{output &}} which would give you:

This customer has invoice totals $20 $80 $10.

Items in the collection that are missing the value that you are listing will be skipped over.  For example, if the second invoice didn't have an amount, you would get $20 & $10.

Getting a sum of all values in the collection

This time, we want to total up all the invoice amounts.  It's as simple as using {{output =}}.  Just like this:

Which results in:

This customer has been billed $110.

Note that although {{output =}} can handle the $ symbol in the value and still add them up, it will return a number so we need to add the $ back in.

Counting the number of items in a collection

To get a count for how many items there are in a collection, you can use {{output #}}.  This will count the number of values it finds.

So we can use this to count how many invoices a customer has:

Resulting in:

This customer has been sent 3 invoices.

Items in the collection that are missing the value that you are counting will be skipped.  So if the second invoice for our example customer didn't have an amount, and you counted the amounts, you would count  2.

Repeating the field for each item in the collection (Magic Repeat)

It's called Magic Repeat because it magically repeats your text for every item in the collection, making it easy to list the details of the collection in whatever format you choose.

Even though it's powerful, it's still really simple to us.  Just use {{output *}} to make your output a Magic Repeat.

To see it in action, lets assume we want to list the details of all invoices that have been sent to our customer.  Use Magic Repeat like this:

When the task is run, it gets this input:

123 for $20.
456 for $80.
789 for $10.

It's as simple and useful as that.  The first magic repeat found in the field determines the collection that should be repeated.

Note that when you use magic repeat, the  whole field will repeat for each item in the collection.  Make sure you use {{output *}} for every output that you want to change for each item in the collection, just like in the example above.

The text will be repeated for every item in the collection, regardless of whether it has values missing. If you reference a value and it's missing for the item being repeated, it will be replaced with nothing (an empty string).

Collections Cheat Sheet

To quickly remind yourself of the options available with collections, here are all the options:

• {{ output 1 }} - use the first item (same as {{ output }})
• {{ output 5 }} - use the 5th item
• {{ output n }} - use the last item
• {{ output = }} - sum of all values
• {{ output # }} - count of all values
• {{ output & }} - space separated list of all values
• {{ output && }} - formatted list of all values
• {{ output * }} - Magic Repeat

Let us know how we can improve Flow XO on our feedback site.