Goal

...

Background - DistrictSpecific Mode

With v3.4, the ODS / API supports a new deployment and partitioning mode, DistrictSpecific, for use by collaboratives. Like YearSpecific mode, you get one API atop multiple databases. In DistrictSpecific mode, each District (identified by EdOrg Id) gets its own database. In this mode, API calls are routed to the appropriate EdOrg database based on the particular Key and Secret pair used by the calling client application. At the time that Clients are defined, they can be associated with their EdOrg Id.

Admin App is in need of special support for this mode. To date, Admin App has set up a singular Key and Secret for itself to use as a singular Client.

Goal

At a high level, the goal here is to support management of multiple ODS instances in a collaborative scenario, to minimize the need for "home grown" management workarounds in the field, and to exhibit & promote Ed-Fi's recommended deployment and data partitioning approach.

More concretely, the goal here is for Admin App to support administration of the ODS in DistrictSpecific mode. Therefore, this document will tend towards using the phrases "District Database" or "EdOrg Id" rather than "Instance Database" or "Instance Id".

Once Admin App has the ability to manage multiple ODS instancesdistrict databases, per-user roles and permissions become a vital new concern: users should only be able to access the particular ODS instances districts they have been assigned to manage, rather than allowing all Admin App users to automatically access all districts.

Although DistrictSpecific mode is the driving target here, Admin App should minimize coupling to that mode. For instance, the future may bring other partitioning modes, and supporting them should be a minimal variation on this design for DistrictSpecific mode. The more that Admin App's implementation can be made in terms of existing concepts (API Client setup, Ed Org Ids, etc), the smoother future partitioning modes can go.

The reference architecture is Indiana/INSITE as seen in Multi-Instance Reference Architectures:

...

• One EdFi_Admin
• One EdFi_Security
• One API, deployed and configured in DistrictSpecific mode.
• Mulitple ODS databases (ie , one per district). "Multiple Instance" refers to these multiple ODS databases behind the single API.
• One Admin App installation, capable of managing all the defined ODS instancesdistrict databases.
  • A given Admin App user is limited to which ODS instance databases they access.

...

Given that users in the field have a number of deployment scenarios and workarounds already, it's important that this design respect and leverage existing ODS Platform concepts where applicable, rather than mistakenly "reinvent the wheel". The desire for "One API" for instance, strongly suggests that part of the user-to-instance routing and security would naturally be performed by the ODS itselfKey here is the fact that the ODS itself is responsible for routing a given API call to the right database. It does so via the Key/Secret provided, and the mapping from API Client to EdOrg. Admin App, therefore, needs to be concerned more with Client definition and Key/Secret usage, and less concerned with databases, "instances", and routing.

This design should allow for a reasonable degree of developer parallelism, and should allow each planned piece to be developed and merged in a state that could be released at any moment without harm. Implemented as one large Pull Request, for instance, would be a high-risk mistake.

Although this work is to support multi-instanceDistrictSpecific mode, not all end users find themselves in a multi-instance that scenario. The experience for simpler deployment scenarios should not be harmed, but we also need to strive for a singular implementation rather than a sort of "internal fork" of the project. Therefore, this work may change the experience for simple deployment scenarios, such as the precise steps taken from installation to first time setup of a singular ODS instance, so long as that experience is still sound.

...

This design is about enabling users to administer the multi-instance scenario depicted above under "Goal". Just as Admin App today does not deploy its singular ODS instance, a MultiDistrictSpecific-Instance enabled Admin App would not deploy  ODS  ODS instances. Rather, it would gain support for administering the deployed ODS instances databases just as it does today for its singular ODS instancedatabase. That new multi-instance support therefore largely focus on configuring the connections to each ODS instancedistrict, performing the "first time setup" work for each, and configuring/controlling which users are allowed access to the instancesdistricts.

Recommendation

"Settings" & "Global" Sections

