Building a Converter Flow

Last Updated: 08/11/2016 Introduced in Verision: 2.0

Converter flows are specially designated to create data or transform objects from one datatype to another. Because of their unique nature, converter flows are implemented as a mapping type, rather than as a sub-flow. Converter flows can be created just like any other flow, but their End Step must output an item or collection of items with a defined type. Such a converter flow may then be implemented in other flows by selecting Run Converter Flow as the Mapping type, and then selecting the converter flow you’d like to use.

Example

Our example will consist of two flows: a converter flow that will transform a list of user accounts into a list of the email addresses associated with those accounts, and a master flow that will display this list of email addresses within a form field. 

Note that all the default conversion flows are found under System > Shared Designer Elements > System Defaults > Converter Flows. It is recommended to save any new converter flows to this location to keep them organized (however, it is not required). Create a new flow and give it a name, such as “Get All Email Addresses” and click OK to open the Flow Designer.
 
From a high level, building this converter flow will:
  1. Use the Get All component to collect a list of user accounts.
  2. Use the Create or Copy component to create a list that will contain the email addresses.
  3. Add a data definition to the Create or Copy step.
  4. Use the ForEach component to iterate through a list of user accounts.
  5. Specify the ForEach step’s collection type, path and mapping type.
  6. Use the Add Item to List component to extract email addresses from the user accounts and add them to the list.
  7. Map the inputs and outputs for the Add Items to List step.
  8. Add an output to the End step so that the converter flow will output the list of email addresses.

The first step of our converter flow is to collect all of our user accounts. To do this, select the Get All component from the Flow Designer start-up window. This component can be found under the Integrations > All Integrations > Internal Services > Account Service category. Click Add to place it to our flow.

 

 flowStarts

The next step of our converter flow will be to create a list which will eventually contain the email addresses we’ve extracted from our user accounts. To do this, drag the Create or Copy Data component from the Toolbox panel and place it in our flow. This component can be found under the Data category. Connect the steps as follows:

createOrCopyData

 
For our step, Create or Copy Data 1, to know what type of data it will be creating or copying, we must add a data definition. Click on the Create or Copy Data 1 step.
In the Properties panel, under Data Definitions, click the Add button and create one. Our list will be composed of email addresses, so we can give it the name “Email Address List.” The list will be comprised of just email addresses, not objects, so we can give it a type of String. We want to create a list of elements, not just one, so select the Is List checkbox. We also want to allow for the possibility that some accounts may not have email addresses associated with them, so check the box Can Be Null. This completes our data definition for the Create or Copy Data 1 step. Click OK.
 datadefinitionForCreateData
 
 
Our next step will be to iterate through our list of user accounts, one by one, so that we can copy each email address and add it to our Email Address List. From the Toolbox panel, under Flow Management, drag the ForEach Step component to the workspace.
 
In order for ForEach Step 1 to know what kind of items it will be iterating over, it is necessary to specify its collection type. This control can be found in the Properties panel, under Collection > Type, and we select the collection type Account.
 pickTypeForForeachStep
 

In order for the ForEach Step to know exactly which output contains the collected accounts we want it to iterate through, also specify the path and mapping type of its input. This control can be found in the Properties panel, under Inputs > Collection. Select Select Value and browse to the output of the step Get All 1 – GetAll1_Output.

getAllOutput

 

Our flow is now set up to collect all of our system’s user accounts, create an empty list of email addresses, and iterate through the collected accounts, but we still have to extract the email addresses from the accounts collection and add them to our empty email addresses list. We can do this with the Add Item to List component, which can be found in the Toolbox panel, under Data > List.

Structure the paths from ForEach Step 1 so that each Next outcome or iteration will pass through the step Add Item to List 1. When the Add Item to List 1 step returns an outcome of Done, our flow will be directed back to ForEach Step 1. When ForEach Step 1 is Done, meaning that it has reached the end of our collected accounts, it will direct our flow to the End Step for final output.

addItemToListStep

 

To work correctly, Add Item to List 1 must know the type of list to which it will be adding items, and what those items will consist of. In Create or Copy Data 1 we defined our data as a list of strings, so we will select the type String in the ListType field.

Our next step is to tell Add Item to List 1 what our items will consist of. To do this, open the Mapping Editor. Add Item to List expects two inputs: an original list and a new item to be added.

Our original list was created in the step Create or Copy Data 1, and we can map that list by selecting and dragging the appropriate anchor from Email Address List to the input Original List.

New items for our list should consist only of the email addresses associated with our accounts. Because each email address is a property of an Account object outputted by ForEach Step 1, expand the Account output Item to display its properties. Near the middle of the properties list, find EmailAddress, and map to the input New Item.
 mappingEditorForAddItemToList
 

Our last step in mapping the data for Add Item to List 1 will be to map the appropriate output. Because we want our email address list to be accumulative – that is, each time an email is added, the list is saved before adding the next – map our output back to the original list created in Create or Copy Data 1. To do this, drag the anchor for our output – New List – to Email Address List. With this last mapping completed, click OK to save our mappings.

mappOutputsForAddItem

 

Our converter flow is almost complete. The last step is to configure our flow to output the list of email addresses so they can be used in another flow. To do this, add output to our End step by clicking the Add button under Output in the Properties panel.

To quickly and easily define our output, this Object Editor gives us the option to select the data to output from a list of available outputs. See this list by clicking the link Pick from flow data.
 addFlowOutput
 

In this new pop-up, we’re allowed to choose any of the step outputs from our flow. Select Email Address List and click OK.

Also select the Can be null and Is list checkboxes to indicate that our output consists of a list which may contain empty values. Click OK to complete our End Step‘s output definition.
 finishOutputStepDefinition
 
 
Our converter flow is now complete. However, one last setting needs to be established, and that is its flow behavior.
 
From the Actions menu for the flow, click on Manage > Set Flow Behavior.
 setFlowBehavior
 
 
Select Converter Flow and click Set. Now the flow can be properly recognized as a conversion flow. See the topic Changing Flow Behavior for more information.
 
 
To use it within the context of another flow, save it and create a new flow to use it, which we’ll refer to as a master flow. See the topic Using a Custom-Built Converter Flow to continue.  
 
 

Additional Resources