Compatibility

The Analytics Middle Tier views support these Ed-Fi ODS database versions:

Preparation

Before beginning the installation, you will need to:

1. Select a deployment model, which will determine the correct server and database names to use. The deployment options are:
   • Option 1. Installing into a replicated or log-shipped copy of the production ODS database (the generally recommended approach).
   • Option 2. Directly installing on your production ODS database.
2. Decide which of the optional Collections to install, if any.
3. Ensure that the machine running the installation has network access to the database server, and that you can supply database credentials with sufficient access to create new objects in the destination database.
4. Review the following documents for awareness of security and performance considerations:
   1. Limiting Impact on the Production ODS
   2. Administrative Security
   3. Improving ODS Query Performance With Indexes

Installation

While installation of the views is a relatively simple, there are a few steps that need to be followed carefully for a successful and secure deployment:

These are described in more detail below.

Step 1 (option A). Download or Build from Source

• Raw source code (build instructions follow). Can be run from a Linux host.

• Download a compiled release in either format:

  Note
  Binaries for version 2.0.0 and earlier are posted the older GitHub organization, pre-Apache License. To download the binaries, you must be signed in to GitHub with an account that has Ed-Fi licensee access.

  
  

  • EdFi.AnalyticsMiddleTier.zip (~2 MB) is a .NET Core framework-dependent deployment, meaning that you must have the .NET Core 3.1 SDK and Runtime installed on the system on which you wish to run the application. Can be run from a Linux host.

  • EdFi.AnalyticsMiddleTier-win10.x64.zip (~30 MB) is a self-contained deployment, meaning that you can run it without downloading and installing .NET Core 3.1. Must be run from a Windows host.

Choose an appropriate version, download, and unzip the files.

Step 1 (option B). Run the Installer from Docker

This option assumes you already have a docker environment set up and running.  If you don't have a a docker environment, consider using the existing installer in the option A of Step 1.  The instructions below use Docker Desktop for workstation usage.  Docker is also available for on-premise and cloud providers as well.

• Images for Analytics Middle Tier (AMT) can be found at Docker AMT Images

• To run the installer in Step 2, your installation command will look like:

  Code Block
  docker run edfialliance/analytics-middle-tier --connectionString "...." --options A, B, C

  
  

Step 2. Run the Installer

Command Line Arguments

Command line arguments can be provided using either a "short flag" (e.g., -c "...") or "long flag" (e.g. –connectionString "...").

Running the Tool

The precise syntax for running the tool varies slightly depending on which download and build strategy you have chosen. Examples are shown below for each approach.

Connection String

The connection string will be in standard .NET format, for example:

server=yourServer;database=EdFi_ODS_ReadOnly;integrated security=sspi;

host=yourServer;database=EdFi_ODS_Readonly;username=postgres;

The detailed examples below leave the connection string out in order to focus attention on other elements of the command.

From Source Code

Note that the "long flag" is required for the options when running from source (e.g., use --connectionString and not -c):

cd Ed-Fi-Analytics-Middle-Tier\src
dotnet run --connectionString "..."

cd Ed-Fi-Analytics-Middle-Tier\src
dotnet run --connectionString "..." --engine PostgreSQL

cd Ed-Fi-Analytics-Middle-Tier\src
dotnet run --connectionString "..." --options Indexes EWS

Framework-Dependent Download

As with source code, when using EdFi.AnalyticsMiddleTier.zip you must provide command parameters via the "long flag" form for options.

cd Ed-Fi-Analytics-Middle-Tier\src
dotnet EdFi.AnalyticsMiddleTier.Console.dll --connectionString "..."

cd Ed-Fi-Analytics-Middle-Tier\src
dotnet EdFi.AnalyticsMiddleTier.Console.dll --connectionString "..." --engine PostgreSQL

cd Ed-Fi-Analytics-Middle-Tier\src
dotnet EdFi.AnalyticsMiddleTier.Console.dll --connectionString "..." --options Indexes EWS

Self-Contained Executable

In this scenario, you can use the long flags as shown above or the short flags as shown below.

cd EdFi.AnalyticsMiddleTier-win10.x64
.\EdFi.AnalyticsMiddleTier.Console.exe -c "..."

cd EdFi.AnalyticsMiddleTier-win10.x64
.\EdFi.AnalyticsMiddleTier.Console.exe -c "..." -e PostgreSQL

cd EdFi.AnalyticsMiddleTier-win10.x64
.\EdFi.AnalyticsMiddleTier.Console.exe -c "..." -o Indexes EWS

Using Docker

In this scenario, you can use the long flags as shown above or the short flags as shown below.

docker run edfialliance/analytics-middle-tier --connectionString "...." --options A, B, C

docker run edfialliance/analytics-middle-tier --connectionString "...." -e PostgreSQL

docker run edfialliance/analytics-middle-tier --connectionString "...." -o Indexes EWS

Installing Additional Collections

An administrator can run the installation tool repeatedly with no harm; the install is an idempotent operation. To install additional collections after the initial install, simply re-run the tool and provide the additional collection name(s) at the command line.

Common Errors Seen During Installation

When running the installer in a Non-Windows Environment, such as Linux, MacOS, Windows Subsystem for Linux, or Google Cloud, you could receive the following error:

Error:
An assembly specified in the application dependencies manifest (EdFi.AnalyticsMiddleTier.Console.deps.json) was not found:
package: 'System.Data.SqlClient', version '4.6.0'
path: 'runtimes/unix/lib/netcoreapp2.1/System.Data.SqlClient.dll'

This error comes about due to one of the subfolders that was extracted from the zip file not having the correct permissions. To resolve this you can run the following command from the root of the contents of the extracted zip file:

sudo chmod -R 755 runtimes/*

Once this has been done, then you should be able to run the installer successfully.

Step 3. Configure Database User Access

The installer creates a new security role in the database, analytics_middle_tier, with permission to query all of the views in the analytics schema. The database administrator will need to assign user(s) to this role as appropriate. This can be done by issuing a command like:

ALTER ROLE [analytics_middle_tier] ADD MEMBER [someUserName]

Note that this does not substitute for applying Row-Level Security Collection in the downstream applications. Since the user connecting to the database will have access to all students' data, the end-user application needs to provide its own appropriate row-limiting security features.

Step 4. Configure Descriptor Mappings

The installation process automatically loads descriptor mappings that match up with the default descriptors provided by the Ed-Fi Alliance in the "minimal template" install of the ODS / API. These need to be reviewed and customized for each field implementation.

For detailed information and instructions, please see Descriptor Mapping.

Step 5. Configure Optional Features

Some of the optional Collections have their own configurability mechanisms. Please review and apply instructions from each relevant collection below.

• Row-Level User Security: Configuration
• Early Warning System Collection: Configuration
• /wiki/spaces/EXCHANGE/pages/22488932