DataPower Gateway (Classic)
only

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.

You can create an implementation for your policy by using the usual tools available to IBM® DataPower Gateway developers. However, the DataPower user interface is typically the tool that is used to create processing rules and actions.
Note: You must be skilled in DataPower tooling and concepts, before you can create a policy implementation.
In order for your processing actions to work well under the API Gateway configuration, and also to enable the use of contextual information that is relevant to the processing actions, a library of functions and templates is available that you can use to assist you in writing the XSLT or GatewayScript transformations. This library provides the following mechanisms:
  • 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 create an implementation for your user-defined policy in the IBM DataPower Gateway. The implementation must adhere to the following conventions:
  1. 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 name property in the "info" section of the policy YAML file), followed by -main; for example checkmembership-main.
  2. 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.
  3. The names of the processing actions and all other objects also must start with the name of the user-defined policy (the value of the name property in the "info" section of the policy YAML file).
  4. 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>.
  5. 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).
  6. 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');
The following steps describe how to create an implementation for your user-defined policy: .

Procedure

  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.

Results

You have created an implementation for your user-defined policy and exported this implementation from the DataPower user interface.

What to do next

Create a user-defined policy package that can then be imported into IBM API Connect. For details, see Packaging and importing your policies into IBM API Connect.