WIP: Multi-Instance First Time Setup

Introduction

This document covers present day behavior of First Time Setup on Azure and On-Premises, and discusses the impact of multi-instance scenarios.

Primary Recommendation

Given the following unknowns and assumptions

• What does an API request to a specific instance look like? Operating under the assumption that because we have the other components, the only missing info for a new instance is a db catalog name

The first recommendation is to move report view creation out of First Time Setup and into the platform. This could help First Time Setup become instance agnostic as it only deals with the API, Admin DB, and Security DB, all of which are singular even in a multi-instance scenario. No further changes would be necessary for First Time Setup to work in a multi-instance environment. Regardless of report creation, a "New Instance" screen should be created to manage which instance is active

Current State: What First Time Setup Does

First Time Setup - Process and Affected Operations

Azure First Time Setup

Critical path operations:

1. Create Sql Logins for APIs and Application
2. Bootstrap the AdminApp in the Application/Vendor/ApiClients table
3. Create AdminApp specific hidden claimset
4. Create report views

Non-critical operations:

1. "Setup" account creation
2. "Runtime" account creation
3. Extra database initialization (hangfire)
4. Remove "Setup" account
5. Learning standards claims
6. read and create performance level descriptors

These operations might be critical for a specific version of Admin App to work, but some of them are or will be accounted for in future platform versions. Setup/runtime accounts are azure specific operations to account for the accounts not being created during deployment. 

On Prem First Time Setup

Critical path operations:

1. Bootstrap the AdminApp in the Application/Vendor/ApiClients table
2. Create AdminApp specific hidden claimset
3. Create report views

Non-critical operations:

1. Learning standards claims
2. read and create performance level descriptors

Affected Operations

Report Views operate against the ODS database and therefore will be changed when First Time Setup supports multi instance

Bootstrapping AdminApp ApiClient must know which which EdOrgId to associate our key/secret to. Since this won't be know at first time setup time, it will be need to be changed in order to support multi-instance

Secondary Recommendations

It may be that the platform cannot take ownership of creating its reporting views itself. There are a few options available even then:

Small - Continue to Define Report Views During First Time Setup

Scope Minimizing Opportunity: If it is possible to infer the list of District databases in a DistrictSpecific deployment, then Admin App could simply loop over the list of databases, connecting to each in turn, performing the same view creation steps it does today. There's an assumption here that Admin App's view creation scripts are applicable to the ODS version of each database, but that's already a coupling risk today.

Medium - Admins Define Instance by Name, Setting up Report Views at That Time

If it is not possible to infer the list of District databases, we'll need to move this step out of the First Time Setup and into a new page where the user defines the connection to a specific District database by providing only its name (or by EdOrg Id, implying the full database name). A connection string would be assembled from this name and the existing connection string in the web.config. The act of adding that connection would include setting up its reporting views. Think of this as a first time setup for that database.

This alone leaves the config file unchanged. In other words, api url and database connection still provided at build/installation time in web.config.

Pros: Simple to implement, and limits the amount of code that has to run against a new instance to the absolutely minimal amount. Absolutely no change for single instance users.
Cons: Bulky setup for a multi-instance user, with a misleading step at the beginning to choose **any** catalog name in order to provide a valid ODS connection string
Risks: Running the report scripts against any ods database could be problematic for version reasons.

Large - Move Database Specific Code out of First Time Setup

The smallest change provides an odd user experience because the user still has to choose an arbitrary instance to run through first time setup and then set up additional instances in a new page. This change aims to keep first time setup and most of the config changes as is, but moves the ODS database specific code to a new configuration page.

Pros: less work/risk/change than modifying the entire setup flow, and provides a single spot for multi-instance users to add N instances
Cons: Still multiple steps of configuration during installation and after running setup in order to be ready to use

Add a "New Instance" page

Very similar to the "Medium" suggestion, with the difference that this page will be used to setup N ODS instances. This new page will have a table of instance names with the ability to add a new one and run report setup on each instance.

Extra Large - Adapting for Multi-Instance

With infinite time and money these are the changes to support multi-instance mode. This approach streamlines installation and setup, giving any user one place to setup their (N) instances, while greatly reducing the amount of information needed during installation and improves the troubleshooting experience for users. It will require non-trivial changes to the app and major changes to the first time experience for all users

Cons: most expensive choice, and installation benefits may or may not be seen depending on installer timeline
Pros: Moving all configuration to one place makes a streamlined experience for the user regardless of mode and greatly simplifies installation (no sql connection screens, or api connection, until they see config screen inside application).

Assumption: The user will always see the configuration screen and can't reach any part of the application before setup as run against one instance

Build Time vs Run Time Configuration

The AA currently supports configuration during installation time, which forces validation at this time too. We could leverage the validation framework already in place and provide a better UX if this configuration was done while running the application (new config screen). Additionally, and probably most importantly, this removes a lot of the "guess and check" of providing the right URL during installation only to see it fail when used in the AA. We've seen this is hard to get right in Data Import, so adding validation will be important.

Major steps

The biggest parts of this process are:
1. Running AA schema migrations the first time the app is launched. Will have to account for running with install credentials not runtime credentials
2. Changing the application to read a connection string from a service instead of directly from web.config.
3. Separating first time setup operations from ods catalog specific setup (only report views for now)
4. Running first time setup on first application launch
5. Providing a new UI page for AA/Security/API config and Instance config

Developer Steps

1. Add a new "configuration screen", along the lines of data import, that allows the user to enter "Global" instance. This serves as a replacement for any install/build time config and should instead write to a new database table. Not exclusive to multi-instance
- DB Server connection properties. We don't want them to build a connection string, but something similar to the installer sql screens instead
- API Url
- Name of the ODS Catalog

2. Remove first time setup and move to the configuration screen as an operation done before reaching the application

3. Modify usages of API Url or Ods connection string to read from a service instead of directly from web.config

4. Add ability to configuration screen for adding new instances and generating their report views

5. Add ability to switch between active instances