Rough draft notes from investigating First Time Setup: how it operates today in Azure and On-Premises, and what operations preformed are important in a multi-instance scenario
Primary Recommendation
Given the following unknowns and assumptions
- What does a 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
My first recommendation is to move report creation out of First Time Setup and into the platform. If this is possible First Time Setup becomes instance agnostic as it only deals with the API, Admin DB, and Security DB; all of which only have one instance provided at installation time. 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
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:
- "Setup" account creation
- "Runtime" account creation
- Extra database initialization (hangfire)
- Remove "Setup" account
- Learning standards claims
- 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:
- Bootstrap the AdminApp in the Application/Vendor/ApiClients table
- Create AdminApp specific hidden claimset
- Create report views
Non-critical operations:
- Learning standards claims
- read and create performance level descriptors
Affected Operations
Report Views are the only operation listed above that operates against the ODS database, and therefore is the only operation that will be changed when First Time Setup supports multi instance
Secondary Recommendations
If report creation can't be moved out of First Time Setup; listed below are three different approaches to support First Time Setup. All three approaches focus on running report views in a more ad-hoc fashion in a "New Instance" screen.
Adapting for Multi-Instance - Smallest Change
Support multi instance with no setup config changes. 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
Add a "New Instance" page
Because there is still one API/Admin/Security, we won't have to preform most setup actions again.
The one exception is:
- Creates report views
It appears these reports are specific to the ODS database, so each new instance will have to generate reports on the fly.
BIG UNKNOWN: What versions are these multiple instance databases going to be on? Need to ensure it's a version we can safely run report view creation on. If we have to have multiple versions of reports scripts, it hurts decoupling efforts.
This page should only need one additional piece of information in order to function (assuming we know api url and server connection). It will allow the user to run the setup operation on a new instance, given the identifying name of that instance
- New Instance Catalog Name (db name)
Adapting for Multi-Instance - Medium Change
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 first suggestion, with the difference that this page will be used by every kind of user 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.
Adapting for Multi-Instance - Large Change
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