Profile chains

Occasionally you are confronted with a problem that is not solvable in a single profile. For this case, we offer the possibility to create profile chains in which a profile calls one or several subsequent profiles. These profile chains can, in principle, be arbitrarily long, but the performance should be kept in mind. It is the responsibility of the user/developer to avoid endless loops (or to handle them appropriately) when using the mechanisms described here!

Modules

The module "Data Flow" is a useful tool for visualizing and analyzing profile chains of this type.

Error behavior

Normally, if a subsequent profile is not found, an exception is generated. This behavior can be modified by adding the following entry to the configuration file ./etc/startup.xml.

<Set name="disposeMessageForUnknownProfile">true</Set>

First possibility: Message and data

A profile with a Response of type "Message" starts a profile with an Input Agent of type "Message". Profile 2 receives the output data of profile 1 (the receiving profile has to be active).

Please note that both profiles have to use the same queue and the same context. You can use the default values of a new profile. You will find more detailed information in the description of the Response/Input Agent of type "Message".

Profile 1, Response

Profile name: <Name profile 2>

Context name: System

Queue name: DWForwardReceiver

Profile 2, Input Agent

Message context: System

Message queue: DWForwardReceiver

Second possibility: Message and trigger

If you are only interested in triggering the subsequent profile and not in transferring the output data of the triggering profile, the subsequent profile (this profile has to be active) can also have a time-driven Input Agent.

It should be noted that the option "Content" in profile 1 must be set to "Trigger profile" (the encoding is not relevant).

The subsequent profile receives its data via the executed time-driven Input Agent. The type of the Input Agent is not relevant. You only have to select option Trigger/External call and another profile on page Times/Execution.

NOTE : There is a special case in profiles with time-driven Input Agents. You can trigger a subsequent profile there in the same way, but 'hard-wired'. Please note that in this case, variables with prefix MSG_CALL_ cannot be accessed in triggered profiles (variables are not yet initialized in the triggering profile in phase 1, see also section Variables), unless the triggering profile is also triggered by another profile. Its MSG_CALL_ variables can then be passed through.

Third possibility: HTTP response chain

Data pass back via endless responses of type "Custom class"

There are cases in which a client that sends a request to a profile expects a response from that profile (e.g. for HTTP requests or web service calls).

If it is necessary to build up a chain of profiles, this would normally be done by means of a message to the subsequent profile, but then the reply to the client from the subsequent profile would no longer be possible.

The Input Agent of type "HTTP" (and all time-driven Input Agents triggered via HTTP) allows a dynamic response (HTTP response) via the Response custom classes PassBackDataResponse and DefaultWebServiceResponse (also PassBackBinaryDataResponse and DefaultWebServiceResponseBinary). Please set checkbox "Custom class or Pass back data in response channel of profile" in the HTTP Input Agent and checkbox "Return data" for the triggered Input Agents.

Thus, the content of the response can be created dynamically in the profile (mapping, etc.) and can be returned via one of these classes (to the Input Agent and from there to the client).

To extend this process via a profile chain, the classes CallProfile (for subsequent profiles that do not have a time-driven Input Agent) and CallCronProfile (for subsequent profiles that do have a time-driven Input Agent) can be used. The structure of that kind of profile chain is shown in the following figure.

IMPORTANT : The subsequent profile that is called with class CallProfile (or CallCronProfile) must have the encoding in phase 2 set to UTF8. In addition, all called profiles must be active.

NOTE : If a subsequent profile is called by Message (or has to be called by Message), there is another way to pass back data. Look at the post-executor class TempFileReadPostExecuter for that.

Data pass back via single-step Responses of type "Message" and "HTTP"

Alternatively, you can use the option "Return data" in the Responses "Message" and "HTTP". Details see there.

Set the checkbox "Custom class or Pass back data in response channel of profile" in the Input Agent "HTTP" (profile 1). Alternatively, set checkbox "Return data" for all time-driven Input Agents triggered via HTTP.

If you are using a Response "Message", you also have to use one of the Response classes (PassBackDataResponse, DefaultWebServiceResponse, PassBackBinaryDataResponse, DefaultWebServiceResponseBinary) in profile 2.

NOTE : A subsequent profile or an error profile can also be called in the Response "HTTP" and the response can be generated and returned from this profile instead of directly returning the response of the Response "HTTP" (for details, see the documentation of the Response). In this case, you also have to use one of the Response classes (PassBackDataResponse, DefaultWebServiceResponse, PassBackBinaryDataResponse, DefaultWebServiceResponseBinary) in the subsequent/error profile.

