How To: Use a Loop Step without a Pre-Existing Reference

This article illustrates how to configure a workflow to loop through a list of items with the following scenario:

This demonstration uses a SQL table as the data source. You can use the same instructions for other data sources that do not have a primary key. For an alternative method see How To: Use a Loop Step with a Loop Index.
K2 uses a primary key, such as an ID, to identify each list item uniquely. When there is no primary key, you can use a inline reference in the loop step to iterate through each item in the list. In this way, every item in the list represents one loop that is repeated sequentially until there are no more items. When using this approach, you should not use a pre-existing reference. This article covers looping through a list where there is no primary key assigned. For lists that have a primary key, see How To: Use a Loop Step to Loop Through a List.

A workflow loop without a pre-existing reference
Loop Step in Workflow

Scenario

You work in Sales where you maintain a list of customers. Each month you email your customers with the latest deals. To accomplish this, you have configured a workflow that sends an email to each customer in your list. You start the workflow manually when deals change. Your list of customers is located in a data source that does not have a primary key and where your workflow does not have a pre-existing reference.

Steps

Begin by creating a list of customers in a data source that does not have a primary key. This demonstration uses a table in a SQL database. If necessary, create a service instance pointing to the data source, then generate SmartObjects. Your workflow consists of a loop step that sends an email to each customer, then a final email to yourself to confirm the workflow completed.

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Add and Configure Workflow Steps to Loop Through List Items.

  1. Create a table in a SQL Server database called ContactDetails with the following columns: ID, Name, Company, Email. Do not create a primary key. Add at least three customers to the table. From the K2 Management site, create an instance of the SQL Server service type that points to the SQL database. Generate SmartObjects.

    Instructions for creating a table in SQL is beyond the scope of this article. If you need help, contact your database administrator.

    1. In a SQL Server database, create a table called
      ContactDetails
      with the columns shown below. Do not create a primary key.
      ContactDetails Table
    2. Add at least three customers. For ease in testing, use the same email address for each customer.
      Add Customers

      3. Now that you have a data source, you can register it with K2. You do this by creating an instance of the SQL Server service type that points to your SQL Server database. Then you generate a SmartObject based on the ContactDetails table. The SmartObject allows you to use the table's properties and methods in other K2 elements, namely a workflow. Remember, properties are like the columns in a table (such as Company, Name, Email) and methods allow you to interact with the data (such as Create, Delete, List).

    3. Launch the K2 Management site in a new browser tab.
      If you do not know how to access the K2 Management site, see Accessing K2 Sites.
    4. Expand the Integration node and click Service Types. A list of available service types appears in the central pane. Locate the SQL Server Service type by scrolling through the pages or using the search feature. Select SQL Server Service and click the New Instance button.
      SQL Server Service

      5. Point this instance to the SQL database containing the ContactDetails table.

      Your settings may not match the following steps depending on your environment, the location of the SQL Server table, and naming conventions. The settings below are based on a K2-provided VM where the SQL Server is running on the same machine as the K2 server. In this demonstration, the database name is My SQL Database and the table name is ContactDetails. If you need assistance with your settings, contact your K2 or database administrator.

    5. Under the Service Instance heading, enter
      My SQL Database
      for the Display Name. For the Description, enter
      Sample service instance for demonstrations.
      Display Name
    6. Under the Service Authentication heading, change the Authentication Mode to Service Account.
      Service Authentication
    7. Under the Service Keys heading, enter the Database name. If your SQL Server is located on a different server, enter the Server name and change On Different SQL server to true. Click OK. Click OK for the service instance confirmation dialog.
      Service Keys

      8. Finally, you create a SmartObject from the service instance. This exposes the data source properties and methods and allows you to use them in other K2 elements such as a workflow.

    8. Still in the Integration category, click Service Instances. Navigate to the My SQL Database service instance and select it. Click the Generate SmartObjects button.
      Generate SmartObjects
    9. On the Generate SmartObjects screen, click Select All, then click OK.
      Generate SmartObjects

      10. Before moving on, test your SmartObject and confirm it returns customer data.

    10. Expand the Categories > SQL Server Service > My SQL Database > Tables nodes. Select the [dbo].[ContactDetails] SmartObject. In the central pane, locate the Methods section. Select the List method and click Execute.
      Execute List Method
    11. You want to return all records, so click Execute (without entering any filters). You see a list of customers from your SQL database. Click Done to exit the results window.
      Execute SmartObject

      12. You now have a SmartObject that points to a data source that does not have a primary key. In the next sections, you build a workflow and configure it to loop through your customers. This method requires one column with unique values. In this case, you use the ID column but you could use Company or Name.

  2. From K2 Designer, create a new workflow called Email Customers. (Optional) Create categories first to keep your work organized.
    1. Launch K2 Designer.
      If you do not know how to access K2 Designer, see Accessing K2 Sites.
    2. Create categories to keep your work organized. Right-click All Items and select New Category. Use the image below as a guide if necessary.
      Create Categories
    3. Next, create a workflow. Right-click the Loop No Reference category and select New Workflow.
    4. Name the workflow
      Email Customers
      and click Create.
      Create Workflow

      5. You see a Welcome screen with an interactive panel. You can click the right and left arrows to learn more about the workflow designer. Click Close to proceed to the design canvas.
      Welcome Screen

