Prepared by Certica Solutions on 7/31/2020, Reviewed by Ed-Fi 8/14/2020

Table of Contents

Introduction

Before multiple-connection awareness, a single global connection was implicitly referenced throughout the solution. Our efforts so far to implement support for multiple API connection have revealed design considerations that were not clear when we initially started on this initiative. Additional dialog has led to a refinement of the design so that concerns and challenges are addressed. This document describes the outcome of this effort.

Behavior Changes

This section describes functionality that is not clear from the perspective of the data model and UI changes, or calls out significant behavior decisions for multiple connection support that are motivators for the proposed data model and UI changes.

API Versions

With the introduction of support for multiple connections, there is a requirement to store distinct resource metadata per version of API connections encountered.

We explored whether to introduce API version as a strong identifier in Data Import or leave it purely as a visual indicator. We also considered whether to model this with its own master table, and whether to identity the primary key of the table with an identity column or a natural key. Furthermore, we reviewed the impact of associating API resource metadata with the API version or the API connection. 

The outcome of this analysis is to move forward with API version as a significant entity, accepting some limitations in the multiple connection release, while using a design that supports future enhancements to increase the flexibility of Data Import when working with different versions of the ODS API.

Note: The earlier recommendation of using a natural key for the ApiVersions table is reversed in favor of any identity column. This minimizes impact to the data model when implementing future enhancements. 

Future Enhancements:

1. Enhance the versioning concept to understand variations on standard Ed-Fi versions resulting from extensions.
2. Enhance the import feature to make it easier to permit data maps targeting one version to be used with another compatible version (for example, to enable a 3.2 shared template to be imported and used with a 3.4 version).

Bootstrap Data Applicability

How bootstrap data fits into a multiple connection design has been subject to some discussion. Two distinct contexts must be considered:

1. Is the bootstrap data applicable to the execution of the agent?
• We considered that it can always be treated as applicable regardless of API version. If it does not send successfully, then we handle that as an error preventing execution of the agent. However, this potentially creates an unresolvable situation in which bootstrap data design for one API version is incompatible when posting to a different API version.
• A logical solution to this problem is to associate bootstrap data with API versions. However, we already tried something like that (for API connections instead of API versions) and it resulted in an uncompelling user experience.
• A better option is to manage applicable bootstrap data in the context of defining the agent. This mirrors the approach already used for associating data maps with an agent.
• This is preferred because it avoids trying to manage a compatibility matrix of bootstrap data items and API versions. Instead, applicability is determined solely within the context of where it will be applied.
2. Does the bootstrap data need to be sent to the ODS API before the execution of the data maps against the file?
• The existing semantics to automatically send every bootstrap data item as the first step of executing an agent if the bootstrap data had not previously been sent to the connection or the bootstrap data was changed since it was sent.
• This is easily extended to the concept of multiple connections by tracking the processed data per API connection. Even better, by deciding to associate bootstrap data items to agents, we eliminate the requirement to process bootstrap data that is not related to the responsibilities of the agent.

Access to Configuration Screen

The existing configuration screen includes ODS API server connection details, template sharing service details, enable user management, and enable product improvement. We agree to move the ODS API server connection management to a separate screen but want to ensure that users are still presented with the remaining configuration options at first setup.

Note: It was also discussed that the existing behavior requires setup of the template sharing service (except potentially when running on a development environment). However, this does not seem to be the case.

The existing behavior is as follows:

• Redirect to configuration screen after registering first user.
• Redirect to configuration screen on attempt to access ODS API if no ODS API configured.
• Redirect to configuration screen on attempt to access Sharing API if no Sharing API configuration.
• Validate Sharing API key/secret has been supplied when saving configuration settings (not required for local development environment). 

Proposed approach:

• The existing behavior will remain unchanged. 
• The configuration screen will include a link to navigate to a separate screen to manage ODS API server connection details (“API Connections”).
• The “API Connections” page will only be accessible from the Configuration page (i.e., there is no direct access menu item).

Menu Changes

There is an annoying issue with the nav bar wrapping on smaller resolutions and causing page content to be hidden:

An alternate menu layout was introduced by Certica on the first PR and received favorable feedback in the Headspring review. While this does not technically need to be addressed in the context of multi-connection support, it is bothersome enough that we would like to apply the new design in the context of preparing a second PR.

The new design introduces a Configure dropdown:

Also, the “Hello <email>” on the far right is converted to a dropdown containing “Manage” and “Log Off”.

Collectively, these changes address the nav bar wrapping issue. As a bonus, with Bootstrap Data now being assigned to agents, it is also preferred to include it in the “Configure” menu rather than the “Admin” menu where it currently resides. 

Deletion Behavior

Agent Deletion

• No change to Agent deletion behavior – they will continue to be archived (logically deleted).

Data Map Deletion

• No change to Map deletion behavior – they are physically deleted, and associated agent references are removed.

Bootstrap Data Deletion

• Bootstrap data is physically deleted.
• Deletion will now also require removal of associated API connection and agent references.

API Connection Deletion

• API connection will be physically deleted.
• An API connection cannot be deleted if any agents reference it (must delete the agents first or change their connections).
• Associated references to bootstrap data are removed when an API connection is deleted.

User Interface Changes

Data Model Changes

Alternate Design

Another design approach for adding multiple connection support is for Data Import to operate within a current connection context. This approach was originally taken by Certica for their enhancements to Data Flow.

Both design approaches address the requirement for multiple connections although how that requirement is satisfied is significantly different. 

I have spent some considerable time working with and thinking about both approaches. Both have their merit, and which approach is ultimately “best” is dependent on the longer-term vision of use cases for how data import is used. The following is an effort to characterize the distinctions of each design.