Configuring the UCW

The Universal Connect Widget (UCW) enables you to manage a local institution list and your routing preferences. The widget uses cached data on the server to support function. This means it doesn’t rely on any UCP hosted services and remains fully functional given any outages to those services.

Both your institutions and your preferences can be configured locally on the widget server. Each of these files are located in ./apps/server/cachedDefaults. The Connect Widget server requires both the Preferences and Institution files to be present. These files are loaded in a redis cache.

Cached Institutions

When you fork the ucw-app project, the most recent version of the institutions list is automatically available in the ./apps/server/cachedDefaults folder. This file is a .json file that includes a list of all institutions exported from MX’s database. The widget is built to index and search this file. At this time, the institution list is static and no additional lists are available for update.

Configuring Preferences and Routing

Before you can configure your preferences, you must provide your own credentials for each of the providers you plan to support in the ./apps/server/.env file. At least one provider is required.

Route provider connections by defining your preferences by provider and volume. Preferences are defined in a .json file that is cached.

Configuration options include:

Supported and default providers
Provider and institution volume
Hidden and recommended institutions

To configure preferences

In the root folder, run cp ./apps/server/cachedDefaults/preferences.example.json ./apps/server/cachedDefaults/preferences.json to copy the preferences example provided in the repository.
Edit ./apps/server/cachedDefaults/preferences.json to configure your preferences.

How Does Routing Work?

In the Preferences file, you can decide whether you prefer to use a specific provider, route more or less traffic to a specific provider, or route more or less traffic for a certain institution to a specific provider.

note

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

There are three ways you can define your routing preferences:

Routing Method	When to Use	Object in .json file
Provider by Volume	If you prefer to use more than one provider, but want to route specific amounts of traffic to certain providers.	`defaultProviderVolume`
Provider by Volume per Institution	If you prefer to use more than one provider and route more or less traffic to different providers for specific institutions.	`institutionProviderVolumeMap`
Default provider	Define your preferred provider to use as a backup to `defaultProviderVolume` and `institutionProvideVolumeMap`.	`defaultProvider`

The widget first attempts to resolves using institutionProviderVolumeMap. If it can't be resolved using that, then it attempts to resolve using defaultProviderVolume. If it can't resolve using that, then it attempts use defaultProvider. If it can't resolve using that, then it randomly chooses one.

Configuring Preferences

To configure preferences:

In the root folder, run cp ./apps/server/cachedDefaults/preferences.example.json ./apps/server/cachedDefaults/preferences.json to copy the preferences example provided in the repository.
Edit ./apps/server/cachedDefaults/preferences.json to configure your preferences.

Preferences File Reference

The following table explains each configuration option for preferences and an example.

Field/Object	Type	Required?	Description	Example
`supportedProviders`	`string[]`	Yes	An array of your supported providers.	`"mx", "sophtron"`
`recommendedInstitutions`	`string[]`	Yes	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 institutionID as defined by the cached institution list.	`"recommendedInstitutions": [ "UCP-b087caf69b372c9", "UCP-ce8334bbb890163", "UCP-ebca9a2b2ae2cca", "UCP-b0a4307160ecb4c", "UCP-8c4ca4c32dbd8de", "UCP-412ded54698c47f" ]`
`institutionProviderVolumeMap`	`{ [key: string]: { [key:string]: number } }`	No	The desired volume per institution per provider. For each institution, include Institution ID: The institution ID for the institution as defined by the cached institution list. Provider: The name of the provider. Volume: The percent of traffic as an integer for that provider.	`"institutionProviderVolumeMap": { "UCP-8c4ca4c32dbd8de": { "mx": 70, "sophtron": 30 }, "UCP-ce8334bbb890163": { "sophtron": 100 } }`
`defaultProviderVolume`	`{[key: string]: number }`	No	The percent chance that traffic is routed to each provider. Must equal 100.	`"mx": 70`
`defaultProvider`	`string`	No	The default provider is used when there is no alternative provider available.	`"mx"`
`hiddenInstitutions`	`string[]`	No	An array of institutions that should not be displayed in the search results. For each institution, enter the institutionID as defined by the cached institution list.	`"hiddenInstitutions": ["UCP-2e2b825bd378172"]`

