Transitioning Conditional Error Processing Policy from webMethods Gateway to API Manager

Introduction

IBM API Connect v12 is a unified product that includes both webMethods Gateway and API Manager components. When transitioning from webMethods-managed assets to API Manager-managed assets, one of the critical aspects is understanding how your existing policies transform into the API Manager's API Studio format. This blog post focuses on the Conditional Error Processing policy, a powerful feature for customizing error responses based on specific conditions.

The APIC Transition Helper automates this transformation, converting webMethods Gateway's Conditional Error Processing policy into API Manager's ErrorProcessing custom resource format, which is used by API Studio. Let's explore how this transformation works and what you need to know.

Understanding Conditional Error Processing

What is Conditional Error Processing?

Conditional Error Processing allows you to:

• Customize error responses based on runtime conditions
• Transform error payloads into different formats (JSON, XML, plain text)
• Modify HTTP status codes and headers in error scenarios
• Execute pre/post-processing logic using webMethods IS services or XSLT transformations
• Control error message content based on content-type negotiation

This policy is essential for providing consistent, user-friendly error responses across your API ecosystem.

Transformation Architecture

From webMethods-Managed to API Manager-Managed Assets

The transformation process converts webMethods Gateway's conditionalErrorProcessing policy action into API Manager's ErrorProcessing custom resource (API Studio format). Here's the high-level mapping:

Key Components Transformed

1. Condition Logic: Boolean expressions that determine when the policy executes
2. Transformations: Header modifications, status code changes, custom variables, and payload templates
3. Pre/Post Processing: webMethods IS service invocations and XSLT transformations
4. Metadata: XML namespaces for XPath operations

Detailed Transformation Examples

1. Condition Transformation

webMethods Gateway Format:

{
  "templateKey": "transformationConditions",
  "parameters": [{
    "templateKey": "logicalConnector",
    "values": ["OR"]
  }, {
    "templateKey": "transformationCondition",
    "parameters": [{
      "templateKey": "transformationVariable",
      "values": ["${response.statusCode}"]
    }, {
      "templateKey": "transformationConditionOperator",
      "values": ["equals"]
    }, {
      "templateKey": "transformationConditionValue",
      "values": ["200"]
    }]
  }]
}

API Manager (API Studio) Format:

spec:
  enabled: true
  condition: "${response.statusCode} equals 200"

The transformation engine converts complex nested parameter structures into a simple, readable condition string.

2. Error Response Customization

One of the most powerful features is customizing error messages based on content type. You can define multiple failure messages for different content types (JSON, XML, TEXT) and specify a default:

webMethods Gateway Format:

{
  "templateKey": "customFailureMessages",
  "parameters": [{
    "templateKey": "sendNativeProviderFault",
    "values": ["true"]
  }, {
    "templateKey": "failureMessage",
    "parameters": [{
      "templateKey": "contentType",
      "values": ["json"]
    }, {
      "templateKey": "errortemplate",
      "values": ["{\"status\": \"error\", \"message\": \"Custom JSON error\"}"]
    }, {
      "templateKey": "useAsDefault",
      "values": ["false"]
    }]
  }, {
    "templateKey": "failureMessage",
    "parameters": [{
      "templateKey": "contentType",
      "values": ["xml"]
    }, {
      "templateKey": "errortemplate",
      "values": ["<?xml version=\"1.0\"?><error><status>error</status><message>Custom XML error</message></error>"]
    }, {
      "templateKey": "useAsDefault",
      "values": ["true"]
    }]
  }, {
    "templateKey": "failureMessage",
    "parameters": [{
      "templateKey": "contentType",
      "values": ["text"]
    }, {
      "templateKey": "errortemplate",
      "values": ["Error: Custom text error message"]
    }, {
      "templateKey": "useAsDefault",
      "values": ["false"]
    }]
  }]
}

API Manager (API Studio) Format:

spec:
  transformations:
    setPayload:
      content-types:
      - application/json: '{"status": "error", "message": "Custom JSON error"}'
      - application/xml: '<?xml version="1.0"?><error><status>error</status><message>Custom XML error</message></error>'
      - text/plain: 'Error: Custom text error message'
      defaultContentType: "application/xml"
    sendNativeError: true

