Implementing your policy

Create an implementation for your user-defined policy by using DataPower® processing rules and actions.

1. Create a main processing rule that is called <policy-name>-main where <policy-name> is the name of your user-defined policy (the value of the name property in the "info" section of the policy YAML file).
   Note: You must specify the following processing rule settings:

   • Rule direction: Both Directions
   • Non-XML Processing: on
2. Create one or more processing actions.
   Each processing action should have a unique name and must start with the name of the user-defined policy (as defined in the policy YAML file).

   Note: Different processing actions in DataPower might require different releases of the DataPower firmware. When using the GatewayScript actions, the minimum DataPower firmware that should be used is version 7.2.0.

   The following processing actions are available:

   • Configure access to the input properties in XSLT (policyProperties), or in GatewayScript (apic.getPolicyProperty).

     If required by the properties that are defined in the policy YAML file, when the policy is attached to an API the API developer must enter the input settings or variables for a particular property. This function provides the mechanism to retrieve these input settings or variables at run time. For an example code snippet, see Access to input properties code snippet.

   • Configure access to the runtime context in XSLT (getContext), or in GatewayScript (apic.getContext).

     When an API is invoked, runtime information about the request can be accessed by using a user-defined policy, and this information is known as the runtime context. The function getContext provides the mechanism to access this runtime context. For an example code snippet, see Access to runtime context code snippet. For a complete list of context variables, see API Gateway context variables.

   • Configure access to the input payload in XSLT (payloadRead), or in GatewayScript (apic.readInput(callback)).

     Some policies require access to the input message or payload that is provided by the application. Accessing the input message or payload during an assembly flow can be difficult, as this information might change as the policies and the assembly steps run. This function provides a mechanism to get the correct input message or payload at the time of policy execution. For an example code snippet, see Access to input payload code snippet.

     This function returns an XML node-set that contains the payload of the request. If the payload is in JSON format, a JSONx node-set is returned that can then be manipulated within an XSLT or GatewayScript stylesheet. If the payload is not in JSON or XML format, the node-set that is returned is empty.

     Note: The payloadType() function can be called to determine what type of payload (XML or JSONx) will be returned by the payloadRead() or the apic.readInput(callback) function.
   • Configure access to the HTTP headers in XSLT (getContext), or in GatewayScript (apic.getContext).

     The HTTP header information of a request can be retrieved from the request context. The HTTP header names are normalized to lowercase. The function getContext() provides the mechanism to access the HTTP header information. For an example code snippet, see Access to HTTP headers code snippet.

     Note: Access or modification of HTTP headers by using DataPower extensions, such as dp:set-request-header, is not advisable, as such actions might yield unexpected results when the policy is combined with other policies and assembly steps.
   • Modify the payload in XSLT or GatewayScript.

     When a policy implementation is required to change a payload message, you must configure the DataPower Transform Processing Action to set the Output context field to OUTPUT (referred to as the OUTPUT named context).

     The output must be an XML node-set, which represents an XML or SOAP message, or a JSON message by using JSONx. To assist the API Gateway policy framework to accept the new or transformed message, call the apim-output template. For an example code snippet, see Modify the payload code snippet.

     Note: The modify the payload processing action works only with a proxy task. An HTTP or web service task always overwrites the output of a policy implementation.
   • Configure the implementation to produce error information.

     If you require your policy implementation to produce error information when there is a failure, you must configure the implementation by calling the error template. For an example code snippet, see Configure error information code snippet.

   • Set variables.

     Use the setVariable template to set a runtime variable to a specified string value. This value can then be retrieved by using the function getVariable(), or by mapping the value into a step. For an example code snippet, see Set variables code snippet.

3. Export your policy implementation from DataPower.
   From the DataPower user interface, export the objects and files that are referenced by your main processing rule as a compressed file. No other objects or files should be exported. The following file list is an example configuration of an export from DataPower:

   Archive: checkmembership.zip
   
   11819    11-19-2014 22:53 dp-aux/basetypes.xml
   3028207  11-19-2014 22:53 dp-aux/drMgmt.xml
   6456     11-19-2014 22:53 dp-aux/map-dmz.xsl
   7299     11-19-2014 22:53 dp-aux/management.xsl
   23130    11-19-2014 22:53 dp-aux/SchemaUtil.xsl
   216003   11-19-2014 22:53 dp-aux/clixform.xsl
   5284     11-19-2014 22:53 local/policy/checkmembership/check.xsl
   5061     11-19-2014 22:53 export.xml

   The example shows the exported configuration file (export.xml) that contains all the processing actions and DataPower objects, the referenced files, and the DataPower configuration schemas that are created by using the configuration export in the DataPower user interface.