Format of a rule set

A rule set must be written in a specific format.

zosConnect-2.0 Applies to zosConnect-2.0.

A rule set consists of one or more rules. Each rule contains one or more conditions and one or more actions. If the conditions are met, IBM® z/OS® Connect performs the related actions.

Rule specifications

A rule consists of a name attribute and the following sub elements:

conditions: Only one conditions element is allowed in each rule. The conditions element has one or more header elements with the attribute's name and value. Multiple header elements have a Boolean AND relationship, so all header conditions must be met for the actions to be performed. If more than one value is defined, then any one of those values can match.
actions: An action or list of actions to be performed if the condition is met. For example, the set action can be used to change the value of a property.

Note:

Leading and trailing white space for each comma-separated value is ignored.
If match="ANY_VALUE" is specified, the header condition is satisfied when an HTTP header with the correct name is included in the API request, regardless of the HTTP header value.
Rules are not validated by IBM z/OS Connect. If the header name, property, or value is not entered correctly, results are unpredictable.

Example 1


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ruleset>
    <rule name="groupOne">       
        <conditions>
            <header name="group" value="A,B,C"/>
        </conditions>       
        <actions>
            <set property="imsConnectionRef" value="groupOneConnection"/>
            <set property="imsInteractionRef" value="groupOneInteraction"/>
        </actions>
    </rule>
    <rule name="groupTwo">
        <conditions>
            <header name="group" value="X,Y,Z"/>
        </conditions>       
        <actions>
            <set property="imsConnectionRef" value="groupTwoConnection"/>
            <set property="imsInteractionRef" value="groupTwoInteraction"/>
        </actions>   
    </rule>
    <rule name="setTrancode">       
        <conditions>
            <header name="trancode" value="update"/>
        </conditions>       
        <actions>
            <set property="imsTranCode" value="IVTNO"/>
        </actions>
    </rule>
</ruleset>

This sample rule set defines three rules. Multiple rules have a Boolean OR relationship. Each rule is checked separately. If for example, a request is received where the value of the HTTP header property group is B and trancode is update, then IBM z/OS Connect performs the following actions:

<rule name="groupOne">. The condition is met and the value of imsConnectionRef is changed to groupOneConnection and imsInteractionRef groupOneInteraction.
<rule name="groupTwo">. The condition is not met, so the actions are ignored.
<rule name="setTrancode">. The condition is met, so the imsTranCode property is changed to IVTNO.

Variables

You can use variable substitution to target a specific transaction according to the header value in the request.

Example 2


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ruleset name="variableSubstitution">
    <rule name="connectionInteraction">
        <conditions>
            <header name="connectionType" value="A,B,C"/>
        </conditions>       
        <actions>
            <set property="imsConnectionRef" value="${connectionType}Connection"/>
            <set property="imsInteractionRef" value="${connectionType}Interaction"/>       
        </actions>
    </rule>
</ruleset>

This rule set has only one rule, but performs as if there are many rules. For example, if a request is received where the header property connectionType contains the value A, then the imsConnectionRef property is changed to AConnection and imsInteractionRef to AInteraction.

Variable substitution can be placed at any location in the value string, provided it is in the correct format. The substitution can also be used with no hardcoded value.

Example 3

Example 3 illustrates the use of multiple headers.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ruleset>
    <rule name="groupOne">       
        <conditions>
            <header name="groupA" value="A"/>
        </conditions>       
        <actions>
            <set property="imsConnectionRef" value="groupOneConnection"/>
            <set property="imsInteractionRef" value="groupOneInteraction"/>
        </actions>
    </rule>
    <rule name="groupTwo">
        <conditions>
            <header name="groupA" value="A"/>
            <header name="groupB" value="B"/>
        </conditions>       
        <actions>
            <set property="imsConnectionRef" value="groupTwoConnection"/>
            <set property="imsInteractionRef" value="groupTwoInteraction"/>
        </actions>   
    </rule>
</ruleset>

When multiple headers are defined in the same conditions element, they have a Boolean AND relationship so that all conditions must be met for the actions to be performed. In this example, the rule groupTwo has multiple conditions. The header groupA must match the value A and the header groupB must match the value B. If either condition is not met, then no actions occur.

In this example, the header that is named groupA appears in both rules, but the rule groupTwo has two headers, so it is considered to be more specific than the rule groupOne and is checked first, even though it appears later in the ruleset than rule groupOne. If both conditions are met, then rule groupOne is not checked. It is good practice to write your ruleset so that the most specific rules appear first. This format is easier to understand when diagnosing problems.

Example 4

Example 4 illustrates how a rule can set properties for multiple service providers and any properties not relevant to the service provider in use are ignored by the service provider.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ruleset>
    <rule name="groupOne">                                          
        <conditions>                                               
             <header name="groupA" value="A"/>                     
        </conditions>                                              
        <actions>                                                  
            <set property="cicsConnectionRef" value="cicsOneconnection" />  
            <set property="imsTranCode" value="IVTNO"/>
        </actions>                                                 
    </rule>
</ruleset>

Each service checks the actions that are applicable to it and ignores the others. In this example, the CICS® service acts on the cicsConnectionRef property and the IMS service acts on the imsTranCode property.

Example 5

Example 5 illustrates how a rule can be configured to perform an action when a specific header is present on the API request, regardless of the value of that header. This method eliminates the need to include a long list of acceptable values in the rule set.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ruleset>
    <rule name="cicsTransId">                                          
        <conditions>                                               
             <header name="target" value="" match="ANY_VALUE"/>                     
        </conditions>                                              
        <actions>                                                  
            <set property="cicsTransId" value="${target}" />  
        </actions>                                                 
    </rule>
</ruleset>

If an API request header contains target, then the value of that header is substituted into cicsTransId.

Note: If you use the match attribute, you should always specify value="" as this attribute is required but is not used when the request header is checked for a matching name.