19.4 Customizing Transformation Rules

Transformation rules are used by APS.

The transformation rules illustrated in the following example are the default rules provided by Access Manager. A Clone can be configured to override these OOTB rules. This section documents how some of these rules can be modified and how to configure Access Manager to recognize these custom rules.

Default Transformation Rules

<?xml version="1.0" encoding="UTF-8"?>
<mdc-transform-rule>
 <changes-to-include entity-path="/policy"/>
 <changes-to-include 
  entity-path="/config/NGAMConfiguration/DeployedComponent/Agent/WebGate/Instance">
  <replace attribute-match="/*/PrimaryServerList/*/host" value-match="(.*)">
   <replace-with 
n="1">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/serverhost}</replace-with>
  </replace>
  <replace attribute-match="/*/UserDefinedParameters/logoutRedirectUrl" 
   value-match="(.*)://(.*):(.*)/oam/server/logout">
  <replace-with 
n="1">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/serverprotocol}</replace-with>
  <replace-with 
n="2">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/serverhost}</replace-with>
  <replace-with 
n="3">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/serverport}</replace-with>
  </replace>
  <replace attribute-match="/*/logoutRedirectUrl" 
   value-match="(.*)://(.*):(.*)/oam/server/logout">
  <replace-with 
n="1">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/serverprotocol}</replace-with>
  <replace-with 
n="2">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/serverhost}</replace-with>
  <replace-with 
n="3">${/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/serverport}</replace-with>
 </replace>
</changes-to-include>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/AuthenticationModules"/>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/oamproxy"/>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/Sme/SessionConfigurations"/>
<changes-to-include entity-path=
"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER">
<ignore attribute-match="/serverprotocol"/>
<ignore attribute-match="/serverhost"/>
<ignore attribute-match="/serverport"/>
</changes-to-include>
<changes-to-include entity-path="/config/NGAMConfiguration/DataCenterConfiguration/Cluster">
<ignore attribute-match="/DataCenterType"/>
<ignore attribute-match="/ClusterId"/>
<ignore attribute-match="/WriteEnabledFlag"/>
</changes-to-include>
</mdc-transform-rule>

These transformation rules make changes to WebGate agent definitions. The following information details how you can modify these changes for the PrimaryServerList and logoutRedirectUrl attributes.

PrimaryServerList updates the primary server list for all WebGate agents and replaces them with the Access Manager server host from the Clone environment. This change can be viewed in the oam-config.xml file; it replaces the value of the PrimaryServerList attribute with the value equal to ${DeployedComponent/Server/NGAMServer/Profile/OAMServerProfile/OAMSERVER/serverhost}; for example, oam1-lon.example.com. The limitation of this rule is that it updates all servers in the primary list.

You can use the transformation rule in the following example to update servers in PrimaryServerList with the different Clone servers.
```
<changes-to-include entity-path=
 "/config/NGAMConfiguration/DeployedComponent/Agent/WebGate/Instance">
    <replace attribute-match="/*/PrimaryServerList/0/host" value-match="(.*)">
        <replace-with n="1">${"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
 Instance/oam_server1/host"}
        </replace-with>
    </replace>
    <replace attribute-match="/*/PrimaryServerList/1/host" value-match="(.*)">
        <replace-with n="1">${"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
 Instance/oam_server2/host"}
        </replace-with>
    </replace>
</changes-to-include>
```
Note:
The OAM Managed Servers such as oam_server1 and oam_server2 must be updated with the names specified during deployment.

A load balancer is recommended between the WebGate and Access Manager server. In this case, you do not have to update the PrimaryServerList across data centers and can remove this transformation rule from the XML. However, you do need to update the PrimaryServerList parameter for IAMSuiteAgent and accessgate-oic unless you have configured these agents to communicate with the load balancer as well.

The following example illustrates how to change the transformation rule to update the PrimaryServerList only for IAMSuiteAgent and accessgate-oic agents and not WebGate agents.
```
<changes-to-include entity-path="/config/NGAMConfiguration/DeployedComponent/
 Agent/WebGate/Instance">
    <replace attribute-match="/IAMSuiteAgent/PrimaryServerList/*/host" value-match="(.*)">
        <replace-with n="1">${"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
 Profile/OAMServerProfile/OAMSERVER/serverhost"}
        </replace-with>
    </replace>
    <replace attribute-match="/accessgate-oic/PrimaryServerList/*/host" value-match="(.*)">
        <replace-with n="1">${"/config/NGAMConfiguration/DeployedComponent/Server/NGAMServer/
 Profile/OAMServerProfile/OAMSERVER/serverhost"}
        </replace-with>
    </replace>
</changes-to-include>
```
The logoutRedirectUrl attribute updates the logout URL protocol, host and port for all WebGate agents with respective values from the Clone. If a load balancer is used globally to define the logout URL for all WebGate agents in the Master environment, you don't need to replace the logout URL in the Clone environment and can remove the transformation rule. If you are using a DCC authentication scheme and a global load balancer host name to define the DCC login and logout URL, then again you don't need to replace the login and logout URL in the Clone environment and can remove the transformation rule.

To configure Access Manager to use custom transformation rules, update the setDomainEnv.xml file on the Clone machine. Each Clone can use different transformation rules. Be sure to restart the Clone's AdminServer after changing a transformation rule. Figure 19-3 illustrates how to apply these custom rules.

Figure 19-3 Applying Custom Transformation Rules

Description of "Figure 19-3 Applying Custom Transformation Rules"