IBM DataPower WebGUI

IBM DataPower Gateway is a family of network devices designed to simplify, secure, and optimize the delivery of web, mobile, application, and API workloads. It is a hardware appliance that can act as an intermediary between clients and servers, providing security, integration, and acceleration features.

DataPower Gateway is designed to handle a variety of workloads, including XML, JSON, REST, and SOAP-based messages. It can transform and route messages, enforce security policies, and provide advanced application layer protection against web application attacks. Some key features of IBM DataPower Gateway include:

• Security
• Integration
• Acceleration
• Management

Traceable provides you with a zip file containing pre- and post-flow policies. Traceable instruments IBM DataPower by adding pre-processing and post-processing rules to an API collection. Note that IBM DataPower comes with a default set of API pre- and post-processing rules. When an API collection is created, these preconfigured rules are added by default to the collection. Traceable makes a copy of the default rules and adds Traceable IBM Datapower policies to it.

Before you begin

Make a note of the following points before proceeding with the set-up:

• The document assumes that you have working knowledge of IBM DataPower and IBM DataPower WebGUI.
• API Collection - Make sure you understand what an API collection is in IBM DataPower. For more information, see Configuring an API collection. The topic assumes that you have an existing API collection. Traceable policies are applied to an API collection. You can have one or more than one API collection. Traceable policies are applied separately to each API collection.
• Rules and assembly - Knowledge of rules and assembly in IBM DataPower. Assemblies provide a higher-level view of message processing flows, defining the structure and sequence of processing stages, while rules offer detailed, specific instructions for how individual aspects of message processing should be handled. Assemblies often include rules within their stages to implement the desired message processing behavior. Together, assemblies and rules enable administrators to design and configure complex message processing logic in IBM DataPower.
• Domain - Make a note of the domain in which you wish to apply the configurations. Domains in IBM DataPower provide a structured way to organize and manage configurations and resources, making it easier to maintain separation between different aspects of an organization's infrastructure or different phases of application development and deployment. Each domain operates as an independent unit, which enhances security, control, and manageability within the DataPower appliance. For more information, see Domains.
• Traceable Platform agent - Make sure that you have already installed Traceable Platform agent. For more information on installation, see Platform agent. Make a note of the IP address of the Traceable Platform agent. This would be used in configuring the Traceable policy.
• Note that the communication between DataPower and Traceable Platform agent is over HTTPS using port number 5443.
• Download the Traceable policies from Traceable's download site. Navigate to agent → ibm-datapower. Click on ibm-datapower-webgui-<version>.zip file.
• Make sure that you have a valid account with IBM DataPower WebGUI with a privileged user role. For more information, see User accounts.

Create a configuration checkpoint

Creating a configuration checkpoint helps in reverting to a previous configuration. Complete the following steps:

1. Navigate to Administration → Configuration → Configuration Checkpoints. Enter the checkpoint name and click on Save Checkpoint.
2. Click on Confirm on the Execute Action page.
3. The checkpoint is added to the Configurations Checkpoints page. 

As a first step, determine whether the API collection for which you wish to instrument Traceable uses default or custom rules. The default rules are read-only rules. To modify the default rules, we create a copy of those rules and then add Traceable rules to it.

If the API collection already uses a custom API processing rule, then instrumentation requires adding the Traceable rules to the custom rules. 

Determine API collection with default or custom rules

You can determine whether a collection is using a default rule by navigating through the steps as described below:

1. From the Control Panel, select the domain and then click on Services → API Gateway → API Gateway as shown in the screenshot below.
2. Click on the Domain name from the Configure API gateway page. apiconnect is the Gateway in this example. Your environment would have a different Gateway.
3. In the Configure API gateway page, select the API collection from the drop-down menu for which you wish to determine whether it uses the default rules. Click on the three dots (...) as shown below. The Configure API collection page would open in a new window.
4. In the Configure API collection page, check the following four fields. If the values are as mentioned below, then the API collection has default rules.

   Field	Value
   API processing rule	default-assembly-func-rule
   API error rule	default-api-error-rule
   Assembly preprocessing	default-preflow
   Assembly postprocessing	(none)

Similarly, if the API collection has a similar looking (as shown in the screenshot below) API processing rule and assembly, then the API collection is using custom rules. 

Import policy

Import the Traceable policy zip file that you downloaded in the Before you begin section. If you have not downloaded the policy files, then download the Traceable policies from Traceable's download site. Navigate to agent → ibm-datapower. Click on ibm-datapower-webgui-<version>.zip file.

Navigate to Administration → Configuration → Import Configuration in IBM DataPower WebGUI. Complete the following steps:

1. Click on Browse and open the downloaded zip file and click on Next. 
2. On the Import Configuration page, select all the new configurations and click on Import.
3. Click on Import to view the Import Configuration confirmation page.

Configure Traceable Platform agent

You need to configure Traceable Platform agent's IP address in the imported Traceable policy. Complete the following steps: 

1. Navigate to Administration → Main → File Management.
2. Click on the Edit button as shown above.
3. Click on the Edit button on the policy page and add the Traceable Platform agent's IP address. Click on Submit button. Make sure the URL is https://<IP_address or FQDN>:5443.

Add Traceable rules

Add the Traceable rules in the API collection rules chain.  There are two methods to add the rules based on whether the API collection has default or custom rules. 

Method 1 - API collection uses default rules

To add Traceable rules when the API collection uses default rules, complete the following steps:

1. From the Control Panel, select the domain and then click on Services → API Gateway → API Gateway.
2. From the API Collection section, select the collection for which you wish to add Traceable policies.
3. Update the following rules as mentioned below:
   1. API processing rule → traceable-global-func-call-rule
   2. Assembly preprocessing → traceable-pre-assembly
   3. Assembly postprocessing → traceable-post-assembly

Method 2 - API collection uses custom rules

Use this method to add Traceable rule when your collection has custom rules. Complete the following steps:

1. From the Control Panel, select the domain and then click on Services → API Gateway → API Gateway.
2. From the API Collection section, select the collection for which you wish to add Traceable policies. 
3. In this example, the Assembly preprocessing has a custom assembly. Click on the three dots (...) to edit the assembly rule.
4. In the Configure Assembly page, edit the custom-rule. The custom-rule is an example; in your environment, it would be different. Click on the three dots (...) to edit the rule.
5. In the Configure API rule page, add traceable-pre-gs-action API action as the last action and click on Apply.

Modify API rule

Navigate to Objects → Configuration Management → API Rule and click on traceable-assembly-global-rule to edit the rule.

Modify traceable-assembly-global-rule with the following API actions. custom-preflow-func-call is an example; it would be different in your environment.

default-api-route (Routing API action)	
custom-preflow-func-call (Function call assembly action)	
default-func-call-main (Function call assembly action)	
traceable-func-call-postflow(Function call assembly action)

Follow the same steps if you have post-processing custom rule to add traceable-post-gs-action as the last rule and modify traceable-assembly-global-rule to have custom-postflow-func-call. The custom-postflow-func-call is an example, it would be different in your environment.

Upgrade

To upgrade Traceable policies, follow the steps mentioned in the Import Policy section and reconfigure your Traceable Platform agent. When you import the policy, it would overwrite the existing policy.

Uninstall

To uninstall, remove the Traceable rules from your API collection. Furthermore, you can revert to an old configuration using the configuration checkpoint that you created earlier.