Batch Loop Snippet

Overview

For an easy way to process array rows in batches, you'll use the Batch Loop snippet. But first, you'll learn what an array is. 

In your application, you have data. When you group that data together, you make an object. And when you group objects together, you have an array. As an array grows, manipulating the data it holds can grow more challenging. That's where the Batch Loop snippet helps. 

For example, you might have an array of credit card applicants. This array holds data for many people, but you need to run a credit check for each individual person. With the Batch Loop snippet, you can extract one at a time and verify the credit score.

Here's another example of how you can use this snippet. Let's say you have an investment firm. And, you're considering doing business with another entity (country or group). You want to check trade restrictions between the United States and other countries. With the Batch Loop snippet, this is easy to do.

Here's how the snippet looks in Express View:

And here's how the snippet looks in the Module Builder:

What You'll Learn

In this article, you'll learn:

• How to add the Batch Loop snippet.
• How the Batch Loop snippet works.
• How to configure the Batch Loop snippet.
• How to remove the Batch Loop snippet.

Adding the Snippet

Once you determine a need for a batch loop process, you'll add the Batch Loop Snippet.

Before you use this snippet in your application, you must install the snippet to your environment.

Adding the Snippet to Your Environment

To add the snippet to your environment:

1.

At the top right of the Unqork Designer Platform, click Library.

2.

Click Templates.

3.

Click Marketplace.

4.

In the Search the Listings Directory field, enter Batch Loop.

5.

Click the Batch Loop tile.

6.

Click Install to Environment.

7.

Click Install Template.

Now, you can now use your newly installed snippet in your application.

Adding the Snippet to Your Module

After you install the Batch Loop snippet to your environment, you can drag and drop the snippet into your module:

1.

In the left sidebar of the Module Builder, click the Snippets button.

2.

In the search bar, enter Batch Loop.

3.

Drag and drop the Batch Loop snippet onto your canvas.

4.

Save your module.

How the Snippet Works

Data Workflows are the main drivers of the Batch Loop snippet. You'll find 2 Data Workflow components when using this snippet:

• dwfBatchLoop: Separates the data in your array and sends it through the API (application programming interface) you're calling (more on that later). This works in tandem with the Plug-In component included in the snippet, which runs the API call. As mentioned above, that API call might check a credit score. Or it can find trade restrictions between the US and a specific country. The call itself depends on the configuration of your Plug-In.

• dwfProcessBatch: Reassembles the returned data for easy display in a ViewGrid.

Now, to do their job, your Data Workflows reference 3 Hidden components. Here's a look at each:

• loopCounter: Counts how many pieces of data have gone through the first Data Workflow. This ensures the process stops when you're out of data.

• batchLimit: Sets how many rows to process at once. Your dwfBatchLoop references this before it begins processing data.

• batch: This is where your dwfBatchLoop puts returned data. Your dwfProcessBatch then references this component to put the data back together.

Of course, your Batch Loop doesn't work if you don't have any data to process. That's why your snippet also includes a Data Table. The Data Table comes preloaded with sample data to use for demonstration purposes. Or, you can replace it with your own.

Finally, to start and stop the batch, the snippet includes 2 Initializer components.

You'll also see a Field Group component included in the snippet. As is the nature of a Field Group component, this is here for organization and structure. If you need to move the inner-workings of the snippet for any reason, the Field Group makes it easy to do so.

Now it's time to take a look at the snippet in action.

Setting Up the Snippet

Out of the box, the Batch Loop snippet contains a simple demonstration. But to see what's happening inside your application, you'll connect it to a ViewGrid. As an example, create a module that checks if the U.S. has trade restrictions on a particular country. This is useful for banking and investing, when you don't want to do business with certain entities. For example, a country can have unethical influences, which show up on a list kept by the Office of Foreign Assets Control (OFAC). You'll set up a Batch Loop that compares a list of countries to that OFAC list.

What You Need

To complete this use case, you need:

• 1 ViewGrid component

• 1 Button component

• 1 Batch Loop snippet

The Batch Loop snippet includes:

• 1 Panel component

• 2 Initializer components

• 1 Data Table component

• 1 Field Group component

• 3 Hidden components

• 2 Data Workflow components

• 1 Plug-In component

Add the Batch Loop Snippet

To start, add the Batch Loop snippet to your canvas.

1.

In the left sidebar of the Module Builder, click Snippets.

2.

Enter Batch Loop in the search bar.

3.

Drag and drop the Batch Loop snippet onto your canvas.

Update the Data Table Component

Next, configure the snippet to fit our example. The first update you'll make to the snippet is to include a list of countries. To do that, rename the Data Table component and add new data to it.

1.

Hover over the exampleArrayToProcess Data Table component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Configuration window.

3.

In the Label and Property Name fields, enter dtOfacEntities.

4.

Update cell A1 to read Entity.

5.

Update cells A2 through A9, to read: Uruguay, Iran, USA, Germany, Kazakhstan, Ireland, Qatar, and Mexico.

6.

Click Save.

Update the Limit Hidden Component

By default, the snippet processes 10 rows of the array in each batch. For this example, you only want to process one row at a time. To make that change, update the batchLimit Hidden component. 

1.

Hover over the batchLimit Hidden component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Configuration window.

3.

In the Default Value field, enter 1.

4.

Click Save.

