Loops for API-Builder

Today API-Builder doesn't support to execute Nested-Flows out of the box. However, a nested flow is for instance useful to execute a different flow based on an array of input objects. This is basically the same as writing a function in a classic programming language which is called from a loop.
This flow node allows to you iterate over an array and invoke a nested flow for each element.

Creating the nested flow

:point_up:
One of the unsupported features is to create a flow that isn't bound to an API endpoint.
That means, there's actually no UI for doing this.
However, you can manually create nested flows as you want in the /flows diretory of your API-Builder project and call them with the For-Each flownode this project provides.

To streamline the process for you, we have installed two sample flows during installation of the plugin into your flows directory.

• /flows/ExampleParentFlow.json
• /flows/PerItemFlow.json

Consider both flows as examples. You can create your own flows, just by copy the existing ones and rename them.

Main flow

The main flow is typically a normal flow you have created using the API-Builder UI and attached to an API-Endpoint.
The provided sample Main-Flow is supposed just to give you an example how a to call a Nested-Flow as shown in the following screenshot:

If you would like to open the sample main flow in your API-Builder flow editor to see how it is working, use the following URL:
http://localhost:8080/console/project/flows/ExampleParentFlow/edit

Nested flow

The nested flow (see below) is called by the sample main flow. You can do whatever you need in that flow by using all installed API-Builder plugins.
The result value of your nested flow is returned in $.response.

You may create as many Nested-Flows as you want just by copy an existing flow in the flows directory, rename the file and configure the expected parameters within the JSON-File.

Sample nested flow

You may open nested-flows in the API-Builder editor just by using the following URL with the correct flow name:
http://localhost:8080/console/project/flows/PerItemFlow/edit
Obviously you can do the same with your own nested flows you have created. But please remember to restart the API-Builder process to make the flows available to the UI.

Best is to open both flows (Main and Nested) in parallel in two Browser-Tabs at the same time to be able to modify both simultaneously.

Nested flow parameters

The nested flow is like a function and you need to tell the expected input parameters. The parameters given by the main flow have to pass a schema validation in the nested flow.
For example when iterating in the main flow over an array of objects [ { name: 'Tom' }, { name: 'Dick' }, { name: 'Harry' }] the nested flow gets a single object: { name: 'Dick' }, hence the parameter in the nested flow must be configured like so:

	"parameter": {
		"properties": {
		    "name": { "type": "string" }
		},
		"additionalProperties": false,
		"required": []
	},

The properties field contains the expected object, which is in the example an object having a field: name which must be of type String.

Therefore, to pass the schema validation when calling the nested flow, the flow parameter: items has to be an Array, that contains a Javascript object as defined above. Configured like so:

:exclamation: Iterating over arrays of primitives (e.g. an Array of Strings) is not supported. Therefore, this example wont work:

In the example above, the flow will execute 3 times, as the array had 3 elements. $.name will be the Tom on the first, Dick on the second, and Harry on the third.

Flow

The Flow method iterates over an array of objects and invokes the specified flow with the object as the input.

| Param | Type | Required | Description | | --- | --- | --- | --- | | flow | string | y | The flow id of the flow to execute. Filename of the flow without .json | | items | array | y | The array to iterate over. The array must contain objects that fit the desclared parameters in the nested flow |

Install

After creating your API Builder service (api-builder init), you can install this plugin using npm:

npm install --no-optional @axway-api-builder-ext/api-builder-plugin-fn-foreach

Changelog

See Change-Log