Enricher

Introduction

Enricher is a component that can be used for calling web services and returning their response or a part of it. This JSON can be returned as it is or "enriched" into another JSON. It is built into Automation Engine AKA Audit, but can also be used as a separate component in another systems.

Web service requirements

In order to be called by enricher the web service should match the following requirements:

• HTTP Web service
• Should return JSON as a response in the HTTP response Body
• Should accept the parameters if any in the following way:
  • GET
    • URL parameters specified as a query argument i.e. /api/resource?parameter=value
    • URL parameters specified as a part of the URL path i.e. /api/resource/parametervalue
  • POST - should support a JSON request body e.g.

{
    "parameter": "value"
}

it is not recommended by RESTful specifications to use POST for data retrieval, but it can be done in some circumstances

• The web service should be protected in one of the following way:
  • with a static Bearer token that should be passed in "Authorization" Header of the request
  • with a Bearer token that should be retrieved from an authorization service using OAuth 2.0 authorization protocol. In this case Authorization Server Url, CertificateThumbprint, ClientId and Required Scopes must be specified
  • with a Bearer token that should be retrieved from an authorization service using OAuth 2.0 authorization protocol. In this case Authorization Server Url, ClientId, ClientSecret and Required Scopes must be specified.

Configuration in Automation Engine

When Enricher is used within Automation Engine (Audit), the configuration is entered in the Enricher configuration field of the Reporting System Parameters screen. The configuration is a JSON object with a top-level name identifier and an invokers array. Each entry in invokers represents one external service call.

{
  "name": "JsonEnricher",
  "invokers": [
    {
      "name": "enricher-policy-info",
      "type": "http",
      "url": "https://url-to-call.com/service",
      "httpMethod": "GET",
      "authorizationServerUrl": "https://login.microsoftonline.com/",
      "oAuth2ClientId": "clientId123",
      "oAuth2ClientSecret": "secretsecret",
      "requiredScopes": [
        "micro_scope"
      ],
      "input": {
        "parameters": [
          {
            "name": "claimNumber",
            "type": "selector",
            "value": "$.payload.claim.number"
          }
        ]
      },
      "output": {
        "resultSelector": "",
        "injectAs": "$.policyInfo"
      }
    }
  ]
}

Multiple invokers can be defined in the array — each one will be called independently and its result injected into the payload at the path specified by output.injectAs.

Examples

The examples below show individual invoker configurations. Each object belongs inside the invokers array of the top-level Enricher configuration shown above.

HTTP GET with static token authorization

{
  "name": "weather",
  "type": "http",
  "url": "https://weather.nu/external_api",
  "httpMethod": "GET",
  "bearerToken": "b09e2254-6ade-4e44-9c98-25eefed5599a",
  "input": {
    "parameters": [
      {
        "name": "country",
        "type": "selector",
        "value": "$.address.country"
      },
      {
        "name": "date",
        "type": "selector",
        "value": "$.date"
      }
    ]
  },
  "output": {
    "resultSelector": "",
    "injectAs": "$.weather"
  }
}

HTTP GET with OAuth 2.0 authorization using Authorization server and certificate

{
  "name": "weather",
  "type": "http",
  "url": "https://weather.nu/external_api",
  "httpMethod": "GET",
  "authorizationServerUrl": "https://oauth.weather.nu",
  "oAuth2CertificateThumbprint": "1d4b45e90df21fce012c9a804a5b7c166326c6cf",
  "oAuth2ClientId": "some_id",
  "requiredScopes": [
    "weather:read"
  ],
  "input": {
    "parameters": [
      {
        "name": "country",
        "type": "selector",
        "value": "$.address.country"
      },
      {
        "name": "date",
        "type": "selector",
        "value": "$.date"
      }
    ]
  },
  "output": {
    "resultSelector": "",
    "injectAs": "$.weather"
  }
}

HTTP GET with OAuth 2.0 authorization using Authorization server and client credentials flow

{
  "name": "weather",
  "type": "http",
  "url": "https://weather.nu/external_api",
  "httpMethod": "GET",
  "authorizationServerUrl": "https://oauth.weather.nu",
  "oAuth2ClientId": "weather-client",
  "oAuth2ClientSecret": "RAcmIxj0Tsn3_-GZjp6OomL-xRxoae9kZHvx81zLNj8",
  "requiredScopes": [
    "weather:read"
  ],
  "input": {
    "parameters": [
      {
        "name": "country",
        "type": "selector",
        "value": "$.address.country"
      },
      {
        "name": "date",
        "type": "selector",
        "value": "$.date"
      }
    ]
  },
  "output": {
    "resultSelector": "",
    "injectAs": "$.weather"
  }
}

Conditional invocation

An invoker can be configured to skip execution when a specific condition is not met. This is useful in cases where, for example, an external service call should not be made for a particular claim type.

To enable this, add an invocationCondition property to the invoker configuration. The condition is evaluated against the payload sent to the Enricher. If it evaluates to false, the invoker is skipped.

Important: The condition value must be a string (not a JSON object), and object keys must be wrapped in single quotes (').

The following example shows an invoker that is called only when the claim type is not GLA (glass) and PaintOrderTime is less than 78:

{
  "name": "weather",
  "type": "http",
  "url": "https://weather.nu/external_api",
  "httpMethod": "GET",
  "authorizationServerUrl": "https://oauth.weather.nu",
  "oAuth2ClientId": "weather-client",
  "oAuth2ClientSecret": "RAcmIxj0Tsn3_-GZjp6OomL-xRxoae9kZHvx81zLNj8",
  "requiredScopes": [
    "weather:read"
  ],
  "invocationCondition": "{'and': [{'!=': ['$.ClaimData.EventType', 'GLA']}, {'<': ['$.Estimate.PaintOrderTime', 78]}]}",
  "input": {
    "parameters": [
      {
        "name": "country",
        "type": "selector",
        "value": "$.address.country"
      },
      {
        "name": "date",
        "type": "selector",
        "value": "$.date"
      }
    ]
  },
  "output": {
    "resultSelector": "",
    "injectAs": "$.weather"
  }
}

Condition structure

Each condition is composed of an operator key, a JSON path to a value in the payload, and optionally a static value to compare against:

{'<operator>': ['$.Path.To.Value', <compareValue>]}

Note: JSON paths are case-sensitive and must exactly match the field names in the payload.

Because operators serve as object keys, the same operator cannot appear twice at the same level. Use grouping instead:

// Incorrect — duplicate keys
{'and': [conditionA], 'and': [conditionB]}

// Correct — grouped under a single 'and'
{'and': [{'==': [conditionA]}, {'!=': [conditionB]}]}

Supported operators

Logic and boolean

Numeric

Array and string

Using JSON paths as values

Any static value in a condition can be replaced with a JSON path. All paths are resolved to their actual payload values before the condition is evaluated.

"invocationCondition": "{'==': [{'+': ['$.Report.PaintPrice', '$.Report.WheelPrice', '$.Report.WindScreenPrice']}, '$.Report.TotalPrice']}"

This invokes the enricher only if the sum of the three price fields equals the total price.