Page tree
Skip to end of metadata
Go to start of metadata

Compatibility

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

Ed-Fi ODS / APIData StandardDatabase Engine
2.5.1
2.6.0​
​2.2SQL Server 2016
SQL Server 2017

3.1.1
3.2.0

3.1SQL Server 2016
SQL Server 2017
3.3.03.2a

SQL Server 2016
SQL Server 2017

3.4.03.2bSQL Server 2016
SQL Server 2017
PostgreSQL 11 ((warning) experimental)
Suite 3, version 5.0.03.2.0-cSQL Server 2016
SQL Server 2017
PostgreSQL 11 ((warning) experimental)

Deprecation Notice

Support for Data Standard v2.2 will be removed in the next major release (v3.0). As new views are added to the Analytics Middle Tier 2.x.y, support for Data Standard v2.2 will be on a case-by-case basis.

PostgreSQL Status

Installation of the views in PostgreSQL works, however the output has not been fully verified in a large test database (e.g., Glendale). We expect to have a Glendale database on PostgreSQL in Q2-2020. At that time we will be able to perform detailed testing. We plan to remove the "experimental" notice and fully support PostgreSQL at the earliest opportunity.

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

PostgreSQL Tip

We recommend using a pgpass configuration file to store PostgreSQL user password. This approach allows the connection string to contain a database user name without requiring a password.

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. 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:

    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 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 "...").

Short Flag

Long Flag

Description

-c--connectionStringREQUIRED. Full connection string for the SQL server database on which to install the solution.
-e--engineOPTIONAL. Database engine, either SqlServer or PostgreSQL . Defaults to SqlServer.
-o--options

OPTIONAL. One or more optional use case collection names, space separated (e.g., EWS RLS CHRAB Indexes)  to install the four collections EWS, RLS, CHRAB, and Indexes. If left blank, the installer will only create the core views.

The current available options:

-u--uninstall

OPTIONAL. Default: false. Removes all views and indexes, leaving in place the tables configuration tables and role analytics_middle_tier.

(warning) Generally only used by developers.

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:

SQL Server
server=yourServer;database=EdFi_ODS_ReadOnly;integrated security=sspi;
PostgreSQL
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):

Core Views Only, SQL Server
cd Ed-Fi-Analytics-Middle-Tier\src
dotnet run --connectionString "..."
Core Views Only, PostgreSQL
cd Ed-Fi-Analytics-Middle-Tier\src
dotnet run --connectionString "..." --engine PostgreSQL
Optional Indexes and Early Warning System Collection, on SQL Server
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.

Core Views Only, SQL Server
cd Ed-Fi-Analytics-Middle-Tier\src
dotnet EdFi.AnalyticsMiddleTier.Console.dll --connectionString "..."
Core Views Only, PostgreSQL
cd Ed-Fi-Analytics-Middle-Tier\src
dotnet EdFi.AnalyticsMiddleTier.Console.dll --connectionString "..." --engine PostgreSQL
Optional Indexes and Early Warning System Collection, on SQL Server
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.

Core Views Only, SQL Server
cd EdFi.AnalyticsMiddleTier-win10.x64
.\EdFi.AnalyticsMiddleTier.Console.exe -c "..."
Core Views Only, PostgreSQL
cd EdFi.AnalyticsMiddleTier-win10.x64
.\EdFi.AnalyticsMiddleTier.Console.exe -c "..." -e PostgreSQL
Optional Indexes and Early Warning System Collection, on SQL Server
cd EdFi.AnalyticsMiddleTier-win10.x64
.\EdFi.AnalyticsMiddleTier.Console.exe -c "..." -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.

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.

Contents

  • No labels