Copyright © Cloud Software Group, Inc. All Rights Reserved

Parsing Step

The parse step is an optional preprocessing of the facade request used for both content validation and for identifying and normalizing control data. Using the parse step you can enhance the downstream processing by setting or overwriting predefined parameters that are derived either from the request message content or the request transport context. The parsing of the request is done using an XSLT- based transformation file configured in the New ProcessBody Transform or ProcessBody Transform field on the ROUTING > Facade Operations tab of the Config UI.

The transformation (XSLT) file defined in the parsing step is used for the following purposes:

•	Setting a partner identity for the requester that is derived from the payload content or transport context of the request

•	Setting a routing key that is used to identify the route for the request to the appropriate target operation endpoint

•	Enriching the transaction audit trail logging information of the request

•	Validating the request content with the ability to set an error code and error message when a request doesn't pass the content validation rules

•	Setting a metric increment for content-based throttles

•	Setting sticky key for load-balancing with StickyResourceAffinity routing algorithm type.

Set the Partner Identity for Request

TIBCO API Exchange Gateway supports multiple identity types for identification of the requester. These identities use different protocol standards to support either transport level identification or request-based identification. In addition to the standards-based protocols, TIBCO API Exchange Gateway also provides a way to derive custom identities from either the payload message of the request or the transport context of the request.

The XSLT transformation file in the parse step can be used to populate the partner identity for the request. If the partner identity is set by the parse XSLT file, it will override any other standards-based identity associated with the request.

When a standards-based identity is associated with the request which gets overridden by the parse XSLT, the original partner identity is stored as a row in the ASG_TRANSACTION_KEYS table that is associated with the audit trail log record of the request in the ASG_TRANSACTIONS table. The override log records or such credential mapping records are stored with a value of incomingPartner for the key_type column.

Set the Routing Key for Request

For a single facade operation, multiple routes can be configured. Each of the routing configurations map a facade operation to a different target operation or target group. When multiple routes are configured for a facade operation, the request processing requires to derive a routing key for that request to determine which of the configured routes should process the request.When the routing key should be dynamically derived from the request payload message or the request transport context, the parse step XSLT can be used to set the routing key for the request. See Routing.

Enrich the Audit Trail Log for Request

You can extract data from the request payload message or the request transport context and use it to enrich the audit trail logging data that is stored in the Central Logger database. The parse step XSLT transformation supports the following elements in its output document to support this function:

•	Reference Id

referenceId is a specific element that is used to store an external transaction ID or reference key for the request. Any value mapped into the referenceId element of the output document generated by the parse step XSLT transformation is stored in the TRN_TRANSACTION_ID column of the ASG_TRANSACTIONS table in the Central Logger database.

•

Key

key is a repeatable element in the output document of the parse step XSLT transformation that can be used in a more generic fashion. It is typically used to store business keys extracted from the received request. Each populated key element is stored as a separate row in the ASG_TRANSACTION_KEYS table and includes a foreign key to the associated row in the main ASG_TRANSACTIONS table of the Central Logger database. The value of the key element is stored in the KEY_VALUE column.

The key element provides the following attributes:

−

@type

−

@log

@type attribute

When you set a @type attribute for the key element, the @type attribute is stored in the KEY_TYPE column in the ASG_TRANSACTION_KEYS table.

By using the @type attribute for the key element, users can search for specific audit trial logging records in the Central Logger database through the business keys from the request message. This also provides the flexibility to enrich the standard audit trail logging data with any key, value pair based contextual information without the need for customization of TIBCO API Exchange Gateway itself.

@log attribute

If you do not want to store the parameters in the Central Logger database, you can use the @log attribute of the key element. The @log attribute is a boolean attribute and its value determines whether this key should be stored in the Central Logger database or not. When there is no @log attribute set for key elements, a default value of true is set for the key elements and the key elements are stored as rows in the ASG_TRANSACTION_KEYS table of the Central Logger database. If you do not want to store the key elements in the database, set the @log attribute to false.

Log Request Headers

The BookQueryBE example ships the sample XSLT file to parse the request for queryBookByAuthor facade operation and store the header values into the database.

To store the header values using the parse_headers.xsl,follow these steps:

1.	Stop the Config UI server, if running.

2.	Navigate to the ASG_CONFIG_HOME/BookQueryBE/xslt directory.

3.	Copy the parse_headers.xsl file to ASG_CONFIG_HOME/BookQueryBE/xslt/operations directory.

4.	Start the Config UI server.

5.	Login to the Config UI using your credentials.

6.	Click BookQueryBE project.

7.	Select ROUTING > Facade Operations tab.

8.	Select queryBookByAuthor operation.

9.	Select operations/parse_headers.xsl from the drop-down list in the ProcessBody Transform field.

10.	Save changes to the configuration.

Sample XSLT

Refer to the following sample XSLT to store the headers of the request message:

---

 

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:f="http://www.tibco.com/asg/content-types/form"

xmlns:c="http://www.tibco.com/schemas/asg/context"

