Restructure function

Usually, a function such as Java, Boolean, Database, and API, is run as defined in the sequence. If the function has input parameters that are linked to elements and attributes in the input document, here is what happens:

• The corresponding data is read from the input document, from preceding functions, or from variables.
• The function is run, for example, the manually created Java code.
• If the function has output parameters, data created when executing the function is written to elements and attributes in the output document or assigned to variables.

These steps are run in real time per function in the sequence: read data, run function, and write data.

The Restructure function is different. The last two parts are the same as described above; the function is run and the output parameters fetch data that is linked to the output document or assigned to variables. This data is not fetched from the input document, even though the input parameters have to be linked to elements and attributes in the input document. If the input parameters are linked to Collector functions, data is not fetched from these. Instead, the data is fetched from memory where it has been restructured. So, when is the data read from the input document or from the Collector functions?

You can compare the Restructure function to a Boolean function. It can only exist first inside a loop and it has to control the loop. This type of loop is now called a restructure loop. You can have nested restructure loops, each controlled by a separate Restructure function.

Before the outmost restructure loop begins to run, the data is prepared. If data is used directly from the input document, it is read from the input document through an invisible "automatic mapping" that, if visible, would look more or less like the mapping you would manually create to read data from the input document. If the input document contains two nested repeating elements, for example CreditTransferPayment and PaymentTransaction, the "automatic mapping" has two nested loops controlled by these two input elements. Within each loop, data is read from input data elements and attributes. Only the references to the data are stored in memory, the input data is never duplicated. This keeps the memory consumption low for the restructuring process.

If data from Collector functions is used, you have to manually create a mapping to collect the restructure data. Collector functions are used to store references to the data in memory. If you use data directly from the input document, the collector mapping looks similar to the "automatic mapping" described here. In this case, it is easier to use data directly from the input document, because you do not need to create the collector mapping. Although, if you need to alter the data before it is restructured, you must create the collector mapping, for example, removing time to sort and group data on date, converting amounts, or maybe excluding records.

See the Collector function.

Whether the data is read from the input document or from Collector functions, it is structured data. The input schema defines the structure for the input document. XPaths for elements and attributes are used as internal identifiers. For Collector functions, the function paths and the parameter names are used as internal identifiers.

Follow this example:

• The collector path "/CreditTransferPaymentCollectorLoop/PaymentTransactionCollectorLoop/Collector_1/Name"

  corresponds to:

• The input document XPath "/SyncCreditTransfer/DataArea/CreditTransfer/CreditTransferPayment/PaymentTransaction/Name".

These two different structure contexts cannot be mixed. For example, you cannot combine the element RequestedExecutionDateTime from the input document with Name from Collector_1 because they have no structural relationship. You do not know if the Collector parameter Name is linked from the input document, or if it is created in some other way. This means that for a nested Restructure loop structure you must use data, either directly from the input document or from Collector functions, for all Restructure functions within the Restructure loop structure. All input data must belong to the same structure to be able to restructure the data.

When you have the data in memory, in its original structure, the data or data references are restructured. Then, the outmost restructure loop that is run is controlled by the Restructure function. Restructured data is fetched from memory and assigned to the output parameters. If there are nested restructure loops, these are also run like any other nested loop. The nested Restructure functions automatically keep track of the restructure context. For example, only the payment transactions for supplier A are given if there is an outer restructure loop grouping the suppliers, and supplier A is the current supplier.