Top Level Navigation: Admin App users in prior releases first select "Settings" (features against their single ODS instance such as Applications, Descriptors, Reports) or "Global" (Vendors and Claim Sets). The Vendors page already suggests, even, the natural workflow: define Vendors, define Applications within those Vendors, obtains Keys. Given the natural order of that workflow, we recommend swapping the order of the "Settings" and "Global" navigation items, and then renaming "Settings" to "ODS Instances":

Consider the current tabs within the The present-day Settings screen :

...

has many tabs (Applications, Descriptors, ...). For an ODS in DistrictSpecific mode, this screen will gain a new District selector, allowing the user to select the EdOrg Id in effect in each tab below. The list of available EdOrg Ids to select from is limited to those the user has been granted access to. Special cases:

• The list may be empty for this user, in which case we need to explain to the user what needs to happen for them to proceed.
• The list may have exactly one item to choose, in which case we should automatically select it to save the user a click. We should consider displaying the District name in plain text rather than as a single-item drop down list.

Within any tab under this District selector, and in any popup reached from those tabs, some preexisting controls become redundant. For instance, the Reports tab already has a District selection populated with EdOrg Ids that becomes redundant with the page-wide selector. As an other example, the form to add a new Application has preexisting controls around choosing an LEA or School, at least some of which becomes redundant with the page wide selector. Minimal handling of these redundancies would take the form of automatically filling them in, and possibly hiding them, in the case of a DistrictSpecific ODS.

Tabs:

• Applications - In DistrictSpecific mode, limit to show only those Applications defined under the selected District. As described above, care must be taken for the similar preexisting controls in the Add Application popup.
• Descriptors - In DistrictSpecific mode, show descriptors for the selected District.
• Education Organizations - In DistrictSpecific mode, limit to only those districts (and schools) at-or-beneath the selected District.
  • Does "Add Local Education Agency" no longer make sense in DistrictSpecific mode?
    • Review also the similar Edit flow once this question is answered.
• Bulk Load - Because bulk load hits the API with a specific Key and Secret entered in this screen, we expect no further need for Multi-Instance concerns here. Is this in fact a "global" API-level concern, belonging under Global, or is it somehow in fact ODS instance specific, though
  • Is the assumption that a bulk load would happen for a single District at a time, with a dedicated key and secret used by the ODS for routing the bulk load?
  • Is obtaining such a key a new responsibility for the Admin App?
• Learning Standards - Same questions as for Bulk Load.
• Reports - AA
  • Admin App currently adds reporting views to the target ODS database to enable reports.
  We expect this page to need an ODS Instance selection similar to Applications and Education Organizations.
  • Risk: There's a similar conceptual/vocabulary risk here as with Education Organizations above. This screen has a District drop down list. Given that specific ODS instances have been described in terms of districts so far, it raises the question about how strictly true those examples are, or whether we need to be extra precise in our language: on the reports tab, for instance, would the user select both an ODS Instance and a District, and when would those not be the same apparently selection to the user.
  • Recommendation: When the existing "Select District" dropdown has only one option, autoselect it. The underlying data for this dropdown is Local Education Agencies, so should "Select District" be rephrased to match?
• Recommendation for any ODS instance selector: when the current user has exactly one instance available to them, autoselect it.

...

• • As called out above, the preexisting District dropdown here becomes redundant in the case of DistrictSpecific mode, as the page itself would have a new District selector already. Care must be taken whether we are in DistrictSpecific mode or not.

User Management: Roles, Permissions, Registration & Login

Because the set of Admin App users are managed by Admin App for use against all the ODS Instancesdatabases, new user administration features will appear under the "Global" top level navigation.

See User Management for Admin App (Multi-Instance Mode) for technical design of the users/roles/permissions aspects of Multi-Instance. At a high level, administrators should be able to define the list of known ODS databases, create and manage user accounts, and associate users to their approved list of Districts.

First-Time Setup

See Multi-Instance First Time Setup for the design of the First-Time Setup aspects of Multi-Instance.

...