DataPower

Creating the XML Firewall

In this section you will learn how to quickly build a XML Firewall loopback echo service.

FYI, if you are not seeing the same Control Panel screen as shown in the diagrams below, it means you’re using the Blueprint WebUI. Please remove everything after the 9090 port (/dp/index.html) from the URL, and you will see the older DataPower WebUI interface.

1. Log into DataPower and navigate to an application domain you may create this service in. Once in the domain, select the XML Firewall icon from the main page.
   
   
2. Click on the Add Wizard.
   
   
3. Choose the Pass Thru (testing only) choice, and click Next.
   
   
4. Enter Utility_XMLF in the name field and click Next.
   
   
5. Select Loopback from the list of Firewall Types, and click Next.
   
   
6. Enter the port number which will not conflict with other services (go to the port status page to check whether the port you choose is being used). For this example, port 2088 will be used, and click Next.
   
   
7. The review page appears and click Commit.
   
   
8. On the confirmation page, click Done.
9. Using cUrl or Postman, post a message to the service:
   curl –data-binary “{“hello”:”world”}” http://<your_datapower_endpoint>:2088
   
   

Adding a Processing Rule to convert XML to JSON

In this section you will add a Processing Rule which allows a client to POST XML to the service with the URI /tojson to be able to convert XML-to-JSON or XML to PlainJSON.

1. Create a sub-directory on the local:/// directory to organize the artifacts for the Processing Policy by navigating to the File Management, then click on the Action > Create Subdirectory.
   
   
2. Create the directory Utility_XMLF and click Confirm Create.
   
   
3. Navigate back into the Utility_XMLF service and click on Edit button for the Processing Policy “Utility_XMLF”.
   
   
4. Click on New Rule and update the name to Utility_XMLF_rule_xml2json.
   
   
5. Configure the Match Action: 
   1. Double click on the Match Action to open it.
   2. Click on Add New icon to add a new matching rule.
   3. Name it tojson
   4. Click on Add to add a new Matching Type.
   5. Enter the following URL match: */tojson
   6. Click Apply and continue to apply until you get back to the Utility_XMLF Policy.
      
      
6. Locate the GatewayScript Action and drag it after the Match Action.
   
   
7. Double-click to open the GatewayScript Action and click on Upload… to upload the toJson.js script. Click Done afterwards.
   
   
8. Back in the Configure XML Firewall Style Policy, move the Utility_XMLF_rule_xml2json rule up to the top. Click Apply Policy afterwards.
   
   
   
   Click Close Window to close the Configure XML Firewall Style Policy window.
9. Back in the Configure XML Firewall window, find the Request Type, drop it down, and select Non-XML. Click Apply and Save Config.
   
   
10. To test the service, send the following cURL command to the /tojson endpoint with the following command:
    curl –data-binary “<xml>hello</xml>” http://<your_dataPower_URL>:2088/tojson
    
    
    
    

Summary: In this section you have learned how to add a Processing Policy, with another URI identifier on the same loopback echo service, where a client may invoke to POST and convert an XML body.

The echo endpoind still exist if you invoke http://<your_datapower_url>:2088, but now, by passing the /tojson uri, you have a XML-to-JSON function on the same XML Firewall service.

Note (Badgerfish): You’ll notice that the response will contain a “$” in the json (e.g. {“xml”:{“$”:”hello”}}). This is because the gatewayscript converter.toJSON() uses a conversation standard called Badgerfish. The format would account for attributes and namespace elements in XML nodes, if any.

More details about badgerfish may be found here: http://badgerfish.ning.com/

Details for the converter.toJSON DataPower function may be found here: https://www.ibm.com/support/knowledgecenter/SS9H2Y_7.7.0/com.ibm.dp.doc/json-xml-converter_js.html#converter.toJSON 

Optional

You may create another Processing Policy to accept Plain JSON (strips badgerfish from the converter.toXML datapower function) or import the toPlainJson.js script to step #7.

Be wary, the toPlainJson.js will not account for different namesapces and attributes.

For example, if you have the following:
<element name=”xyz”>hello</element>

The output from the toPlainJson (striped badgerfish) will output:

{
     “element”: “hello”
}

The output from the toJson.js (badgerfish) will output:

{
     “element”: {
          “@name”: “xyz”,
          “$”: “hello”
     }
}

You may use the same steps as shown in the this section, but here are the shortened instructions to create the new Processing Policy for a XML-to-Plain JSON Processing Rule:

1. Navigate back into the Utility_XMLF is not already there, and edit the Processing Policy: Utility_XMLF.
2. When the Configure XML Firewall Style Policy pops up, click on New RUle, and update the name to Utility_XMLF_rule_xml2plainjson.
   
   
3. Double-click on the Match Action and create a math rule titled toPlainJson with a URL match */toplainjson.
   
   
4. Drag and drop a GatewayScript Action and upload the toPlainJson.js into the Utility_XMLF directory.
   
   
5. Apply the policy, save the XML Firewall, and Save Configuration.
6. Test.

You will now notice by invoking http://<your_datapower_url>:2088/toplainjson you will not get badgerfish any more.

Analyzing the system log and probe

In this section we’ll take a look at the system log and probe to familiarize yourself where you may troubleshoot and debug.

1. Set Debug logging by navigating to the Troubleshooting > Logging section, and find the Set Log Level. Drop-down and select debug and click Set Log Level.
   
   
2. In the same Troubleshooting page, find and navigate into the Probe tab. Look under the XML Firewall section, drop-down to select the Utility_XMLF, and click Add Probe.
   
   
3. Click on the Probe magnifying glass icon for Utility_XMLF.
   
   
4. Run a transaction, and you will see the probe log it.
   If you click on the trans# (as shown in the diagram below transaction number 360161), you will see the syslogs for the transaction.
   If you click on the magnifying glass, you will see the step-by-step processing of the transaction through the service.
   
   
5. Click the trans# 360161 and you’ll see the debug logs for the particular transaction for the Utility_XMLF service.
   
   
6. Click on the magnifying glass, you will see the step-by-step process of the input payload, headers, and context variables from one action to another.
   As shown in the diagram, you will see the input from the client, the context variables from the transaction at each action step, and the post transformation from the GatewayScript Action.
   

Artifacts

1. toJson.js
2. toPlainJson.js
3. Export of the Utility_XMLF.zip (NOTICE: the port used is 2088, therefore please adjust accordingly if imported)