Using a Multi-Instance Loop for Employee notifications

We still have the requirement that all employees who are consuming the order need to be notified when it is delivered. So far, we have only implemented notification to the submitter of the Order record, using a Send Message activity. For the Recipients property of User Message, we need to find the Login ID of each associated Employee record in turn in order to notify them. How can we do this?

By now you will have already guessed that we will need to use the association definition we used in the New Order View, called Orders Submitted on Behalf of Employees. As you recall, this is a many-to-many relationship, so any given Order record can have multiple Employee records associated with it. Wouldn't it be nice if we could simply ask the Send Message activity to act on a set of data instead of just one object? The good news is that the process designer supports almost all activities doing exactly that: using properties that turn the activity into a Multi-Instance Loop.

Configuring the loop

The configuration for these properties can be a bit hard to understand the first time, so we will describe how the loops work in general, and then show how the configuration works, step-by-step (for more information, please check out To enable multi-instance loop in the article Creating-process-steps-or-activities).

For the purposes of this particular example, the important properties to configure are:

• Input Data Item - this refers to a process Local Variable that can describe one instance of the data in question. Before choosing this, the Local Variable must have been created first, so, setting this up is a prerequisite.
• Loop Data Input - this is an expression that refers to the set of data to be looped over. When using associations, this will be the Role Name of the association you want to use.

Once these are configured, the Loop Data Item can be used within this activity to refer to exactly one of the employees that will be consuming the order.

The following diagram depicts visually how these configurations interact with the data in our specific example. The most important aspects are the references to the associations, and to the Local Variable that will be used as the Input Data Item. If you still find this confusing, don't worry, because we will show the details for each of the five numbered steps as well.  Remember that you can click on the diagram to make it more readable.

Let's walk through it step-by-step. As usual, we will "start from the bottom" and configure the prerequisities first, and then put them together to complete the configuration.

1. Define a Local Variable that represents one Employee record instance.  
   1. Go to the Properties inspector (GENERAL properties).
   2. Use Add/Remove Variables
   3. Use Add Variable
   4. Define the name of the new Local Variable.  This label can be anything, but consider our convention (described earlier) that the "many" side of the Association Role Name would be plural (in this case, Consuming Employees). A nice convention for the Input Data Item will be to use the singular of that, Consuming Employee, and this makes it pretty clear what your intention is in declaring it. It references one from that set.
   5. Choose the type as Record because it will represent a while record.
   6. Choose the Record Definition as Employee (once again you will need to use the Search button to easily find the Foundation's Employee record). 
      
2. Configure it to be updated for every iteration of the Multi-Instance Loop.  
   1. Drag in a new Send Message activity and give it the label Notify Consumers. 
      
   2. Down near the bottom of the Property Inspector, in the MULTI INSTANCE LOOP section, choose the Loop Type as Sequential. This now expands to show the other loop control properties.
      
   3. From the Input Data Item pulldown, select the Consuming Employee Local Variable you just created.
      
      
3. Identify the set of data to loop over. You need to find the right association Role Name to use.
   1. From the Loop Data Input property, bring up the Edit Expression dialog.
   2. In the Available Values tree, open Process Variables → Order → Associations
   3. Drag in Consuming Employees into the Expression. (Note: don't be confused by the variable called Consuming Employee - singular).
      
4. Leave the Completion Criteria empty (this is used only when there is some "early termination" condition you want to handle, not when you need to process every element of the data).
5. For the Recipients property, access fields of the current Consuming Employee 
   1. The data we really need to use is the Login ID found under Process Variables → Consuming Employee.  
   2. All we have to do is reference it in the Edit Expression dialog.
      
6. For the Subject and Body, use other Associations as we did with earlier Send Message activities, to pull in data such as Restaurant and Dish.

Note that the Notify Consumers activity now shows its looping nature at a glance with the horizontal bars glyph.

Change the flow so our new Notify Consumers activity follows Notify Submitter of Delivery.

Testing

Now you can repeat the testing of the Order Lifecycle Process. One difference here is that the recipients of the User Message may not have Developer credentials and therefore may not have access to run from BMC Helix Innovation Studio. You may run into permissions problems for the first time here, and you can trouble shoot these now if you like. If you simply want to test this new looping behavior, make sure there are some Employees who have the Tenant Adminstrator flag set so you can see the Bell Notification behavior without any issues because of incomplete permissions.

Challenge

• Extend the Order Lifecycle to send one notification to the employee, and a different notification to the manager of the employee.
• Implement a broadcast notification to all employees

What we learned

Looping is a powerful technique. The important points are:

• When configured with associations, it makes an easy way to traverse across related records.
• You can also use it to traverse the Output of any activity that brings back multiple records, such as Get Records by Query, or a custom-coded activity that returns an array (that is, a collection).
• The looping properties can be set on most activities
• One, in particular, called Sub-Process, is very powerful. This is because the looping properties can apply to a flow within your process where multiple activities can access the Loop Data Item.
• The Completion Criteria give you flexibility to loop over anything, combined withe the Compute Value activity to keep track of a loop counter (we will work with Compute Value more in a later part of this tutorial).
  
  

Now, we are ready to move on to the last part of our Order Lifecycle process: implementing the ability to cancel an order using error handling.