<SCHEDULE/> Asynchronous rule execution

Connecting external logic to dynamic forms

The <SCHEDULE/> tag can be used to integrate external logic (via a service) into a dynamic form. This means that the actual validation logic is stored outside in a FirstSpirit module (“asynchronous rule execution”).

To enable this, the related module must be installed on the FirstSpirit Server prior to executing the rule.

The <SCHEDULE/> section of a rule definition is used for value determination via an external service and in this case replaces the <WITH/> section of a conventional rule definition. The <SCHEDULE/> section must be defined before the tags that introduce a handling instruction.

In the process, the following applies for the definition of a value determination:

• A value determination must be defined for each rule. This can be done in the usual way using a <WITH/> section or, if external logic is to be used, via a <SCHEDULE/> section.
• Another option is to define a <CONDITION/> tag within a <SCHEDULE/> section.
  The <CONDITION/> tag corresponds to the definition of a <IF/> precondition in the case of the conventional rule definition. A Boolean value is determined using the condition. If the condition is fulfilled (TRUE), the defined service is requested; if not (FALSE), the service is not requested. If no condition is defined, the service is always requested.
  The precondition is always related to a particular property of the form element or of the form itself (“Was the form opened in the Page Store?”). A <PROPERTY/> tag needs to be entered in the <CONDITION/> section for this purpose. Additional values can be derived via the expressions below. The value of the input component, for example, can be checked against certain regular expressions or against a comparison value.
  • logical (<AND/>, <NOT/>, <OR/>),
  • comparative (<EQUAL/>, <GREATER_THAN/>, <LESS_THAN/>, <NULL/>/ <NOT_NULL/>, <CONTAINS/>), or
  • regular expressions (<MATCHES/>).
• If the value determination is transferred from SiteArchitect to a FirstSpirit module, parameters and values can be passed to the external logic within a <SCHEDULE/> section, such as the current values from an input component of the form. As a minimum, a <PROPERTY/> tag and any other required tags must be entered within a <PARAM/> tag.
• Three attributes can be passed in a <SCHEDULE/> tag:
  • The mandatory service attribute is used to specify the name of an external class.
  • The mandatory id attribute is used to specify a freely selectable identifier.
  • The optional delay attribute can be used to define a delay for executing the transferred service, e.g.:<SCHEDULE service="Keywords" id="x" delay="500">

The following applies when implementing external logic:

• Only a single component of the “Public” type module can be referenced via each <SCHEDULE/> tag.
• To implement a service, the ValueService interface must be implemented: public class MyValueService implements ValueService {...}
• The return value (i.e., the object type) of the ValueService.getValue() implementation should match the desired (target) input component.
• The transfer parameters (see <PARAM/>) are always of the object type and must be cast accordingly in the implementation.
• Values from FirstSpirit input components can be used in a ValueService implementation. This functionality is supported for the following input components:
  • CMS_INPUT_TEXT
  • CMS_INPUT_TEXTAREA
  • CMS_INPUT_DATE
  • CMS_INPUT_TOGGLE
  • CMS_INPUT_NUMBER
• Values from complex input components (e.g., FS_DATASET, FS_REFERENCE) cannot be used in a ValueService implementation.

External services are only available for the rule evaluation (in the <SCHEDULE/> section) if a form is being interactively edited by an editor. These rules do not take effect if read, save, or release actions are being carried out via API, e.g., in executables or Beanshell scripts. Validations with the restriction levels scope="RELEASE" / scope="SAVE" in conjunction with <SCHEDULE/> are only suitable for editing tasks (similar to the EDITABLE property) and not to technically ensure the validity of content.

Determine values that are available outside the current context

In addition to values that are available in the current context of a rule execution, i.e. that affect the current form or FirstSpirit element in which the rule is executed, it is also possible to access FirstSpirit elements that are outside the current context.

This means that information from other forms, e.g.:

• form data from another page,
• from metadata forms, or
• from the project settings

can be retrieved.

This value determination is executed in a rule definition via the <SCHEDULE/> tag using the services FormDataValueService or MetaDataValueService:
For documentation and examples see Accessing information from other forms.

Attributes

"service" attribute

The “service” attribute is used to reference a single public component of the module.
The name of the public component that is defined under <name> in the component module descriptor is passed, which in this case would be
<SCHEDULE service='Keywords'.../>:

...
<components>
 <public>
 <name>Keywords</name>
 <class>mypackage.Keywords</class>
 </public>
</components>
...

"id" attribute

The “id” attribute is used to assign an identifier. If the public component is referenced multiple times within the rule definition, “similar” calls can be avoided by assigning different identifiers in the <SCHEDULE/> sections.

For instance, if (depending on the rule definition) the “Keywords” service is started but a service with the specified service name/ID combination is already active in the current user session, the existing service call is canceled.

<RULE>
 <SCHEDULE service="Keywords" id="k1" delay="500">
 ...
 </SCHEDULE>
 <DO>
 ...
 </DO>
</RULE>

<RULE>
 <SCHEDULE service="Keywords" id="k2" delay="500">
 ...
 </SCHEDULE>
 <DO>
 ...
 </DO>
</RULE>

"delay" attribute

The optional “delay” attribute is used to specify a waiting time in milliseconds. The value “0” is always used if no value is entered. If a value greater than “0” is entered, the execution time of the actual service call is delayed according to the value entered.