Examples & Scenarios

The following examples walk through several possibilities when indicates routing preferences.

Routing Traffic to Two Providers at 50/50 for All Institutions

In the following example, the preferences have been defined to route traffic to both Sophtron and MX at 50%. This means that regardless of the institution the end user selects, there is a 50% chance that traffic will go to Sophtron and a 50% chance that traffic will go to MX.

You can see in the example that:

The supportedProviders array has been used to define both Sophtron and MX as providers for the UCW.
The defaultProviderVolume object has been used to define a 50/50 split for percent chance of traffic.
The institutionProviderVolumeMap object has not been defined so the widget will use the defaultProviderVolume object.
In the event that the widget cannot resolve that preference, it will use the defaultProvider defined as MX.

This is defined using the defaultProviderVolume where mx has a value of 50 and sophtron has a value of 50.

{
  "defaultProvider": "mx",

  "supportedProviders": [
    "mx",
    "sophtron"
  ],

  "defaultProviderVolume": {
    "mx": 50,
    "sophtron": 50
  },

  "recommendedInstitutions": [
    "UCP-b087caf69b372c9",
    "UCP-ce8334bbb890163",
    "UCP-ebca9a2b2ae2cca",
    "UCP-b0a4307160ecb4c",
    "UCP-8c4ca4c32dbd8de",
    "UCP-412ded54698c47f"
  ]
}

Routing Traffic for Specific Institutions for Two Providers

In this scenario, the preferences are defined to route traffic to specific providers based on the institution selected. For simplicity this scenario only defines preferences for three institutions.

First we can see that supported providers for UCW are MX and Sophtron and that we have three recommended institutions that will be displayed on the search page by default.

Based on the how routing works, the UCW will first attempt to resolve routing based on the institutionProviderVolumeMap. The example code indicates that:

When the institution with the institution_id of UCP-8c4ca4c32dbd8de is selected, there is then a 70% chance that traffic will be routed to MX and a 30% chance that traffic will be routed to Sophtron.
When the institution with the institution_id of UCP-ce8334bbb890163 is selected, there is then a 100% chance that traffic will be routed to Sophtron with no chance of being routed to MX.
When the institution with the institution_id of UCP-ebca9a2b2ae2cca is selected, there is then a 25% chance that traffic will be routed to MX and a 75% chance that traffic will be routed to Sophtron.

If for some reason, the UCW cannot resolve the institutionProviderVolumeMap object, routing will use the information in the defaultProviderVolume object which states that when any institution is selected, there is a 30% chance that traffic will be routed to MX and a 70% chance that traffic will be routed to Sophtron.

If at any point the defaultProviderVolume can't be resolved, then Sophtron is the backup provider.

{
    "supportedProviders": [
    "mx",
    "sophtron"
  ],
    "recommendedInstitutions": [
    "UCP-b087caf69b372c9",
    "UCP-ce8334bbb890163",
    "UCP-ebca9a2b2ae2cca",
  ],

    "institutionProviderVolumeMap": {
    "UCP-8c4ca4c32dbd8de": {
      "mx": 70,
      "sophtron": 30
    },
    "UCP-ce8334bbb890163": {
      "sophtron": 100
    },
    "UCP-ebca9a2b2ae2cca": {
      "mx": 25,
      "sophtron": 75
    },
  },

    "defaultProviderVolume": {
    "mx": 30,
    "sophtron": 70
  },

  
  "defaultProvider": "sophtron",



  "hiddenInstitutions": ["UCP-2e2b825bd378172"]

}

Configuring the UCW

Cached Institutions​

Configuring Preferences and Routing​

To configure preferences​

How Does Routing Work?​

Configuring Preferences​

Preferences File Reference​

Examples & Scenarios​

Routing Traffic to Two Providers at 50/50 for All Institutions​

Routing Traffic for Specific Institutions for Two Providers​