Route Aggregators

Objective

Define aggregator routing preferences, including:

• Supported aggregators
• Fallback default aggregator
• Traffic percentages (global and per-institution)
• Hidden institutions & recommended institutions shown on the search page

"Routing" means choosing which aggregator (for example, MX or Sophtron) will create the connection between the user and the financial institution they selected. It can be set in your preferences.json file:

• by institution via institutionAggregatorVolumeMap
• by aggregator via defaultAggregatorVolume

UCW resolves your routing preferences in that order.

You can also set a single fallback aggregator via defaultAggregator. If the preference still can't be resolved with defaultAggregator, it'll randomly choose one of those routing options.

How To

To set your routing preferences:

1. Ensure you provided your own credentials for each aggregator you plan to support in the ./apps/server/env/staging.env or ./apps/server/env/production.env file. At least one aggregator is required.
2. In the root folder, run this command to copy the preferences example provided in the repository: cp ./apps/server/cachedDefaults/preferences.example.json ./apps/server/cachedDefaults/preferences.json.
3. Edit ./apps/server/cachedDefaults/preferences.json to configure your preferences. See:
   • Preferences File Reference — configurations available in preferences.json
   • Example 1 — 50/50 routing to two aggregators
   • Example 2 — Routing for specific institutions

info

Since the preferences and institutions files are cached from the server, the widget remains fully functional given any service outages.

Preferences File Reference

This table explains each configuration option available to use in preferences.json.

info

UCW doesn't track how much traffic is routed to each aggregator. It uses random chance each time the end user selects an institution using the defined preferences.

Field/Object	Type	Description
Required supportedAggregators	string[]	An array of your supported aggregators. Example: "supportedAggregators": [ "mx", "sophtron" ]
Required recommendedInstitutions	string[]	An array of institutions that should be displayed as recommendations before an end user enters anything into the search bar. For each institution, enter the institution ID as defined by the cached institution list. Example: "recommendedInstitutions": [ "9ea81818-c36d-41d6-93b8-f9d4c1398e3d", "33232943-49ca-49ae-bea6-bc40acb9f207", "e4996bf9-9540-456f-8287-30da92edf326", "956af43b-c894-4640-8594-f774ceee3ce6"]
institutionAggregatorVolumeMap	{ [key: string]: { [key:string]: number } }	The desired volume per institution per aggregator. For each institution, include the institution ID (as defined by the cached institution list) and a map of aggregator names to integer percent values. Use this if you prefer to use more than one aggregator and route more or less traffic to different aggregators for specific institutions. Example: "institutionAggregatorVolumeMap": { "1e65df13-be46-46c1-9aab-b950ef6523dd": { "mx": 70, "sophtron": 30 }, "33232943-49ca-49ae-bea6-bc40acb9f207": { "sophtron": 100 } }
defaultAggregatorVolume	{ [key: string]: number }	The percent chance that traffic is routed to each aggregator. Must sum to 100. Use this if you prefer to use more than one aggregator, but want to route specific amounts of traffic to certain aggregators. Example: "defaultAggregatorVolume": { "mx": 70, "sophtron": 30 }
defaultAggregator	string	The default aggregator used as a fallback to defaultAggregatorVolume and institutionAggregatorVolumeMap. Example: "defaultAggregator": "mx"
hiddenInstitutions	string[]	An array of institutions that should not be displayed in the search results. For each institution, enter the institution ID as defined by the cached institution list. Example: "hiddenInstitutions": ["7a909e62-98b6-4a34-8725-b2a6a63e830a"]

Example 1

This example routes traffic 50/50 to Sophtron and MX. Since institutionAggregatorVolumeMap isn't defined, UCW uses defaultAggregatorVolume, then defaultAggregator as a fallback.

{
  "defaultAggregator": "mx", // fallback when other routing options can't resolve preference
  "supportedAggregators": [  // defines your supported aggregators
    "mx",
    "sophtron"
  ],
  "defaultAggregatorVolume": { // 50/50 split for percent chance of traffic
    "mx": 50,
    "sophtron": 50
  },
  "recommendedInstitutions": [ // recommended institutions that display before an end user enters anything into the search bar
    "9ea81818-c36d-41d6-93b8-f9d4c1398e3d",
    "33232943-49ca-49ae-bea6-bc40acb9f207",
    "e4996bf9-9540-456f-8287-30da92edf326",
    "956af43b-c894-4640-8594-f774ceee3ce6",
    "1e65df13-be46-46c1-9aab-b950ef6523dd",
    "10b0aa0d-ee76-4015-b065-d0db092a7423"
  ]
}

Example 2

This example defines per-institution routing. Supported aggregators in this example are MX and Sophtron; three institutions are defined as recommended and will appear on the widget's search page by default.

The JSON below indicates the per-institution routing preferences:

• 1e65df13-be46-46c1-9aab-b950ef6523dd: MX 70%, Sophtron 30%.
• 33232943-49ca-49ae-bea6-bc40acb9f207: Sophtron 100%.
• 9ea81818-c36d-41d6-93b8-f9d4c1398e3d: MX 25%, Sophtron 75%.

If an institution isn't listed, UCW attempts to use defaultAggregatorVolume.

{
  "supportedAggregators": [
    "mx",
    "sophtron"
  ],
  "recommendedInstitutions": [ // recommended institutions that display before an end user enters anything into the search bar
    "1e65df13-be46-46c1-9aab-b950ef6523dd",
    "33232943-49ca-49ae-bea6-bc40acb9f207",
    "9ea81818-c36d-41d6-93b8-f9d4c1398e3d"
  ],
  "institutionAggregatorVolumeMap": {
    "1e65df13-be46-46c1-9aab-b950ef6523dd": { // for this institution, 70% of the routing will go to MX
      "mx": 70,
      "sophtron": 30
    },
    "33232943-49ca-49ae-bea6-bc40acb9f207": {
      "sophtron": 100
    },
    "9ea81818-c36d-41d6-93b8-f9d4c1398e3d": {
      "mx": 25,
      "sophtron": 75
    }
  },
  "defaultAggregatorVolume": { // 30/70 split for percent chance of traffic if institutionAggregatorVolumeMap doesn't resolve a preference
    "mx": 30,
    "sophtron": 70
  },
  "defaultAggregator": "sophtron",
  "hiddenInstitutions": ["7a909e62-98b6-4a34-8725-b2a6a63e830a"] // this institution won't display in search results
}