Implementing your policy
Create an implementation for your user-defined policy by using DataPower® processing rules and actions.
Before you begin
You must create a policy YAML file before you create an implementation. For more information, see Describing your policy.
- Access to input property values (input from the assembly editor).
- Access to context values (the API Gateway runtime context).
- Access to the runtime payload message and media-type.
- Ability to modify the payload message.
- Ability to end the policy execution with an error.
About this task
- You must create a main processing rule, and this rule will be the starting point for the policy.
The rule name must start with the name of the policy (the value of the
nameproperty in the "info" section of the policy YAML file), followed by -main; for example checkmembership-main.
- There are no restrictions on what actions the processing rule can execute, on condition that the rule adheres to the naming convention in point 1. and the instructions that are detailed in this topic.
- The names of the processing actions and all other objects also must start with the name of the
policy (the value of
nameproperty in the "info" section of the policy YAML file).
- If your processing rule runs transformation actions that use XSLT or GatewayScript files, these files must be stored in the following location: local://policy/<policy-name>.
- If you have certificate and key files that must be stored in the cert: folder, the names of these files also must start with the name of the user-defined policy (as defined in the policy YAML file).
- If your policy is using GatewayScript transformations, your policy code must require
apim.custom.js, for example:
var apic = require('local://isp/policy/apim.custom.js');
- Create a main processing rule.
- Create one or more processing actions:
- Export your policy implementation.
Create a main processing rule that is called
<policy-name> is the name of your user-defined policy (the value of the
nameproperty 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
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 (
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 (
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
getContextprovides 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 (
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
- Configure access to the HTTP headers in XSLT
getContext), or in GatewayScript (
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-outputtemplate. 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.
setVariabletemplate 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.
- Configure access to the input properties in XSLT (
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:
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.
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