SOAP Service Attribution Resolver

Overview

The SoapServiceAttributionResolver is a component responsible for identifying the correct service for incoming SOAP requests when the request URL is insufficient for attribution. This is common in architectures where a content-based router (such as IBM DataPower) fronts multiple backend services. In such cases, clients send requests to a single generic endpoint (e.g., POST /), and the router dispatches the request based on the SOAP message content.

This component solves the problem of "unattributable" traffic that would otherwise appear to have a junk URI (/), making it impossible to monitor the health and usage of the underlying services. It provides a mechanism to look past the request URL and use the SOAP identity—specifically the SOAPAction header or the SOAP body's root element—to resolve the canonical service URI.

The resolver is called for traffic with an unusable service URI. Its inputs are the SOAPAction header and the request body payload. Its output is either the canonical service URI for the identified service or null if the service cannot be determined. A null result indicates that the traffic should remain unattributed, ensuring that data is not corrupted by incorrect guesses.

How it works

The resolver operates in two main phases: building an in-memory catalog from WSDL definitions and using that catalog to resolve service URIs for incoming requests.

Catalog Generation

The resolver maintains an in-memory catalog that maps SOAP identifiers to canonical service URIs. This catalog is refreshed from the database periodically.

1. Data Source: The catalog is built by querying the s2r_wsdl_artifact and s2r_wsdl_operation_catalog database tables. These tables contain information imported from the WSDLs of discovered services.

2. Reloading: The catalog is reloaded from the database every 10 minutes (RELOAD_INTERVAL_MS). This process is synchronized to prevent race conditions. If a reload fails, the resolver logs a warning and continues to use the existing (potentially stale) catalog to avoid interrupting traffic processing.

3. Mapping Creation: During a load, the following SQL query is executed to fetch the necessary data:

   select a.target_namespace, a.source_name, o.operation_name, o.soap_action
   from s2r_wsdl_artifact a
   join s2r_wsdl_operation_catalog o on o.artifact_id = a.id
   where coalesce(a.source_name, '') <> ''
   

   For each row returned:

   • The WSDL's source_name (its URL) is converted into a canonical service URI using the ServiceUriCanonicalizer.
   • Three types of mappings are created:
     1. SOAPAction header value to service URI.
     2. A composite key of {namespace}|{operation} to service URI.
     3. The lowercase operation name alone to service URI, as a fallback.

4. Ambiguity Resolution: A key principle of the resolver is to refuse ambiguity. If two different WSDLs map the same identifier (e.g., the same SOAPAction) to two different canonical service URIs, that identifier is considered ambiguous. The resolver removes the key from the catalog entirely. This ensures that traffic is never mis-attributed, even at the cost of leaving some traffic unattributed.

Resolution Logic

When the resolveServiceUri method is called, it attempts to find a matching service URI using a specific order of precedence.

The following diagram illustrates the resolution flow:

flowchart TD
    A[Start Resolution] --> B{Is `soapAction` available?};
    B -- Yes --> C["Normalize `soapAction` (unquote, lowercase)"];
    C --> D["Lookup normalized `soapAction` in catalog"];
    D -- Match found --> Z([Return Service URI]);
    D -- No match --> E;

    B -- No --> E["Parse `requestPayload` for SOAP Body Identity <br/>(namespace and operation name)"];
    E --> F{Is identity found?};
    F -- No --> Y([Return null]);

    F -- Yes --> G["Lookup `{namespace}|{operation}` in catalog"];
    G -- Match found --> Z;
    G -- No match --> H["Lookup lowercase operation name in catalog"];
    H -- Match found --> Z;
    H -- No match --> Y;

The step-by-step process is:

1. Check the provided soapAction string. If it's present, it is normalized (trimmed, unquoted, and converted to lowercase) and used to look up a service URI in the bySoapAction map. If a match is found, the URI is returned.
2. If no match is found by SOAPAction, the requestPayload is parsed to extract the SOAP body's root element namespace and local name (SoapBodyIdentity).
3. If a SOAP body identity is successfully parsed, a composite key of {namespace}|{operation} is created and looked up in the byNamespaceAndOperation map. If a match is found, the URI is returned.
4. If the qualified name does not yield a match, the resolver attempts a final lookup using only the lowercase operation name (localName) in the byOperationName map.
5. If no match is found through any of these methods, the method returns null.

API Reference

The SoapServiceAttributionResolver component exposes the following public methods.

resolveServiceUri

Resolves the canonical service URI for an event based on its SOAP identity.

String resolveServiceUri(String soapAction, String requestPayload)

Parameters

Returns

A String containing the canonical service URI (e.g., /App/services/Thing) if a unique service can be identified. Returns null if the identity information is absent, the identifier is not found in the catalog, or the identifier is ambiguous. A null return signifies that the traffic should remain unattributed.

isUnusableServiceUri

A static utility method to check if a given service URI is considered unusable for attribution.

public static boolean isUnusableServiceUri(String serviceUri)

Parameters

Returns

Returns true if the serviceUri is null, empty, or exactly /. Otherwise, returns false.

Configuration

The component's behavior is controlled by an internal constant.

Troubleshooting

Attribution Fails for All SOAP Traffic

If resolveServiceUri consistently returns null, verify that the upstream traffic capture system is configured to log and forward the SOAPAction header and/or the request body. The resolver cannot function without this data.

Catalog Reload Failures

If the resolver fails to reload its catalog from the database, it logs a warning and continues to use the last known-good snapshot.

• Log Message: SOAP attribution catalog reload failed, keeping previous snapshot: [exception details]
• Impact: Attribution will continue based on potentially stale data. New services or changes to existing WSDLs will not be reflected until a reload succeeds. This is a "fail-open" design to prevent data ingest from halting due to a database issue.

Some Traffic Remains Unattributed

If some, but not all, SOAP traffic remains unattributed, it may be due to the ambiguity resolution logic. If an identifier like a SOAPAction or operation name is mapped to multiple, distinct service URIs in the WSDL catalog, the resolver intentionally drops that mapping. This is by design to prevent mis-attribution. The log message printed after a successful catalog reload shows the final counts of keys in each map, which can be used to diagnose if the catalog is smaller than expected.

See Also

• ServiceUriCanonicalizer: The component used to derive a canonical service URI from a WSDL's source_name URL.
• Database Tables: The source of truth for the catalog is stored in s2r_wsdl_artifact and s2r_wsdl_operation_catalog.
• Design Documentation: For further background on the gateway configuration requirements, see the internal design document at docs/rfc/datapower-routed-traffic-attribution.md.

All SOAP-to-REST docs