Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at Stonebranch Integration Hub - Terms of Use.

Overview

This integration is designed to automate the processing of input data by reading it from a flat file in Windows/Linux or a UAC script data repository. The core functionality revolves around a for-each loop, which iterates through the input data, parsing it using a predefined delimiter (such as a comma, pipe, or any one or two characters).

The parsed data segments are extracted and provided further to UAC tasks or workflows during each iteration. This allows for modular processing, where each task can handle a specific aspect of the data, enabling efficient and organized execution of complex workflows.

Version Information

Template Name	Version
For-Each-Input Loop	1.0.1

Refer to changelog for version history information.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Software Requirements for Universal Template and Universal Task

Requires Python 3.7.6 or higher. Tested with the Universal Agent bundled Python distribution.

Software Requirements for Universal Agent

Both Windows and Linux agents are supported.

Universal Agent for Windows x64 Version 7.1.0.0 and later with Python options installed.
Universal Agent for Linux Version 7.1.0.0 and later with Python options installed.
Python modules required:
- requests

Software Requirements for Universal Controller

Universal Controller Version 7.1.0.0 and later.

Network and Connectivity Requirements

Key Features

This Universal Extension provides the following key features:

Actions
- Read input from a Windows or Linux flat file.
- Read input from UAC script type data.
- Parse each line of input via any single or two characters.
- Launch UAC task or workflow for every line of the parsed input via REST API.
- Option to wait and launch UAC tasks or workflows based on the previous execution's completion.
- Capability to launch UAC tasks or workflows either sequentially or in parallel and monitor executions of launched task instances.
- Restart the for-each loop task from the failed line of input or customize the input lines accordingly in the UAC script data.
- Option to abort for For-Each-Input Loop task execution when one of the launched child tasks or workflows fails.
Authentication
- Authentication through HTTP(S)
Input/Output
- Capability to read input from a flat file in Windows or Linux Operating system
- Can Accept from UAC script data
- It can also accept input from UAC script data that points to a variable potentially the data coming from predecessors Taks
- Print the summary of Tasks instances launched for the input data and their status
Other
- It's a UAC utility that helps to iterate through the input data and process it by launching a UAC task or workflow via REST-API

Import Universal Template

To use the Universal Template, you first must perform the following steps.

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Input Fields

The For-Each-Input Loop task contains the following Input fields

Field	Input type	Default value	Type	Description
Select a Function	Required	Trigger by Script Input	Choice	The action performed upon the task execution. Valid values are: Trigger by Script Input Trigger by reading Target File
UAC Base URL	Required		Text	Provide the universal controller base URL. Eg.-https://xxxxxxx.stonebranchdev.cloud/
UAC Credentials	Required	-	Credentials	Credentials for "Basic" Authorization Type. The Credentials definition should be as follows. Universal Controller User as "Runtime User". Universal Controller User Password as "Runtime Password".
User Defined Input	Required	-	Script	Select or Create a UAC Script type of data that can be provided as input. Required when the field: Select a Function is selected with "Trigger by Script Input"
Specify Script name by Variable	Optional	False	Boolean	The flag that determines whether the UAC Script type of data provided as a variable
Script Name by Variable	Optional	-	Text	Provide the UAC Variable that points to the UAC Script of type data Required when the field "Specify Script name by Variable" is set to True
Specify the Input File	Optional	-	Text	Provide the Input File Name included with path either from a Windows or a Linux OS Required when the field: Select a Function is selected with "Trigger by reading Target File"
Specify Delimiter to Parse Input	Optional	False	Boolean	Enable it when it required to parse the input data with a single or two-character delimiter
Variable Delimiter	Optional	-	Text	Specify the delimiter value by which the extracted line of input is to be parsed E.g. Comma or Pipe or ## or any single or double character
First Row as Header	Optional	False	Boolean	Enable this field if the First row in the input file or script needs to be considered as a header. If the first line in data is considered as Header, every UAC task launch will have the corresponding header (column name) as a variable name
UAC Task to trigger	Required	-	Text	Specify the UAC Task Name or Workflow that needs to be triggered for every input line read
Parallel Job launch	Optional	False	Boolean	Check this field if the UAC Task needs to be launched in Parallel for every line of Input that is been read By default, the UAC Task is launched Sequentially & monitored for every line of input read
Abort Execution When a triggered Job Fails	Optional	False	Boolean	Enable this field if the Parent "For-Each-Input Loop" task needs to fail when one of the launched child UAC Task fails
Restart from Failure	Optional	False	Boolean	Enable the field when the Parent "For-Each-Input Loop" task needs to be restarted and input lines to be corrected in UAC Script of type data
Restart Execution Input	Optional	-	Script	Provides the restart input in the UAC script of type data

Task Examples

Task Output

Trigger For-Each-Input-Loop Task by reading a Flat File

UAC Task launched with Variables :

Trigger For-Each-Input-Loop Task by reading the UAC Script of type data

Trigger For-Each-Input-Loop Task by reading the UAC script with input variables from the predecessor task

Task execution output: For-Each-Input-Loop

Example Workflow: Process Files in Loop

Example Workflow: Process Servicenow Infra Create RITM request in a loop

Example Workflow: Handling SAP Transport request from Azure DevOps in a loop

Exit Codes

The exit codes for these Universal Templates are described below.

Exit Code	Status Classification Code	Status Classification Description	Status Description
0	SUCCESS	Successful Execution	SUCCESS: Successful Task execution
2	FAILED	Failed Execution	FAILURE: Input list is empty
5	FAILED	Failed Execution	FAILURE: Issues while monitoring the UAC-launched Task
10	FAILED	Failed Execution	FAILURE: Exception while launching the UAC Task or Workflow
99	FAILED	Failed Execution	FAILURE: Error Launching the UAC Task ( Response Code not 200 )
100	FAILED	Failed Execution	FAILURE: when one of the launched tasks failed

STDOUT and STDERR

STDOUT and STDERR provide additional information to the User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.

Document References

This document references the following documents.

Document Link	Description
Universal Templates	User documentation for creating, working with and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.
Credentials	User documentation for creating and working with credentials.
Resolvable Credentials Permitted Property	User documentation for Resolvable Credentials Permitted Property.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

Python code modifications should not be done.
Template Modifications
- General Section
  - "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
- Universal Template Details Section
  - "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
- Result Processing Defaults Section
  - Success and Failure Exit codes should not be changed.
  - Success and Failure Output processing should not be changed.
- Fields Restriction Section
  The setup of the template does not impose any restrictions, However with respect to "Exit Code Processing Fields" section.
  1. Success/Failure exit codes need to be respected.
  2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Changelog

ut-cs-for-each-input-loop-1.0.1 (2024-08-01)

Fixes

Exits with RC 2 when the input list is empty

ut-cs-for-each-input-loop-1.0.0 (2024-05-29)

Initial Version

UAC Utility: For-Each-Input Loop