Content Type Mapping:

• JSON → application/json
• XML → application/xml
• TEXT → text/plain

Key Features:

• Multiple formats: Define error templates for JSON, XML, and plain text
• Default selection: Use useAsDefault: true to specify which format is returned when no Accept header matches
• Native error forwarding: sendNativeProviderFault: true becomes sendNativeError: true

3. Header and Status Code Transformations

webMethods Gateway Format:

{
  "templateKey": "restHeaderTransformation",
  "parameters": [{
    "templateKey": "remove",
    "values": ["${response.headers.Content-Type}", "${response.headers.Content-Length}"]
  }, {
    "templateKey": "addOrModify",
    "parameters": [{
      "templateKey": "transformationVariable",
      "values": ["${response.headers.X-Custom-Header}"]
    }, {
      "templateKey": "transformationValue",
      "values": ["CustomValue"]
    }]
  }]
}

API Manager (API Studio) Format:

spec:
  transformations:
    set:
    - key: "${response.headers.X-Custom-Header}"
      value: "CustomValue"
    remove:
    - "${response.headers.Content-Type}"
    - "${response.headers.Content-Length}"

Status Code Transformation:

spec:
  transformations:
    set:
    - key: "${response.statusCode}"
      value: "200"
    - key: "${response.statusMessage}"
      value: "Success"

4. Pre/Post Processing with webMethods IS Services

The transformation handles complex pre and post-processing workflows:

webMethods Gateway Format:

{
  "templateKey": "preProcessingSteps",
  "parameters": [{
    "templateKey": "invokeESBParam",
    "parameters": [{
      "templateKey": "invokeISService",
      "parameters": [{
        "templateKey": "serviceName",
        "values": ["pub.flow:debugLog"]
      }, {
        "templateKey": "runAsUser",
        "values": ["Administrator"]
      }, {
        "templateKey": "complyToISSpec",
        "values": ["true"]
      }]
    }]
  }]
}

API Manager (API Studio) Format:

The ErrorProcessing policy references the WebMethodsISService custom resource:

spec:
  pre-processing:
    webMethodsISService:
    - $ref: "namespace:WebmISService-84ee78:1.0.0"

A separate WebMethodsISService custom resource is created:

---
kind: "WebMethodsISService"
apiVersion: "api.ibm.com/v2"
metadata:
  name: "WebmISService-84ee78"
  namespace: "test-namespace"
  version: "1.0.0"
  labels:
    gatewayTypes:
    - "webMethods"
    catalog_during_migration: "586e3b09-41d1-490e-b530-781835001131"
spec:
  enabled: true
  alias:
  - "webMethodsISServiceCustomUser"
  - "DebugAlias"
  services:
  - complyToISSpec: true
    name: "pub.flow:debugLog"
    runAs: "Administrator"

The transformation:

1. Extracts each IS service invocation from the webMethods Gateway policy
2. Creates a separate WebMethodsISService custom resource (kind: WebMethodsISService, apiVersion: api.ibm.com/v2)
3. Generates a unique name (e.g., WebmISService-84ee78)
4. Maps service details including:
   • Service name (e.g., pub.flow:debugLog)
   • Run-as user (e.g., Administrator)
   • Compliance flag (complyToISSpec)
5. Maps alias references from esbAlias parameter to the alias array (if configured)
6. References the custom resource in the ErrorProcessing policy

Alias Support: If the webMethods Gateway policy includes esbAlias values, they are mapped to the alias array in the WebMethodsISService spec. These aliases reference configured webMethods IS connection aliases.

Important: The actual IS services must remain available in webMethods Gateway and Integration Server. The WebMethodsISService custom resource only contains references to these services (service names, execution parameters, and alias references), not the service implementations themselves.

5. XSLT Transformations

For XSLT-based transformations, the converter supports both embedded XSLT documents and XSLT alias references:

Option 1: XSLT Document (Embedded Content)

webMethods Gateway Format:

