EnvironmentCheckByFilter
|
Configuration file |
Yes. See below. |
|
Class name |
com.ebd.hub.datawizard.extensions.EnvironmentCheckByFilter |
Description
This environment check class calls a function, whose result is interpreted as data type "Boolean" and is used for the decision whether the job is started or suspended.
A properties configuration file specifies what function is called for the decision whether a job is started or suspended, what parameters it receives and if exceptions in the function should be suppressed.
The waiting time in seconds until the next execution of the environment check can either be specified as integer value or by calling another function (wait function) during runtime. If the waiting time has the value "2147483647" (Integer.MAX_VALUE), the job is not suspended but deleted. In this case, the backup file is deleted as well.
If the decision calls a macro that uses the "abort execution()" function (or if the function is called directly) and the function aborts, the profile job is not started or suspended, but terminated (but without an error).
Configuration
|
Property |
Meaning |
Default |
Comment |
|
|
|
|
The following properties are for the decision function |
|
filter.class |
Name of the function class. |
No default. |
Complete or short class name. If no class is specified, the function ID is used. |
|
filter.id |
Registered function ID. |
226 |
Function ID of a function registered in ./etc/admin/datawizard/filter.properties or custom_filter.properties. The property is only used if no class name is specified. If neither class name nor the ID of the wait function is specified, the function "logical-condition()" with ID 226 is used. |
|
filter.param.a |
Parameter a. |
No default. |
Value that is passed on to the function as parameter a. It depends on the specific function whether this parameter is expected. Note: You can use variables (syntax @MSG_CALL_MYVAR@) and system constants (syntax %MYCONST%) for function (filter) parameter values. |
|
filter.param.b |
Parameter b. |
No default. |
Value that is passed on to the function as parameter b. It depends on the specific function whether this parameter is expected. |
|
filter.param.N |
Parameter N. |
No default. |
Value that is passed on to the function as parameter N (where N = {c-z}). It depends on the specific function whether this parameter is expected. |
|
|
|
|
The following properties are for the wait function. |
|
wait.time |
Waiting time in seconds until restart. |
30 |
Values smaller than 1 are ignored and the default 30 is used. This value can only be increased during runtime (with the wait function). |
|
wait.filter.class |
Name of the wait function class. |
No default. |
Class name of the function that is used to calculate the waiting time. Has priority over wait.filter.id. |
|
wait.filter.id |
ID of the wait function class. |
No default. |
Registered ID of the function that is used to calculate the waiting time. Will be ignored if wait.filter.class exists. If neither the ID nor the class of the wait functions is specified but wait.filter.param.a exists, the function "logical-condition()" with ID 226 is used. |
|
wait.filter.param.a |
Parameter a for wait function. |
No default. |
Value that is passed on to the wait function as parameter a. It depends on the specific function whether this parameter is expected. |
|
wait.filter.param.b |
Parameter b for wait function. |
No default. |
Value that is passed on to the wait function as parameter b. It depends on the specific function whether this parameter is expected. |
|
wait.filter.param.N |
Parameter N for wait function. |
No default. |
Value that is passed on to the wait function as parameter N (where N = {c-z}). It depends on the specific function whether this parameter is expected. |
|
|
|
|
The following properties are for the exception handling (valid for both functions). |
|
filter.exception |
Suppress exceptions. |
No default. |
If this property has the value ignore, exceptions in both functions will be suppressed and not be forwarded to the job. Exceptions in decision functions are interpreted as false. The job will be suspended in this case. For exceptions in wait functions, the waiting time defined in wait.time is used. |
|
|
|
|
The following properties are for the behaviour at restart. |
|
restart.execute |
Also at restart. |
false |
If true, the environment check is also started if the job is started with the 'Restart…' dialogue. Default: No environment check at restart. |
Application description
Start or suspend a job?
The decision function is set with filter.class or filter.id and parameter values filter.param.N. You can use lowercase letters a to z for N. Only the parameters that are expected by the function are passed on.
The function "logical-condition()" is used preferentially if neither filter.class nor filter.id are defined. This function can also call a function macro if the name of the macro is specified in parameter a. The prefix not allows the negation of the boolean macro logic. By using macros, more complex function chains are possible.
The return value of the function decides whether the job is executed or suspended. Return value true executes the job and false suspends it. If the return valued does not have the data type "Boolean", an implicit typecast will be done. The following rules apply for the implicit typecast.
|
String |
The word true (not case-sensitive) is converted to the boolean value true. Everything else to false. |
|
Integer, BigInteger, Float, Double, BigDecimal |
All values greater than 0 are converted to true. Negative values and 0 to false. |
|
Date, Timestamp |
Every valid point in time after 1970-01-01 is converted to true. Empty values (no value) to false. |
Waiting time until next Environment Check
If a job has been suspended, the environment check is executed again after a waiting period. The result of the repeated check decides whether the job stays suspended or is executed.
Configured waiting time
The waiting time in seconds is set in the property wait.time. If the property is not set or the value is smaller than 1 second, the default value of 30 seconds is used.
Calculation of the waiting time during runtime
The waiting time can be re-calculated with a function (the wait function) during runtime. The calculated waiting time will only be used if it is bigger than the configured waiting time.
The goal of the calculated waiting time is to avoid unnecessary runs of the environment check if it is likely that another check would lead to a further suspension. Therefore, only an extension (no shortening) of the waiting time is possible.
Analogous to the decision function, the wait function is set with wait.filter.class or wait.filter.id and the parameter values wait.filter.param.N. You can use lowercase letters a to z for N. Only the parameters that are expected by the wait function are passed on.
If neither wait.filter.class, wait.filter.id nor wait.filter.param.a are defined, no calculation of the waiting time is done and no wait function is executed.
If wait.filter.param.a exists, but neither wait.filter.class nor wait.filter.id are defined, the function "logical-condition()" is used. Usually, a macro is called, whose return value is the number of seconds of the calculated waiting time.
Behaviour in case of function exceptions
The goal of the environment check is to check the availability of an external system. It is possible that this check ends with an exception if the system is not available. If this exception is not intercepted and ignored, it is passed on to the profile and will create an entry in the error list of the Control Center.
The property filter.exception=ignore can intercept these exceptions. This leads to the following behaviour in case of an exception.
Value false is used for the decision function in case of an exception. The job is suspended.
If an exception occurs in the wait function, the configured waiting time is used instead.
Behaviour in case of a manual restart
If an already executed job is restarted with the Restart… dialogue, it has to be decided whether the environment check with class EnvironmentCheckByFilter is executed. Default: No environment check for restarts. If you want to have environment checks, set the property restart.execute to true.
Resolution of variables and system constants
The environment check is executed before phase 2, so before the actual job environment exists. Therefore, only the system variables that are known from phase 1 and MSG_CALL_ variables (if they are defined in the profile) are available. This allows for a parameterisation of the environment check if the profile is called by a Message or is triggered by HTTP or a profile.
Variables that are defined in the profile and receive a value from 'outside' can be used as value of a property in the configuration file with syntax @variable_name@. System constants can be used with syntax %constant_name%.
Caution: Since a repeated environment check after a waiting time uses the original set of variables, the values are usually the same after a suspension.
Since the system variable VAR_FILENAME is not available, the pseudo-variable @<file>@ that contains the name of the input file can be used.
Restrictions
The job environment does not exist at the time the environment check is executed. Therefore, a rudimentary substitute environment is created.
Maps, lists and value splitters are available in the substitute environment and can be used in the environment check, but created list, map or splitter objects are not passed on to the job environment.
Some functions might not work in the rudimentary environment. A complete check of all functions in all combinations has not been performed.
Application examples
Scenario 1
A profile receives data via email and creates a destination file with fixed filename ./temp/output/Env2Check.txt, which is fetched and thereby deleted by another system/process. A data loss might occur if the file is overwritten by a subsequent job before the destination system has fetched it.
The first measure is to set profile option Profile is a singleton (tab Extended settings in phase 2). Regardless, occasionally the file gets overwritten.
Goal: Suspend subsequent jobs of the profile until the destination file has been fetched or deleted.
Solution: The environment check is done with class com.ebd.hub.datawizard.extensions.EnvironmentCheckByFilter and the following configuration.
filter.param.a=not filefilter.param.b=./temp/output/Env2Check.txtrestart.execute=trueExplanation: Since neither class name nor an ID has been defined for the decision function, function "logical-condition()" is used. This function calls function "file-exists()" (with key "file") that checks the existence of the file specified in filter.param.b.
Placing the prefix not in front of file inverts the logic. The subsequent job is suspended as long as the file has not been fetched or deleted.
Since no wait.time or wait function is configured, the environment check is repeated every 30 seconds.
restart.execute=true guarantees the environment check at restarts.
Scenario 2
During working hours, data is produced that should only be processed several hours after the end of work. All jobs of the profile have to be suspended in between 6.30 am (0630) and 7.45 pm (1945). Since it is quite a long period of time, we would like to avoid unnecessary runs of the environment check by calculating the waiting time.
Solution: Two function macros are developed and tested: macros.zip
Macro "AfterEight"
The macro is used to decide whether the job is executed or suspended. It has two parameters:
|
a [Suspend start time (HHmm)] b [Suspend end time (HHmm)] |
1) now()2) format date/timestamp to text(date a, template b, [Locale c], [Timezone d])a result: 1b constant: HHmmc constant: d constant: Europe/Berlin3) convert-type( value a, type b, mask c)a result: 2b constant: Integer4) final-on-condition(ret a, cnd b, par c [, d, ...])a constant: trueb constant: <c result: 3d input: 15) a >= ba result: 3b input: 2Macro "SecondsUntilEight"
This macro is used to calculate the waiting time till the next run of the environment check. It has one parameter:
|
a [Target time (HHmm)] |
1) now()2) format date/timestamp to text(date a, template b, [Locale c], [Timezone d])a result: 1b constant: HHmmc constant: d constant: Europe/Berlin3) a - ba input: 1b result: 24) a * ba result: 3b constant: 605) convert-type( value a, type b, mask c)a result: 4b constant: IntegerThe two macros are used in the configuration of the environment check by class EnvironmentCheckByFilter.
filter.param.a=Macro AfterEightfilter.param.b=0630filter.param.c=1945wait.time=27wait.filter.param.a=Macro SecondsUntilEightwait.filter.param.b=1945