Format an IBM z/OS Connect rule set

A z/OS Connect rule set must be written in a specific format.

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, z/OS Connect completes the related actions.

zosConnect-3.0 Applies to zosConnect-3.0.

z/OS Connect 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. The set action can be used to change the value of a property.
For more information about valid properties for use in z/OS Connect policy rules, see Valid properties for use in IBM z/OS Connect policy rules.
Note:
  1. Leading and trailing white space for each comma-separated value is ignored.
  2. 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.
  3. z/OS Connect does not validate the rules. 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="imsTranExpiration" value="true"/>
        </actions>
    </rule>
    <rule name="groupTwo">
        <conditions>
            <header name="group" value="X,Y,Z"/>
        </conditions>       
        <actions>
            <set property="imsConnectionRef" value="groupTwoConnection"/>
            <set property="imsTranExpiration" value="false"/>
        </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 group is B and trancode is update, then z/OS Connect completes the following actions:
  1. <rule name="groupOne">. The condition is met and the value of imsConnectionRef is changed to groupOneConnection and the value of imsTranExpiration is changed to true.
  2. <rule name="groupTwo">. The condition is not met, so the actions are ignored.
  3. <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"/>
        </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.

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"/>
            <header name="groupB" value="B"/>
        </conditions>       
        <actions>
            <set property="imsConnectionRef" value="groupOneConnection"/>
            <set property="imsTranCode" value="GRPONE"/>
        </actions>   
    </rule>
    <rule name="groupTwo">       
        <conditions>
            <header name="groupA" value="A"/>
        </conditions>       
        <actions>
            <set property="imsConnectionRef" value="groupTwoConnection"/>
            <set property="imsTranCode" value="GRPTWO"/>
        </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 groupOne 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 groupOne has two headers, so it is considered to be more specific than the rule groupTwo and is checked first.

If both conditions are met, then rule groupTwo 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 z/OS Asset types and any properties not relevant to the z/OS Asset are ignored.

<?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.

Example 6

Example 6 illustrates the use of headers for an API requester policy. For an example of COBOL application code to set the headers, see Specify policies.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ruleset>
  <rule name="connectionRefRule">
    <conditions>
      <header name="AppEnv" value="DevEnv"/>
      <header name="AppType" value="1"/>
    </conditions>
    <actions>
      <set property="endpointConnectionRef" value="devConnectionRef"/>
    </actions>
  </rule>
</ruleset>