{
  "templateKey": "xsltTransformation",
  "parameters": [{
    "templateKey": "xsltDocument",
    "parameters": [{
      "templateKey": "document",
      "values": ["<base64-encoded-xslt-content>"],
      "extendedProperties": [{
        "key": "document",
        "value": "test.xsl"
      }]
    }, {
      "templateKey": "feature",
      "parameters": [{
        "templateKey": "featureName",
        "values": ["http://javax.xml.XMLConstants/feature/secure-processing"]
      }, {
        "templateKey": "featureValue",
        "values": ["true"]
      }]
    }]
  }]
}

API Manager (API Studio) Format:

spec:
  pre-processing:
    xsl:
    - $path: "./namespace-policyname-version-pre-0-test.xsl"
      feature:
      - name: "http://javax.xml.XMLConstants/feature/secure-processing"
        value: "true"

Option 2: XSLT Alias (Reference to Configured Alias)

webMethods Gateway Format:

{
  "templateKey": "xsltTransformation",
  "parameters": [{
    "templateKey": "xsltAliasSelector",
    "parameters": [{
      "templateKey": "xsltAlias",
      "values": ["MyXSLTAlias"]
    }, {
      "templateKey": "feature",
      "parameters": [{
        "templateKey": "featureName",
        "values": ["http://javax.xml.XMLConstants/feature/secure-processing"]
      }, {
        "templateKey": "featureValue",
        "values": ["false"]
      }]
    }]
  }]
}

API Manager (API Studio) Format:

spec:
  pre-processing:
    xsl:
    - alias: "MyXSLTAlias"
      feature:
      - name: "http://javax.xml.XMLConstants/feature/secure-processing"
        value: "false"

Combined Example (Document + Alias):

spec:
  pre-processing:
    xsl:
    - $path: "./xslttransformtest.xsl"
      feature:
      - name: "http://javax.xml.XMLConstants/feature/secure-processing"
        value: "true"
    - alias: "MyXSLTAlias"
      feature: []

The transformation:

1. For xsltDocument: Extracts XSLT content from base64-encoded document, creates a separate .xsl file with unique name, uses $path property
2. For xsltAliasSelector: Maps the alias name to alias property (not $path)
3. Maps XSLT features as name-value pairs in the feature array for both options
4. Supports mixed usage: Can have both document-based and alias-based XSLT transformations in the same policy
5. Includes the .xsl file in attached files (for xsltDocument only)

XSLT Features: The converter preserves XSLT processor features like secure processing and DOM transformation settings for both document and alias-based transformations.

XSLT Alias: When using xsltAliasSelector, the alias property references a pre-configured XSLT transformation alias in webMethods Gateway. The alias itself must be configured separately.

6. Custom Variables

webMethods Gateway Format:

{
  "templateKey": "customVariables",
  "parameters": [{
    "templateKey": "customVariable",
    "parameters": [{
      "templateKey": "variable",
      "values": ["CustomVar1"]
    }, {
      "templateKey": "value",
      "values": ["CustomValue1"]
    }]
  }]
}

API Manager (API Studio) Format:

spec:
  transformations:
    set:
    - key: "CustomVar1"
      value: "CustomValue1"

7. XML Namespace Handling

For XPath operations in transformations:

webMethods Gateway Format:

{
  "templateKey": "transformationMetadata",
  "parameters": [{
    "templateKey": "namespace",
    "parameters": [{
      "templateKey": "prefix",
      "values": ["cust"]
    }, {
      "templateKey": "uri",
      "values": ["http://example.com/policy/custom"]
    }]
  }]
}

API Manager (API Studio) Format:

spec:
  transformations:
    namespaces:
    - URI: "http://example.com/policy/custom"
      prefix: "cust"

Complete Transformation Example

Let's see a complete example with all features:

webMethods Gateway Policy (Simplified)

{
  "templateKey": "conditionalErrorProcessing",
  "parameters": [
    {
      "templateKey": "transformationConditions",
      "parameters": [/* condition logic */]
    },
    {
      "templateKey": "errorTransformationConfiguration",
      "parameters": [/* transformations */]
    },
    {
      "templateKey": "preProcessingSteps",
      "parameters": [/* pre-processing */]
    },
    {
      "templateKey": "postProcessingSteps",
      "parameters": [/* post-processing */]
    }
  ]
}