Setting variables

You can set variables in the profile via HTTP request headers. For example, if the HTTP request contains the header VAR_TEST, you use it to set variable MSG_CALL_HEADER_HTTP_VAR_TEST (must be created) in the profile.

Fourth possibility: Functions

The first three possibilities can also be realized via the functions trigger profile() and call profile().

Passed variables, lists and maps

Variables

Prefix

In the first and second (not the third!) option, the variables of the calling profile are passed to the called profile. However, the prefix MSG_CALL_ is added. However, the prefix is added only once. A variable name with a prefix MSG_CALL_MSG_CALL_ will never be created.

In the third option (see there), variables can be set via HTTP request headers.

Variables are also passed to called subprofiles.

Setting the variable in the calling profile

You set the variable in the calling profile, not in the subsequent profile. Define the variable in the calling profile. Then assign its value, for example, in the mapping. When the calling profile starts a subsequent profile (first or second possibility), the variable is passed automatically. The prefix MSG_CALL_ is added to its name. The subsequent profile must define a matching MSG_CALL_ variable to read the value. See section Access right below.

Access

The subsequent profile can only access these variables (from phase 1) if they have been defined there. If profile 1 has a variable var__Test, the variable MSG_CALL_var__Test is passed on and profile 2 must define a variable MSG_CALL_var__Test in order to be able to access the content of the variable. The variable names are case-sensitive.

If the mapping is deactivated in the subsequent profile, variables are not defined either. Thus, none of the values of the calling profile's variables can be accessed. If the variable values in the subsequent profile are needed nevertheless without a mapping being required there, the following steps should be taken.

• Activate the mapping in the subsequent profile.

• Create a dummy mapping (e.g. one field).

• Use the content type "as received" in the Responses of the subsequent profile. The target tree created in the mapping will then be ignored.

Name conflicts

If a variable is to be forwarded via multiple profiles by message, care should be taken to ensure that all subsequent profiles do not use any variable names that are used by one of the preceding profiles, since the prefix MSG_CALL_ can result in name conflicts and incalculable behavior during the initialization of variables in subsequent profiles.

Example: Profile 1 calls profile 2, which in turn calls profile 3. In profile 1, there is a variable Count, which is passed to profile 2 as MSG_CALL_Count. If there is also a variable Count in profile 2, the variable MSG_CALL_Count is passed on to profile 3 twice (and possibly with different values). Once the variable MSG_CALL_Count created in profile 2 (to access the passed on variable from profile 1), and then the variable Count created in profile 2 with the added prefix MSG_CALL_.

Profile restart (metadata)

If a profile that has received variables from another profile is restarted, these variables are available because they are stored in the metadata. See also section Metadata editor.

Control Center (metadata)

You can check the variables passed to subsequent profiles and subprofiles in the Control Center (see pages "Overview" and "Errors") via the Metadata Editor.

Lists and maps (and variables in the map)

To pass lists and maps to other profiles (phase 3), you can use the functions serialize map/list() and deserialize map/list() or the autoserialization mechanism via the system variable VAR_AUTOSERIALIZE_DATA. In addition, the copy variables into map() function can be used to write all variables of the calling profile into a map (and then pass them as a map), saving you the use of the MSG_CALL_ prefix.

Other data structures

Other data structures are not transferred from profile to profile.

However, system-wide data structures are available. However, please note that only system constants are available in phase 1. System-wide number ranges and system-wide permanent values are only available in phase 3. If you want to use these values in phase 1, you must take the detour via variables or system constants.

Dispatcher profiles

When working with profile chains, one often has to model branches in the processing sequence. That is, it must be decided at a certain point whether the further processing takes place with profile 2 or profile 3.

For this purpose, it is useful to create a so-called dispatcher profile. So a profile that directs the further processing to the appropriate subsequent profile.

Profile 1 merely has to have several responses of the type "Message". In this case, two. One of them calls profile 2 and the other one calls profile 3.

Calling a response can be controlled via dependencies. Of course, if you are using a variable in the dependency, for example, you can only use variables that are defined in profile 1. These variables may also come from preceding profiles. In that case, you have to use the syntax mentioned earlier .

Alternatively, you can specify the name of the called profile in a single response of type "Message" using a variable (type "String").