xmlns:h="http://www.tibco.com/asg/protocols/http"

xmlns:form="http://www.tibco.com/asg/functions/form" exclude-result-prefixes="xsl h c f form">

<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes" omit-xml-declaration="no"/>

 

<xsl:variable name="context">

<xsl:for-each select="/transformation/context">

   <xsl:copy-of select="document(@href)"/>

</xsl:for-each>

</xsl:variable>

 

<xsl:variable name="httpRequest">

<xsl:copy-of select="$context/c:context/c:entry[@key='asg:httpRequest']/h:request"/>

</xsl:variable>

 

   <xsl:variable name="request-uri">

   <xsl:copy-of select="$httpRequest/h:request/h:request-uri"/>

   </xsl:variable>

 

   <xsl:template match="/">

   <output>

 

   <key type="requestURI" log="true">

     <xsl:copy-of select="normalize-space($request-uri)"/>

   </key>

 

 

   <key type="clientIP" log="true">

   <xsl:choose>

   <xsl:when    test="$httpRequest/h:request/h:header[lower-case(@name)='x-forw   arded-for']">

   <xsl:value-of    select="$httpRequest/h:request/h:header[lower-case(@name)='x-fo   rwarded-for']"/>

   </xsl:when>

   <xsl:otherwise>

     <xsl:value-of select="$httpRequest/h:request/h:client-ip"/>

   </xsl:otherwise>

   </xsl:choose>

   </key>

   <xsl:for-each select="$httpRequest/h:request/h:header">

   <xsl:variable name="hdr_name" select="@name"/>

   <xsl:if test="lower-case($hdr_name)='host'">

     <key type="host" log="true">

     <xsl:value-of select="."/>

     </key>

   </xsl:if>

 

   <xsl:if test="lower-case($hdr_name)='apikey'">

     <key type="apikey" log="true">

     <xsl:value-of select="."/>

     </key>

   </xsl:if>

 

   <xsl:if test="lower-case($hdr_name)='referer'">

     <key type="referer" log="true">

     <xsl:value-of select="."/>

     </key>

   </xsl:if>

 

   <xsl:if test="lower-case($hdr_name)='user-agent'">

     <key type="useragent" log="true">

     <xsl:value-of select="."/>

     </key>

   </xsl:if>

</xsl:for-each>

 

   </output>

   </xsl:template>

   </xsl:stylesheet>

---

 

.

You can use the key elements populated by the parse step XSLT transformation to pass parameters to custom policies, which can be developed leveraging the custom extension mechanism. The SampleStage custom extension in the ASGDefaultImplementation project uses the key elements.

Validate the Request Content

You can use XPath expressions in the parse step XSLT transformation. Using the XPath expressions, you can apply content validation logic to the request payload message. When the request fails a validation check, an appropriate error code and associated error message can be set in the parse step XSLT transformation.

If the parse step XSLT transformation returns an error code, the transaction is terminated and an error response is generated and returned to the client. This functionality allows users to create parse XSLT to return the error codes and descriptions that are expected by the API of which it is a part. Then if an error XSLT is configured for the operation it is called, and any API-specific error document can be created.

Set Metric Increment for Content-Based Throttles

TIBCO API Exchange Gateway supports the notion of content-based throttles, by extending a throttle configuration with a monitor. You can define a content-based metric increment counter using the throttle configuration.

Using the content-based throttles, you can define custom throttle policies. The custom throttle policies enforce the API usage controls on business metric such as order amounts. When a throttle configuration has been extended with a monitor definition, it uses the parse step XSLT transformation at run time. The parse step XSLT transformation maps the business metric containing element from the request payload message to a throttle monitor specific element in the output document generated by the parse step XSLT transformation.

To support the content-based throttle extension mechanism for multiple throttle definitions on a request's throttle chain, the monitor element is defined as a repeatable element in the output document of the parse step XSLT transformation. The monitor element itself is a node element that contains two elements which need to be defined when setting the content-based throttle metric increment. The first element of the monitor node element is the metric name element that must contain the throttle name to which the content-based metric counter increment must be applied. The second element of the monitor node element is the metric increment that contains the actual counter increment that has been derived from the request message payload and needs to be applied to the throttle.

For more information on how to configure and use content-based throttles, see Content Based Throttles section.

Set Sticky Key for Load-Balancing with StickyResourceAffinity

TIBCO API Exchange Gateway supports multiple load-balancing policy types for target operations that are grouped within a target group. When a load-balancing policy with StickyResourceAffinity is configured for a target group, a parse step XSLT transformation is used to derive the sticky key from the request payload message or request transport context. The output document as generated by the parse step XSLT transformation contains a stickyRoutingKey element that needs to be set to associate a sticky routing key to the request for further processing.

For more information on how to configure and use load-balancing policies for target groups with StickyResourceAffinity, see StickyResourceAffinity Target Operation Group Configuration.

Copyright © Cloud Software Group, Inc. All Rights Reserved