API Manager ErrorProcessing Resource (API Studio Format)

---
kind: "ErrorProcessing"
apiVersion: "api.ibm.com/v1"
metadata:
  name: "error-handler"
  namespace: "my-namespace"
  version: "1.0.0"
  labels:
    gatewayTypes:
    - "webMethods"
    id: "c2e4eb60-937a-426a-b523-56f79fc29976"
    catalog_during_migration: "586e3b09-41d1-490e-b530-781835001131"
spec:
  enabled: true
  condition: "${response.statusCode} equals 500"
  pre-processing:
    webMethodsISService:
    - $ref: "my-namespace:WebmISService-84ee78:1.0.0"
    xsl: []
  transformations:
    set:
    - key: "${response.statusCode}"
      value: "200"
    - key: "${response.statusMessage}"
      value: "Success"
    - key: "${response.headers.X-Error-Handled}"
      value: "true"
    remove:
    - "${response.headers.X-Internal-Error}"
    setPayload:
      content-types:
      - application/json: '{"status": "success", "message": "Request processed"}'
      - application/xml: '<?xml version="1.0"?><response><status>success</status></response>'
      defaultContentType: "application/json"
    namespaces:
    - URI: "http://example.com/policy/custom"
      prefix: "cust"
    sendNativeError: false
  post-processing:
    webMethodsISService:
    - $ref: "my-namespace:WebmISService-0a94a0:1.0.0"
    xsl: []

Key Transformation Features

1. Unique Naming Strategy

The converter generates unique names for dependent resources:

• IS Services: WebmISService-<6-char-uuid>
• XSLT Files: <namespace>-<policyname>-<version>-<pre|post>-<counter>.xsl

This prevents naming conflicts during migration.

2. Reference Management

All dependent resources are properly referenced:

$ref: "namespace:resource-name:version"

3. Metadata Preservation

Original webMethods Gateway metadata is preserved:

labels:
  gatewayTypes:
  - "webMethods"
  id: "original-gateway-id"
  catalog_during_migration: "migration-catalog-id"

4. Content Type Normalization

Content types are automatically normalized to MIME types:

• Gateway format: JSON, XML, TEXT
• APIC format: application/json, application/xml, text/plain

Best Practices for Migration

1. Review Conditions

• Verify condition logic translates correctly
• Test with various runtime scenarios
• Ensure variable references are valid in APIC

2. Validate Transformations

• Check header modifications work as expected
• Test status code transformations
• Verify custom variable assignments

3. Test Pre/Post Processing

• Ensure IS services remain available in webMethods Gateway and Integration Server
• Verify WebMethodsISService custom resources correctly reference the IS services
• Validate XSLT transformations produce expected output
• Test execution order of multiple processing steps

4. Content Type Handling

• Verify default content type is appropriate
• Test content negotiation with different Accept headers
• Ensure error templates are valid for each content type

5. Namespace Configuration

• Confirm XML namespaces are correctly defined
• Test XPath expressions with namespace prefixes
• Validate namespace URIs are accessible

Conclusion

The APIC Transition Helper's Conditional Error Processing converter provides a robust, automated transformation from webMethods-managed assets to API Manager-managed assets within IBM API Connect v12. By understanding this transformation process, you can:

• Plan your transition strategy effectively
• Validate transformed policies in API Studio before deployment
• Optimize error handling in your API Manager environment

The transformation maintains the full functionality of your error processing logic while adapting it to API Manager's architecture and API Studio format.

Next Steps

1. Review your existing Conditional Error Processing policies in webMethods Gateway
2. Run the APIC Transition Helper to generate transformed policies in API Studio format
3. Validate the generated ErrorProcessing CRs and dependent resources in API Manager
4. Test in a non-production API Connect environment
5. Deploy to production after successful validation

About the APIC Transition Helper: A tool designed to automate the transition of assets from webMethods-managed to API Manager-managed format within IBM API Connect v12, generating assets in API Studio format.

Resources:

• Gateway Management Plane Transition - IBM API Connect Documentation