...
Introduction
This document covers present day behavior of First Time Setup : how it operates today in on Azure and On-Premises, and what operations preformed are important in a discusses the impact of multi-instance scenarioscenarios.
Primary Recommendation
Given the following unknowns and assumptions
- What does a 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
My The first recommendation is to move report view creation out of First Time Setup and into the platform. If this is possible This could help First Time Setup becomes become instance agnostic as it only deals with the API, Admin DB, and Security DB; , all of which only have one instance provided at installation timeare 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:
...
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:
...
- 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 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
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
.
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 first "Medium" 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.
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
...