Introduction: You can find a description of this phase in section Phase 3 (Introduction). See also section Nested and Networked Profiles.

You can use the context menu on a node or field of the target structure to insert an existing profile (its target structure) as a subnode in the source structure (substructure).

Requirements for a Profile to Be Added (Subprofile)

A profile can be added if

it is active and not suspended,
uses the normal data mapper (not the simple one).
(The options Enter output channels for each record and Incorporate IU must not be set.)

Requirements for an Added Profile

A profile can add another profile if

it does not use document type XML with the V4 parser.

Adding a Subprofile

A profile can be added via the context menu (→ Add profile as sub node in source tree) of any field and node in the target structure. Another dialogue will appear.

images/download/attachments/44946723/1136-version-2-modificationdate-1663149988582-api-v2.png

(1) Select the profile to be added.

(2) Specify a unique prefix and a node name for the substructure. Note: The prefix ensures that all field/node names in the source structure remain unique, since two included profiles could use an identical field/node name, for example. The prefix has the effect that you get two distinct names prefix1.fieldname and prefix2.fieldname, for example. This also allows you to include the same profile twice.

(3) This will add the profile.

Result

As a result, on the one hand, the function call sub profile for source tree (a,b,c,d,e,f,g,h) is placed on your node/field in the target structure. Parameters a, b and h are set automatically (see there).

On the other hand, you will then see the following substructure in the source structure.

images/download/attachments/44946723/1137-version-2-modificationdate-1663150009907-api-v2.png

(4) The attributes of nodes and fields of the subprofile are locked. However, you can modify them manually if you click on the lock if only minor details in the subprofile have changed. Otherwise, you should use the synchronisation (described below).

(5) If changes have been made to the subprofile, you can synchronise them automatically via the context menu of the node (here sub1.generate_random_number) → Synchronize with profile .

Calling a Subprofile and Data Flow

The substructure is always filled with data with function call sub profile for source tree (a,b,c,d,e,f,g,h). The data always comes from the target tree of the subprofile and not from its Integration Unit, etc.

You can delete fields and nodes in the substructure if you only need a partial view of the data, but you always receive the full data from the subprofile. However, the hierarchical structure of the substructure must be preserved for the parsing to work.

You can fill the substructure with data as often as you like by calling the above function multiple times (at any position). As a result, you will then simply get multiples of the substructure. You can also empty the substructure before the function is executed. In addition, the function can cache the result data and use it when called again, instead of calling the subprofile again. Take a look at the example profiles. The order in which the substructure is filled is how the associated function is called. If a subprofile has not yet been called via the function in the target structure, then the substructure in the source structure also has no data yet.

You can map with this substructure as you are used to. If you are using a path, then please do not place it on sub1.generate_random_number, but on sub1.node_random_number.

Important note: It is the responsibility of the user/developer to avoid endless loops (or to handle them appropriately) when using the subprofile mechanism described here! It is possible, for example, to create a profile 1 that includes profile 2. If you then include profile 1 in profile 2, you will get an endless loop.

Passed Variables (and lists and maps)

The variables of the calling profile are passed to the subprofile. See section Passed Variables, Lists and Maps (Profile Chains and Sub Profiles). There you will also find a description of how to pass lists and maps (and all variables of the calling profile in a map).

1:1 Mapping

In a 1:1 mapping, the substructure is not transferred.

Hierarchical Structures

As you may have noticed, the included profiles in the source structure are all 'flat'. Although they have nestings in themselves, you cannot insert a profile 1 first and then a profile 2 into profile 1. Nestings of this kind, i.e. the construction of a hierarchical overall structure, are achieved through mapping and the hierarchical structuring of the target structure. And these methods are all familiar to you from 'normal' mappings. Specifically, the data from profile 2 can be inserted below/inside the data from profile 1 in the target structure.

Application Example

Let's assume profile 2 gets a number of items in an order. You could then go through the articles in the target structure, like you already know from 'normal' mappings, and call a profile 1 (included in the source structure), which provides you with additional information about the respective article (the current price, the current stock in the warehouse, etc.). So profile 1 can be built by anyone as a service profile and you can use it in your profile to enrich your own information. So you only give profile 1 an item number, for example, and get back the desired data, without having to know what happens in the background, such as database queries or accesses to an ERP system. You also do not have to worry about changes in how those other systems are accessed. Your profile 2 can stay the same and only profile 1 has to be maintained if necessary. So just the way you want it in a service-oriented architecture.

Example Profiles

Example 1

...

Following are two simple example profiles for illustration.

Profile-Generate_random_number.pak (Import first and set active.)
Profile-Call_subprofile_1.pak (Phases 4, 5 and 6 of the subprofile are not executed and its backup file is deleted. Have another look at the description of function call sub profile for source tree (a,b,c,d,e,f,g,h))

First, perform a mapping test in profile Call_subprofile_1 (a test file is included). At first there is not much to see there. We only see that the subprofile has been called successfully because the field target_field, on which the subprofile call takes place, has received the return value true. The substructure with the data of the subprofile is not displayed.

However, there is a separate tab in the mapping dialogue where you can see the data that the subprofile provides.

Example 2

...

Next, we simply call the function twice in succession and look at the result. The substructure is then filled with data twice. So just the way you know it, if you read in two positions of an order, for example.

Profile-Call_subprofile_2.pak

Example 3

...

Now we also call the function twice, but we delete the data of the previous call with parameter g in the second function call. So we only get the data of the second call in the substructure.

In the target structure, the data of the substructure is mapped (look at the path). When you do a mapping test, you see one set of data. But in the subprofile calls tab you can see the data of both subprofile calls (as in the previous example).

Profile-Call_subprofile_3.pak

Example 4

...

In this example, we also call the function twice, but we now use parameter j in the first function call to store the result of the subprofile in the internal cache. In the second function call, we then use parameter k to use the cache contents instead of calling the subprofile again.

When you perform a mapping test, you see one record. In the subprofile calls tab, you can also see only one subprofile call.

Profile-Call_subprofile_4.pak

Example 5

...

This example shows how to add the same subprofile twice.

Profile-Call_subprofile_5.pak

Adding Profile as Subnode in Source Structure (Sub Profile)