Add and Configure Workflow Steps to Loop Through List Items

In the next few steps, you add the loop step and its action (sending an email to each customer).

  1. Add a Loop step to the empty placeholder. In the Configuration Panel, click the edit toggle for the List drop-down. Add the ContactDetails (SmartObject) > ID to the List text box, then change the looping option to All items as a collection. (SQL Server Service > My SQL Database > Tables > [dbo].[ContactDetails] > List > ID)
    1. From the Toolbox > Logic menu, drag a Loop step into the empty placeholder below the Start step.
      Toolbox
      Notice the red warning badge on the Loop step. This badge indicates there are required settings in the Configuration Panel. When you expand the panel, you see the same badge next to the required settings.
      Required Settings
    2. Select the Loop step and expand the Configuration Panel.
      The Configuration Panel allows you to configure and customize the steps you add to your workflow.
      Expand Configuration Panel
    3. Select the Loop tab if it is not already active. Locate the List heading and click the edit toggle to the right of the drop-down box. This toggle allows you to enter your own values instead of selecting from a list of items.
      Edit Loop List
    4. Expand the Context Browser by clicking the slider. Click the SmartObjects tab near the lower right corner of your screen. You are selecting the SQL table as the list to loop through.
      The Context Browser contains references, variables, functions, and SmartObject properties. At runtime, K2 replaces references and variables with live data. For example, K2 replaces the ID reference with the ID of the current record.
      Select Identifier
    5. Navigate to the ContactDetails SmartObject. Expand the SQL Server Service > My SQL Database > Tables > [dbo].[ContactDetails] > List node. Drag the ID property into the List text box. When looping through a list where there is no primary key, you must use a column that contains unique values. For example, ID or email where each entry is unique.
      Create Output Mappings
    6. The SmartField editors opens. Change the list item looping to All items as a collection. You want to loop through the entire list. Click the exit icon to close the SmartField editor.
      All Items as a Collection
      You can also select one item based on a filter such as an ID. The Custom option opens a Configuration Panel where you can add filters or set the item order.
      Customer Filtering
    7. Expand the Options section. Notice the reference, Items. K2 creates this reference and stores the ID of the current item (in the looping process). In this way, you can reference the current item in other steps within the loop. Collapse the Configuration Panel by clicking its slider.
      List Item Reference
  2. Add a Send Email step and connect it to the Next Item outcome. Use the Context Browser > SmartObjects > [dbo].[ContactDetails] > Email property for the To value. Map the Items > Value property to the ID SmartField property. Add your own content for the subject line and message body. Use properties from the SmartObject to personalize your message if you like. Connect the Email step to the Loop step.

    Now you need a step that performs an action of some kind. For this demonstration, you send an email to each customer in the list.

    1. From the Toolbox > Basic node, drag a Send Email step onto the canvas.
      To return to the Toolbox main menu, click the Toolbox icon.
      Toolbox Icon
      Send Email Step
    2. The Loop step generates two outcomes: Next Item and Complete. The workflow loops through steps connected to the Next Item outcome until it reaches the end of the list. At that point, it follows the Complete outcome. Connect the Next Item outcome to the Send Email step. Connect the Send Email step back to the Loop step.
      Connect Steps
    3. Select the Send Email step and expand the Configuration Panel. Select the Send Email tab if it is not already active. Expand the Context Browser. In the lower right corner of your screen, click the SmartObjects tab. Navigate to the [dbo].[ContactDetails] SmartObject. In the image below, the path is SmartObjects > SQL Server Service > My SQL Database > Tables > [dbo].[ContactDetails]. Expand the SmartObject. Expand the List method.
      SmartObject Properties

      4. By default, the email To value is Originator. This is the person who starts the instance of the workflow. You want the email recipient to be the current customer from your ContactDetails table. In the next step, you replace the default value with a reference to the current record's email property.

    4. Click the edit toggle to the right of the Originator bar. Select Originator's Email and delete it.
      Edit Entry
    5. Drag the Email property from the [dbo].[ContactDetails] SmartObject into the To text box. .
      Add Email Property

      6. The SmartField editor launches. You must assign an identifier to the email property so that K2 knows which email address to use. You get that value from the Items reference. Remember that K2 stores the ID of the current record (during the looping process) in the Value property of the Items reference. Now, the recipient To value points to the email address for the current record in the loop.

    6. Click the Fields tab. Expand the Items reference. Drag the Value property into the ID text box. Exit the editor.
      SmartField Editor
    7. Configure the Subject and Body sections with your own content. If you like, use properties from the [dbo].[ContactDetails] SmartObject to personalize your message. You must map the Items > Value reference each time you use a SmartObject property. Collapse the Configuration Panel.
      Email Message
  3. Add a Send Email step and connect it to the Complete outcome. Keep the default recipient, Originator. Use your own content for the subject line and message body. Add an End step and connect it to the Send Email step.
    1. Next, you configure an email that lets you know the looping is complete. From the Toolbox > Basic node, drag a Send Email step onto the design canvas. Connect the Complete outcome to the new step.
      Connect Steps
    2. Select the new step and expand the Configuration Panel. Leave the To value with its default, Originator. Enter your own content for the subject line and message body. Collapse the Configuration Panel.
      Email Message
    3. From the Toolbox > Logic node, drag an End step below the new Send Email step. Connect the two steps.
      Use End steps to complete workflow outcomes. You can configure End steps to terminate the workflow or use them as visual indicators that there are no more steps to follow. In this demonstration, the End step provides a clean end to the final Send Email path.
      Add End Step
  4. Deploy the workflow.
    1. Deploying the workflow publishes it to the K2 server and makes it available for use. If you make any changes to the workflow, you must deploy it again so that K2 has the latest version. Select File > Deploy. When you see the success dialog, click File > Close to return to K2 Designer.
      Deploy Workflow
  5. Test the looping process by starting a new instance of the Email Customers workflow from the K2 Management site. Open your email client. You should see one email for each customer in your SQL table, along with the final confirmation email.
    1. Launch the K2 Management site.
      If you do not know how to access the K2 Management site, see Accessing K2 Sites.
    2. Expand the Workflow Server > Workflows node. Navigate to and select the Email Customers workflow. (Your tree may not match the image below depending on your environment and naming convention.) Click the Start New button located in the central pane.
      Start New Workflow Instance
    3. On the Start Workflow Instance screen, keep the default settings and click Start. Click OK for the confirmation dialog.
    4. Open your email client. If working on K2-provided VM, open Outlook in a new browser tab using the OWA link found in the Favorites bar.
      Launch OWA

      5. You should see an email for each customer in your list. You should see an email indicating the looping process completed. Your email titles and message may not match the image below, depending on the content you entered while configuring the Send Email steps.
      Looping Emails

Review

Use the Loop step in a workflow to loop through a list of items. Typically, K2 uses a primary key, such as a list item ID, to identify each item uniquely. A primary key is not required, however. When you have a list containing at least one column with unique values, you can use the built-in Items reference to store the list item identity as the loop progresses through each list item. This method does not require a reference to the list before the loop step. When there are no more items to loop through, the loop completes.

For an example of using a primary key to loop through list items, see How To: Use a Loop Step to Loop Through a List.