Preferences

How Does Routing Work?

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

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 preferences that are defined.

There are three ways you can define your routing preferences:

Routing Method	When to Use	Object in .json file
Aggregator by Volume	If you prefer to use more than one aggregator, but want to route specific amounts of traffic to certain aggregators.	`defaultAggregatorVolume`
Aggregator by Volume per Institution	If you prefer to use more than one aggregator and route more or less traffic to different aggregators for specific institutions.	`institutionAggregatorVolumeMap`
Default aggregator	Define your preferred aggregator to use as a backup to `defaultAggregatorVolume` and `institutionAggregatorVolumeMap`.	`defaultAggregator`

The widget first attempts to resolve using institutionAggregatorVolumeMap. If it can't be resolved using that, then it attempts to resolve using defaultAggregatorVolume. If it can't resolve using that, then it attempts to use defaultAggregator. If it can't resolve using that, then it randomly chooses one.

Create Preferences file

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
`supportedAggregators`	`string[]`	Yes	An array of your supported aggregators.	`"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": [ "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" ]`
`institutionAggregatorVolumeMap`	`{ [key: string]: { [key:string]: number } }`	No	The desired volume per institution per aggregator. For each institution, include Institution ID: The institution ID for the institution as defined by the cached institution list. Aggregator: The name of the aggregator. Volume: The percent of traffic as an integer for that aggregator.	`"institutionAggregatorVolumeMap": { "1e65df13-be46-46c1-9aab-b950ef6523dd": { "mx": 70, "sophtron": 30 }, "33232943-49ca-49ae-bea6-bc40acb9f207": { "sophtron": 100 } }`
`defaultAggregatorVolume`	`{[key: string]: number }`	No	The percent chance that traffic is routed to each aggregator. Must equal 100.	`"mx": 70`
`defaultAggregator`	`string`	No	The default aggregator is used when there is no alternative aggregator 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": ["7a909e62-98b6-4a34-8725-b2a6a63e830a"]`

Example Preferences

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

50/50 Routing to Two Aggregators

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.

{
  "defaultAggregator": "mx",
  "supportedAggregators": [
    "mx",
    "sophtron"
  ],
  "defaultAggregatorVolume": {
    "mx": 50,
    "sophtron": 50
  },
  "recommendedInstitutions": [
    "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"
  ]
}

You can see in the example that:

The supportedAggregators array has been used to define both Sophtron and MX as aggregators for the UCW.
The defaultAggregatorVolume object has been used to define a 50/50 split for percent chance of traffic.
The institutionAggregatorVolumeMap object has not been defined so the widget will use the defaultAggregatorVolume object.
In the event that the widget cannot resolve that preference, it will use the defaultAggregator defined as MX.

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

Routing for Specific Institutions

Traffic may be routed to specific aggregators based on the institution selected. The following preferences example shows how to define routing by institution.

{
  "supportedAggregators": [
    "mx",
    "sophtron"
  ],
  "recommendedInstitutions": [
    "1e65df13-be46-46c1-9aab-b950ef6523dd",
    "33232943-49ca-49ae-bea6-bc40acb9f207",
    "9ea81818-c36d-41d6-93b8-f9d4c1398e3d",
  ],
  "institutionAggregatorVolumeMap": {
    "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
      },
  },
  "defaultAggregatorVolume": {
    "mx": 30,
    "sophtron": 70
  },
  "defaultAggregator": "sophtron",
  "hiddenInstitutions": ["7a909e62-98b6-4a34-8725-b2a6a63e830a"]
}

The above example defines supported aggregators to be MX and Sophtron and includes three recommended institutions that will be displayed on the search page by default.

The UCW will first attempt to resolve routing based on the institutionAggregatorVolumeMap. The example code indicates that:

When the institution with the institution_id of 1e65df13-be46-46c1-9aab-b950ef6523dd 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 33232943-49ca-49ae-bea6-bc40acb9f207 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 9ea81818-c36d-41d6-93b8-f9d4c1398e3d 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 the UCW cannot resolve the institutionAggregatorVolumeMap object, routing will use the information in the defaultAggregatorVolume 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 defaultAggregatorVolume can't be resolved, then Sophtron is the default aggregator.

How Does Routing Work?​

Create Preferences file​

Preferences File Reference​

Example Preferences​

50/50 Routing to Two Aggregators​

Routing for Specific Institutions​