Update the Plug-In Component

Next, update the Plug-In component to reference an external service. Here, you'll use an API to look up records from the Office of Foreign Assets Control (OFAC).

For this to work, your environment must have this API configured under Services Administration. (You can read more on that in our Services Administration article.) If you're working in the Unqork Training environment (training.unqork.io), you're good to go!

1.

Hover over the pluginExample Plug-In component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Configuration window.

3.

In the Property ID and Label Text field, enter pluginOfacAPILookup.

4.

Update the Inputs table to read:

a.

Property ID: enter 'Bearer 3a80c050-07ce-3642-9ccf-0b3781b2fb6b'.

b.

Mapping: enter Authorization.

c.

Header: Yes (checked).

5.

Clear the Internal Services drop-down by opening the drop-down and clicking Choose one.

6.

In the Data Source URL field, enter https://api.trade.gov/Gateway/v1/consolidated_screening_list/search?q={{data.batch[0].entity}}.

7.

Click Save.

Update the First Data Workflow Component

You changed the names of your Plug-In and Data Table components. So, you need to update the components that reference them. First, update the dwfBatchLoop Data Workflow to match your updated Plug-In and Data Table components.

1.

Hover over the dwfBatchLoop Data Workflow component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Configuration window.

Update the Input Operator

1.

Click the exampleArrayToProcess Input operator to open its Info window.

2.

Configure the Input operator's Info window as follows:

Update the Output Operator

1.

Click the pluginExample Output operator to open its Info window.

2.

Configure the Output operator's Info window as follows:

3.

Click Save.

Update the Second Data Workflow Component

Now, update the Create Field operator to calculate the number of times an entity appears on OFAC's list.

1.

Hover over the dwfProcessBatch component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Configuration window.

Update the First Input Operator

1.

Click the pluginExample Input operator to open its Info window.

2.

Configure the Input operator's Info window as follows:

Update the Second Input Operator

1.

Click the exampleArrayToProcess Input operator to open its Info window.

2.

Configure the Input operator's Info window as follows:

Update the Get Operator

1.

Click the Get operator to open its Info window.

2.

Configure the Get operator's Info window as follows:

Update the Create Operator

1.

Click the Create Field operator to open its Info window.

2.

Configure the Create Field operator's Info window as follows:

Update the Output Operator

1.

Click the exampleArrayToProcess Output operator to open its Info window.

2.

Configure the Output operator's Info window as follows:

3.

Click Save.

Update the Initializer Component

Next, update the initCompleteLoop Initializer component to reflect your updated Plug-In.

1.

Hover over the initCompleteLoop Initializer component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Configuration window.

3.

In the Outputs table, enter the following:

4.

Click Save.

Configuring the ViewGrid Component

Now, add a ViewGrid component to display the entities and their OFAC hits.

1.

Drag and drop a ViewGrid component onto the canvas. Place your ViewGrid component in your panelBatchLoop panel below your initCompleteLoop Initializer.

2.

In the Label and Property Name fields, enter vgOfacHits.

3.

In the Inputs table, enter the following:

a.

ID: enter dtOfacEntities.

4.

In the Display table, enter the following:

5.

Click Save.

Configure the Button Component

Next, add a Button component to trigger the entire process.

1.

Drag and drop a Button component onto your canvas. Place your Button component below your ViewGrid component.

2.

In the Property ID field, enter btnRunLoop.

3.

In the Label Text field, enter Run Loop.

4.

From the Button Action Type, select Event.

5.

In the Trigger on Click field, enter initKickoffBatchLoop.

6.

Click Save.

Update the Initializer Component

Finally, update the Trigger type for the Initializer component. You'll change the Trigger Type to Manual now that your Button triggers the Initializer.

1.

Hover over the initKickoffBatchLoop Initializer component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Configuration window.

3.

Select Manual from the Trigger Type.

4.

Click Save.

5.

Save your module.

Now, preview your module. You'll see the list of countries in a table. Click the Run Loop button. When the loop finishes, the Number of OFAC Hits shows the number of hits each country has on the list. The sanctioned column indicates which countries are under sanctions by the United States. This information helps the investment firm decide who they want to do business with.

Removing the Snippet

You might want to remove a snippet from your application. Here, you'll learn how to remove the snippet from your module. Then, you'll learn how to uninstall the snippet from your environment.

Remove the Snippet from Your Module

To remove the Batch Loop snippet:

1.

In the Module Builder, hover over the [propertyIDOfPanel] Panel.

A 5-button toolbar displays above the component on hover-over.

2.

Using the toolbar, click the (Remove) button.

3.

Save your module.

Remove the Snippet from Your Environment

Use the Unqork Template Library to remove unused snippets. To uninstall a snippet from your environment:

1.

At the top right of the Unqork Designer Platform, click Library or Templates.

2.

Find the snippet you want to uninstall.

3.

Click the ellipsis (...) in the snippet's tile header.

4.

Click Uninstall Template.

5.

Click Yes, Uninstall in the confirmation modal.

You can visit the Marketplace and reinstall the snippet at any time.

What if you have an existing application built using this snippet and then uninstall the snippet from your environment? No problem. Your existing application remains unaffected. Also, your application doesn't have any ties to the snippet. So, let's say you reinstall a newer version of the snippet in the future. You can rest assured that the installation doesn't impact your existing application.