Using a Set variable node to create mappings that you can reuse within a flow

You can create your own data properties with defined mappings to use as variables in an IBM® App Connect flow. This enables you to create and store custom mappings in one place in your flow and reference these mappings repeatedly in other places in the same flow.

You can use the Set variable node to create custom reusable mappings. This node contains a property editor that you can use to define simple or complex variables of a particular JSON data type; for example, string, object, or array. Using the editor, you first create properties (as variables) with assigned names, data types, and a structure (if the data type is an object or array of objects). Then, assign mappings to these properties by using values from earlier nodes in your flow. Once defined, you can then use these properties or variables multiple times as input in subsequent nodes in your flow.

The Set variable node is available from the Toolbox tab. You must position this node in your flow before any nodes that will reference your mappings as variables.

Figure 1. Set variable node in the Toolbox

Defining and using reusable mappings
Example

Defining and using reusable mappings

You can define reusable mappings as follows in your Set variable node:

To define your properties, use Add property to add a name and and data type for each property.
Figure 2. Set variable node inserted into a flow, showing buttons for Add property and Edit mappings
(Click image to view full size.)

For properties with a data type of Object or Array of objects, you'll need to also define a structure that identifies any hierarchical parent/child relationships. For more information about adding properties, see Example 1: Using the property editor and Example 2: Using the property editor to map a "source" array to a "target" array in the Defining your own data properties topic. You can define multiple sets of properties from this node.

The following example shows a set of Attendee properties that are defined to be used in a flow that is triggered when someone signs up to attend a company's events.

Figure 3. Property definitions in the Set variable node
(Click image to view full size.)
Expose the properties as fields so you can specify their values by mapping to fields from earlier nodes in the flow. Click Edit mappings to show the property fields and then define their mappings as described in Example 1: Using the property editor in the Defining your own data properties topic.
Note: You can also apply JSONata expressions to the mappings. The following example shows the completed mappings for the Attendee properties from the earlier image.

Figure 4. Mappings for properties in the Set variable node
(Click image to view full size.)

You can now reuse the defined mappings in subsequent nodes in the flow. Let's suppose you want to include a new attendee's full name in a confirmation email about an event (implemented as a Gmail / Create message action). You also want to add the new attendee's details, including their full name, to a spreadsheet that you maintain (implemented as a Google Sheets / Create row action). You can reuse the [FullName] mapping, which is a combination of an attendee's title, first name, and last name (for example, Ms Jane DOE), in both of these nodes. In the following examples, which illustrate the reuse, notice that reusable mappings are displayed under a Set variable section in the Available inputs list.

Figure 5. Adding a reusable mapping for Gmail

Figure 6. Adding a reusable mapping for Google Sheets

Example

I have an Eventbrite account that I use to manage many events for my company called MattClarkeEventsInc.

Each time I receive a new attendee to one of these events, I want to be able to respond in the following way:

Respond by email to the new attendee, providing them with information on other attendees from their company.
For each of those discovered existing attendees, send an email to notify them of the new attendee from their company.
Add information about the new attendee to a spreadsheet that I keep up to date with the known attendee list, indicating if the attendee is an employee of my company or not.

To be able to send the emails and keep the spreadsheet updated, I require the following information:

Attendee's full name
Attendee email
Event name
If they are an employee of my company
The related list of attendees information – each colleague's name and email

My event management flow

Upon receiving a new attendee, I gather the following information using existing Eventbrite retrieve actions:

The event itself (using the event ID of the new attendee)
All attendees to the event (using the same event ID of the new attendee)

With the Set variable node, I can bring together all the information that I need into a readable data structure that can then be mapped to. I define the structure of my variable to be:

Figure 7. The Set variable node used to bring together all the information that I need into a readable data structure

And then I use Edit mappings to define each property's mapping, using JSONata expressions where appropriate:

Edit mappings used to define each property's mapping

(Click image to view full size.)

The Attendee and Event information are fairly trivial mappings; the most complex being deriving if the attendee is my employee or not.

The FellowAttendees mapping is of type Array of objects, as I need it to be a list of attendee objects each with some information about them. That mapping needs to output an array that can be iterated over and have mappings applied on the child properties.

Figure 8. FellowAttendees mapping as an array, showing use of a JSONata expression

I need the contents of the FellowAttendees array to contain all current attendees who are also from the same company of the new attendee. I used the following JSONata expression to establish that list:

$EventbriteRetrieveattendees[profile.company=$Trigger.profile.company][profile.email != $Trigger.profile.email]

The predicate (the rules contained within the [ ] ) for the mapping will evaluate a list of attendees:

Whose company matches the company of the new attendee
But whose email is not that attendee; so that I don't have the new attendee in that list

I can now use those mappings in my actions I want to perform in my flow.

So for the new attendee, I construct the email using my Set variable node mappings:

Figure 9. Create message action, showing use of Set variable node mappings

Because I have the list of fellow attendees as an array structure I need to apply some logic that will allow me to extract that information into a more readable format when sent in an email. JSONata has a set of functions that can be used when working with array structures. This time I use the $map function to convert every array entry into a more readable string of attendee name and email.

Viewing the evaluated sample data, I can see the suggested output of my mapping for the Body field is one that is readable by the receiver of the email.

Figure 10. The evaluated sample data showing the body content of the email message

To now perform the bulk task of emailing fellow attendees, I used a For each node that will iterate over the same array structure that is set on my Set Variable node mapping.

Figure 11. For each node used to iterate over the array structure that is set on the Set Variable node mapping

That allows me to construct a standard email template to be sent to all the attendees in that list, again using the Set Variable node mappings:

Figure 12. Standard email template to be sent to all the attendees in the event list

I then reuse the Set Variable node mappings as the values to insert for the new row in my spreadsheet:

Figure 13. Set Variable node mappings used to insert data for a new spreadsheet row

My flow is now complete and ready to switch on.