Background: External logic is integrated in a <SCHEDULE/> section that reads out and processes the values of a FirstSpirit input component and populates a second input component, for instance. This makes it possible to populate the “zip code” field automatically after entering the “location” and “street” in a form. If the external call is returned after one of the affected fields has been changed (e.g., because a typo in the “location” field has since been corrected), the supplied result is discarded again. This behavior is not desired in all cases, since the external call is potentially time and resource intensive. To prevent a call each time the editor presses a button, the “delay” attribute should be specified.

In the case of more complex queries or a very extensive rule definition, it might also make sense to define a precondition using a <CONDITION/> tag.

Examples

Example 1) Automatic generation of keywords from the value in a form field

A form contains a form field for entering editorial content (“st_text”) and another field for entering keywords (“st_keywords”). A dynamic form has now been introduced to ensure that the content entered by the editor in the first field is automatically copied over to the second form field as keywords. The external logic for this is stored out in a module that first has to be installed on the FirstSpirit Server: FirstSpirit ValueService (example) (Version 0.1)

The rule definition then contains a <SCHEDULE/> section defined with the following attributes:

<RULES>
    <RULE>
        <SCHEDULE service="Keyword service" id="x" delay="500">
            ...
        </SCHEDULE>
    </RULE>
</RULES>       

This syntax is used to request the “Keyword service” under the “x” ID with a delay of 500 ms. However, the service should not be requested continuously, but only when the editor places values in the “st_text” form field. The rule definition is, therefore, expanded within the <SCHEDULE/> section to include a condition (<CONDITION/>):

<RULES>
    <RULE>
        <SCHEDULE service="Keyword service" id="x" delay="500">
            <CONDITION>
                <PROPERTY source="st_text" name="FOCUS"/>
            </CONDITION>
            ...
        </SCHEDULE>
    </RULE>
</RULES>  

The “Keyword service” is now only requested when the editor makes the “st_text” component the focus in the form.

The next step is to read out the content from the “st_text” component. In this case, the values are transferred to the external logic (i.e., the service). For this purpose, parameters are passed in the <SCHEDULE/> section (and under the <CONDITION/>, if applicable) using one or more <PARAM/> tags. The “name” attribute is used to define the parameter name. Value determination then takes place as usual using a <PROPERTY/> tag within the <PARAM/> section. In this example, the current content of the “st_text” input component is passed along with the editorial language in which the form is currently being edited:

<RULES>
    <RULE>
        <SCHEDULE service="Keyword service" id="x" delay="500">
            <CONDITION>
                <PROPERTY source="st_text" name="FOCUS"/>
            </CONDITION>
            <PARAM name="text">
                <PROPERTY source="st_text" name="VALUE"/>
            </PARAM>
            <PARAM name="lang">
                <PROPERTY source="#global" name="LANG"/>
            </PARAM>
        </SCHEDULE>
    </RULE>
</RULES> 

The “text” and “lang” parameter value pairs are transmitted to the service and are further processed there (entry point for the implementation of a value service, see FirstSpirit Access API: ValueService); for instance:

...
public Object getValue(final SpecialistsBroker broker, final Map<String, ?> parameters) {
	    final Locale locale;		
	    final Object lang = parameters.get("lang");
	    ...
}
...

The <DO/> section of the rule is executed after executing the service with the return value determined there. In the example, the determined return values are applied to the “st_keywords” component.

<RULES>

    <RULE>
        <SCHEDULE service="Keyword service" id="x" delay="500">
            <CONDITION>
                <PROPERTY source="st_text" name="FOCUS"/>
            </CONDITION>
            <PARAM name="text">
                <PROPERTY source="st_text" name="VALUE"/>
            </PARAM>
            <PARAM name="lang">
                <PROPERTY source="#global" name="LANG"/>
            </PARAM>
        </SCHEDULE>
        <DO>
            <PROPERTY source="st_keywords" name="VALUE"/>
        </DO>
    </RULE>

</RULES>

Example 2) Checking the validity of an ISBN

A form contains a text form field for entering an ISBN number (“cs_isbn13”). Using a dynamic form ensures that the value of the input component is checked during editing. This check is executed using an external “ISBN13VerificationService” service:

<RULE> 
    <SCHEDULE service="ISBN13VerificationService" id="isbn13" delay="0"> 
        <PARAM name="value"> 
            <PROPERTY source="cs_isbn13" name="VALUE"/> 
        </PARAM> 
    </SCHEDULE> 
    <DO> 
        <VALIDATION> 
            <PROPERTY source="cs_isbn13" name="VALID"/> 
            <MESSAGE lang="*" text="Es muss eine gültige ISBN-13-Nummer angegeben werden!"/> 
        </VALIDATION> 
    </DO> 
</RULE>

The ValueService.getValue() implementation checks the number and returns a Boolean value.

public Boolean getValue(final SpecialistsBroker broker, final Map<String, ?> parameters) { 
    final Object value = parameters.get("value"); 
    if (value instanceof String) { 
        log("Performing ISBN-13 verification..."); 
        return isValidISBN13((String) value); 
    } 
    return false; 
}

The returned value is then evaluated in the <VALIDATION/> section of the rule.