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 clone 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

1. 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.
2. Edit ./apps/server/cachedDefaults/preferences.json to configure your preferences.

Note: An example preferences file is provided for your convenience at /apps/server/cachedDefaults/testData as testPreferences.json.

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.

There are three ways you can define your routing preferences:

Routing Method	When to Use	Object in .json file
Default provider	If you have a provider you prefer to use for all traffic, define the provider.	defaultProvider
Provider by Volume	If you prefer to use more than one provider, but want to route specific amounts of traffic to certain providers.	defaultProviderMap
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

Note: The widget first checks the preferences defined in the institutionProviderVolumeMap object. If this is not defined, it then checks for the preferences defined in the defaultProviderMap object. If this is also not defined, it finally checks defaultProvider. If none of the above options are defined it randomly selects one.

Configuring Preferences

To configure preferences:

1. 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.
2. 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
defaultProvider	string	No	The default provider is used when there is no alternative provider available.	"mx"
supportedProviders	string[]	Yes	An array of all supported providers.	"Mx", "sophtron"
defaultProviderVolume	[key: string]: number }	No	The weighted performance volume for each provider. For each provider list the provider and the weighted volume.	"Mx": 70
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 } }
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"]
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" ]

Example from testPreferences.json

{
  "defaultProvider": "mx",

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

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

  "institutionProviderVolumeMap": {
    "UCP-8c4ca4c32dbd8de": {
      "mx": 70,
      "sophtron": 30
    },
    "UCP-ce8334bbb890163": {
      "sophtron": 100
    },
    "UCP-b0a4307160ecb4c": {
      "sophtron": 100
    },
    "UCP-60155b7292895ed": {
      "sophtron": 100
    },
    "UCP-b087caf69b372c9": {
      "sophtron": 100
    },
    "UCP-ebca9a2b2ae2cca": {
      "sophtron": 100
    },
    "UCP-dba9d2636344aba": {
      "sophtron": 100
    },
    "UCP-cf357b89cd3f592": {
      "sophtron": 100
    },
    "UCP-f4a829f9e5be589": {
      "sophtron": 100
    },
    "UCP-7b326dfce0e627b": {
      "sophtron": 100
    },
    "UCP-d5550e0c94ec25b": {
      "sophtron": 100
    },
    "UCP-e4151e6f16f11e8": {
      "sophtron": 100
    }
  },

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

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