diff --git a/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-docker-installation.md b/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-docker-installation.md index f2bb2a76..86ef13c9 100644 --- a/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-docker-installation.md +++ b/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-docker-installation.md @@ -1,19 +1,16 @@ # Admin API 1.x - Docker installation -# Before You Install +## Before You Install This section provides general information you should review before installing the Ed-Fi ODS / API Admin API for v1.4.0. -## Compatibility & Supported ODS / API Versions +### Compatibility & Supported ODS / API Versions This version of the Admin API has been tested and can be installed for use with -the Ed-Fi ODS / API v3.4 - 6.1. See the [Ed-Fi Technology Version -Index](https://edfi.atlassian.net/wiki/spaces/ETKB/pages/20875717/Ed-Fi+Technology+Version+Index) for more details. +the Ed-Fi ODS / API v3.4 - 6.1. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for more details. -# Installation Instructions - -## General Prerequisites +### General Prerequisites The following are required to install the Admin API: @@ -31,7 +28,7 @@ The following are required to install the Admin API: pre-installed browser on Windows Server) may load but may not function when using Admin API. -# Installation Instructions +## Installation Instructions Admin API is not included with the ODS-Docker solution by default, but can be hosted as part of that ecosystem. @@ -44,14 +41,14 @@ Then, apply the below changes to the environment to introduce the Admin API. Admin API does not support in-place upgrades from prior versions.  Please install a fresh copy of Admin API to upgrade from prior versions. -## 1\. Include Admin API in the ODS Docker Setup +### 1\. Include Admin API in the ODS Docker Setup -### Docker Compose +#### Docker Compose Add the following to your `docker-compose.yml`  file. This can be done either instead of or in addition to the `adminapp`  service. -#### Admin API Application +##### Admin API Application This service depends on the `pb-admin`  and subsequently `db-admin` services to run. @@ -89,7 +86,7 @@ adminapi: # ... below are network and volume configs ``` -#### Admin API Database +##### Admin API Database For the most part, the Admin API shares the same database schema as the Admin App. However, there are a few tables required for storing API client @@ -127,7 +124,7 @@ db-admin: # ... below are other services ``` -### .env Settings +#### .env Settings Add the following to your environment settings file to support Admin API. Note that when running both Admin App and Admin API, some of these settings may @@ -135,7 +132,7 @@ overlap. This is expected, and the same values can be used. **.env for Admin API** -```docker +```ini ADMIN_API_TAG= ADMIN_API_DB_TAG= API_MODE= @@ -164,14 +161,14 @@ ADMIN_API_HEALTHCHECK_TEST="curl -f http://${ADMIN_API_VIRTUAL_NAME}/health" API_INTERNAL_URL = http://${ODS_VIRTUAL_NAME} ``` -### Nginx / Gateway Configuration +#### Nginx / Gateway Configuration Update your nginx server configuration to include the Admin API in the reverse proxy. **default.conf.template** -```json +```none # upstream server config... server { @@ -191,7 +188,7 @@ server { } ``` -## 2\. Relaunch the Docker Composition +### 2\. Relaunch the Docker Composition After updating the files, restart the docker composition. @@ -199,7 +196,7 @@ After updating the files, restart the docker composition. docker compose -f ./compose/your-compose-file.yml --env-file ./.env up -d ``` -## 3\. Execute First-Time Configuration +### 3\. Execute First-Time Configuration Continue on to [First-Time Configuration for Admin 1.x](first-time-configuration-for-admin-api-1x.md). diff --git a/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-iis-installation-manual.md b/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-iis-installation-manual.md index 711a87e4..d2a96aa2 100644 --- a/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-iis-installation-manual.md +++ b/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-iis-installation-manual.md @@ -1,6 +1,6 @@ # Admin API 1.x - IIS Installation (Manual) -# Before You Install +## Before You Install This section provides general information you should review before installing the Ed-Fi ODS / API Admin API for v1.4.0. @@ -8,8 +8,7 @@ the Ed-Fi ODS / API Admin API for v1.4.0. ## Compatibility & Supported ODS / API Versions This version of the Admin API has been tested and can be installed for use with -the Ed-Fi ODS / API v3.4 - 6.1.  See the [Ed-Fi Technology Version -Index](https://edfi.atlassian.net/wiki/spaces/ETKB/pages/20875717/Ed-Fi+Technology+Version+Index) for +the Ed-Fi ODS / API v3.4 - 6.1.  See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for more details. ## Installation Instructions @@ -17,7 +16,7 @@ more details. ### Prerequisites A running instance of the ODS / API v3.4 - 6.1 platform must be configured and -running before installing Admin API.   +running before installing Admin API. Admin API only supports running one instance of the application at a time in an ODS / API ecosystem. Future versions may allow for scaling and load balancing. @@ -139,6 +138,7 @@ Here is a snippet from a properly configured application settings file: ``` #### **Step 5. Create Self-Signed Certificate in IIS Manager** + :::info This step is only necessary if you do not have a certificate from an existing ODS / API and Admin App installation in IIS. @@ -293,6 +293,7 @@ preference. CONSTRAINT PK_Tokens PRIMARY KEY (Id) ); ``` + ::: :::info note: SQL Server @@ -369,6 +370,7 @@ preference. CONSTRAINT PK_Tokens PRIMARY KEY (Id) ); ``` + ::: #### **Step 10. Execute First-Time Configuration** @@ -380,8 +382,8 @@ Continue on to [First-Time Configuration for Admin The following is a NuGet package containing the **Admin API v1.4.0 source** **files** for manual deployment to IIS. - * [EdFi.Suite3.ODS.AdminApi +* [EdFi.Suite3.ODS.AdminApi 1.4.0](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApi/overview/1.4.0) - * [Follow Binary Release for Admin App Database +* [Follow Binary Release for Admin App Database v2.3](https://edfi.atlassian.net/wiki/display/ADMIN/Admin+App+for+Suite+3+v2.3) ::: diff --git a/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-iis-installation-powershell.md b/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-iis-installation-powershell.md index 80b3ea5b..6f366c38 100644 --- a/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-iis-installation-powershell.md +++ b/docs/reference/3-admin-api/admin-api-1.x/installation-for-odsapi-5x-6x/admin-api-1x-iis-installation-powershell.md @@ -37,7 +37,7 @@ The following are required to install the Admin API with IIS: Each step is outlined in detail below for the PowerShell deployment. Ensure that you have permission to execute PowerShell scripts. For more information, -see [http://go.microsoft.com/fwlink/?LinkID=135170](http://go.microsoft.com/fwlink/?LinkID=135170). +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). #### **Step 1. Rename and Unzip Admin API Source Files** @@ -133,6 +133,7 @@ complete.     AdminApiFeatures = $adminApiFeatures } ``` + ::: :::info note: @@ -166,6 +167,7 @@ complete.     AdminApiFeatures = $adminApiFeatures } ``` + ::: #### **Step 3. Open a PowerShell Prompt in Administrator Mode** @@ -318,6 +320,7 @@ preference. CONSTRAINT PK_Tokens PRIMARY KEY (Id) ); ``` + ::: :::info note: @@ -396,6 +399,7 @@ preference. CONSTRAINT PK_Tokens PRIMARY KEY (Id) ); ``` + ::: #### **Step 9. Execute First-Time Configuration** @@ -407,8 +411,8 @@ Continue on to [First-Time Configuration for Admin The following is a Nuget package containing the **Admin API v1.4.0** binaries and installer scripts for deployment to IIS. - * [EdFi.Suite3.ODS.AdminApi +* [EdFi.Suite3.ODS.AdminApi 1.4.0](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApi/overview/1.4.0) - * [Follow Binary Release for Admin App Database +* [Follow Binary Release for Admin App Database v2.3](https://edfi.atlassian.net/wiki/display/ADMIN/Admin+App+for+Suite+3+v2.3) ::: diff --git a/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-docker-installation.md b/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-docker-installation.md index 64969792..3d61aeda 100644 --- a/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-docker-installation.md +++ b/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-docker-installation.md @@ -1,36 +1,33 @@ # Admin API 2.x - Docker installation -# Before You Install +## Before You Install This section provides general information you should review before installing the Ed-Fi ODS / API Admin API for v2.2.0. -## Compatibility & Supported ODS / API Versions +### Compatibility & Supported ODS / API Versions This version of the Admin API has been tested and can be installed for use with -Ed-Fi ODS / API v7.1. See the [Ed-Fi Technology Version -Index](https://edfi.atlassian.net/wiki/spaces/ETKB/pages/20875717/Ed-Fi+Technology+Version+Index) +Ed-Fi ODS / API v7.1. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for more details. -## Installation Instructions - ### General Prerequisites The following are required to install the Admin API: -* The Admin API provides an interface to administer an Ed-Fi ODS / API. - Understandably, you must have an instance of the Ed-Fi ODS / API v7.1 - deployed and operational before you can use the Admin API. Tested - configurations include on-premises installation via [binary - installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) - or [source code - installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation).  -* A SQL Server 2012 or higher, or Postgres 11 or higher database server (i.e., - the same platform requirement applicable to your ODS / API). -* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft - Edge is required to view live Swagger documentation. Internet Explorer 11 (a - pre-installed browser on Windows Server) may load but may not function when - using Admin API. +* The Admin API provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the Ed-Fi ODS / API v7.1 + deployed and operational before you can use the Admin API. Tested + configurations include on-premises installation via [binary + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) + or [source code + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation). +* A SQL Server 2012 or higher, or Postgres 11 or higher database server (i.e., + the same platform requirement applicable to your ODS / API). +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge is required to view live Swagger documentation. Internet Explorer 11 (a + pre-installed browser on Windows Server) may load but may not function when + using Admin API. ## Installation Instructions @@ -56,46 +53,40 @@ instead of or in addition to the `adminapp`  service. Docker compose -:::info note: - - Single-Tenant - - ```text - This service depends on the `pb-admin` and subsequently `db-admin` services to run. - # ... above are other services adminapi: - image: edfialliance/ods-admin-api:${ADMIN_API_TAG} - environment: ADMIN_POSTGRES_HOST: pb-admin - POSTGRES_PORT: "$PGBOUNCER_LISTEN_PORT:-6432}" - POSTGRES_USER: "${POSTGRES_USER}" - POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}" - DATABASEENGINE: "PostgreSql" - AUTHORITY: ${AUTHORITY} - ISSUER_URL: $ISSUER_URL} - SIGNING_KEY: ${SIGNING_KEY} - ADMIN_API_VIRTUAL_NAME: ${ADMIN_API_VIRTUAL_NAME:-adminapi} - API_INTERNAL_URL: ${API_INTERNAL_URL} - AppSettings__DefaultPageSizeOffset: ${PAGING_OFFSET:-0} - AppSettings__DefaultPageSizeLimit: ${PAGING_LIMIT:-25} - volumes: - ../../Docker/ssl:/ssl/ - depends_on: - pb-admin - restart: always - hostname: ${ADMIN_API_VIRTUAL_NAME:-adminapi} - container_name: adminapi - healthcheck: test: $$ADMIN_API_HEALTHCHECK_TEST - start_period: "60s" retries: 3 # ... - below are network and volume configs - ``` - ![](https://edfi.atlassian.net/wiki/images/icons/grey_arrow_down.png) -::: +```none title="Single-Tenant" +This service depends on the `pb-admin` and subsequently `db-admin` services to run. +# ... above are other services adminapi: +image: edfialliance/ods-admin-api:${ADMIN_API_TAG} +environment: ADMIN_POSTGRES_HOST: pb-admin +POSTGRES_PORT: "$PGBOUNCER_LISTEN_PORT:-6432}" +POSTGRES_USER: "${POSTGRES_USER}" +POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}" +DATABASEENGINE: "PostgreSql" +AUTHORITY: ${AUTHORITY} +ISSUER_URL: $ISSUER_URL} +SIGNING_KEY: ${SIGNING_KEY} +ADMIN_API_VIRTUAL_NAME: ${ADMIN_API_VIRTUAL_NAME:-adminapi} +API_INTERNAL_URL: ${API_INTERNAL_URL} +AppSettings__DefaultPageSizeOffset: ${PAGING_OFFSET:-0} +AppSettings__DefaultPageSizeLimit: ${PAGING_LIMIT:-25} +volumes: - ../../Docker/ssl:/ssl/ +depends_on: - pb-admin +restart: always +hostname: ${ADMIN_API_VIRTUAL_NAME:-adminapi} +container_name: adminapi +healthcheck: test: $$ADMIN_API_HEALTHCHECK_TEST +start_period: "60s" retries: 3 # ... +below are network and volume configs +``` -:::info note: +:::note - Multi-Tenant +Please consider having appsettings.dockertemplate.json file for defining tenant details. +File content example: - ```json - Note: - Please consider having appsettings.dockertemplate.json file for defining tenant details. - File content example: +::: + + ```json title="Multi-Tenant" {   "Tenants": {     "tenant1": { @@ -117,8 +108,9 @@ Docker compose   } } - Compose file section: - This service depends on db-admin-tenant1, db-admin-tenant2 services to run + Compose file section: This service depends on db-admin-tenant1, db-admin-tenant2 services to run + + ```none # ... above are other services adminapi: image: edfialliance/ods-admin-api:${ADMIN_API_TAG} @@ -153,7 +145,6 @@ Docker compose     retries: 3 # ... below are network and volumes configs ``` -::: ##### Admin API Database @@ -172,13 +163,9 @@ for your DB service. **If you are introducing Admin API to an existing composition do** NOT **change the volume mapping configuration in order to preserve your data**. Only change the image and tag of the existing service. The below block is a sample of -this, based on an example ODS / API Docker environment composition.  - -:::info note: +this, based on an example ODS / API Docker environment composition. - Single-Tenant - - ```docker + ```docker title="Single-Tenant" # ... above are other services db-admin: image: edfialliance/ods-admin-api-db:${ADMIN_API_DB_TAG} @@ -191,13 +178,8 @@ this, based on an example ODS / API Docker environment composition.  container_name: ed-fi-db-admin # ... below are other services ``` -::: - -:::info note: - Multi-Tenant - - ```docker + ```docker title="Multi-Tenant" # ... above are other services db-admin-tenant1:     image: edfialliance/ods-admin-api-db:${ADMIN_API_DB_TAG} @@ -232,7 +214,6 @@ this, based on an example ODS / API Docker environment composition.        retries: 3 # ... below are other services ``` -::: #### .env Settings @@ -240,9 +221,7 @@ Add the following to your environment settings file to support Admin API. Note that when running both Admin App and Admin API, some of these settings may overlap. This is expected, and the same values can be used. -**.env for Admin API** - -```docker +```docker title=".env for Admin API" ADMIN_API_TAG= ADMIN_API_DB_TAG= ADMIN_API_VIRTUAL_NAME= @@ -273,9 +252,7 @@ ADMIN_API_HEALTHCHECK_TEST="curl -f http://${ADMIN_API_VIRTUAL_NAME}/health" Update your nginx server configuration to include the Admin API in the reverse proxy. -**default.conf.template** - -```json +```json title="default.conf.template" # upstream server config... server { @@ -299,7 +276,7 @@ server { After updating the files, restart the docker composition. -```shell +```bash docker compose -f ./compose/your-compose-file.yml --env-file ./.env up -d ``` @@ -308,9 +285,12 @@ docker compose -f ./compose/your-compose-file.yml --env-file ./.env up -d Continue on to [First-Time Configuration for Admin API 2.x](first-time-configuration-for-admin-api-2x.md). -:::info note: - The following is the DockerHub repo for **Admin API v2.2.0 Docker Image** for inclusion in Docker compose: - * [edfialliance/ods-admin-api:v2.2.0](https://hub.docker.com/layers/edfialliance/ods-admin-api/v2.2.0/images/sha256-0e818c3741e4dea8473af1b52d25a512684f27bf9529fc43a5c9954e00dc5b0d?context=explore) +:::info + +The following is the DockerHub repo for **Admin API v2.2.0 Docker Image** for inclusion in Docker compose: + +* [edfialliance/ods-admin-api:v2.2.0](https://hub.docker.com/layers/edfialliance/ods-admin-api/v2.2.0/images/sha256-0e818c3741e4dea8473af1b52d25a512684f27bf9529fc43a5c9954e00dc5b0d?context=explore) + +* [edfialliance/ods-admin-api-db:v2.2.0](https://hub.docker.com/layers/edfialliance/ods-admin-api-db/v2.2.0/images/sha256-ad0563347f65d9c44bfab6fffee302d6793be4ea84e6d0369242c6cd15a17d39?context=explore) - * [edfialliance/ods-admin-api-db:v2.2.0](https://hub.docker.com/layers/edfialliance/ods-admin-api-db/v2.2.0/images/sha256-ad0563347f65d9c44bfab6fffee302d6793be4ea84e6d0369242c6cd15a17d39?context=explore) ::: diff --git a/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-iis-installation-manual.md b/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-iis-installation-manual.md index c55e731f..ec39db65 100644 --- a/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-iis-installation-manual.md +++ b/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-iis-installation-manual.md @@ -1,23 +1,20 @@ # Admin API 2.x - IIS Installation (Manual) -# Before You Install +## Before You Install This section provides general information you should review before installing the Ed-Fi ODS / API Admin API for v2.2.0. -## Compatibility & Supported ODS / API Versions +### Compatibility & Supported ODS / API Versions This version of the Admin API has been tested and can be installed for use with -the Ed-Fi ODS / API v7.1.  See the [Ed-Fi Technology Version -Index](https://edfi.atlassian.net/wiki/spaces/ETKB/pages/20875717/Ed-Fi+Technology+Version+Index) for +the Ed-Fi ODS / API v7.1.  See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for more details. -## Installation Instructions - ### Prerequisites A running instance of the ODS / API v7.1 platform must be configured and running -before installing Admin API.   +before installing Admin API. Admin API only supports running one instance of the application at a time in an ODS / API ecosystem. Future versions may allow for scaling and load balancing. @@ -38,7 +35,7 @@ The following are required to install the Admin API with IIS: ### **Step 1. Create Admin API Directory** Create a directory to hold all of the Admin API source files. In this example, -we'll use a directory on the following path: "C:\\Ed-Fi\\AdminAPI". +we'll use a directory on the following path: `C:\Ed-Fi\AdminAPI`. ![Empty Installation Folder](https://odsassets.blob.core.windows.net/public/docs.ed-fi.org/reference/3-admin-api/img/installation-v2/Empty%20Installation%20Folder.png) @@ -78,7 +75,7 @@ step. ### **Step 4. Configure App/Web Configuration Files** You will need to manually edit connection strings, authorization settings, and -keys in "AdminApi\\appsettings.json". Some values to note: +keys in `AdminApi\appsettings.json`. Some values to note: * Authentication Settings * `Authentication:SigningKey`  must be a Base64-encoded 256-bit string. The @@ -117,42 +114,42 @@ keys in "AdminApi\\appsettings.json". Some values to note: Here is a snippet from a properly configured application settings file: -**appsettings.json** - -```json - "AppSettings": { - "DatabaseEngine": "SqlServer", - "PathBase": "", -        "DefaultPageSizeOffset": 0, - "DefaultPageSizeLimit": 25, -        "MultiTenancy": false +```json title="appsettings.json" +{ + "AppSettings": { + "DatabaseEngine": "SqlServer", + "PathBase": "", +       "DefaultPageSizeOffset": 0, + "DefaultPageSizeLimit": 25, +       "MultiTenancy": false       }, - "Authentication": { - "Authority": "https://YOUR_SERVER_NAME_HERE/AdminApi", - "IssuerUrl": "https://YOUR_SERVER_NAME_HERE/AdminApi", - "SigningKey": "YOUR_BASE64_ENCODED_256_BIT_STRING", - "AllowRegistration": false - }, + "Authentication": { + "Authority": "https://YOUR_SERVER_NAME_HERE/AdminApi", + "IssuerUrl": "https://YOUR_SERVER_NAME_HERE/AdminApi", + "SigningKey": "YOUR_BASE64_ENCODED_256_BIT_STRING", + "AllowRegistration": false + },     "SwaggerSettings": { - "EnableSwagger": false, - "DefaultTenant": "" - }, + "EnableSwagger": false, + "DefaultTenant": "" + },     "EnableDockerEnvironment": false, - "ConnectionStrings": { - "Admin": "Data Source=(local);Initial Catalog=EdFi_Admin;Trusted_Connection=True", - "Security": "Data Source=(local);Initial Catalog=EdFi_Security;Trusted_Connection=True" - }, - "Log4NetCore": { - "Log4NetConfigFileName": "log4net\\log4net.config" - }, - "Logging": { - "LogLevel": { - "Default": "Information", - "Microsoft": "Warning", - "Microsoft.Hosting.Lifetime": "Information" - } - }, - "AllowedHosts": "*" + "ConnectionStrings": { + "Admin": "Data Source=(local);Initial Catalog=EdFi_Admin;Trusted_Connection=True", + "Security": "Data Source=(local);Initial Catalog=EdFi_Security;Trusted_Connection=True" + }, + "Log4NetCore": { + "Log4NetConfigFileName": "log4net\\log4net.config" + }, + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + }, + "AllowedHosts": "*" +} ``` ### **Step 5. Create Self-Signed Certificate in IIS Manager** @@ -250,71 +247,69 @@ etc..) Execute the below script against the EdFi\_Admin database using psql , PgAdmin, or the tool of your choice. - **adminapi-tables-pgsql.sql** - - ```sql - CREATE SCHEMA IF NOT EXISTS adminapi; - - CREATE TABLE adminapi.Applications ( - Id INT NOT NULL GENERATED ALWAYS AS IDENTITY, - ConcurrencyToken VARCHAR(128) NULL, - ClientId VARCHAR(256) NULL, - ClientSecret VARCHAR(256) NULL, - Type VARCHAR(256) NULL, - ConsentType VARCHAR(256) NULL, - Permissions VARCHAR NULL, - Properties VARCHAR NULL, - Requirements VARCHAR NULL, - DisplayName VARCHAR(256) NULL, - DisplayNames VARCHAR NULL, - RedirectUris VARCHAR NULL, - PostLogoutRedirectUris VARCHAR NULL, - CONSTRAINT PK_Applications PRIMARY KEY (Id) - ); - - CREATE TABLE adminapi.Scopes ( - Id INT NOT NULL GENERATED ALWAYS AS IDENTITY, - Name VARCHAR(256) NULL, - ConcurrencyToken VARCHAR(128) NULL, - Description VARCHAR NULL, - Descriptions VARCHAR NULL, - DisplayName VARCHAR(256) NULL, - DisplayNames VARCHAR NULL, - Properties VARCHAR NULL, - Resources VARCHAR NULL, - CONSTRAINT PK_Scopes PRIMARY KEY (Id) - ); - - CREATE TABLE adminapi.Authorizations ( - Id INT NOT NULL GENERATED ALWAYS AS IDENTITY, - ConcurrencyToken VARCHAR(128) NULL, - ApplicationId int NOT NULL, - Scopes VARCHAR NULL, - Subject VARCHAR(256) NULL, - Status VARCHAR(256) NULL, - Properties VARCHAR NULL, - CreationDate TIMESTAMP NULL, - CONSTRAINT PK_Authorizations PRIMARY KEY (Id), - CONSTRAINT FK_AuthorizationsId_ApplicationId FOREIGN KEY ApplicationId) REFERENCES adminapi.Applications (Id) ON DELETE RESTRICT - ); - - CREATE TABLE adminapi.Tokens ( - Id INT NOT NULL GENERATED ALWAYS AS IDENTITY, - ConcurrencyToken VARCHAR(128) NULL, - ApplicationId int NULL, - AuthorizationId int NULL, - Type VARCHAR(256) NULL, - CreationDate TIMESTAMP NULL, - ExpirationDate TIMESTAMP NULL, - RedemptionDate TIMESTAMP NULL, - Payload VARCHAR NULL, - Properties VARCHAR NULL, - Subject VARCHAR(256) NULL, - Status VARCHAR(256) NULL, - ReferenceId VARCHAR(256) NULL, - CONSTRAINT PK_Tokens PRIMARY KEY (Id) - ); - ``` +```sql title="adminapi-tables-pgsql.sql" +CREATE SCHEMA IF NOT EXISTS adminapi; + +CREATE TABLE adminapi.Applications ( + Id INT NOT NULL GENERATED ALWAYS AS IDENTITY, + ConcurrencyToken VARCHAR(128) NULL, + ClientId VARCHAR(256) NULL, + ClientSecret VARCHAR(256) NULL, + Type VARCHAR(256) NULL, + ConsentType VARCHAR(256) NULL, + Permissions VARCHAR NULL, + Properties VARCHAR NULL, + Requirements VARCHAR NULL, + DisplayName VARCHAR(256) NULL, + DisplayNames VARCHAR NULL, + RedirectUris VARCHAR NULL, + PostLogoutRedirectUris VARCHAR NULL, + CONSTRAINT PK_Applications PRIMARY KEY (Id) +); + +CREATE TABLE adminapi.Scopes ( + Id INT NOT NULL GENERATED ALWAYS AS IDENTITY, + Name VARCHAR(256) NULL, + ConcurrencyToken VARCHAR(128) NULL, + Description VARCHAR NULL, + Descriptions VARCHAR NULL, + DisplayName VARCHAR(256) NULL, + DisplayNames VARCHAR NULL, + Properties VARCHAR NULL, + Resources VARCHAR NULL, + CONSTRAINT PK_Scopes PRIMARY KEY (Id) +); + +CREATE TABLE adminapi.Authorizations ( + Id INT NOT NULL GENERATED ALWAYS AS IDENTITY, + ConcurrencyToken VARCHAR(128) NULL, + ApplicationId int NOT NULL, + Scopes VARCHAR NULL, + Subject VARCHAR(256) NULL, + Status VARCHAR(256) NULL, + Properties VARCHAR NULL, + CreationDate TIMESTAMP NULL, + CONSTRAINT PK_Authorizations PRIMARY KEY (Id), + CONSTRAINT FK_AuthorizationsId_ApplicationId FOREIGN KEY ApplicationId) REFERENCES adminapi.Applications (Id) ON DELETE RESTRICT +); + +CREATE TABLE adminapi.Tokens ( + Id INT NOT NULL GENERATED ALWAYS AS IDENTITY, + ConcurrencyToken VARCHAR(128) NULL, + ApplicationId int NULL, + AuthorizationId int NULL, + Type VARCHAR(256) NULL, + CreationDate TIMESTAMP NULL, + ExpirationDate TIMESTAMP NULL, + RedemptionDate TIMESTAMP NULL, + Payload VARCHAR NULL, + Properties VARCHAR NULL, + Subject VARCHAR(256) NULL, + Status VARCHAR(256) NULL, + ReferenceId VARCHAR(256) NULL, + CONSTRAINT PK_Tokens PRIMARY KEY (Id) +); +``` ::: @@ -326,9 +321,7 @@ etc..) Management Studio, Azure Data Studio, PowerShell SQL Tools, or the tool of your choice. - **adminapi-tables-mssql.sql** - - ```sql + ```sql title="adminapi-tables-mssql.sql" IF NOT EXISTS (SELECT 1 FROM sys.schemas WHERE name = 'adminapi') BEGIN EXEC( 'CREATE SCHEMA adminapi' ); diff --git a/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-iis-installation-powershell.md b/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-iis-installation-powershell.md index 1aae3d75..7c217405 100644 --- a/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-iis-installation-powershell.md +++ b/docs/reference/3-admin-api/admin-api-2.x/installation-for-odsapi-7x/admin-api-2x-iis-installation-powershell.md @@ -17,7 +17,7 @@ more details. ### Prerequisites A running instance of the ODS / API v7.1 platform must be configured and running -before installing Admin API.   +before installing Admin API. Admin API only supports running one instance of the application at a time in an ODS / API ecosystem. Future versions may allow for scaling and load balancing. @@ -37,7 +37,7 @@ The following are required to install the Admin API with IIS: Each step is outlined in detail below for the PowerShell deployment. Ensure that you have permission to execute PowerShell scripts. For more information, -see [http://go.microsoft.com/fwlink/?LinkID=135170](http://go.microsoft.com/fwlink/?LinkID=135170). +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). #### **Step 1. Rename and Unzip Admin API Source Files** @@ -113,6 +113,7 @@ Database engine specific connection information ($dbConnectionInfo):         Password = "examplePassword" } ``` + ::: :::info note: @@ -128,6 +129,7 @@ Database engine specific connection information ($dbConnectionInfo):         Password = "examplePassword" } ``` + ::: :::info note: @@ -153,6 +155,7 @@ Database engine specific connection information ($dbConnectionInfo):   AuthenticationSettings = $authenticationSettings } ``` + ::: :::info note: @@ -189,6 +192,7 @@ Database engine specific connection information ($dbConnectionInfo):   } } ``` + ::: #### **Step 3. Open a PowerShell Prompt in Administrator Mode** @@ -275,6 +279,6 @@ Continue on to [First-Time Configuration for Admin API The following is a Nuget package containing the **Admin API v2.2.0** binaries and installer scripts for deployment to IIS. - * [EdFi.Suite3.ODS.AdminApi +* [EdFi.Suite3.ODS.AdminApi v2.2.0](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApi/overview/2.2.0) ::: diff --git a/docs/reference/3-admin-api/admin-api-2.x/readme.md b/docs/reference/3-admin-api/admin-api-2.x/readme.md index f3b9d7c7..23865122 100644 --- a/docs/reference/3-admin-api/admin-api-2.x/readme.md +++ b/docs/reference/3-admin-api/admin-api-2.x/readme.md @@ -3,7 +3,7 @@ The Ed-Fi Admin API is an API-based administrative interface for the Ed-Fi ODS / API Platform. The Admin API is available as a standalone application, and is also available for deployments on Docker. The Admin API v2.2 is available for -[Ed-Fi ODS / API v7.x](https://docs.ed-fi.org/reference/ods-api). +[Ed-Fi ODS / API v7.x](/reference/ods-api). ## Documentation diff --git a/docs/reference/3-admin-api/readme.md b/docs/reference/3-admin-api/readme.md index 7b27b3ba..7a24d443 100644 --- a/docs/reference/3-admin-api/readme.md +++ b/docs/reference/3-admin-api/readme.md @@ -3,7 +3,7 @@ The Ed-Fi Admin API is an API-based administrative interface for the Ed-Fi ODS / API Platform. The Admin API is available as a standalone application, and is also available for deployments on Docker. The Admin API v2.2 is available for -[Ed-Fi ODS / API v7.x](https://docs.ed-fi.org/reference/ods-api) and Admin API +[Ed-Fi ODS / API v7.x](/reference/ods-api) and Admin API 1.4 is available for [Ed-Fi ODS / API v5.x-6.x](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V62/overview). diff --git a/docs/reference/8-admin-app/getting-started/installation/admin-app-v33.md b/docs/reference/8-admin-app/getting-started/installation/admin-app-v33.md new file mode 100644 index 00000000..ca29fdac --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/admin-app-v33.md @@ -0,0 +1,361 @@ +# Admin App v3.3 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App v3.3 for ODS/API 3.4 to 6.2. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App has been tested and can be installed for use +with the Ed-Fi ODS / API 3.4 to 6.2. See the [Ed-Fi Technology Suite Supported Versions](../../../0-roadmap/supported-versions.md) for +more details. + +Admin App supports two deployment modes:  Docker Deployment and On-Premise +Installation, as documented below.  Please choose the deployment mode that fits +your environment. + +## Docker Deployment for Admin App + +Docker image for Admin App 3.3 is available at: +[https://hub.docker.com/r/edfialliance/ods-admin-app](https://hub.docker.com/r/edfialliance/ods-admin-app) + +Please refer [Docker Deployment - Ed-Fi Tools - Ed-Fi Tech Docs](../../../7-docker/readme.mdx) for +more details. + +## On-Premise Installation + +## Prerequisites + +The following are required to install the Admin App: + +:::info note: + Below are links to Nuget packages containing the Admin App Installer + or App Binaries. Download from the link and rename  the file extension to +  `.zip,` or use the PowerShell command from Step 1 below. **Admin App v3.3:** + [EdFi.Suite3.Installer.AdminApp.3.3.1.0.nupkg](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApp.Web/overview/3.3.1) +::: + +:::info note + The following is the DockerHub repo for **Admin App v3.3.1 Docker + Image** for inclusion in Docker compose: + +* [edfialliance/ods-admin-app:v3.3.1](https://hub.docker.com/layers/edfialliance/ods-admin-app/v3.3.1/images/sha256-ebc0ab6b1aafff1788477f97a0e86bcb46e1e9a1dfddfda69a69593cb8b19395?context=explore) +::: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the supported Ed-Fi ODS / API + deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via [binary + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V62/pages/18219081/Getting+Started+-+Binary+Installation) + or [source code + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V62/pages/18219161/Getting+Started+-+Source+Code+Installation). +* Both the [.NET 8 SDK and .NET 8 Hosting + Bundle](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) are required + on the destination server before installation of Admin App. + * After installing the .NET Core SDK and the .NET Core SDK, it is necessary + to restart the computer for the changes to take effect. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as + also in use with your ODS / API v6.0 installation. +* IIS must be enabled before installing .NET Core Hosting Bundle. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + + Admin App does not today support in-place upgrades from prior versions. + Please install a fresh copy of Admin App to upgrade from prior versions. + + ## Required Information + + You will need the following information to complete this installation: + + * The location of your Ed-Fi ODS / API. + * Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + + This section provides step-by-step instructions for installation. The + specific steps are different depending on the deployment model and version + of your Ed-Fi ODS / API. + +## On-Premises Deployment + + Each step is outlined in detail below for the PowerShell deployment. Ensure + that you have permission to execute PowerShell scripts. For more + information, + see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + + Download , rename the file extension from to `.zip`  and unzip the package + +* Installer and binaries for Admin App 3.3: + [EdFi.Suite3.ODS.AdminApp.Web.3.3.1.nupkg](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApp.Web/overview/3.3.1) + + Alternatively, run the below PowerShell command to download the package as a + zip file directly: + + ```shell + # Web App Binaries + Invoke-WebRequest "https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/3.2.1/content?api-version=6.0-preview.1" -OutFile .\EdFi.Suite3.ODS.AdminApp.Web-3.2.1.0.zip + ``` + + ### Step 2. Configure Installation File + + Open the "install.ps1" file on installer folder in a text editor. You will + need to edit this file with your configuration details. If a value is not + present for any of the parameters, it will use its default value. + + :::info note: + Editing Item 3b below is mandatory for ODS / API URL and must be + done for installation to complete. + ::: + + 1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can + use "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + c1. If you plan to use Windows authentication, this value will be + "$true" + c2. If you plan to use SQL Server/ PostgreSQL server authentication, + this value will be "$false" and the Username and `Password` must + be provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is + not needed + + f. `Port.` Optional. Used to specify the database server port, presuming + the server is configured to use the specific port. + + 2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 + minute security metadata cache timeout. + + 3. Configure `$p`. This is the variable used to send all the information to + the installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + c1. For example, when configuring the `OdsDatabaseName`, the value + here will be the name of the ODS database, whereas the + `AdminDatabaseName` and `SecurityDatabaseName` will be the name + of the Admin and Security databases, respectively. + + d. `WebApplicationName.` Optional. Defaults to "AdminApp". + + e. `WebSitePort`. Optional. Defaults to 443. + + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + + Configuration samples for the "install.ps1" file: + + :::info note: + + SQL Server Shared Instance + + ```json title="install.ps1 for MSSQL" + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + } + ``` + + PostgreSQL District Specific + + ```json title="install.ps1 for PostgreSQL" + $dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" + } + + $adminAppFeatures = @{ + ApiMode = "districtspecific" + } + + $parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + + SQL Server Year Specific + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $adminAppFeatures = @{ + ApiMode = "yearspecific" + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + + ::: + + ### Step 3. Open a PowerShell Prompt in Administrator Mode + + Method 1: Open \[Windows Key\]-R which will open a Run dialog for tasks needing administrative privileges. Type "PowerShell" to open a PowerShell prompt in Administrator mode. + + ![windows shell](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/image2020-4-20_12-37-43.png) + + Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" and right-click the "Windows PowerShell" option when provided. Select "Run as Administrator" to open a PowerShell prompt in Administrator mode. + + ![windows menu](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/image2020-4-20_12-37-57.png) + + Change the directory to the unzipped directory for the Admin App Installer. + + ### Step 4. Run the Installation via PowerShell + + Run "install.ps1" script. + + ### Database login setup on integrated security mode + + During the installation process, you will be prompted to choose database login details. Entering "Y" will continue with default option( Installation process will create IIS APPPOOL\\AdminApp database login on the server). + + Choosing 'n' will prompt you to enter windows username. The installation process will validate and create database login using entered username, if the login does not exist on the database server already. + + ![pws sql logins](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/image2022-9-20_12-7-6.png) + + ![pws sql login authorization](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/image2022-9-20_12-8-32.png) + + Please refer Steps 5 and 6 for more details on verifying the database login and setting up the application pool identity. + + The PowerShell output will look something like the following: + + ![pws main results](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/Successful-Installation.JPG) + + ### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + + This step only needs to be completed if you set `useIntegratedSecurity` to true on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead to Step 5. + + The installation process sets up an appropriate SQL Login for use with the dedicated AdminApp Application Pool in IIS. You can verify this in SQL Server Management Studio: + + ![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/SqlLogin.JPG) + +* On the Server Roles page, make sure that  "public" and "sysadmin" checkboxes + are checked. Once you have confirmed a proper SQL Server login exists, + continue to the next step. + + ![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/SQLLogin-role.JPG) + + ### Step 6. Update Application Pool Identity (Optional) + + As mentioned on Step 5, installation process sets up an appropriate SQL + Login for use with the dedicated AdminApp Application Pool in IIS. If you + would like to use the default "ApplicationPoolIdentity", then you can skip + this bit. + + Else in the same Advanced Settings window, click on the browse icon under + Process Model > Identity. We'll choose the custom account option and click + "Set...". When setting the credentials, you can just use the username and + password that you use to log in to Windows. If you need to include the app + pool domain in the username, then the username can look something like this: + "localhost\\username", where "localhost" is the app pool domain. Once we + have entered the correct credentials, we'll click OK on all screens until + we're back to the main Application Pools page. + + ![sql set credentials](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/image2022-9-20_12-24-43.png) + + ### Step 7. Check Folder Permissions + + Folders to verify: + + 1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). + 2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + + For checking permissions: + + * **Right-click** the folder, choose **Properties**, view the **Security** + tab. + * Verify the "Group or user names" section has AdminApp with Full control. + + ![Upload-folder-permission.JPG](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/Upload-folder-permission.JPG) + + If the AdminApp not available on the list, add with Full control. + + ![AddFolderPermission.JPG](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/AddFolderPermission.JPG) + + Note: If you choose custom login over default Application Pool Identity ( + Refer Step 6 for more details), then make sure the custom login has full + control on the above mentioned folders. + + ### Step 8. Create Initial Administrative User + + Upon first launch of the Admin App, you will have to create the initial + administrative user for the application. This consists of creating a + username and password for the initial user. Additional users can be added at + a later time. Please see [Securing the Admin + App](../../getting-started/securing-the-admin-app) for more information. + + ### Step 9. Open Admin App to Complete Installation + + The installation will default to `https:///AdminApp`. + + To verify and launch the Admin App, open "Internet Information Services + (IIS) Manager". Open the server name, open the Sites folder and open the + Ed-Fi branch. Observe three web applications have been installed for the + Ed-Fi Tech Suite. Clicking on "AdminApp", use Manage Application to view the + configured URL. Click on "Browse ``" to launch Admin App. + + ![image2020-4-20_12-37-43.png](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/installation/image2020-4-20_12-37-43.png) + + ### Step 10. Using the Admin App + + The Admin App is now configured for use with your Ed-Fi ODS / API instance. + Please visit the following articles to help with next actions in using Admin + App: + + * [Securing the Admin App](../../getting-started/securing-the-admin-app) + * [Multi-Instance + Connections](../../getting-started/multi-instance-connections) + * [Next Steps](../../getting-started/next-steps) + * [Known Issues](../../getting-started/known-issues) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v201.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v201.md new file mode 100644 index 00000000..9244739a --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v201.md @@ -0,0 +1,265 @@ +# Admin App for Suite 3 v2.0.1 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App for Suite 3 v2.0.1. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App can be installed for use with the Ed-Fi ODS / +API v3.4 and v5.0.0. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +## Prerequisites + +The following are required to install the Admin App: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the Ed-Fi ODS / API v3.4 or + v5.0.0 deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via the Tech Suite + Installer or [manual installation via source + code](https://edfi.atlassian.net/wiki/display/ODSAPI34/Getting+Started). +* The [.NET Framework 4.8 + Runtime](https://dotnet.microsoft.com/download/dotnet-framework/thank-you/net48-web-installer) and + [.NET Core 3.1 + SDK](https://dotnet.microsoft.com/download/dotnet-core/thank-you/sdk-3.1.301-windows-x64-installer) + is required on the destination server before installation of Admin App. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v3.4 or v5.0.0 installation. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +You can download the EdFi.Suite3.Installer.AdminApp.2.0.1 package from the link +in the sidebar to the right, rename it to \*.zip and extract it as you would any +zip file. Alternatively, you can accomplish the same with PowerShell. Open +PowerShell and change to a temporary directory, then download and open the +EdFi.Suite3.Installer.AdminApp package. The following script downloads the +package, opens it, changes to the unzipped directory, and opens Windows Explorer +in that location: + +```shell +cd c:\temp +$url = "https://www.myget.org/F/ed-fi/api/v2/package/EdFi.Suite3.Installer.AdminApp/2.0.1" +$pkg = "EdFi.Suite3.Installer.AdminApp.2.0.1" +Invoke-RestMethod $url -OutFile "$pkg.zip" +Expand-Archive "$pkg.zip" +cd $pkg +explorer . +``` + +### Step 2. Configure Installation + +Open the "install.ps1" file. You will need to edit this file with your +configuration details. If a value is not present for any of the parameters, it +will use its default value. + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + + c1. If you plan to use Windows authentication, this value will be "$true" + + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + + b. `OdsApiUrl`. Base URL for the ODS / API. Mandatory. + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + d. `WebApplicationName`, `WebApplicationPath`. Optional. Defaults + to "AdminApp" and "C:\\inetpub\\Ed-Fi\\AdminApp" respectively. + + e. `WebSitePort`. Optional. Defaults to 443. + + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Below is an example of the configuration of the "install.ps1" file for SQL +Server with `sharedinstance` mode: + +**install.ps1(SQLServer)** Expand source + +```json +$dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true +} + +$p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" +} +``` + +Below is an example of the configuration of the "install.ps1" file for +PostgreSQL with districtspecific mode: + +**install.ps1(PostgreSQL)** Expand source + +```json +$dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" +} + +$adminAppFeatures = @{ + ApiMode = "districtspecific" +} + +$parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures +} + +``` + +### Step 3. Run the Installation via PowerShell + +Run "install.ps1" script. + +The PowerShell output will look something like the following: + +![Run Powershell](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 4. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +Now that the installation has finished, follow these steps to create a new SQL +Server login for the AdminApp Application Pool: + +* Open SQL Server Management Studio and at the server-level, expand the + "Security" folder. **Right-click**, select **Logins** > **New Login...** +* For the Login Name, enter "IIS APPPOOL\\AdminApp". +* On the left side of the pop-up window, select the **Server Roles** tab and + ensure the "sysadmin" checkbox is checked. +* Everything else can be left at the default setting. +* Once you're done, click **OK**. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 5. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +### Step 6. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. + +### Step 7. Restart the ODS / API + +To finish the Admin App on-premises setup, the ODS / API should be restarted. + +Steps for restarting the ODS / API: + +* Open IIS Manager (inetmgr). +* In the Connections pane on the left, expand **Sites** and locate the **Ed-Fi** + website. +* **Right-click** the website and select **Manage Website** > **Restart**. +* Close IIS Manager. + +### Step 8. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Multi-Instance + Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v21.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v21.md new file mode 100644 index 00000000..ddac7102 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v21.md @@ -0,0 +1,275 @@ +# Admin App for Suite 3 v2.1 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App for Suite 3 v2.1. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App can be installed for use with the Ed-Fi ODS / +API v3.4, v5.0.0 and v5.1.0. See the [Ed-Fi Technology Version Index](/reference/roadmap/supported-versions) for +more details. + +## Prerequisites + +The following are required to install the Admin App: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the Ed-Fi ODS / API v3.4, v5.0.0 + or v5.1.0 deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via [Binary + Installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) + or [Source Code + Installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation). +* The [.NET Framework 4.8 + Runtime](https://dotnet.microsoft.com/download/dotnet-framework/thank-you/net48-web-installer) and + [.NET Core 3.1 + SDK](https://dotnet.microsoft.com/download/dotnet-core/thank-you/sdk-3.1.301-windows-x64-installer) + is required on the destination server before installation of Admin App. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v3.4, v5.0.0 or v5.1.0 installation.  .NET + Framework 4.8 Runtime is still needed for the PowerShell installations + scripts. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +Admin App does not today support in-place upgrades from prior versions.  Please +install a fresh copy of Admin App to upgrade from prior versions. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +* Admin App for Suite 3 v2.1 +* [Before You Install](#before-you-install) +* [Compatibility \& Supported ODS / API Versions](#compatibility--supported-ods--api-versions) +* [Prerequisites](#prerequisites) +* [Required Information](#required-information) +* [Installation Instructions](#installation-instructions) +* [On-Premises Deployment](#on-premises-deployment) + * [Step 1. Download and Open Installer Package](#step-1-download-and-open-installer-package) + * [Step 2. Configure Installation](#step-2configure-installation) + * [Step 3. Run the Installation via PowerShell](#step-3-run-the-installation-via-powershell) + * [Step 4. Create SQL Server Login (if "useIntegratedSecurity" set to "true")](#step-4-create-sql-server-login-if-useintegratedsecurity-set-to-true) + * [Step 5. Check Folder Permissions](#step-5check-folder-permissions) + * [Step 6. Create Initial Administrative User](#step-6-create-initial-administrative-user) + * [Step 7. Restart the ODS / API](#step-7-restart-theods--api) + * [Step 8. Using the Admin App](#step-8-using-the-admin-app) + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +Download and +unzip [AdminAppInstaller.2.1.0.zip](https://odsassets.blob.core.windows.net/public/adminapp/AdminAppInstaller.2.1.0.zip). + +### Step 2. Configure Installation + +Open the "install.ps1" file in a text editor. You will need to edit this file +with your configuration details. If a value is not present for any of the +parameters, it will use its default value. + +**Editing Step 3b is mandatory and must be done for installation to complete.** + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + + c1. If you plan to use Windows authentication, this value will be "$true" + + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + d. `WebApplicationName`, `WebApplicationPath`. Optional. Defaults + to "AdminApp" and "C:\\inetpub\\Ed-Fi\\AdminApp" respectively. + + e. `WebSitePort`. Optional. Defaults to 443. + + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Below is an example of the configuration of the "install.ps1" file for SQL +Server with `sharedinstance` mode: + +**install.ps1(SQLServer)** Expand source + +```json +$dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true +} + +$p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" +} +``` + +Below is an example of the configuration of the "install.ps1" file for +PostgreSQL with districtspecific mode: + +**install.ps1(PostgreSQL)** Expand source + +```json +$dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" +} + +$adminAppFeatures = @{ + ApiMode = "districtspecific" +} + +$parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures +} +``` + +### Step 3. Run the Installation via PowerShell + +Run "install.ps1" script. + +The PowerShell output will look something like the following: + +![Pws Installation](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 4. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +Now that the installation has finished, follow these steps to create a new SQL +Server login for the AdminApp Application Pool: + +* Open SQL Server Management Studio and at the server-level, expand the + "Security" folder. **Right-click**, select **Logins** > **New Login...** +* For the Login Name, enter "IIS APPPOOL\\AdminApp". +* On the left side of the pop-up window, select the **Server Roles** tab and + ensure the "sysadmin" checkbox is checked. +* Everything else can be left at the default setting. +* Once you're done, click **OK**. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 5. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +### Step 6. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. Please see [Securing the Admin App (v2.x)](../../securing-the-admin-app.md) for more +information. + +### Step 7. Restart the ODS / API + +To finish the Admin App on-premises setup, the ODS / API should be restarted, +which Admin App will advise. + +Steps for restarting the ODS / API: + +* Open IIS Manager (inetmgr). +* In the Connections pane on the left, expand **Sites** and locate the **Ed-Fi** + website. +* **Right-click** the website and select **Manage Website** > **Restart**. +* Close IIS Manager. + +### Step 8. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App (v2.x)](../../securing-the-admin-app.md) +* [Multi-Instance Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v22.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v22.md new file mode 100644 index 00000000..085ef2e8 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v22.md @@ -0,0 +1,350 @@ +# Admin App for Suite 3 v2.2 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App for Suite 3 v2.2. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App has been tested and can be installed for use +with the Ed-Fi ODS / API v3.4 through v5.2. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +## Prerequisites + +The following are required to install the Admin App: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the Ed-Fi ODS / API v3.4 through + v5.2 deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via [via source + code](https://edfi.atlassian.net/wiki/display/ODSAPI34/Getting+Started). +* The [.NET Framework 4.8 + Runtime](https://dotnet.microsoft.com/download/dotnet-framework/thank-you/net48-web-installer) and + [.NET Core 3.1 + SDK](https://dotnet.microsoft.com/download/dotnet-core/thank-you/sdk-3.1.301-windows-x64-installer) + is required on the destination server before installation of Admin App. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v3.4, v5.0.0, v5.1.0, and v5.2.0 installation. + .NET Framework 4.8 Runtime is still needed for the PowerShell installations + scripts. +* [.NET Core Hosting Bundle v3.1.10 or + higher](https://dotnet.microsoft.com/download/dotnet/thank-you/runtime-aspnetcore-3.1.12-windows-hosting-bundle-installer) + * After installing the .NET Core SDK and the .NET Core SDK, it is necessary to + restart the computer for the changes to take effect. +* IIS must be enabled before installing .Net Core Hosting Bundle. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +Admin App does not today support in-place upgrades from prior versions.  Please +install a fresh copy of Admin App to upgrade from prior versions. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +Download and +unzip [AdminAppInstaller.2.2.0.zip](https://odsassets.blob.core.windows.net/public/adminapp/AdminAppInstaller.2.2.0.zip). + +### Step 2. Configure Installation + +Open the "install.ps1" file in a text editor. You will need to edit this file +with your configuration details. If a value is not present for any of the +parameters, it will use its default value. + +:::info note: + Editing Item 3b below is mandatory for ODS / API URL and must be done + for installation to complete. +::: + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + c1. If you plan to use Windows authentication, this value will be "$true" + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + + `yearspecific`. Defaults to `sharedinstance` + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + d. `WebApplicationName`, `WebApplicationPath`. Optional. Defaults + to "AdminApp" and "C:\\inetpub\\Ed-Fi\\AdminApp" respectively. + + e. `WebSitePort`. Optional. Defaults to 443. + + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Configuration samples for the "install.ps1" file: + +:::info note + + SQL Server Shared Instance + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + } + ``` + +::: + +:::info note + + PostgreSQL District Specific + + **install.ps1(PostgreSQL)** + + ```json + $dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" + } + + $adminAppFeatures = @{ + ApiMode = "districtspecific" + } + + $parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +:::info note + + SQL Server Year Specific + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $adminAppFeatures = @{ + ApiMode = "yearspecific" + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +### Step 3. Open a PowerShell Prompt in Administrator Mode + +Method 1: Open \[Windows Key\]-R which will open a Run dialog for tasks needing +administrative privileges. Type "PowerShell" to open a PowerShell prompt in +Administrator mode. + +![RunAs](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-43.png) + +Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" +and right-click the "Windows PowerShell" option when provided. Select "Run as +Administrator" to open a PowerShell prompt in Administrator mode. + +![Windows menu](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-57.png) + +Change the directory to the unzipped directory for the Admin App Installer. + +### Step 4. Run the Installation via PowerShell + +Run "install.ps1" script. + +The PowerShell output will look something like the following: + +![Run Powershell](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +Now that the installation has finished, follow these steps to create a new SQL +Server login for the AdminApp Application Pool: + +* Open SQL Server Management Studio and at the server-level, expand the + "Security" folder. **Right-click**, select **Logins** > **New Login...** +* For the Login Name, enter "IIS APPPOOL\\AdminApp". +* On the left side of the pop-up window, select the **Server Roles** tab and + ensure the "sysadmin" checkbox is checked. +* Everything else can be left at the default setting. +* Once you're done, click **OK**. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 6. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +### Step 7. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. Please see [Securing the Admin App +(v2.x)](../../securing-the-admin-app.md) for more +information. + +### Step 8. Enable Product Improvement Features + +Upon first launch of the Admin App, you will have the option to opt-out of the +**Product Improvement** feature for the application (the user is opted-in by +default). Opting-in to this feature allows the application to collect useful +telemetric data, page views and usage data of the product, as we do with +[Ed-Fi.org](http://Ed-Fi.org) and other Ed-Fi web sites. Admin App also provides +an option to opt-in/out at a later time using the Configuration screen in the +application. Please see [\_Product +Improvement](https://edfi.atlassian.net/wiki/spaces/EDFITOOLS/pages/24118943) for +more information. +![Product Improvement](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2021-4-29_9-20-3.png) + +### Step 9. Restart the ODS / API + +To finish the Admin App on-premises setup, the ODS / API should be restarted, +which Admin App will advise. + +Steps for restarting the ODS / API: + +* Open IIS Manager (inetmgr). +* In the Connections pane on the left, expand **Sites** and locate the **Ed-Fi** + website. +* **Right-click** the website and select **Manage Website** > **Restart**. +* Close IIS Manager. + +### Step 10. Open Admin App to Complete Installation + +The installation will default to `https:///AdminApp`. + +To verify and launch the Admin App, open "Internet Information Services (IIS) +Manager". Open the server name, open the Sites folder and open the Ed-Fi branch. +Observe three web applications have been installed for the Ed-Fi Tech Suite. +Clicking on "AdminApp", use Manage Application to view the configured URL. Click +on "Browse ``" to launch Admin App. + +![IIS Manager](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_13-56-8.png) + +### Step 11. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App + (v2.x)](../../securing-the-admin-app.md) +* [Multi-Instance + Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) + +:::info + +**Admin App v2.2 Binaries are included with ODS / API 5.2**: [Binary +Releases](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100418/Binary+Releases) + +::: diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v221.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v221.md new file mode 100644 index 00000000..fd8a7750 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v221.md @@ -0,0 +1,390 @@ +# Admin App for Suite 3 v2.2.1 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App for Suite 3 v2.2.1. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App has been tested and can be installed for use +with the Ed-Fi ODS / API v3.4 through v5.2. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +## Prerequisites + +The following are required to install the Admin App: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the Ed-Fi ODS / API v3.4 through + v5.2 deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via [binary + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) + or [source code + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation). +* The [.NET Framework 4.8 + Runtime](https://dotnet.microsoft.com/download/dotnet-framework/thank-you/net48-web-installer) and + [.NET Core 3.1 + SDK](https://dotnet.microsoft.com/download/dotnet-core/thank-you/sdk-3.1.301-windows-x64-installer) + is required on the destination server before installation of Admin App. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v3.4, v5.0.0, v5.1.0, and v5.2.0 installation. + .NET Framework 4.8 Runtime is still needed for the PowerShell installations + scripts. +* [.NET Core Hosting Bundle v3.1.10 or + higher](https://dotnet.microsoft.com/download/dotnet/thank-you/runtime-aspnetcore-3.1.12-windows-hosting-bundle-installer) + * After installing the .NET Core SDK and the .NET Core SDK, it is necessary to + restart the computer for the changes to take effect. +* IIS must be enabled before installing .Net Core Hosting Bundle. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +Admin App does not today support in-place upgrades from prior versions.  Please +install a fresh copy of Admin App to upgrade from prior versions. + +### Upgrade Admin App from 2.2.0 to 2.2.1 + +If user wants to upgrade Admin App from 2.2.0 to 2.2.1, please follow the +preparation steps [here](#), before installing 2.2.1. + +:::info note: +After installation, please make sure to clear browser cookies before +accessing the latest version of Admin App. +::: + +Clear browser cookies (Admin App specific cookies can be searched on the browser +settings with host name). + +Example: + +![Upgrade Version](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2021-9-1_15-51-15.png) + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +* Admin App for Suite 3 v2.2.1 +* [Before You Install](#before-you-install) + * [Compatibility \& Supported ODS / API Versions](#compatibility--supported-ods--api-versions) + * [Prerequisites](#prerequisites) + * [Upgrade Admin App from 2.2.0 to 2.2.1](#upgrade-admin-app-from-220-to-221) + * [Required Information](#required-information) +* [Installation Instructions](#installation-instructions) + * [On-Premises Deployment](#on-premises-deployment) + * [Step 1. Download and Open Installer Package](#step-1-download-and-open-installer-package) + * [Step 2. Configure Installation](#step-2configure-installation) + * [Step 3. Open a PowerShell Prompt in Administrator Mode](#step-3-open-a-powershell-prompt-in-administrator-mode) + * [Step 4. Run the Installation via PowerShell](#step-4-run-the-installation-via-powershell) + * [Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true")](#step-5-create-sql-server-login-if-useintegratedsecurity-set-to-true) + * [Step 6. Check Folder Permissions](#step-6check-folder-permissions) + * [Step 7. Create Initial Administrative User](#step-7-create-initial-administrative-user) + * [Step 8. Enable Product Improvement Features](#step-8-enable-product-improvement-features) + * [Step 9. Restart the ODS / API](#step-9-restart-theods--api) + * [Step 10. Open Admin App to Complete Installation**](#step-10-open-admin-app-to-complete-installation) + * [Step 11. Using the Admin App](#step-11-using-the-admin-app) + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +Download and +unzip [AdminAppInstaller.2.2.1.zip](https://odsassets.blob.core.windows.net/public/adminapp/AdminAppInstaller.2.2.1.zip). + +### Step 2. Configure Installation + +Open the "install.ps1" file in a text editor. You will need to edit this file +with your configuration details. If a value is not present for any of the +parameters, it will use its default value. + +:::info note: + Editing Item 3b below is mandatory for ODS / API URL and must be done + for installation to complete. +::: + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + 1. If you plan to use Windows authentication, this value will be "$true" + 2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + d. `WebApplicationName`, `WebApplicationPath`. Optional. Defaults + to "AdminApp" and "C:\\inetpub\\Ed-Fi\\AdminApp" respectively. + + e. `WebSitePort`. Optional. Defaults to 443. + + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Configuration samples for the "install.ps1" file: + +:::info note: + + SQL Server Shared Instance + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + } + ``` + +::: + +:::info note: + + PostgreSQL District Specific + + **install.ps1(PostgreSQL)** + + ```json + $dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" + } + + $adminAppFeatures = @{ + ApiMode = "districtspecific" + } + + $parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +:::info note: + + SQL Server Year Specific + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $adminAppFeatures = @{ + ApiMode = "yearspecific" + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +### Step 3. Open a PowerShell Prompt in Administrator Mode + +Method 1: Open \[Windows Key\]-R which will open a Run dialog for tasks needing +administrative privileges. Type "PowerShell" to open a PowerShell prompt in +Administrator mode. + +![RunAs](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-43.png) + +Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" +and right-click the "Windows PowerShell" option when provided. Select "Run as +Administrator" to open a PowerShell prompt in Administrator mode. + +![Windows menu](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-57.png) + +Change the directory to the unzipped directory for the Admin App Installer. + +### Step 4. Run the Installation via PowerShell + +Run "install.ps1" script. + +The PowerShell output will look something like the following: + +![Run Powershell](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +Now that the installation has finished, follow these steps to create a new SQL +Server login for the AdminApp Application Pool: + +* Open SQL Server Management Studio and at the server-level, expand the + "Security" folder. **Right-click**, select **Logins** > **New Login...** +* For the Login Name, enter "IIS APPPOOL\\AdminApp". +* On the left side of the pop-up window, select the **Server Roles** tab and + ensure the "sysadmin" checkbox is checked. +* Everything else can be left at the default setting. +* Once you're done, click **OK**. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 6. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +### Step 7. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. Please see [Securing the Admin App +(v2.x)](../../securing-the-admin-app.md) for more +information. + +### Step 8. Enable Product Improvement Features + +Upon first launch of the Admin App, you will have the option to opt-out of the +**Product Improvement** feature for the application (the user is opted-in by +default). Opting-in to this feature allows the application to collect useful +telemetric data, page views and usage data of the product, as we do with +[Ed-Fi.org](http://Ed-Fi.org) and other Ed-Fi web sites. Admin App also provides +an option to opt-in/out at a later time using the Configuration screen in the +application. Please see [\_Product +Improvement](https://edfi.atlassian.net/wiki/spaces/EDFITOOLS/pages/24118943) for +more information. +![Product Improvement](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2021-4-29_9-20-3.png) + +### Step 9. Restart the ODS / API + +To finish the Admin App on-premises setup, the ODS / API should be restarted, +which Admin App will advise. + +Steps for restarting the ODS / API: + +* Open IIS Manager (inetmgr). +* In the Connections pane on the left, expand **Sites** and locate the **Ed-Fi** + website. +* **Right-click** the website and select **Manage Website** > **Restart**. +* Close IIS Manager. + +### Step 10. Open Admin App to Complete Installation + +The installation will default to `https:///AdminApp`. + +To verify and launch the Admin App, open "Internet Information Services (IIS) +Manager". Open the server name, open the Sites folder and open the Ed-Fi branch. +Observe three web applications have been installed for the Ed-Fi Tech Suite. +Clicking on "AdminApp", use Manage Application to view the configured URL. Click +on "Browse ``" to launch Admin App. + +![IIS Manager](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_13-56-8.png) + +### Step 11. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App + (v2.x)](../../securing-the-admin-app.md) +* [Multi-Instance + Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) + +:::info + +**Admin App v2.2.1 Binaries are included with ODS / API 5.2 (for +manual installations)**: [Binary +Releases](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100418/Binary+Releases) + +::: diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v23.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v23.md new file mode 100644 index 00000000..285d8e0f --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v23.md @@ -0,0 +1,376 @@ +# Admin App for Suite 3 v2.3 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App for Suite 3 v2.3. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App has been tested and can be installed for use +with the Ed-Fi ODS / API v3.4 through v5.3. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +## Prerequisites + +The following are required to install the Admin App: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the Ed-Fi ODS / API v3.4 through + v5.3 deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via [binary + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) + or [source code + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation). +* The [.NET Framework 4.8 + Runtime](https://dotnet.microsoft.com/download/dotnet-framework/thank-you/net48-web-installer) and + [.NET Core 3.1 + SDK](https://dotnet.microsoft.com/download/dotnet-core/thank-you/sdk-3.1.301-windows-x64-installer) + is required on the destination server before installation of Admin App. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v3.4 - v5.3.0 installation.  .NET Framework 4.8 + Runtime is still needed for the PowerShell installations scripts. +* [.NET Core Hosting Bundle v3.1.10 or + higher](https://dotnet.microsoft.com/download/dotnet/thank-you/runtime-aspnetcore-3.1.12-windows-hosting-bundle-installer) + * After installing the .NET Core SDK and the .NET Core SDK, it is necessary to + restart the computer for the changes to take effect. +* IIS must be enabled before installing .Net Core Hosting Bundle. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +Admin App does not today support in-place upgrades from prior versions.  Please +install a fresh copy of Admin App to upgrade from prior versions. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +* Admin App for Suite 3 v2.3 +* [Before You Install](#before-you-install) +* [Compatibility \& Supported ODS / API Versions](#compatibility--supported-ods--api-versions) +* [Prerequisites](#prerequisites) +* [Required Information](#required-information) +* [Installation Instructions](#installation-instructions) +* [On-Premises Deployment](#on-premises-deployment) + * [Step 1. Download and Open Installer Package](#step-1-download-and-open-installer-package) + * [Step 2. Configure Installation](#step-2configure-installation) + * [Step 3. Open a PowerShell Prompt in Administrator Mode](#step-3-open-a-powershell-prompt-in-administrator-mode) + * [Step 4. Run the Installation via PowerShell**](#step-4-run-the-installation-via-powershell) + * [Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true")](#step-5-create-sql-server-login-if-useintegratedsecurity-set-to-true) + * [Step 6. Check Folder Permissions**](#step-6-check-folder-permissions) + * [Step 7. Create Initial Administrative User](#step-7-create-initial-administrative-user) + * [Step 8. Enable Product Improvement Features](#step-8-enable-product-improvement-features) + * [Step 9. Restart the ODS / API (ODS / API 3.4-5.2 only)](#step-9-restart-the-ods--api-ods--api-34-52-only) + * [Step 10. Open Admin App to Complete Installation](#step-10-open-admin-app-to-complete-installation) + * [Step 11. Using the Admin App](#step-11-using-the-admin-app) + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +Download and +unzip [AdminAppInstaller.2.3.zip](https://odsassets.blob.core.windows.net/public/adminapp/AdminAppInstaller.2.3.1.zip). + +### Step 2. Configure Installation + +Open the "install.ps1" file in a text editor. You will need to edit this file +with your configuration details. If a value is not present for any of the +parameters, it will use its default value. + +:::info note: + Editing Item 3b below is mandatory for ODS / API URL and must be done + for installation to complete. +::: + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + + c1. If you plan to use Windows authentication, this value will be "$true" + + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + d. `WebApplicationName.` Optional. Defaults to "AdminApp". + e. `WebSitePort`. Optional. Defaults to 443. + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Configuration samples for the "install.ps1" file: + +:::info note: + + SQL Server Shared Instance + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + } + ``` + +::: + +:::info note: + + PostgreSQL District Specific + + **install.ps1(PostgreSQL)** + + ```json + $dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" + } + + $adminAppFeatures = @{ + ApiMode = "districtspecific" + } + + $parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + ``` + +::: + +:::info note: + + SQL Server Year Specific + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $adminAppFeatures = @{ + ApiMode = "yearspecific" + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +### Step 3. Open a PowerShell Prompt in Administrator Mode + +Method 1: Open \[Windows Key\]-R which will open a Run dialog for tasks needing +administrative privileges. Type "PowerShell" to open a PowerShell prompt in +Administrator mode. + +![RunAs](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-43.png) + +Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" +and right-click the "Windows PowerShell" option when provided. Select "Run as +Administrator" to open a PowerShell prompt in Administrator mode. + +![Windows menu](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-57.png) + +Change the directory to the unzipped directory for the Admin App Installer. + +### Step 4. Run the Installation via PowerShell + +Run "install.ps1" script. + +The PowerShell output will look something like the following: + +![Run Powershell](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +Now that the installation has finished, follow these steps to create a new SQL +Server login for the AdminApp Application Pool: + +* Open SQL Server Management Studio and at the server-level, expand the + "Security" folder. **Right-click**, select **Logins** > **New Login...** +* For the Login Name, enter "IIS APPPOOL\\AdminApp". +* On the left side of the pop-up window, select the **Server Roles** tab and + ensure the "sysadmin" checkbox is checked. +* Everything else can be left at the default setting. +* Once you're done, click **OK**. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 6. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +### Step 7. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. Please see [Securing the Admin App +(v2.x)](../../securing-the-admin-app.md) for more +information. + +### Step 8. Enable Product Improvement Features + +Upon first launch of the Admin App, you will have the option to opt-out of the +**Product Improvement** feature for the application (the user is opted-in by +default). Opting-in to this feature allows the application to collect useful +telemetric data, page views and usage data of the product, as we do with +[Ed-Fi.org](http://Ed-Fi.org) and other Ed-Fi web sites. Admin App also provides +an option to opt-in/out at a later time using the Configuration screen in the +application. Please see [\_Product +Improvement](https://edfi.atlassian.net/wiki/spaces/EDFITOOLS/pages/24118943) for +more information. +![Product Improvement](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2021-4-29_9-20-3.png) + +### Step 9. Restart the ODS / API (ODS / API 3.4-5.2 only) + +:::info note: + This step is only for ODS / API versions is 3.4 through 5.2.  ODS / + API versions 5.3 and higher do not require a service restart. +::: + +To finish the Admin App on-premises setup, the ODS / API should be restarted, +which Admin App will advise. + +Steps for restarting the ODS / API: + +1. Open IIS Manager (inetmgr). +2. In the Connections pane on the left, expand **Sites** and locate the + **Ed-Fi** website. +3. **Right-click** the website and select **Manage Website** > **Restart**. +4. Close IIS Manager. + +### **Step 10. Open Admin App to Complete Installation** + +The installation will default to `https:///AdminApp`. + +To verify and launch the Admin App, open "Internet Information Services (IIS) +Manager". Open the server name, open the Sites folder and open the Ed-Fi branch. +Observe three web applications have been installed for the Ed-Fi Tech Suite. +Clicking on "AdminApp", use Manage Application to view the configured URL. Click +on "Browse ``" to launch Admin App. + +![IIS Manager](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_13-56-8.png) + +### Step 11. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App + (v2.x)](../../securing-the-admin-app.md) +* [Multi-Instance + Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) + +:::info + +The following is a ZIP package containing PowerShell scripts for the +installation of the **Admin App for Suite 3 v2.3 (for automated +installations):** +[EdFi.Suite3.Installer.AdminApp.nupkg](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.Installer.AdminApp/verview/2.3.2) +Use the Download button in the upper-right corner. Rename from `.nupkg`  to +`.zip`  after downloading. + +**Admin App v2.3 Binaries are included with ODS / API 5.3 (for manual +installations)**: [Binary +Releases](https://edfi.atlassian.net/wiki/display/ODSAPIS3V53/Binary+Releases) + +::: diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v24.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v24.md new file mode 100644 index 00000000..15eafe89 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v24.md @@ -0,0 +1,458 @@ +# Admin App for Suite 3 v2.4 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App for Suite 3 v2.4. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App has been tested and can be installed for use +with the Ed-Fi ODS / API v3.4 through v5.3. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +Admin App supports two deployment modes:  Docker Deployment and On-Premise +Installation, as documented below.  Please choose the deployment mode that fits +your environment. + +## Docker Deployment for Admin App + +Docker image for Admin App 2.4 is available at: +[https://hub.docker.com/r/edfialliance/ods-admin-app](https://hub.docker.com/r/edfialliance/ods-admin-app) + +Please refer [Docker Deployment - Ed-Fi Tools - Ed-Fi Tech +Docs](https://edfi.atlassian.net/wiki/display/EDFITOOLS/Docker+Deployment) for +more details. + +## On-Premise Installation + +## Prerequisites + +The following are required to install the Admin App: + +:::info note: + Below are links to Nuget packages containing the Admin App Installer + or App Binaries. Download from the link and rename  the file extension to +  `.zip,` or use the PowerShell command from Step 1 below. **Admin App for + Suite 3 v2.4 (for automated installations):** + [EdFi.Suite3.Installer.AdminApp.2.4.12.nupkg](https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.Installer.AdminApp/versions/2.4.12/content?api-version=6.0-preview.1) + **Admin App v2.4 Binaries (for manual installations)**: + [EdFi.Suite3.ODS.AdminApp.Web + 2.4.48.nupkg](https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/2.4.48/content?api-version=6.0-preview.1) +::: + +:::info note: + The following link contains published image: + [https://hub.docker.com/r/edfialliance/ods-admin-app](https://hub.docker.com/r/edfialliance/ods-admin-app) +::: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the Ed-Fi ODS / API v3.4 through + v5.3 deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via [binary + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) + or [source code + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation). +* Both the [.NET 6 SDK and .NET 6 Hosting + Bundle](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) are required + on the destination server before installation of Admin App. + * After installing the .NET Core SDK and the .NET Core SDK, it is necessary to + restart the computer for the changes to take effect. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v3.4 - v5.3.0 installation. +* IIS must be enabled before installing .Net Core Hosting Bundle. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +Admin App does not today support in-place upgrades from prior versions.  Please +install a fresh copy of Admin App to upgrade from prior versions. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +* Admin App for Suite 3 v2.4 +* [Before You Install](#before-you-install) + * [Compatibility \& Supported ODS / API Versions](#compatibility--supported-ods--api-versions) + * [Docker Deployment for Admin App](#docker-deployment-for-admin-app) + * [On-Premise Installation](#on-premise-installation) + * [Prerequisites](#prerequisites) +* [Installation Instructions](#installation-instructions) + * [On-Premises Deployment](#on-premises-deployment) + * [Step 1. Download and Open Installer Package](#step-1-download-and-open-installer-package) + * [Step 2. Configure Installation](#step-2configure-installation) + * [Step 3. Open a PowerShell Prompt in Administrator Mode](#step-3-open-a-powershell-prompt-in-administrator-mode) + * [Step 4. Run the Installation via PowerShell](#step-4-run-the-installation-via-powershell) + * [Database login setup on integrated security mode](#database-login-setup-on-integrated-security-mode) + * [Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true")](#step-5-create-sql-server-login-if-useintegratedsecurity-set-to-true) + * [Step 6. Update Application Pool Identity (Optional)](#step-6-update-application-pool-identity-optional) + * [Step 7. Check Folder Permissions**](#step-7-check-folder-permissions) + * [Step 8. Create Initial Administrative User](#step-8-create-initial-administrative-user) + * [Step 9. Enable Product Improvement Features](#step-9-enable-product-improvement-features) + * [Step 10. Restart the ODS / API (ODS / API 3.4-5.2 only)](#step-10-restart-the-ods--api-ods--api-34-52-only) + * [Step 11. Open Admin App to Complete Installation](#step-11-open-admin-app-to-complete-installation) + * [Step 12. Using the Admin App](#step-12-using-the-admin-app) + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +Download , rename the file extension from to `.zip`  and unzip the package + +* Installer for Admin App 2.4: + [EdFi.Suite3.Installer.AdminApp.2.4.12.nupkg](https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.Installer.AdminApp/versions/2.4.12/content?api-version=6.0-preview.1) +* Binaries for Admin App 2.4: [EdFi.Suite3.ODS.AdminApp.Web + 2.4.48.nupkg](https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/2.4.48/content?api-version=6.0-preview.1) + +Alternatively, run the below PowerShell command to download the package as a zip +file directly: + +```shell +# Installer +Invoke-WebRequest "https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.Installer.AdminApp/versions/2.4.12/content?api-version=6.0-preview.1" -OutFile .\EdFi.Suite3.Installer.AdminApp.2.4.12.zip + +# Web App Binaries +Invoke-WebRequest "https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/2.4.48/content?api-version=6.0-preview.1" -OutFile .\EdFi.Suite3.ODS.AdminApp.Web-2.4.48.zip +``` + +### Step 2. Configure Installation + +Open the "install.ps1" file in a text editor. You will need to edit this file +with your configuration details. If a value is not present for any of the +parameters, it will use its default value. + +:::info note: + Editing Item 3b below is mandatory for ODS / API URL and must be done + for installation to complete. +::: + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + + c1. If you plan to use Windows authentication, this value will be "$true" + + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + d. `WebApplicationName.` Optional. Defaults to "AdminApp". + e. `WebSitePort`. Optional. Defaults to 443. + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Configuration samples for the "install.ps1" file: + +:::info note: + + SQL Server Shared Instance + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + } + ``` + +::: + +:::info note: + + PostgreSQL District Specific + + **install.ps1(PostgreSQL)** + + ```json + $dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" + } + + $adminAppFeatures = @{ + ApiMode = "districtspecific" + } + + $parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + ``` + + ::: + + :::info note: + + SQL Server Year Specific + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $adminAppFeatures = @{ + ApiMode = "yearspecific" + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +### Step 3. Open a PowerShell Prompt in Administrator Mode + +Method 1: Open \[Windows Key\]-R which will open a Run dialog for tasks needing +administrative privileges. Type "PowerShell" to open a PowerShell prompt in +Administrator mode. + +![RunAs](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-43.png) + +Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" +and right-click the "Windows PowerShell" option when provided. Select "Run as +Administrator" to open a PowerShell prompt in Administrator mode. + +![Windows Menu](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-57.png) + +Change the directory to the unzipped directory for the Admin App Installer. + +### Step 4. Run the Installation via PowerShell** + +Run "install.ps1" script. + +### Database login setup on integrated security mode + +During the installation process, you will be prompted to choose database login +details. Entering "Y" will continue with default option( Installation process +will create IIS APPPOOL\\AdminApp database login on the server). + +Choosing 'n' will prompt you to enter windows username. The installation process +will validate and create database login using entered username, if the login +does not exist on the database server already. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-7-6.png) + +![SqlLogin Credentials](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-8-32.png) + +Please refer Steps 5 and 6 for more details on verifying the database login and +setting up the application pool identity. + +The PowerShell output will look something like the following: + +![Pws Installation](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +The installation process sets up an appropriate SQL Login for use with the +dedicated AdminApp Application Pool in IIS. You can verify this in SQL Server +Management Studio: + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +On the Server Roles page, make sure that  "public" and "sysadmin" checkboxes are +checked. Once you have confirmed a proper SQL Server login exists, continue to +the next step. + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 6. Update Application Pool Identity (Optional) + +As mentioned on Step 5, installation process sets up an appropriate SQL Login +for use with the dedicated AdminApp Application Pool in IIS. If you would like +to use the default "ApplicationPoolIdentity", then you can skip this bit. + +Else in the same Advanced Settings window, click on the browse icon under +Process Model > Identity. We'll choose the custom account option and click +"Set...". When setting the credentials, you can just use the username and +password that you use to log in to Windows. If you need to include the app pool +domain in the username, then the username can look something like this: +"localhost\\username", where "localhost" is the app pool domain. Once we have +entered the correct credentials, we'll click OK on all screens until we're back +to the main Application Pools page. + +![Pool Identity](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-24-43.png) + +### Step 7. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +:::info note: +If you choose custom login over default Application Pool Identity ( Refer +Step 6 for more details), then make sure the custom login has full control on +the above mentioned folders. +::: + +### Step 8. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. Please see [Securing the Admin App +(v2.x)](../../securing-the-admin-app.md) for more +information. + +### Step 9. Enable Product Improvement Features + +Upon first launch of the Admin App, you will have the option to opt-out of the +**Product Improvement** feature for the application (the user is opted-in by +default). Opting-in to this feature allows the application to collect useful +telemetric data, page views and usage data of the product, as we do with +[Ed-Fi.org](http://Ed-Fi.org) and other Ed-Fi web sites. Admin App also provides +an option to opt-in/out at a later time using the Configuration screen in the +application. Please see [\_Product +Improvement](https://edfi.atlassian.net/wiki/spaces/EDFITOOLS/pages/24118943) +for more information. + +![Product Improvement](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2021-4-29_9-20-3.png) + +:::info + Starting with Admin App 2.4, Product Improvement can be disabled at + the AppSettings level, by setting the `EnableProductImprovementSettings` + setting to `false` . Doing so will _disable_ Product Improvement, skip the + above screen at startup, and remove the "Configuration" screen to prevent + future changes to the setting. If Product Improvement was previously enabled + before this flag was set to `false` , it will become disabled. To restore the + ability to set the Product Improvement configuration, change + \``EnableProductImprovementSettings` back to `true` . +::: + +### Step 10. Restart the ODS / API (ODS / API 3.4-5.2 only) + +:::info note: +This step is only for ODS / API versions is 3.4 through 5.2.  ODS / +API versions 5.3 and higher do not require a service restart. +::: + +To finish the Admin App on-premises setup, the ODS / API should be restarted, +which Admin App will advise. + +Steps for restarting the ODS / API: + +1. Open IIS Manager (inetmgr). +2. In the Connections pane on the left, expand **Sites** and locate the + **Ed-Fi** website. +3. **Right-click** the website and select **Manage Website** > **Restart**. +4. Close IIS Manager. + +### Step 11. Open Admin App to Complete Installation + +The installation will default to `https:///AdminApp`. + +To verify and launch the Admin App, open "Internet Information Services (IIS) +Manager". Open the server name, open the Sites folder and open the Ed-Fi branch. +Observe three web applications have been installed for the Ed-Fi Tech Suite. +Clicking on "AdminApp", use Manage Application to view the configured URL. Click +on "Browse ``" to launch Admin App. + +![IIS Manager](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_13-56-8.png) + +### Step 12. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App + (v2.x)](../../securing-the-admin-app.md) +* [Multi-Instance + Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v17-for-ods-api-v33.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v17-for-ods-api-v33.md new file mode 100644 index 00000000..d3ab81db --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v17-for-ods-api-v33.md @@ -0,0 +1,330 @@ +# Admin App v1.7 for ODS / API v3.3 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App. + +## Prerequisites + +The following are required to install the Admin App: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an Ed-Fi ODS / API deployed and operational + before you can use the Admin App. The ODS / API must be an On-Premises + Installation either via [Windows Installers for the Ed-Fi ODS/API (Suite + 3)](https://edfi.atlassian.net/wiki/pages/viewpage.action?pageId=22487668) + or [manual installation via source + code](https://edfi.atlassian.net/wiki/display/ODSAPI33/Getting+Started). +* You must have an Ed-Fi license to use the Admin App. If you have an + installation of the ODS / API, you already have a license. The Ed-Fi License + is free and available online. If you haven't done so already, visit + the [Ed-Fi.org licensing + section](https://www.ed-fi.org/getting-started/license-ed-fi-technology/) for + details and a link to get started. +* Admin App authentication will work via Single Sign-On using either Active + Directory or Active Directory for Azure depending on deployment. +* Download and install the Microsoft IIS URL Rewrite + Tool: [https://www.iis.net/downloads/microsoft/url-rewrite](https://www.iis.net/downloads/microsoft/url-rewrite) if + it is not already available (this may require computer restart). +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but not function when using Admin App. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +## Compatibility & Supported ODS / API Versions + +Currently, the ODS / API Admin App can be installed for use with the Ed-Fi ODS / +API v3.3. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +## On-Premises Deployment for ODS / API for v3.3 + +Each step is outlined in detail below. + +### Step 1. Select Install Location + +Select an installation location. + +![Web Setup](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/setuppage1.JPG) + +### Step 2. Configure SQL Connection + +Next, we'll set up a SQL connection to your local test server for Ods, Security, +and Admin databases. + +For local testing, use the following values: + +* Server: (local) for testing. +* Authentication: Trusted Connection. + +We strongly recommend you test that the credentials are correct by +clicking **Test Sql Connection** on each database configuration page. + +**Ods database connection:** + +Enter appropriate Ods database name if it is different (ex: EdFi\_Ods). + +![ODS Connection](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-1-31_9-28-6.png) + +**Security database connection:** + +![Data Base](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page3.JPG) + +**Admin database connection:** + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page4.JPG) + +### Step 3. ODS / API URL Configuration + +At this point, we'll connect to the ODS / API: + +![API Configuration](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page5.JPG) + +For testing against a local ODS / API, +use [http://localhost:54746](http://localhost:54746) ( default value for ODS API +local developer installation). + +### Step 4. ODS / API Mode + +Next, choose which mode the ODS / API is running under. If the ODS was installed +and left in default mode: select "Shared (default)". + +![ODS Mode](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2019-8-2_13-50-33.png) + +If the ODS / API was configured after installation to run in Year Specific mode: +select "Year Specific" and provide the configured school year: + +![School Year](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2019-8-2_13-48-57.png) + +For additional information about Year Specific mode and configuring the Admin +App or ODS without use of the exe installers, +see [https://edfi.atlassian.net/wiki/spaces/ODSAPI32/pages/27099724](https://edfi.atlassian.net/wiki/spaces/ODSAPI32/pages/27099724) and [Year-Specific +Mode (v1.x)](../../../technical-articles/year-specific-mode-v1x). + +### Step 5. Create SQL Server Login (if "Trusted Connection" used above) + +This step only needs to be completed if you selected Trusted Connection option +on any of the database configuration pages in Step 2. If you did not, please +move on to Step 6. + +Now that the installation has finished, follow these steps to create a new SQL +Server login for the EdFi.AdminApp App Pool: + +* Open SQL Server Management Studio and at the server-level, expand the + "Security" folder, right-click "Logins", and then select "New Login...". +* For the Login Name, enter "IIS APPPOOL\\EdFi.AdminApp". +* On the left side of the pop-up window, select the "Server Roles" tab and + ensure the "sysadmin" checkbox is checked. +* Everything else can be left as default. Once that is done, hit OK. + +![Sql Logins](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-1-23_14-28-11.png) + +![Sql Permissions](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-1-23_14-30-55.png) + +### Step 6. Checking Folder Permission (Optional) + +**Folders to verify:** + +1. Admin App application folder (Default folder path: C:\\Ed-Fi\\Admin App v1.7) +2. Admin App log folder (Default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp) + +For checking permission _–_ right-click the folder then choose Properties, +select Security tab to verify the "Group or user names" section has +EdFi.AdminApp with full control. + +![Sql Permissions](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-1-23_15-12-45.png) + +### Step 7. Securing the Admin App + +If you're performing a production on-premises installation, now would be a good +time to review the documentation on [Securing the Admin +App](https://edfi.atlassian.net/wiki/display/ADMIN/Securing+the+Admin+App), +particularly the material on IIS configuration and NTLM. + +### Step 8. Admin App Licensing & Configuration + +This section provides an overview of the initial Admin App configuration. We'll +continue using a local test environment. + +Connect to the Admin App URL +[https://localhost/AdminApp](https://localhost/AdminApp) to complete the setup. + +If you are using Microsoft Edge you may see an active directory security +authentication window. + +![Edge Security](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2019-2-26_6-1-34.png) + +Go ahead and sign in. + +You'll see the following screen. To complete the additional setup process, press +**Continue**. + +![Setup Required](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page0.jpg) + +You should land on the **Admin App Home** page. + +![AdminApp](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Applicationpage1.JPG) + +### Step 9. Restart the ODS / API + +To finish the Admin App on-premises setup the ODS / API must be restarted. + +Steps for restarting the ODS / API: + +* Open IIS Manager (inetmgr) +* In the Connections pane on the left, expand **Sites** and locate the **Ed-Fi** + website +* Right-click the website and select **Manage Website** > **Restart** +* Close the IIS Manager (inetmgr) + +### Step 10. Admin app walk through + +**Step 10.1 Add Vendor & Application** + +In this step, we'll add a new vendor and a client application. + +If you're not already there, go to the Admin App Home page: + +![Main Admin App](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-1-24_15-55-45.png) + +Click **Settings** and you'll be presented with the screen below. We'll use this +screen to add a vendor. + +![Global Settings](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-1-24_15-56-6.png) + +Clicking on Add Vendor will open the following screen for adding a new vendor. + +![Add Vendor](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-2-10_11-15-48.png) + +Please enter company, namespace, contact name and contact e-mail address and hit +Save Changes. + +![Vendor Settings](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-2-10_11-19-1.png) + +Now, we'll add an application to the vendor we just created. Applications are +specific to an ODS / API instance. + +Click on the **ODS Instance** tab to go through the step below. + +![Main Ods](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/applicationpage4.JPG) + +Clicking on Add Application will show following screen. + +![Add Application](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Applicationpage5.JPG) + +Steps for adding application to vendor + +* Provide application name +* Select either option for education organization type +* Choose any available education organization ID from the drop-down menu +* Select appropriate claim set name +* Click Add Application to save the application + +You will be presented with the key and secret at the next screen. Copy this +information to a safe place. + +It's useful to test client system functionality (in this document we will be +using the generated key and secret for Bulk upload process). + +![Product Application ](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-1-24_16-20-38.png) + +After completing the above step, you'll see the new Test application you just +added. + +![Vendor Application](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page7.JPG) + +**Step 10.2 Descriptors tab** + +View configured descriptors for a known instance. + +![Descriptors](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page8.JPG) + +**Step 10.3 Education Organizations tab** + +View and manage education organizations (LEAs and schools). + +![Education Organization](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page9.JPG) + +**Step 10.4 Bulk Upload process** + +Please enter generated key and secret (on step 10.1) here and save credentials. +Saved key and secret will be used to authorize the bulk upload process. + +![Bulk Upload](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page10.JPG) + +After saving credentials, bulk upload page will be presented. + +![Bulk Progress](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page11.JPG) + +To perform upload, please select appropriate file type and input file and click +upload. After clicking the upload button, the popup will display the upload +progress. + +![Bulk Finish](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page12.JPG) + +Bulk upload is completed successfully. + +**Step 10.5 Sync Learning Standards** + +In this step, we'll populate learning standards in the ODS / API by using the +Admin App to synchronize with the AB Connect API. + +To synchronize learning standards in on local environment, select the **Learning +Standards** tab. You'll be presented with the screen below: + +![Sync Learning](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/applicationpage13.JPG) + +The screen contains instructions on how to get an API ID and Key from Certica +Solutions. Following the instructions on screen to obtain an ID and Key. + +Please enter AB connect ID and Key obtained from Certica and click **Enable +Learning Standards.** Syncing will begin. A progress bar will show you the +current status, and you'll see a "completed successfully" message once done. + +![Ods Complete](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Applicationpage14.JPG) + +Clicking Reload will take you to the following screen, where you can reset the +AB connect credentials or update the learning standards. + +![Learning Success](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Applicationpage15.JPG) + +**Optional Verification Step** + +To confirm that learning standards have been populated, a SQL query, such as +shown below, can be run against your ODS / API instance database. The query +should return a count in the thousands from a successful learning standards +synchronization: + +```sql +SELECT COUNT(*) FROM EdFi.LearningStandard WHERE [Namespace] LIKE '%api.academicbenchmarks%'; +``` + +### Step 11. Reports + +Clicking the Reports on Home screen, will take you to the Ods Instance Reports. + +![ODS Main](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Applicationpage16.JPG) + +Choosing district will provide district specific reports. + +![ODS District](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Applicationpage17.JPG) + +By clicking on the individual report link will take you to the detailed report +page. + +![ODS District Report](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Applicationpage18.JPG) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v181-for-ed-fi-ods-api-v34.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v181-for-ed-fi-ods-api-v34.md new file mode 100644 index 00000000..95953aa1 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v181-for-ed-fi-ods-api-v34.md @@ -0,0 +1,323 @@ +# Admin App v1.8.1 for Ed-Fi ODS / API v3.4 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App for the ODS / API v3.4. + +:::info + September 2020:  Admin App v1.8.1 has been released to address an + issue with the Microsoft URL Rewrite package which link was broken within + Admin App v1.8. +::: + +## Prerequisites + +The following are required to install the Admin App: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an Ed-Fi ODS / API deployed and operational + before you can use the Admin App. The ODS / API can be installed [source + code](https://edfi.atlassian.net/wiki/display/ODSAPI34/Getting+Started). +* Admin App authentication will work via Single Sign-On using either Active + Directory or Active Directory for Azure depending on deployment. Admin App + v1.8 contains a preview of non-Active Directory using ASP.NET Identity as an + alternate authentication method (see: [ASP.NET Identity (Preview in + v1.8)](../../../technical-articles/aspnet-identity-preview-in-v18)). +* The [.NET Framework 4.8 + Runtime](https://dotnet.microsoft.com/download/dotnet-framework/net48) is + required on the destination server before installation of Admin App. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App can be installed for use with the Ed-Fi ODS / +API v3.4. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +### Other Versions + +The Admin App downloadable from this page is compatible with the ODS / API v3.4. + +## On-Premises Deployment for ODS / API for v3.4 + +Each step is outlined in detail below for the PowerShell deployment. + +### Step 1. Unzip Admin App Installation Files + +Unzip the contents of the Installation ZIP into any folder of your choosing. Our +directory is on the following path: "C:\\Ed-Fi\\AdminAppInstallation". + +### Step 2. Locate the Installation Script Files + +Installation script files can be found under the tools folder. + +![Installation Scripts](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-1-30_10-58-34.png) + +### Step 3. Configure Installation + +Open the "install-config.json" file. We will need to edit this file with our +configuration details. + +1. Set the `installationDirectory` to the directory where the Admin App source + files should be installed. + + a. Be sure to escape any special characters like slashes (For example, a + path like "C:\\inetpub\\Ed-Fi\\AdminApp" must be changed to + "C:\\\\inetpub\\\\Ed-Fi\\\\AdminApp"). + +2. Configure values for the `odsApi` section. + + a. `apiUrl` is the base URL for the ODS / API. + + b. `apiMode` is either going to be "Shared Instance" or "Year Specific". + b1. If "Shared Instance" was chosen, the `schoolYear` can be left blank. + b2. If "Year Specific" was chosen, you must provide the `schoolYear`. + +3. Configure the values for the `databases` section. These are used to construct + the connection strings. + + a. `applicationCredentials.` These credentials will be used with database + connection strings on application's Web.config file. + + b. `installCredentials.` These credentials will be used while deploying the + admin app specific database setup. + + c. `useIntegratedSecurity.` Will either be "true" or "false". + + c1. If you plan to use Windows authentication, this value will be "true" + and `databaseUser` and `databasePassword` can be left blank. + + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "false" and the `databaseUser` and `databasePassword` + must be provided. + + d. `engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + e. `databaseServer.` The name of the database server. For a local server, we + can use "(local)" for SQL and "localhost" for PostgreSQL. + + f. `databasePort.` Used to specify the database server port, presuming the + server is configured to use the specific port. The default port value for + PostgreSQL is "5432". + + g. `adminDatabaseName`, `odsDatabaseName`, `securityDatabaseName.` Simply + the name of the respective databases being referenced. + + g1. For example, when configuring the `odsDatabaseName`, the value here + will be the name of the ODS database, whereas the `adminDatabaseName` + and `securityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + h. Several values can be left at their defaults as they are not directly + relevant to Admin App installation. These are: + + h1. `useTemplates`. Defaults to false. Okay as-is. + + h2. `odsTemplate.` Defaults to "populated". Okay as-is. + + h3. `noDuration.` Defaults to false. Okay as-is. + + h4. `dropDatabases.` Defaults to false. Okay as-is. + +Below is an example of a complete "install-config.json" file for SQL Server: + +**install-config.json(SQLServer)** Expand source + +```json +{ + "installationDirectory": "C:\\inetpub\\Ed-Fi\\AdminApp", + "odsApi": { + "apiUrl": "", + "apiMode": "Shared Instance", + "schoolYear": "" + }, + "databases": { + "applicationCredentials": { + "databaseUser" : "", + "databasePassword" : "", + "useIntegratedSecurity" : true + }, + "installCredentials": { + "databaseUser" : "", + "databasePassword" : "", + "useIntegratedSecurity" : true + }, + "engine" : "SQLServer", + "databaseServer" : "(local)", + "databasePort" : "", + "adminDatabaseName" : "EdFi_Admin", + "odsDatabaseName" : "EdFi_Ods", + "securityDatabaseName" : "EdFi_Security", + "useTemplates" : false, + "odsTemplate" : "populated", + "noDuration" : false, + "dropDatabases" : false + } +} +``` + +Below is an example of a complete "install-config.json" file for PostgreSQL: + +**install-config.json(PostgreSQL)** Expand source + +```json +{ + "installationDirectory": "C:\\inetpub\\Ed-Fi\\AdminApp", + "odsApi": { + "apiUrl": "", + "apiMode": "Shared Instance", + "schoolYear": "" + }, + "databases": { + "applicationCredentials": { + "databaseUser" : "postgres", + "databasePassword" : "", + "useIntegratedSecurity" : false + }, + "installCredentials": { + "databaseUser" : "postgres", + "databasePassword" : "", + "useIntegratedSecurity" : false + }, + "engine" : "PostgreSQL", + "databaseServer" : "localhost", + "databasePort" : "", + "adminDatabaseName" : "EdFi_Admin", + "odsDatabaseName" : "EdFi_Ods", + "securityDatabaseName" : "EdFi_Security", + "useTemplates" : false, + "odsTemplate" : "populated", + "noDuration" : false, + "dropDatabases" : false + } +} +``` + +### Step 4. Run the Installation via PowerShell + +Ensure that you have permission to execute PowerShell scripts. For more +information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +Launch PowerShell as an administrator, "cd" to the directory containing the +installation files, and run the "install.ps1" script. + +The PowerShell output will look something like the following: + +![Pws Installation](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the install-config.json in Step 3, above. If you did not, we can skip ahead +to Step 6. + +Now that the installation has finished, follow these steps to create a new SQL +Server login for the AdminApp Application Pool: + +* Open SQL Server Management Studio and at the server-level, expand the + "Security" folder. **Right-click**, select **Logins** > **New Login...** +* For the Login Name, enter "IIS APPPOOL\\AdminApp". +* On the left side of the pop-up window, select the **Server Roles** tab and + ensure the "sysadmin" checkbox is checked. +* Everything else can be left at the default setting. +* Once you're done, click **OK**. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 6. Checking Folder Permissions + +Folders to verify: + +1. Admin App application folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has Ed-Fi.AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +### Step 7. Securing the Admin App + +If you're performing a production on-premises installation, now would be a good +time to review the documentation on [Securing the Admin App](../../securing-the-admin-app.md), +particularly the material on IIS configuration and NTLM. + +### Step 8. Admin App Licensing & Configuration + +This section provides an overview of the initial Admin App configuration. We'll +continue using a local test environment. + +Connect to the Admin App URL (`https://localhost/AdminApp`) to complete the +setup. + +If you're using Microsoft Edge, you may see an active directory security +authentication window. + +![Edge Security](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2019-2-26_6-1-34.png) + +Go ahead and sign in. + +You'll see the following screen. To complete the final steps in the setup +process, press **Continue**. + +![Setup Required](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/page0.jpg) + +You should land on the **Admin App Home** page. + +![AdminApp](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Applicationpage1.JPG) + +### Step 9. Restart the ODS / API + +To finish the Admin App on-premises setup, the ODS / API must be restarted. + +Steps for restarting the ODS / API: + +* Open IIS Manager (inetmgr). +* In the Connections pane on the left, expand **Sites** and locate the **Ed-Fi** + website. +* **Right-click** the website and select **Manage Website** > **Restart**. +* Close IIS Manager. + +### Step 10. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App (v1.x)](../../securing-the-admin-app.md) +* [ASP.NET Identity (Preview in + v1.8)](../../../technical-articles/aspnet-identity-preview-in-v18) +* [Year-Specific Mode + (v1.x)](../../../technical-articles/year-specific-mode-v1x) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v30-for-odsapi-v60.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v30-for-odsapi-v60.md new file mode 100644 index 00000000..d2948623 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v30-for-odsapi-v60.md @@ -0,0 +1,436 @@ +# Admin App v3.0 for ODS/API v6.0 + +Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App v3.0 for ODS/API 6.0. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App has been tested and can be installed for use +with the Ed-Fi ODS / API v6.0. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +Admin App supports two deployment modes:  Docker Deployment and On-Premise +Installation, as documented below.  Please choose the deployment mode that fits +your environment. + +## Docker Deployment for Admin App + +Docker image for Admin App 3.0 is available at: +[https://hub.docker.com/r/edfialliance/ods-admin-app](https://hub.docker.com/r/edfialliance/ods-admin-app) + +Please refer [Docker Deployment - Ed-Fi Tools - Ed-Fi Tech +Docs](https://edfi.atlassian.net/wiki/display/EDFITOOLS/Docker+Deployment) for +more details. + +## On-Premise Installation + +## Prerequisites + +The following are required to install the Admin App: + +:::info note: Below are links to Nuget packages containing the Admin App + Installer or App Binaries. Download from the link and rename  the file + extension to `.zip,` or use the PowerShell command from Step 1 below. **Admin +  App v3.0 for ODS/API 6.0 (for automated installations):** + [EdFi.Suite3.Installer.AdminApp.3.0.0.18.nupkg](https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.Installer.AdminApp/versions/3.0.0.18/content?api-version=6.0-preview.1) + **Admin App v3.0 Binaries (for manual installations)**: + [EdFi.Suite3.ODS.AdminApp.Web.3.0.0.nupkg](https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/3.0.0/content?api-version=6.0-preview.1) + ::: + +:::info note: The following link contains published image: + [https://hub.docker.com/r/edfialliance/ods-admin-app](https://hub.docker.com/r/edfialliance/ods-admin-app) + ::: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the Ed-Fi ODS / API v6.0 deployed + and operational before you can use the Admin App. Tested configurations + include on-premises installation via [binary + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) + or [source code + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation). +* Both the [.NET 6 SDK and .NET 6 Hosting + Bundle](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) are required + on the destination server before installation of Admin App. + * After installing the .NET Core SDK and the .NET Core SDK, it is necessary to + restart the computer for the changes to take effect. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v6.0 installation. +* IIS must be enabled before installing .Net Core Hosting Bundle. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +Admin App does not today support in-place upgrades from prior versions.  Please +install a fresh copy of Admin App to upgrade from prior versions. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +* Admin App v3.0 for ODS/API v6.0 + * [Compatibility \& Supported ODS / API Versions](#compatibility--supported-ods--api-versions) + * [Docker Deployment for Admin App](#docker-deployment-for-admin-app) + * [On-Premise Installation](#on-premise-installation) + * [Prerequisites](#prerequisites) +* [Installation Instructions](#installation-instructions) + * [On-Premises Deployment](#on-premises-deployment) + * [Step 1. Download and Open Installer Package](#step-1-download-and-open-installer-package) + * [Step 2. Configure Installation](#step-2configure-installation) + * [Step 3. Open a PowerShell Prompt in Administrator Mode](#step-3-open-a-powershell-prompt-in-administrator-mode) + * [Step 4. Run the Installation via PowerShell](#step-4-run-the-installation-via-powershell) + * [Database login setup on integrated security mode](#database-login-setup-on-integrated-security-mode) + * [Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true")](#step-5-create-sql-server-login-if-useintegratedsecurity-set-to-true) + * [Step 6. Update Application Pool Identity (Optional)](#step-6-update-application-pool-identity-optional) + * [Step 7. Check Folder Permissions**](#step-7-check-folder-permissions) + * [Step 8. Create Initial Administrative User](#step-8-create-initial-administrative-user) + * [Step 9. Enable Product Improvement Features](#step-9-enable-product-improvement-features) + * [Step 10. Open Admin App to Complete Installation](#step-10-open-admin-app-to-complete-installation) + * [Step 11. Using the Admin App](#step-11-using-the-admin-app) + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +Download , rename the file extension from to `.zip`  and unzip the package + +* Installer for Admin App 3.0: + [EdFi.Suite3.Installer.AdminApp.3.0.0.18.nupkg](https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.Installer.AdminApp/versions/3.0.0.18/content?api-version=6.0-preview.1) +* Binaries for Admin App 3.0: + [EdFi.Suite3.ODS.AdminApp.Web.3.0.0.nupkg](https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/3.0.0/content?api-version=6.0-preview.1) + +Alternatively, run the below PowerShell command to download the package as a zip +file directly: + +```shell +# Installer +Invoke-WebRequest "https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.Installer.AdminApp/versions/3.0.0.18/content?api-version=6.0-preview.1" -OutFile .\EdFi.Suite3.Installer.AdminApp.3.0.0.18.zip + +# Web App Binaries +Invoke-WebRequest "https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/3.0.0/content?api-version=6.0-preview.1" -OutFile .\EdFi.Suite3.ODS.AdminApp.Web-3.0.0.zip +``` + +### Step 2. Configure Installation + +Open the "install.ps1" file in a text editor. You will need to edit this file +with your configuration details. If a value is not present for any of the +parameters, it will use its default value. + +:::info note: + Editing Item 3b below is mandatory for ODS / API URL and must be done + for installation to complete. +::: + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + + c1. If you plan to use Windows authentication, this value will be "$true" + + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. a. `ToolsPath`. Path for storing installation tools, + e.g., nuget.exe. Defaults to "C:/temp/tools" + + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + d. `WebApplicationName.` Optional. Defaults to "AdminApp". + + e. `WebSitePort`. Optional. Defaults to 443. + + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Configuration samples for the "install.ps1" file: + +:::info note: + + SQL Server Shared Instance + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + } + ``` + +::: + +:::info note: + + PostgreSQL District Specific + + **install.ps1(PostgreSQL)** + + ```json + $dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" + } + + $adminAppFeatures = @{ + ApiMode = "districtspecific" + } + + $parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +:::info note: + + SQL Server Year Specific + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $adminAppFeatures = @{ + ApiMode = "yearspecific" + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +### Step 3. Open a PowerShell Prompt in Administrator Mode + +Method 1: Open \[Windows Key\]-R which will open a Run dialog for tasks needing +administrative privileges. Type "PowerShell" to open a PowerShell prompt in +Administrator mode. + +![RunAs](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-43.png) + +Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" +and right-click the "Windows PowerShell" option when provided. Select "Run as +Administrator" to open a PowerShell prompt in Administrator mode. + +![Windows menu](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-57.png) + +Change the directory to the unzipped directory for the Admin App Installer. + +### Step 4. Run the Installation via PowerShell + +Run "install.ps1" script. + +### Database login setup on integrated security mode + +During the installation process, you will be prompted to choose database login +details. Entering "Y" will continue with default option( Installation process +will create IIS APPPOOL\\AdminApp database login on the server). + +Choosing 'n' will prompt you to enter windows username. The installation process +will validate and create database login using entered username, if the login +does not exist on the database server already. + +![Pws SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-7-6.png) + +![Pws SqlPermissions](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-8-32.png) + +Please refer Steps 5 and 6 for more details on verifying the database login and +setting up the application pool identity. + +The PowerShell output will look something like the following: + +![Pws Installation](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +The installation process sets up an appropriate SQL Login for use with the +dedicated AdminApp Application Pool in IIS. You can verify this in SQL Server +Management Studio: + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +On the Server Roles page, make sure that  "public" and "sysadmin" checkboxes are +checked. Once you have confirmed a proper SQL Server login exists, continue to +the next step. + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 6. Update Application Pool Identity (Optional) + +As mentioned on Step 5, installation process sets up an appropriate SQL Login +for use with the dedicated AdminApp Application Pool in IIS. If you would like +to use the default "ApplicationPoolIdentity", then you can skip this bit. + +Else in the same Advanced Settings window, click on the browse icon under +Process Model > Identity. We'll choose the custom account option and click +"Set...". When setting the credentials, you can just use the username and +password that you use to log in to Windows. If you need to include the app pool +domain in the username, then the username can look something like this: +"localhost\\username", where "localhost" is the app pool domain. Once we have +entered the correct credentials, we'll click OK on all screens until we're back +to the main Application Pools page. + +![Pool Identity](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-24-43.png) + +### Step 7. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://techdocs.ed-fi.org/download/attachments/83801576/Upload-folder-permission.JPG?version=1&modificationDate=1611248544353&api=v2) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://techdocs.ed-fi.org/download/attachments/83801576/AddFolderPermission.JPG?version=1&modificationDate=1611248544370&api=v2) + +:::info note: +If you choose custom login over default Application Pool Identity ( Refer +Step 6 for more details), then make sure the custom login has full control on +the above mentioned folders. +::: + +### Step 8. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. Please see [Securing the Admin App +(v2.x)](../../securing-the-admin-app.md) for more +information. + +### Step 9. Enable Product Improvement Features + +Upon first launch of the Admin App, you will have the option to opt-out of the +**Product Improvement** feature for the application (the user is opted-in by +default). Opting-in to this feature allows the application to collect useful +telemetric data, page views and usage data of the product, as we do with +[Ed-Fi.org](http://Ed-Fi.org) and other Ed-Fi web sites. Admin App also provides +an option to opt-in/out at a later time using the Configuration screen in the +application. Please see [\_Product +Improvement](https://edfi.atlassian.net/wiki/spaces/EDFITOOLS/pages/24118943) +for more information. + +![Product Improvement](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2021-4-29_9-20-3.png) + +:::info + Starting with Admin App 3.0, Product Improvement can be disabled at + the AppSettings level, by setting the `EnableProductImprovementSettings` + setting to `false` . Doing so will _disable_ Product Improvement, skip the + above screen at startup, and remove the "Configuration" screen to prevent + future changes to the setting. If Product Improvement was previously enabled + before this flag was set to `false` , it will become disabled. To restore the + ability to set the Product Improvement configuration, change + \``EnableProductImprovementSettings` back to `true` . +::: + +### Step 10. Open Admin App to Complete Installation + +The installation will default to `https:///AdminApp`. + +To verify and launch the Admin App, open "Internet Information Services (IIS) +Manager". Open the server name, open the Sites folder and open the Ed-Fi branch. +Observe three web applications have been installed for the Ed-Fi Tech Suite. +Clicking on "AdminApp", use Manage Application to view the configured URL. Click +on "Browse ``" to launch Admin App. + +![IIS Manager](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_13-56-8.png) + +### Step 11. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App](../../../getting-started/securing-the-admin-app) +* [Multi-Instance + Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v31.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v31.md new file mode 100644 index 00000000..0524ada7 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v31.md @@ -0,0 +1,407 @@ +# Admin App v3.1 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App v3.1 for ODS/API 3.4 to 6.1. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App has been tested and can be installed for use +with the Ed-Fi ODS / API 3.4 to 6.1. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +Admin App supports two deployment modes:  Docker Deployment and On-Premise +Installation, as documented below.  Please choose the deployment mode that fits +your environment. + +## Docker Deployment for Admin App + +Docker image for Admin App 3.1 is available at: +[https://hub.docker.com/r/edfialliance/ods-admin-app](https://hub.docker.com/r/edfialliance/ods-admin-app) + +Please refer [Docker Deployment - Ed-Fi Tools - Ed-Fi Tech +Docs](https://edfi.atlassian.net/wiki/display/EDFITOOLS/Docker+Deployment) for +more details. + +## On-Premise Installation + +## Prerequisites + +The following are required to install the Admin App: + +:::info note: + Below are links to Nuget packages containing the Admin App Installer + or App Binaries. Download from the link and rename  the file extension to +  `.zip,` or use the PowerShell command from Step 1 below. **Admin App v3.1:** + [EdFi.Suite3.Installer.AdminApp.3.1.2.0.nupkg](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApp.Web/overview/3.1.2) +::: + +:::info note: + The following is the DockerHub repo for **Admin App v3.1.2 Docker + Image** for inclusion in Docker compose: + +* [edfialliance/ods-admin-app:v3.1.2](https://hub.docker.com/layers/edfialliance/ods-admin-app/v3.1.2/images/sha256-b813746fea49e848f0326aed31bdaefdcbb270e28f057a5b62428d7c614987e7?context=explore) +::: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the supported Ed-Fi ODS / API + deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via [binary + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) + or [source code + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation). +* Both the [.NET 6 SDK and .NET 6 Hosting + Bundle](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) are required + on the destination server before installation of Admin App. + * After installing the .NET Core SDK and the .NET Core SDK, it is necessary to + restart the computer for the changes to take effect. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v6.0 installation. +* IIS must be enabled before installing .Net Core Hosting Bundle. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +Admin App does not today support in-place upgrades from prior versions.  Please +install a fresh copy of Admin App to upgrade from prior versions. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +* Admin App v3.1 + * [Compatibility \& Supported ODS / API Versions](#compatibility--supported-ods--api-versions) + * [Docker Deployment for Admin App](#docker-deployment-for-admin-app) + * [On-Premise Installation](#on-premise-installation) + * [Prerequisites](#prerequisites) + * [Installation Instructions](#installation-instructions) + * [On-Premises Deployment](#on-premises-deployment) + * [Step 1. Download and Open Installer Package](#step-1-download-and-open-installer-package) + * [Step 2. Configure Installation](#step-2configure-installation) + * [Step 3. Open a PowerShell Prompt in Administrator Mode](#step-3-open-a-powershell-prompt-in-administrator-mode) + * [Step 4. Run the Installation via PowerShell](#step-4-run-the-installation-via-powershell) + * [Database login setup on integrated security mode](#database-login-setup-on-integrated-security-mode) + * [Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true")](#step-5-create-sql-server-login-if-useintegratedsecurity-set-to-true) + * [Step 6. Update Application Pool Identity (Optional)](#step-6-update-application-pool-identity-optional) + * [Step 7. Check Folder Permissions**](#step-7-check-folder-permissions) + * [Step 8. Create Initial Administrative User](#step-8-create-initial-administrative-user) + * [Step 9. Open Admin App to Complete Installation](#step-9-open-admin-app-to-complete-installation) + * [Step 10. Using the Admin App](#step-10-using-the-admin-app) + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +Download , rename the file extension from to `.zip`  and unzip the package + +* Installer and binaries for Admin App 3.1: + [EdFi.Suite3.ODS.AdminApp.Web.3.1.2.nupkg](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApp.Web/overview/3.1.2) + +Alternatively, run the below PowerShell command to download the package as a zip +file directly: + +```shell +# Web App Binaries +Invoke-WebRequest "https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/3.1.2/content?api-version=6.0-preview.1" -OutFile .\EdFi.Suite3.ODS.AdminApp.Web-3.1.2.0.zip +``` + +### Step 2. Configure Installation + +Open the "install.ps1" file on installer folder in a text editor. You will need +to edit this file with your configuration details. If a value is not present for +any of the parameters, it will use its default value. + +:::info note: + Editing Item 3b below is mandatory for ODS / API URL and must be done + for installation to complete. +::: + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + + c1. If you plan to use Windows authentication, this value will be "$true" + + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + d. `WebApplicationName.` Optional. Defaults to "AdminApp". + + e. `WebSitePort`. Optional. Defaults to 443. + + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Configuration samples for the "install.ps1" file: + +:::info note: + SQL Server Shared Instance + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + } + ``` + +::: + +:::info note: + + PostgreSQL District Specific + + **install.ps1(PostgreSQL)** + + ```json + $dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" + } + + $adminAppFeatures = @{ + ApiMode = "districtspecific" + } + + $parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +:::info note: + + SQL Server Year Specific + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $adminAppFeatures = @{ + ApiMode = "yearspecific" + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +### Step 3. Open a PowerShell Prompt in Administrator Mode + +Method 1: Open \[Windows Key\]-R which will open a Run dialog for tasks needing +administrative privileges. Type "PowerShell" to open a PowerShell prompt in +Administrator mode. + +![RunAs](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-43.png) + +Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" +and right-click the "Windows PowerShell" option when provided. Select "Run as +Administrator" to open a PowerShell prompt in Administrator mode. + +![Windows Menu](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-57.png) + +Change the directory to the unzipped directory for the Admin App Installer. + +### Step 4. Run the Installation via PowerShell + +Run "install.ps1" script. + +### Database login setup on integrated security mode + +During the installation process, you will be prompted to choose database login +details. Entering "Y" will continue with default option( Installation process +will create IIS APPPOOL\\AdminApp database login on the server). + +Choosing 'n' will prompt you to enter windows username. The installation process +will validate and create database login using entered username, if the login +does not exist on the database server already. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-7-6.png) + +![SqlLogin Credentials](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-8-32.png) + +Please refer Steps 5 and 6 for more details on verifying the database login and +setting up the application pool identity. + +The PowerShell output will look something like the following: + +![Pws Installation](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +The installation process sets up an appropriate SQL Login for use with the +dedicated AdminApp Application Pool in IIS. You can verify this in SQL Server +Management Studio: + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +On the Server Roles page, make sure that  "public" and "sysadmin" checkboxes are +checked. Once you have confirmed a proper SQL Server login exists, continue to +the next step. + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 6. Update Application Pool Identity (Optional) + +As mentioned on Step 5, installation process sets up an appropriate SQL Login +for use with the dedicated AdminApp Application Pool in IIS. If you would like +to use the default "ApplicationPoolIdentity", then you can skip this bit. + +Else in the same Advanced Settings window, click on the browse icon under +Process Model > Identity. We'll choose the custom account option and click +"Set...". When setting the credentials, you can just use the username and +password that you use to log in to Windows. If you need to include the app pool +domain in the username, then the username can look something like this: +"localhost\\username", where "localhost" is the app pool domain. Once we have +entered the correct credentials, we'll click OK on all screens until we're back +to the main Application Pools page. + +![Pool Identity](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-24-43.png) + +### Step 7. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +:::info note: +If you choose custom login over default Application Pool Identity ( Refer +Step 6 for more details), then make sure the custom login has full control on +the above mentioned folders. +::: + +### Step 8. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. Please see [Securing the Admin App +(v2.x)](../../securing-the-admin-app.md) for more +information. + +### Step 9. Open Admin App to Complete Installation + +The installation will default to `https:///AdminApp`. + +To verify and launch the Admin App, open "Internet Information Services (IIS) +Manager". Open the server name, open the Sites folder and open the Ed-Fi branch. +Observe three web applications have been installed for the Ed-Fi Tech Suite. +Clicking on "AdminApp", use Manage Application to view the configured URL. Click +on "Browse ``" to launch Admin App. + +![Product Improvement](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_13-56-8.png) + +### Step 10. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App](../../../getting-started/securing-the-admin-app) +* [Multi-Instance + Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v32.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v32.md new file mode 100644 index 00000000..1e154bd5 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/admin-app-v32.md @@ -0,0 +1,407 @@ +# Admin App v3.2 + +## Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App v3.2 for ODS/API 3.4 to 6.1. + +## Compatibility & Supported ODS / API Versions + +This version ODS / API Admin App has been tested and can be installed for use +with the Ed-Fi ODS / API 3.4 to 6.1. See the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) for +more details. + +Admin App supports two deployment modes:  Docker Deployment and On-Premise +Installation, as documented below.  Please choose the deployment mode that fits +your environment. + +## Docker Deployment for Admin App + +Docker image for Admin App 3.2 is available at: +[https://hub.docker.com/r/edfialliance/ods-admin-app](https://hub.docker.com/r/edfialliance/ods-admin-app) + +Please refer [Docker Deployment - Ed-Fi Tools - Ed-Fi Tech +Docs](https://edfi.atlassian.net/wiki/display/EDFITOOLS/Docker+Deployment) for +more details. + +## On-Premise Installation + +## Prerequisites + +The following are required to install the Admin App: + +:::info note: + Below are links to Nuget packages containing the Admin App Installer + or App Binaries. Download from the link and rename  the file extension to +  `.zip,` or use the PowerShell command from Step 1 below. **Admin App v3.2:** + [EdFi.Suite3.Installer.AdminApp.3.2.1.0.nupkg](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApp.Web/overview/3.2.1) +::: + +:::info note: + The following is the DockerHub repo for **Admin App v3.2.1 Docker + Image** for inclusion in Docker compose: + +* [edfialliance/ods-admin-app:v3.2.1](https://hub.docker.com/layers/edfialliance/ods-admin-app/v3.2.1/images/sha256-6e924a4fd629a7c97acbec12cf32687abfa8eabde48d02600711d365bac823ab?context=explore) +::: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an instance of the supported Ed-Fi ODS / API + deployed and operational before you can use the Admin App. Tested + configurations include on-premises installation via [binary + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100419/Getting+Started+-+Binary+Installation) + or [source code + installation](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V520/pages/25100348/Getting+Started+-+Source+Code+Installation). +* Both the [.NET 6 SDK and .NET 6 Hosting + Bundle](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) are required + on the destination server before installation of Admin App. + * After installing the .NET Core SDK and the .NET Core SDK, it is necessary to + restart the computer for the changes to take effect. +* A SQL Server 2012 or higher, or Postgres 11 or higher database server as also + in use with your ODS / API v6.0 installation. +* IIS must be enabled before installing .Net Core Hosting Bundle. +* A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft + Edge. Internet Explorer 11 (a pre-installed browser on Windows Server) may + load, but may not function when using Admin App. + +Admin App does not today support in-place upgrades from prior versions.  Please +install a fresh copy of Admin App to upgrade from prior versions. + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +## Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +* Admin App v3.2 + * [Compatibility \& Supported ODS / API Versions](#compatibility--supported-ods--api-versions) + * [Docker Deployment for Admin App](#docker-deployment-for-admin-app) + * [On-Premise Installation](#on-premise-installation) + * [Prerequisites](#prerequisites) +* [Installation Instructions](#installation-instructions) + * [On-Premises Deployment](#on-premises-deployment) + * [Step 1. Download and Open Installer Package](#step-1-download-and-open-installer-package) + * [Step 2. Configure Installation](#step-2configure-installation) + * [Step 3. Open a PowerShell Prompt in Administrator Mode](#step-3-open-a-powershell-prompt-in-administrator-mode) + * [Step 4. Run the Installation via PowerShell](#step-4-run-the-installation-via-powershell) + * [Database login setup on integrated security mode](#database-login-setup-on-integrated-security-mode) + * [Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true")](#step-5-create-sql-server-login-if-useintegratedsecurity-set-to-true) + * [Step 6. Update Application Pool Identity (Optional)](#step-6-update-application-pool-identity-optional) + * [Step 7. Check Folder Permissions](#step-7-check-folder-permissions) + * [Step 8. Create Initial Administrative User](#step-8-create-initial-administrative-user) + * [Step 9. Open Admin App to Complete Installation](#step-9-open-admin-app-to-complete-installation) + * [Step 10. Using the Admin App](#step-10-using-the-admin-app) + +## On-Premises Deployment + +Each step is outlined in detail below for the PowerShell deployment. Ensure that +you have permission to execute PowerShell scripts. For more information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +### Step 1. Download and Open Installer Package + +Download , rename the file extension from to `.zip`  and unzip the package + +* Installer and binaries for Admin App 3.2: + [EdFi.Suite3.ODS.AdminApp.Web.3.2.1.nupkg](https://dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_artifacts/feed/EdFi/NuGet/EdFi.Suite3.ODS.AdminApp.Web/overview/3.2.1) + +Alternatively, run the below PowerShell command to download the package as a zip +file directly: + +```shell +# Web App Binaries +Invoke-WebRequest "https://pkgs.dev.azure.com/ed-fi-alliance/Ed-Fi-Alliance-OSS/_apis/packaging/feeds/EdFi/nuget/packages/EdFi.Suite3.ODS.AdminApp.Web/versions/3.2.1/content?api-version=6.0-preview.1" -OutFile .\EdFi.Suite3.ODS.AdminApp.Web-3.2.1.0.zip +``` + +### Step 2. Configure Installation + +Open the "install.ps1" file on installer folder in a text editor. You will need +to edit this file with your configuration details. If a value is not present for +any of the parameters, it will use its default value. + +:::info note: + Editing Item 3b below is mandatory for ODS / API URL and must be done + for installation to complete. +::: + +1. Configure `$dbConnectionInfo`. These values are used to construct the + connection strings. + + a. `Server`. The name of the database server. For a local server, we can use + "(local)" for SQL and "localhost" for PostgreSQL. + + b. `Engine.` Admin App supports SQL and PostgreSQL database engines. So + setting up the `Engine` will decide which database engine to be used. + Valid values are "SQLServer" and "PostgreSQL". + + c. `UseIntegratedSecurity.` Will either be "$true" or "$false". + c1. If you plan to use Windows authentication, this value will be "$true" + + c2. If you plan to use SQL Server/ PostgreSQL server authentication, this + value will be "$false" and the Username and `Password` must be + provided. + + d. `Username`. Optional. The username to connect to the database. + If `UseIntegratedSecurity` is set to $true, this entry is not needed + + e. `Password`. Optional. The password to connect to the + database. If `UseIntegratedSecurity` is set to $true, this entry is not + needed + + f. `Port.` Optional. Used to specify the database server port, presuming the + server is configured to use the specific port. + +2. Configure `$adminAppFeatures`. These values are used to set Optional + overrides for features and settings in the web.config. + + a. `ApiMode.` Possible values: `sharedinstance`, `districtspecific` and + `yearspecific`. Defaults to `sharedinstance` + + b. `SecurityMetadataCacheTimeoutMinutes`. Optional. Defaults to 10 minute + security metadata cache timeout. + +3. Configure `$p`. This is the variable used to send all the information to the + installation process. + + a. `ToolsPath`. Path for storing installation tools, e.g., nuget.exe. + Defaults to "C:/temp/tools" + + b. **`OdsApiUrl`. Base URL for the ODS / API. Mandatory.** + + c. `AdminDatabaseName`. , `OdsDatabaseName`, + `SecurityDatabaseName`. Optional. Specify _only_ if ODS / API was set + with a custom database name. + + c1. For example, when configuring the `OdsDatabaseName`, the value here + will be the name of the ODS database, whereas the `AdminDatabaseName` + and `SecurityDatabaseName` will be the name of the Admin and Security + databases, respectively. + + d. `WebApplicationName.` Optional. Defaults to "AdminApp". + + e. `WebSitePort`. Optional. Defaults to 443. + + f. `WebsiteName`. Optional. Defaults to "Ed-Fi". + + g. `PackageVersion`. Optional. If not set, will retrieve the latest full + release package. + +Configuration samples for the "install.ps1" file: + +:::info note: + + SQL Server Shared Instance + + **install.ps1(SQL Server)** + + ```json + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + } + ``` + +::: + +:::info note: + + PostgreSQL District Specific + + **install.ps1(PostgreSQL)** + + ```json + $dbConnectionInfo = @{ + Server = "localhost" + Engine = "PostgreSQL" + Username = "exampleAdmin" + Password = "examplePassword" + } + + $adminAppFeatures = @{ + ApiMode = "districtspecific" + } + + $parameters = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +:::info note: + + SQL Server Year Specific + + **install.ps1(SQL Server)** + + ``` + $dbConnectionInfo = @{ + Server = "(local)" + Engine = "SqlServer" + UseIntegratedSecurity = $true + } + + $adminAppFeatures = @{ + ApiMode = "yearspecific" + } + + $p = @{ + DbConnectionInfo = $dbConnectionInfo + OdsApiUrl = "https://localhost:54746" + AdminAppFeatures = $adminAppFeatures + } + + ``` + +::: + +### Step 3. Open a PowerShell Prompt in Administrator Mode + +Method 1: Open \[Windows Key\]-R which will open a Run dialog for tasks needing +administrative privileges. Type "PowerShell" to open a PowerShell prompt in +Administrator mode. + +![RunAs](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-43.png) + +Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" +and right-click the "Windows PowerShell" option when provided. Select "Run as +Administrator" to open a PowerShell prompt in Administrator mode. + +![Windows Menu](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_12-37-57.png) + +Change the directory to the unzipped directory for the Admin App Installer. + +### Step 4. Run the Installation via PowerShell + +Run "install.ps1" script. + +### Database login setup on integrated security mode + +During the installation process, you will be prompted to choose database login +details. Entering "Y" will continue with default option( Installation process +will create IIS APPPOOL\\AdminApp database login on the server). + +Choosing 'n' will prompt you to enter windows username. The installation process +will validate and create database login using entered username, if the login +does not exist on the database server already. + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-7-6.png) + +![SqlLogin Credentials](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-8-32.png) + +Please refer Steps 5 and 6 for more details on verifying the database login and +setting up the application pool identity. + +The PowerShell output will look something like the following: + +![Pws Installation](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Successful-Installation.JPG) + +### Step 5. Create SQL Server Login (if "useIntegratedSecurity" set to "true") + +This step only needs to be completed if you set `useIntegratedSecurity` to true +on the "install.ps1" script in Step 2, above. If you did not, we can skip ahead +to Step 5. + +The installation process sets up an appropriate SQL Login for use with the +dedicated AdminApp Application Pool in IIS. You can verify this in SQL Server +Management Studio: + +![SqlLogin](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SqlLogin.JPG) + +On the Server Roles page, make sure that  "public" and "sysadmin" checkboxes are +checked. Once you have confirmed a proper SQL Server login exists, continue to +the next step. + +![SQLLogin-role](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/SQLLogin-role.JPG) + +### Step 6. Update Application Pool Identity (Optional) + +As mentioned on Step 5, installation process sets up an appropriate SQL Login +for use with the dedicated AdminApp Application Pool in IIS. If you would like +to use the default "ApplicationPoolIdentity", then you can skip this bit. + +Else in the same Advanced Settings window, click on the browse icon under +Process Model > Identity. We'll choose the custom account option and click +"Set...". When setting the credentials, you can just use the username and +password that you use to log in to Windows. If you need to include the app pool +domain in the username, then the username can look something like this: +"localhost\\username", where "localhost" is the app pool domain. Once we have +entered the correct credentials, we'll click OK on all screens until we're back +to the main Application Pools page. + +![Pool Identity](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2022-9-20_12-24-43.png) + +### Step 7. Check Folder Permissions + +Folders to verify: + +1. Admin App application "uploads" folder (default folder path: + C:\\inetpub\\Ed-Fi\\AdminApp\\uploads). +2. Admin App log folder (default folder path: + C:\\ProgramData\\Ed-Fi-ODS-AdminApp). + +For checking permissions: + +* **Right-click** the folder, choose **Properties**, view the **Security** tab. +* Verify the "Group or user names" section has AdminApp with Full control. + +![Properties](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/Upload-folder-permission.JPG) + +If the AdminApp not available on the list, add with Full control. + +![Permission groups](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/AddFolderPermission.JPG) + +:::info note: +If you choose custom login over default Application Pool Identity ( Refer +Step 6 for more details), then make sure the custom login has full control on +the above mentioned folders. +::: + +### Step 8. Create Initial Administrative User + +Upon first launch of the Admin App, you will have to create the initial +administrative user for the application. This consists of creating a username +and password for the initial user. Additional users can be added at a later +time. Please see [Securing the Admin App +(v2.x)](../../securing-the-admin-app.md) for more +information. + +### Step 9. Open Admin App to Complete Installation + +The installation will default to `https:///AdminApp`. + +To verify and launch the Admin App, open "Internet Information Services (IIS) +Manager". Open the server name, open the Sites folder and open the Ed-Fi branch. +Observe three web applications have been installed for the Ed-Fi Tech Suite. +Clicking on "AdminApp", use Manage Application to view the configured URL. Click +on "Browse ``" to launch Admin App. + +![Product Improvement](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/older-versions-of-admin-app/image2020-4-20_13-56-8.png) + +### Step 10. Using the Admin App + +The Admin App is now configured for use with your Ed-Fi ODS / API instance. +Please visit the following articles to help with next actions in using Admin +App: + +* [Securing the Admin App](../../../getting-started/securing-the-admin-app) +* [Multi-Instance + Connections](../../../getting-started/multi-instance-connections) +* [Next Steps](../../../getting-started/next-steps) +* [Known Issues](../../../getting-started/known-issues) diff --git a/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/readme.md b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/readme.md new file mode 100644 index 00000000..449b9889 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/older-versions-of-admin-app/readme.md @@ -0,0 +1,15 @@ +# Older Versions of Admin App + +Below are older versions of Admin App: + +* [Admin App v3.2](admin-app-v32) +* [Admin App v3.1](admin-app-v31) +* [Admin App v3.0 for ODS/API v6.0](admin-app-v30-for-odsapi-v60) +* [Admin App for Suite 3 v2.4](admin-app-for-suite-3-v24) +* [Admin App for Suite 3 v2.3](admin-app-for-suite-3-v23) +* [Admin App for Suite 3 v2.2.1](admin-app-for-suite-3-v221) +* [Admin App for Suite 3 v2.2](admin-app-for-suite-3-v22) +* [Admin App for Suite 3 v2.1](admin-app-for-suite-3-v21) +* [Admin App for Suite 3 v2.0.1](admin-app-for-suite-3-v201) +* [Admin App v1.8.1 for Ed-Fi ODS / API v3.4](admin-app-v181-for-ed-fi-ods-api-v34) +* [Admin App v1.7 for ODS / API v3.3](admin-app-v17-for-ods-api-v33) diff --git a/docs/reference/8-admin-app/getting-started/installation/readme.md b/docs/reference/8-admin-app/getting-started/installation/readme.md new file mode 100644 index 00000000..f43d536a --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/installation/readme.md @@ -0,0 +1,7 @@ +# Installation + +Below are installation guides to match the targeted version of Admin App and ODS +/ API: + +* [Admin App v3.3](admin-app-v33) +* [Older Versions of Admin App](older-versions-of-admin-app) diff --git a/docs/reference/8-admin-app/getting-started/known-issues.md b/docs/reference/8-admin-app/getting-started/known-issues.md new file mode 100644 index 00000000..a6c8206b --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/known-issues.md @@ -0,0 +1,133 @@ +# Known Issues + +Below are known issues with information or workarounds for the Admin App for +Ed-Fi Technical Suite Two and Three as supported by active ODS / API releases. +This page will be updated as issues are found and resolved. + +## Can I use Admin App for my sandbox mode ODS / API instance?** + +No, Admin App supports shared, year-specific and district-specific modes only. +Admin App does not support sandbox mode which is intended for development and +the [Sandbox Administration +Portal](https://edfi.atlassian.net/wiki/display/ODSAPIS3V520/Using+the+Sandbox+Administration+Portal) +is the tool to use for sandbox modes.  Admin App cannot administer sandbox +instances nor instances that started as sandboxes, then migrated to other modes. + +**An error message when synching learning standards that reads “### learning +standards may not have synchronized…”** + +Ed-Fi is aware of an issue where all available standards from Academic +Benchmarks may not fully load on the first try. If this occurs, you will get a +similar error message to “### learning standards may not have synchronized…”. +The technical issue is a sequencing of learning standards between parent and +child related elements. We are working on a resolution to this issue for release +in the fall. For the time being, to resolve this issue, repeat the loading of +standards using Admin App until the error message goes away. While this is an +edge case in our QA testing, we've found that 1–3 more tries typically resolves +this issue when presented. + +For any issues not identified here, as well as suggestions for improvements, +please use the [Ed-Fi Tracker](https://tracker.ed-fi.org) to file an issue or +bug report under the "EDFI" queue for development review and resolution. + +## Rerun Admin App's First-Time Setup** + +The steps below will reset Admin App as if it was a fresh install, and can be +useful if the connection between Admin App and the ODS API becomes corrupted. +This will keep any new Vendors, Applications, or Claim Sets you created with the +Admin App + +1. Replace secret.json file with default content. This file exists in the root + of the web site directory. Delete the secret.json and re-create it with the + following content. **Note: this is only required for versions before Admin + App 1.8**. For Admin App versions 1.8+ you can skip this step. + + ```json + { + "AdminCredentials": { + "Password": "", + "UserName": "", + "UseIntegratedSecurity": "false" + }, + "StagingApiCredentials": { + "Password": "", + "UserName": "" + }, + "HostName": ".\\", + "ProductionApiCredentials": { + "Password": "", + "UserName": "EdFiOdsProductionApi" + }, + "AdminAppCredentials": { + "Password": "", + "UserName": "EdFiOdsAdminApp" + } + } + ``` + +2. Create a new text file named `SetupRequired` and remove the file extension + so it shows as “File” in file explorer. **Note: this is only required for + versions before Admin App 2.0.1**. For Admin App versions 2.0+ you can skip + this step. +3. Connect to the EdFi\_Admin database on your SQL Server and remove old data + created by the original run of setup. There might be a table in the sample + below that doesn’t exist -- you can remove these lines if they show an error + in SSMS. + + :::info Note + please use Admin App version appropriate script + ::: + + **Admin App 1.8** + + ```sql + BEGIN TRAN + DECLARE @ApplicationId INT; + SELECT @ApplicationId = ApplicationId FROM dbo.Applications WHERE ApplicationName = 'Ed-Fi ODS Admin App' DELETE FROM dbo.ClientAccessTokens WHERE EXISTS ( + SELECT 1 FROM dbo.ApiClients + WHERE ClientAccessTokens.ApiClient_ApiClientId = ApiClients.ApiClientId + AND Application_ApplicationId = @ApplicationId + ) + + -- Depending on your ODS version, this table might not exist and can be safely removed from the query + DELETE FROM dbo.ClientAuthorizationCodes WHERE EXISTS ( + SELECT 1 FROM dbo.ApiClients + WHERE ClientAuthorizationCodes.ApiClient_ApiClientId = ApiClients.ApiClientId + AND Application_ApplicationId = @ApplicationId + ) + + DELETE FROM dbo.ApiClients WHERE Application_ApplicationId = @ApplicationId + DELETE FROM dbo.ApplicationEducationOrganizations WHERE Application_ApplicationId = @ApplicationId + DELETE FROM dbo.ProfileApplications WHERE Application_ApplicationId = @ApplicationId + DELETE FROM dbo.Applications WHERE ApplicationId = @ApplicationId + DELETE FROM dbo.OdsInstances + + ``` + + **Admin App 2.0+** + + ```sql + BEGIN TRAN + DECLARE @ApplicationId INT; + DECLARE @InstanceId INT; + SELECT @ApplicationId = ApplicationId FROM dbo.Applications WHERE ClaimSetName = 'Ed-Fi ODS Admin App' + SELECT @InstanceId = OdsInstanceId FROM dbo.OdsInstances WHERE Name ='EdFi ODS' --default instance name may vary + DELETE FROM dbo.ClientAccessTokens WHERE EXISTS ( + SELECT 1 FROM dbo.ApiClients + WHERE ClientAccessTokens.ApiClient_ApiClientId = ApiClients.ApiClientId + AND Application_ApplicationId = @ApplicationId + ) + DELETE FROM dbo.ApiClients WHERE Application_ApplicationId = @ApplicationId + DELETE FROM dbo.ApplicationEducationOrganizations WHERE Application_ApplicationId = @ApplicationId + DELETE FROM dbo.ProfileApplications WHERE Application_ApplicationId = @ApplicationId + DELETE FROM dbo.Applications WHERE ApplicationId = @ApplicationId + DELETE FROM adminapp.SecretConfigurations + DELETE FROM adminapp.OdsInstanceRegistrations + DELETE FROM adminapp.ApplicationConfigurations + UPDATE dbo.Applications set OdsInstance_OdsInstanceId = null where OdsInstance_OdsInstanceId = @InstanceId + DELETE FROM [EdFi_Admin].[dbo].[OdsInstances] where OdsInstanceId = @InstanceId + COMMIT TRAN + + ``` + +4. Relaunch Admin App and you should see First Time Setup again. diff --git a/docs/reference/8-admin-app/getting-started/multi-instance-connections.md b/docs/reference/8-admin-app/getting-started/multi-instance-connections.md new file mode 100644 index 00000000..52790baa --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/multi-instance-connections.md @@ -0,0 +1,120 @@ +# Multi-Instance Connections + +## Overview + +Admin App supports administration of multiple ODS instances with a single +instance of the Admin App. + +Admin App supports two roles for this, the Super-Administrator role that can +view and register all ODS / API instances and their functions, and the +Administrator role that is assigned to particular ODS / API instances and their +settings. + +Note that the Admin App does not create multiple ODS / API instances. It +connects to pre-existing instances of the ODS / API, which must be deployed +prior to connection with the Admin App. + +The ODS / API modes supported by multi-instance management within Admin App are: + +1. [District-Specific ODS + Configuration](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V500/pages/18350192/District-Specific+ODS+Configuration) +2. [Year-Specific ODS + Configuration](https://edfi.atlassian.net/wiki/spaces/ODSAPIS3V500/pages/18350191/Year-Specific+ODS+Configuration) + +## General Configuration + +### General + +When multi-instance mode is enabled, users can navigate to ODS Instances list by +clicking on “ODS Instances” from Home page. + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/SuperAdmin-Home.JPG) + +In the absence of any registered instance, the user will be directed to the +Register ODS Instance page.  Otherwise, the user will be presented with +available ODS instances. + +## ODS Instances + +### District-Specific Mode + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/SuperAdmin-InstancesList.JPG) + +  Clicking on the District / EdOrg id link will take the user to an +  instance-specific ODS settings page. + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/Multi-instance-ApplicationsPage.JPG) + +### Year-Specific Mode + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/SuperAdmin-YS-InstancesList.JPG) + +Clicking on the school year will take user to year-specific ODS instance +settings page. + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/SuperAdmin-YS-Application.JPG) + +## Registering New ODS Instance + +### Checklist + + The following checklist and the details below ensure a successful ODS instance + registration: + +* Database should exist on the server. + +          Given a District/EdOrg id or school year, the system will generate a valid instance name (Database name). + +          Ex: District/EdOrg id provided by user = 255901 + +                EdFi\_Ods\_Production database name on web.config = EdFi\_{0} + +                Then generated ODS instance name will be = EdFi\_Ods\_255901 + +                User has to make sure, the database (EdFi\_Ods\_255901) exists on the server. + +* Generated ODS instance / database name length should be below 50 characters. + +**District-Specific Mode** + +* To register a district-specific ODS instance, the user needs to provide a + valid ODS Instance District/EdOrg id and ODS Instance Description. + +![District-Specific](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/SuperAdmin-RegiterNewInstance.JPG) + +**Year-Specific Mode** + +* To register a year-specific ODS instance, the user needs to provide a valid + ODS Instance School Year and ODS Instance Description. + +![Year-Specific](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/SuperAdmin-Registr-YS-Instance.JPG) + +**Registering Many Instances in Bulk** + +* To register many instances in bulk, the user can upload a list of + district/education organization IDs or school years plus descriptions. The + uploaded list must be a CSV file. + +![Bulk Instances](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/SuperAdmin-YS-BulkRegistration.JPG) + +Uploaded CSV files must have the header values NumericSuffix and Description in +the first row. See the listings below for example content. + +**District-Specific sample CSV content** Expand source + +```cs +NumericSuffix,Description +255901,Sampledistrict1 +255902,Sampledistrict2 +255903,Sampledistrict3 +255904,Sampledistrict4 +``` + +**Year-Specific sample CSV content** Expand source + +```cs +NumericSuffix,Description +2019,Description1 +2020,Description2 +2021,Description3 +``` diff --git a/docs/reference/8-admin-app/getting-started/next-steps.md b/docs/reference/8-admin-app/getting-started/next-steps.md new file mode 100644 index 00000000..9bb0c19c --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/next-steps.md @@ -0,0 +1,258 @@ +# Next Steps + +This section outlines a few recommended next steps following a successful +installation: + +## Explore Admin App Features + +After installation, consider exploring the Admin App itself: + +* **Review and edit education organizations.** This allows you to set up + district and school information specific to your organization. If you + installed the Admin App for a new, empty ODS / API, this provides you with an + easy setup. If your Admin App is pointing to an existing ODS / API, you can + confirm that the education organization information is as you expect. +* **Review Ed-Fi Descriptors.** Ed-Fi technology allows you to configure value + lists (i.e., code sets) specific to your context using Ed-Fi Descriptors. You + can review Descriptors in the Admin App to make sure the as-shipped ODS / API + contains values appropriate for your environment. +* **Add client systems.** Data moves in and out of the ODS / API from client + systems such as a student information system, assessment system, rostering + system, and so forth. If your Admin App is connected to a new instance of the + ODS / API, you'll need to set up client systems and provide those system + administrators with credentials to get data into your new ODS / API. If your + Admin App is connected to an existing instance, you can verify that the + vendors and applications are set up as you expect. +* **Add learning standards.** The Ed-Fi Alliance and Certica Solutions partnered + to offer the Academic Benchmarks system of learning standards mappings + available through the Ed-Fi Operational Data Store (Ed-Fi ODS/API). This + partnership will make Academic Benchmarks’ digitized learning standards + readily available to education agencies and vendors. The Admin App has + built-in synchronization to populate an ODS / API directly from Certica AB. + The license is free, and can be obtained online by [visiting this + link](https://certicasolutions.com/products/academic-benchmarks/#demo). + +## Admin App Walkthrough + +Below is a quick start guide and walk through of Admin App's important features. + +### Add Vendor & Application + +In this step, we'll add a new vendor and a client application. + +If you're not already there, go to the Admin App Home page: + +![Vendor Application](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-5-7.png) + +Click **Global** and you'll be presented with the screen below with two +tabs: Vendors and Claim Sets. + +Details for the Claim Sets tab can be found +here: [https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/25238340](https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/25238340). + +We'll continue with the Vendor tab to add a vendor. + +![Main Vendors](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-3-7.png) + +Clicking on Add Vendor will open the following screen for adding a new vendor. + +![Add Vendor](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-6-49.png) + +Please enter company, namespace, contact name, and contact e-mail address and +hit Save Changes. + +![Define Applications](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2021-4-29_9-57-21.png) + +Now, we'll add an application to the vendor we just created. Applications are +specific to an ODS / API instance. We can go to the Application creation screen +using the **Define Applications** button that appears besides the Add Vendor +button when we create the first vendor. In **Shared Instance mode**, the +**Define Applications** button simply takes you to the Applications tab for the +single instance. In **District/Year Specific modes**, the **Define +Applications** button takes you to the Instance selection screen. If there are +instances registered already, the user is guided to select an instance to define +applications for it. + +![Instances](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image-2021-03-26-10-07-59-556.png) + +If there are no instances registered, a **super admin** user is guided to + register an instance and define applications for it. + + ![Define Applications](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image-2021-03-26-10-05-33-329.png) + +If there are no instances registered, a **non-super admin** user is guided to +contact a super admin to get an instance assigned and proceed further. + +![Applications Permissions](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image-2021-03-26-10-04-39-050.png) + +Click on the **Settings from Home** page will take you to **ODS Instance** +section. + +![Ods Section](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-9-36.png) + +Clicking on Add Application will show following screen. + +![Add Application](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/Applicationpage5.JPG) + +Steps for adding application to vendor + +* Provide application name +* Select either option for education organization type +* Choose any available education organization ID from the drop-down menu +* Select appropriate claim set name +* Click Add Application to save the application + +You will be presented with the Key and Secret at the next screen. Copy this +information to a safe place. + +It's useful to test client system functionality (in this document we will be +using the generated key and secret for Bulk upload process). + +![Product Application](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-1-24_16-20-38.png) + +After completing the above step, you'll see the new Test application you just +added. + +![Application](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-11-18.png) + +## Descriptors tab + +View configured descriptors for a known instance. + +![Descriptor tab](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-12-33.png) + +## Education Organizations tab + +View and manage education organizations (LEAs and schools). + +![Education Org](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-13-31.png) + +## Bulk Upload process + +You can enter a generated key and secret here and save the credentials. The +saved key and secret will be used to authorize bulk upload processes. + +![Bulk Upload](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-14-19.png) + +After saving credentials, bulk upload page will be presented. + +![Bulk Modal](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-17-17.png) + +To perform upload, please select appropriate file type and input file and click +upload. After clicking the upload button, the popup will display the upload +progress. + +![Bulk Progress](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/page12.JPG) + +Bulk upload is completed successfully. + +## Sync Learning Standards + +In this step, we'll populate learning standards in the ODS / API by using the +Admin App to synchronize with the AB Connect API. + +To synchronize learning standards in on local environment, select the **Learning +Standards** tab. You'll be presented with the screen below: + +![Learning Standards](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-18-44.png) + +The screen contains instructions on how to get an API ID and Key from Certica +Solutions. Following the instructions on screen to obtain an ID and Key. + +Please enter AB connect ID and Key obtained from Certica and click **Enable +Learning Standards.** Syncing will begin. A progress bar will show you the +current status, and you'll see a "completed successfully" message once done. + +![Learning Standards Progress](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-19-30.png) + +Clicking Reload will take you to the following screen, where you can reset the +AB connect credentials or update the learning standards. + +![Learning Standards Connected](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-20-15.png) + +## Optional Verification Step + +To confirm that learning standards have been populated, a SQL query, such as +shown below, can be run against your ODS / API instance database. The query +should return a count in the thousands from a successful learning standards +synchronization: + +```sql +SELECT COUNT(*) FROM EdFi.LearningStandard WHERE [Namespace] LIKE '%api.academicbenchmarks%'; +``` + +### Reports + +Select Reports tab for Ods Instance specific reports. + +![Report Main](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-21-7.png) + +Choosing district will provide district specific reports. + +![Report District](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-21-58.png) + +By clicking on the individual report link will take you to the detailed report +page. + +![Report Individual](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2020-4-17_13-22-45.png) + +## New features in Admin App 2.2 + +### Product Improvement + +User can find [Product Improvement details +here](https://edfi.atlassian.net/wiki/display/EDFITOOLS/Product+Improvement). + +### Edit School Year + +In this step, the user can set the ODS instance-level School Year setting. The +school year dropdown provides a list of possible years and lets the Admin App +user witness the current selection as well as change that selection. + +In **Shared Instance mode**, the year selection is visible and editable in the +header of the Instance Settings screen. + +![Shared Instances](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image-2021-03-18-17-29-15-964.png) + +In **District/Year Specific modes**, the **Set School Year** column is visible +and editable for the registered instances on the Registered Instances screen. +![District Year](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image-2021-03-19-12-10-48-570.png) + +![Year](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image-2021-03-19-12-11-52-878.png) + +Clicking the edit pencil icon opens up a modal to select the current school year +from the dropdown of possible school years. + +![School Year](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image2021-4-29_8-29-43.png) + +There are special considerations for Year Specific mode. At instance +registration time, we default the instance's year selection to the single year +that the instance is dedicated for, saving the user from (likely) ever needing +to edit it themselves. However, we do still offer the controls, primarily so a +user could correct the system if the school year was altered outside of the +app. When a user goes to edit the year in Year Specific mode, we put up a +warning as well as suggest exactly what value is expected for that instance. +This warning and suggestion also helps to guide the user away from an "off by +one" mistake as "Current Year 2021" really corresponds with a "2020-2021" +school year. + +![Error School Year](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/getting-started/image-2021-03-18-11-55-55-246.png) + +## Review Ed-Fi ODS / API Documentation + +If you're new to the Ed-Fi ODS / API — or even if you're upgrading from a +previous version in tandem with installing the Admin App — the product +documentation for your solution has additional information you'll find useful: + +* The Ed-Fi ODS / API v5.2 documentation is available online + [here](https://edfi.atlassian.net/wiki/spaces/ODSAPI34). +* You can find documentation for prior version at [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions) + +The Platform Developers' Guide and API Client Developers' Guide are essential +reading for platform hosts. + +## Admin App Source Code Access + +Admin App source code is available under Apache 2 license terms, and can be +found +at [https://github.com/Ed-Fi-Alliance-OSS/Ed-Fi-ODS-AdminApp](https://github.com/Ed-Fi-Alliance-OSS/Ed-Fi-ODS-AdminApp). diff --git a/docs/reference/8-admin-app/getting-started/readme.md b/docs/reference/8-admin-app/getting-started/readme.md new file mode 100644 index 00000000..2434aea6 --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/readme.md @@ -0,0 +1,23 @@ +# Getting Started + +This documentation outlines the steps necessary to deploy and set up the Ed-Fi +ODS / API Admin App. The Admin App provides a user-friendly web-based interface +to perform common administrative tasks for an instance of an Ed-Fi ODS / API. + +Admin App supports shared, year-specific and district-specific modes.  Admin App +does not support sandbox mode which is intended for development and the [Sandbox +Administration +Portal](https://edfi.atlassian.net/wiki/display/ODSAPIS3V520/Using+the+Sandbox+Administration+Portal) +is the tool to use for sandbox modes. + +Admin App is a tool that is used to manage account access and other internal +information for the ODS/API Platform.  For this reason, we recommend running +Admin App only within internal, VPN-accessible and/or "extranet" networks with +proper firewall/infrastructure controls to maintain limited access for only its +administrative users. + +## Audience + +This documentation is for administrators and DevOps personnel who will be +installing the Admin App. The information herein may also be of interest to +users of the Admin App. diff --git a/docs/reference/8-admin-app/getting-started/securing-the-admin-app.md b/docs/reference/8-admin-app/getting-started/securing-the-admin-app.md new file mode 100644 index 00000000..ad809fde --- /dev/null +++ b/docs/reference/8-admin-app/getting-started/securing-the-admin-app.md @@ -0,0 +1,64 @@ +# Securing the Admin App + +## Overview + +Admin App v3.0 supports two methods for authentication: web-forms authentication +or single-sign on via Open ID Connect (OIDC).  Both utilize [ASP.NET Core +Identity](https://learn.microsoft.com/en-us/aspnet/core/security/?view=aspnetcore-6.0) +as the underlying framework.  This page will provide details to configure Admin +App based on the selected model.  Please use this as reference for Admin App +v2.x, however the  single-sign on via Open ID Connect method is not supported in +those product versions. + +## Admin App Roles + +Admin App uses two roles within the application for ODS/API management.  The +_Super-Administrator_ role is used to register multiple users with separate +roles and privileges along with all ODS / API instances and its functions. The +_Administrator_ role is allowed to access only specific ODS / API instances and +its functions. This user authentication model pairs well with multi-instance +support within Admin App. + +### 1. Super-Administrator (default role for the first user) + +The Super-Administrator role is intended for an IT Administrator managing a +collection of individual ODS instances, such as found within district +collaboratives. + +#### Super-Administrator Permissions + +* Add a user +* Assign a role to an added user +* Register and delete ODS / API instances +* Change and assign an ODS / API instance to an added user +* Change user settings for other users +* Delete a user +* Plus, all permissions of the Administrator role + +### 2. Administrator + +The Administrator role is one that can access one or more ODS instances assigned +by the Super-Administrator. This means that users in the Administrator role can +only administer ODS / API instances specifically assigned. + +#### Administrator Permissions + +* Manage applications +* API key/secret creation +* View descriptors +* Bulk data uploads +* Learning standards synchronization + +## Securing Admin App + +1. Existing form authentication (Please refer + [here](https://edfi.atlassian.net/wiki/pages/viewpage.action?pageId=25243028) + for more details) + +2. Single sign on (SSO) + +**References:** + +[https://learn.microsoft.com/en-us/aspnet/core/security/authentication/social/?view=aspnetcore-3.1&tabs=visual-studio](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/social/?view=aspnetcore-3.1&tabs=visual-studio) + +[https://www.keycloak.org/getting-started/getting-started-docker](https://www.keycloak.org/getting-started/getting-started-docker) diff --git a/docs/reference/8-admin-app/readme.md b/docs/reference/8-admin-app/readme.md index 800e112f..efdc6648 100644 --- a/docs/reference/8-admin-app/readme.md +++ b/docs/reference/8-admin-app/readme.md @@ -1,9 +1,25 @@ -# Ed-FI ODS Admin App +# ODS / API Admin App -:::tip +Note: June 2024: On behalf of the Ed-Fi community, we are pleased to announce the release of Admin App v3.3.1. This version is compatible with ODS/API versions 3.4 to 6.2. -🚧 This site is under construction. In the meantime, please see [Admin -App](https://edfi.atlassian.net/wiki/spaces/EDFITOOLS/pages/24117525/Admin+App) -in Confluence for more information. +## Overview -::: +The Ed-Fi ODS / API Admin App is a web-based administrative interface for the Ed-Fi ODS / API. The Admin App is available as a standalone application, and is also available for deployments on Azure and Docker. The Admin App is available for Technical Suite Three. + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/AdminApp18-ScreenCap.png) + +## Supported Releases + +Below are supported releases of the Ed-Fi Admin App: + +* [Admin App v3.3](https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/48889918/Admin+App+v3.3) +* [Admin App v3.2](getting-started/installation/older-versions-of-admin-app/admin-app-v32) +* [Admin App for Suite 3 v2.4](getting-started/installation/older-versions-of-admin-app/admin-app-for-suite-3-v24) + +## Documentation + +Documentation for the Ed-Fi ODS / API Admin App is available online: + +* [What's New](whats-new) +* [Getting Started](getting-started) +* [Technical Articles](technical-articles) diff --git a/docs/reference/8-admin-app/technical-articles/aspnet-identity-preview-in-v18.md b/docs/reference/8-admin-app/technical-articles/aspnet-identity-preview-in-v18.md new file mode 100644 index 00000000..33660b73 --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/aspnet-identity-preview-in-v18.md @@ -0,0 +1,95 @@ +# ASP.NET Identity (Preview in v1.8) + +> [!INFO] In the Admin App v2.0.0, ASP.NET Identity was promoted to a supported +> feature. The documentation for the feature can be found in the [Securing the +> Admin App](../getting-started/securing-the-admin-app.md) +> section of the Admin App User Guide. Version 1.8 of the Admin App contained a +> preview version. This is the documentation for the preview in v1.8. + +This section describes how to enable the [ASP.NET +Identity](https://docs.microsoft.com/en-us/aspnet/identity/overview/getting-started/introduction-to-aspnet-identity) +feature preview in the Admin App. + +Admin App supports Active Directory authentication, which is not suitable for +all deployment scenarios. Although some users +may wish to continue using AD for authentication, the Admin App offers +an alternative authentication method using ASP.NET Identity web forms. ASP.NET +Identity +is expected to work seamlessly within different deployment environments, specifically +including cloud deployments. + +The ASP.NET Identity feature is a preview feature for v3.4 and disabled by +default with a new installation of the Admin App. Based on usage and field +reports, we intend to publish a production-ready version in Admin App v2.0.0 for +ODS / API v3.5 and beyond. To enable this preview using ASP.NET Identity, Admin +App has a feature flag which can be turned on. + +## Overview + +Admin App users may choose to enable the ASP.NET Identity to provide web-form +authentication. For more information on enabling the Identity feature set for +the Admin App, please see below: + +## Admin App Configuration + +Admin App requires a single configuration change in the Web.config file in order +to enable the ASP.NET Identity feature. + +### Step 1. Locate the Web.config file + +To find the Web.config file, open IIS Manager and navigate to the AdminApp web +application. **Right-click** and select **Explore**. This will open the +installation directory of Admin App where you will find the Web.config file: + +![IIS Manager](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-2_10-10-19.png) + +### Step 2. Configure for ASP.NET Identity Login + +1. In Web.config, to enable ASP.NET Identity functionality inside Admin App, + change the **AspNetIdentityEnabled** item to a value of **true** as shown + below in the AppSettings node in Web.config: + ![Web Config](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-3-2_15-23-42.png) + +2. Open IIS Manager and navigate to the AdminApp web application. + **Double-click** on **Authentication** under IIS Settings. Set "Anonymous + Authentication" under Authentication settings to "Enabled". If you have an + option of "Windows Authentication" as well, set that to "Disabled". + ![Authentication](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-3-3_10-2-3.png) + +## ASP.NET Identity Login + +After the above configuration change, the Identity feature is enabled on the +Admin App. + +1. The login flow is initiated. + ![Login](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-3-3_9-40-18.png) + +2. Click on the Sign In button to go to the Login page. A new user can be + created on first-time setup by clicking **Register as a new user** on the + lower right. + ![Admin App Login](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-3-3_9-41-34.png) + + Registration requires an e-mail and password: + ![Register](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-3-3_9-49-11.png) + +3. Log in with the created user. Following is the expected home page after + logging in with the Identity feature enabled. Notice the newly created + `` user in the top right corner: + ![Admin App](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-3-3_9-44-7.png) + +## Troubleshooting + +### Common Errors + +If you encounter an issue where your browser appears to be in an endless +redirect loop (as if the browser is repeatedly attempting and failing to arrive +at the login screen) check that the IIS Anonymous Authentication settings are +properly configured (as mentioned in Step 2, item 2, above). This issue is seen +when AspNetIdentityEnabled is set to "true" in Web.config, but IIS Anonymous +Authentication is not enabled. + +### Reporting Issues + +If you encounter issues related to configuration of the Admin App, please create +a ticket in the [Ed-Fi Tracker system (in the EDFI +project)](https://tracker.ed-fi.org/projects/EDFI). diff --git a/docs/reference/8-admin-app/technical-articles/claim-set-editor-tab-preview-in-v17.md b/docs/reference/8-admin-app/technical-articles/claim-set-editor-tab-preview-in-v17.md new file mode 100644 index 00000000..8e53791d --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/claim-set-editor-tab-preview-in-v17.md @@ -0,0 +1,54 @@ +# Claim Set Editor Tab (Preview in v1.7) + +:::info + In the Admin App v1.8 for ODS / API v3.4, the Claim Set Editor was + promoted to a supported feature. The documentation for the feature can be + found in the + [https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/25238340](https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/25238340) + section of the Admin App User Guide. Version 1.7 of the Admin App contained a + preview version. This is the documentation for the preview in v1.7. +::: + +This section describes how to enable the Claim Set Editing tab in the +configuration for Admin App. This feature is a preview feature for v3.3 and +disabled by default with a new installation of the Admin App for v1.7 of the +Admin App. + +## Overview + +Admin App users may choose to enable the "Claim Sets" tab found within the Admin +App ODS Instance Settings. For more information on enabling the claim set +editing feature set for the Admin App, please see below: + +## Admin App Configuration + +Admin App requires a single configuration change in the Web.config file in order +to enable the Claim Set Editor Tab. + +### Step 1. Locate the Web.config file + +To find the Web.config file, open IIS Manager and navigate to the AdminApp web +application. Right-click and select the "Explore" option. This will open the +installation directory of Admin App where you will find Web.config. + +![IIS Manager](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-2_10-10-19.png) + +### Step 2. Configure for Claim Set Editor tab + +In Web.config, to enable Claim Set Editing functionality inside Admin App, +change the **IsClaimSetsTabEnabled** item to have a value of **true** as shown +below in the AppSettings node in Web.config: + +![WebConfig](https://edfi.atlassian.net/wiki/download/attachments/25238416/image2020-1-13_11-15-28.png?version=1&modificationDate=1578935728477&cacheVersion=1&api=v2) + +## Claim Sets Tab + +After the above configuration change, the Claim Sets tab can be accessed within +the Admin App ODS Instance Settings as seen below: +![Claim Sets](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-1-13_11-25-50.png) + +# Reporting Issues + +If you encounter issues related to configuration of the Admin App, please create +a ticket in the [Ed-Fi Tracker system (in the EDFI +project)](https://tracker.ed-fi.org/projects/EDFI). diff --git a/docs/reference/8-admin-app/technical-articles/configuration-settings-v2x.md b/docs/reference/8-admin-app/technical-articles/configuration-settings-v2x.md new file mode 100644 index 00000000..50635f51 --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/configuration-settings-v2x.md @@ -0,0 +1,47 @@ +--- +hide_table_of_contents: true +--- + +# Configuration Settings (v2.x) + +## Overview + +This article describes configuration settings in appSettings.json for Admin App +v2.x. + +## Details + +Following are some important configuration settings for Admin App along with +their corresponding details: + +| Setting Name | Description | Valid Values | +| --- | --- | --- | +| **AppSettings** | | | +| **AppStartup** | Sets the environment in which Admin App is hosted. | "Azure", "OnPrem". Default value: "Azure". "Azure" is used by Cloud ODS deployment exclusively, and it is the default merely in service of Cloud ODS deployment processes. It is set to OnPrem by on-prem installation scripts, for instance. All deployments other than Cloud ODS should use "OnPrem". | +| **DatabaseEngine** | Sets the database engine being used. | "SqlServer", "PostgreSql". Default value: "SqlServer" | +| **ApplicationInsightsInstrumentationKey** | Sets the instrumentation key for Application Insights for Cloud ODS deployments. Admin App logging can be viewed in Application Insights when using Azure. The instrumentation key identifies the resource that you want to associate your telemetry data with. More information can be found [here](https://docs.microsoft.com/en-us/azure/azure-monitor/app/create-new-resource#copy-the-instrumentation-key). | An instrumentation key can be procured from [the Azure portal](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-resources-app-insights-keys?view=azure-bot-service-4.0). Example: "5b46bad4-b3c3-454f-80dc-6f6f5bd7ce4b" | +| **XsdFolder** | Sets the path to the directory containing the Ed-Fi Standard XSD files. | Any string (must be an existing folder path). Default value: "Schema" which points to the Schema folder under the Admin App web project. For most users, this should be left equal to the default. (This setting is expected to become irrelevant for ODS 5.2.0 and above.) | +| **DefaultOdsInstance** | Sets the default ODS instance name to be used in case of SharedInstance mode. | Any string.  Default value: "EdFi ODS" | +| **ProductionApiUrl** | Points to the Ed-Fi ODS / API server url. | Any string (must be a valid server url) | +| **SecurityMetadataCacheTimeoutMinutes** | Sets the amount of time the security metadata from the EdFi\_Security database is cached. E.g., if it is set to 10 mins, the claim set changes will reflect in the API at least after 10 mins without needing to recycle the API process. **This setting must match the same setting on the ODS/API appsettings.json.** | A positive integer representing the number of minutes. Default value: 10 | +| **ApiStartupType** | Sets the component settings for the API. **This setting must match the ODS/API settings.** See the [following section](https://edfi.atlassian.net/wiki/pages/viewpage.action?pageId=20480170#PlatformDevGuideExtensibility&Customization-DbPartition) on Developers' Guide for more information on this setting. | "SharedInstance", "YearSpecific", "DistrictSpecific". Default value: "SharedInstance" | +| **LocalEducationAgencyTypeValue** | Sets the name for the 'Local Education Agency' education organization type. | Any string. Default value: "Local Education Agency" | +| **SchoolTypeValue** | Sets the name for the 'School' education organization type. | Any string. Default value: "School" | +| **BulkUploadHashCache** | Sets the folder path to the Bulk Upload hash cache. | Any string (must be an existing folder path). Default value: `C:\ProgramData\Ed-Fi-ODS-AdminApp\BulkUploadHashCache` | +| **OptionalEntropy** ⚠️ Admin App 2.2x onwards, this appsetting is deprecated. The only encryption protocol supported is AES. This appsetting is, therefore, no longer needed. | Sets the optional entropy value for DPAPI encryption and decryption calls. Entropy is an additional key specific to the application that is protecting the data. If not specified, it allows other applications running on the same machine to decrypt the encrypted data. If specified, it allows for the protection of data from other system applications. | Any string | +| **EncryptionProtocol** ⚠️ Admin App 2.2x onwards, this appsetting is deprecated. The only encryption protocol supported is AES. This appsetting is, therefore, no longer needed. | Sets the encryption protocol to be used. Data Protection API (DPAPI) is the default encryption protocol. AES encryption is used for docker deployments. | "DPAPI", "AES". Default value: "DPAPI" | +| **Cloud ODS Specific App Settings - Set by Cloud ODS Deployment and not recommended to set manually.** | | | +| **IdaAADInstance** | Sets the base URL of the authorization server (this is always `https://login.microsoftonline.com`) | | +| **IdaClientId** | Sets the application/client Id in [Azure Active Directory/App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) for the Azure AD app registered when you deployed | | +| **IdaClientSecret** | Sets the shared secret of the application. In the App Registration screen for the AdminApp. Click on "Certificates & secrets" and add a New Client Secret. This key value is your IdaClientSecret. | | +| **IdaTenantId** | Sets the tenant Id. Can be procured from the Azure portal [under Tenant properties](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Properties). | | +| **IdaSubscriptionId** | Sets the subscription Id. Can be procured from the Azure portal [under Subscription properties](https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade). | | +| **Docker Specific App Settings** | | | +| **ApiExternalUrl** | Points to the Ed-Fi ODS / API server URL. This appsetting is only supposed to be used for displaying the correct URL in docker environments. It is used when displaying the ODS API location on the Applications screen. | Any string (must be a valid server url) | +| **EncryptionKey** | Sets the encryption key for AES encryption. | Must be an AES 256-bit key. An AES 256-bit key can be expressed as a hexadecimal string with 64 characters. It will require 44 characters in base64. Rather than setting this manually, see the [docker setup instructions](../../7-docker/readme.mdx) for populating it via environment variable `ENCRYPTION_KEY`. | +| **ConnectionStrings** | | | +| **Formatting Note:** Example values contain the special character "\\". When placed into a double-quoted JSON string, they must be "escaped" as a double slash:Value: `Data Source=.\\;Initial Catalog=EdFi\_Admin;Integrated Security=True`. Value as appears quoted in appsettings.json: `"Data Source=.\\\\;Initial Catalog=EdFi\_Admin;Integrated Security=True"` | | | +| **ConnectionString Name** | **Description** | **Examples** | +| **Admin** | Sets the connection string for the EdFi\_Admin database. Can be a PostgreSQL or SQLServer connection string depending on the DatabaseEngine appsetting. | `Data Source=.\\;Initial Catalog=EdFi\_Admin;Integrated Security=True` | +| **Security** | Sets the connection string for the EdFi\_Security database. Can be a PostgreSQL or SQLServer connection string depending on the DatabaseEngine appsetting. | `Data Source=.\\;Initial Catalog=EdFi\_Security;Integrated Security=True` | +| **ProductionOds** | Sets the connection string for the EdFi\_ODS database. The database name depends on the ApiStartupType (multi-instance or single instance). Can be a PostgreSQL or SQLServer connection string depending on the DatabaseEngine appsetting. Just like in the ODS's own config, instance name templating with the special placeholder "{0}" is supported. | `Data Source=.\\;Initial Catalog=EdFi\_Ods\_Production;Integrated Security=True`

`Data Source=.\\;Initial Catalog=EdFi\_{0};Integrated Security=True` | diff --git a/docs/reference/8-admin-app/technical-articles/manually-restricting-access-to-a-single-education-organization.md b/docs/reference/8-admin-app/technical-articles/manually-restricting-access-to-a-single-education-organization.md new file mode 100644 index 00000000..02d0ff71 --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/manually-restricting-access-to-a-single-education-organization.md @@ -0,0 +1,104 @@ +# Manually Restricting Access to a Single Education Organization + +## Overview + +Apply restrictions or provide authorization for resources can be achieved with +customizing the claim set, using Admin App Claim set editor. + +Documentation on how to use Claim Set Editor can be found here: +[Claim Set Editor](./claim-set-editor-tab-preview-in-v17.md). + +## Use Case + +Restrict the education organization read permission. If user try to get list of +schools using specific key and secret, then resultant list should only contain +the school/ schools associated with provided key and secret. + +## Steps to Achieve the Filtered List + +1. On Admin App Claim set editor, user can create copy of existing claim sets. +User cannot customize the existing standard claim sets. But can customize newly +added or copied claim set. + +The following list shows existing standard claim sets on Admin app. + + ![Claim Sets](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-8-17.png) + + 2. User can click on the copy (highlighted on the above screen shot) link to + create copy of a specific claim set. In our example, we are creating a copy of + SIS Vendor claim set. + +![Copy Claim Set](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-9-44.png) + + 3.  We created SIS Vendor copy claim set, which is customizable + + ![Copied Claim Set](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-10-35.png) + +Clicking on the Edit link on SIS Vendor Copy Claim set will lead user to claim +set edit page: + +![Permission](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-11-0.png) + +Here user can check or uncheck the resource permissions (Read, create, Update +and Delete). + +Some of the resources will have child resources associated with it. + +Ex: people resource has student, staff, and parent as child resources. So, +making any permission changes to people will reflect on child resources. + +4. In this use case user wants to restrict the education organizations resource. + +![Permissions](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-11-45.png) + +The existing education organization resource only has Read permission with “No +further authorization required” strategy, which is why school list shows all the +schools. + +Now we are going to restrict that by overriding the default authorization +strategy. + +Clicking on +the ![Information Icon](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-12-25.png) + + will open the Authorization strategy override window. + +![Authorization](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-12-36.png) + +Now need to restrict the Read action by editing the authorization strategy. + +![Override Authorization](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-12-57.png) + +Now we did override the Read action’s authorization strategy to “Relationships +with Education Organizations only”. + +![Override Authorization Strategy](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-13-36.png) + +This override will restrict the education organization read action strategy. + +Note: The latest claim set addition/ update  will reflect automatically on ODS +API after 10 mins. + +If user wants to have the changes reflected immediately, then need to restart +the ODS API manually. + +![Warning Claim Set](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-13-58.png) + +5. Next step is to create an application using this newly created claim set and +associate it to specific education organization on Admin App. + +![Select Claim Set](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-14-27.png) + +User must have a key and secret provided during the application creation. + +Using these key and secret value towards ODS API call will provide expected +education organization list. + +Ex: We created application using SIS vendor Copy claim set and associated with +Grand bend high school. + +So, School list will be having only “Grand Bend High School” + +Output on swagger end point using the generated key and secret: + +![Endpoint Claim Set](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-3-17_18-14-49.png) diff --git a/docs/reference/8-admin-app/technical-articles/powershell-installation-ods-api-v33.md b/docs/reference/8-admin-app/technical-articles/powershell-installation-ods-api-v33.md new file mode 100644 index 00000000..74e93cf7 --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/powershell-installation-ods-api-v33.md @@ -0,0 +1,159 @@ +# PowerShell Installation (ODS / API v3.3) + +# Before You Install + +This section provides general information you should review before installing +the Ed-Fi ODS / API Admin App. + +## Prerequisites + +The following are required to install the Admin App: + +* The Admin App provides an interface to administer an Ed-Fi ODS / API. + Understandably, you must have an Ed-Fi ODS / API deployed and operational + before you can use the Admin App. The ODS / API must be an On-Premises + Installation or an Azure Cloud ODS from the Ed-Fi Exchange. +* You must have an Ed-Fi license to use the Admin App. If you have an + installation of the ODS / API, you already have a license. The Ed-Fi License + is free and available online. If you haven't done so already, visit + the [Ed-Fi.org licensing + section](https://www.ed-fi.org/getting-started/license-ed-fi-technology/) for + details and a link to request a license. +* Admin App authentication will work via Single Sign-On using either Active + Directory or Active Directory for Azure depending on deployment. +* Download and install the Microsoft IIS URL Rewrite + Tool: [https://www.iis.net/downloads/microsoft/url-rewrite](https://www.iis.net/downloads/microsoft/url-rewrite) if + it is not already available (this may require computer restart). + +## Required Information + +You will need the following information to complete this installation: + +* The location of your Ed-Fi ODS / API. +* Administrator access and credentials for either on-premises or Azure + environment with target Ed-Fi ODS / API. + +# Installation Instructions + +This section provides step-by-step instructions for installation. The specific +steps are different depending on the deployment model and version of your Ed-Fi +ODS / API. + +## Compatibility & Supported ODS / API Versions + +Currently, the ODS / API Admin App can be installed for use with the Ed-Fi ODS / +API v3.3. See the [Ed-Fi Technology Version +Index](../../0-roadmap/supported-versions.md) for +more details. + +## On-Premises Deployment for ODS / API for v3.3 + +Each step is outlined in detail below. + +### Step 1. Unzip Admin App Source Files + +Unzip the contents of the Source ZIP into any folder of your choosing. Our +directory is on the following path: "C:\\Ed-Fi\\Admin App v1.7". + +![Unzip Installer](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-1-30_10-59-30.png) + +### Step 2. Unzip Admin App Installation Files + +Unzip the contents of the Installation ZIP into any folder of your choosing. Our +directory is on the following path: "C:\\Ed-Fi\\Admin App Installation". + +![Unzip App](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-1-30_10-58-34.png) + +### Step 3. Configure Installation + +Open the "install-config.json" file. We will need to edit this file with our +configuration details. + +1. Set the "installationDirectory" to the path of the directory with the source + files. Be sure to escape any special characters like slashes (For example, a + path like "C:\\Ed-Fi\\Admin App v1.7" should be changed to + "C:\\\\Ed-Fi\\\\Admin App v1.7"). +2. Configure values for the ODS / API. + 1. "apiUrl" is the base URL for the ODS / API. + 2. "apiMode" is either going to be "Shared Instance" or "Year Specific". + 1. If "Shared Instance" was chosen, the "schoolYear" can be left blank. + 2. If "Year Specific" was chosen, you must provide the "schoolYear". +3. Configure values for each database. These are used to construct the + connection strings. + 1. "sqlServer" is the name of the database server. For a local server, we + can use "(local)". + 2. "name" is simply the name of the database being referenced. For example, + when configuring for the "ods" database, the value here will be the name + of the ODS, whereas the "admin" and "security" database names will + probably be "EdFi\_Admin" and "EdFi\_Security", respectively. + 3. "trustedConnection" will either be "true" or "false". + 1. If you plan to use Windows authentication, this value will be "true" + and "username" and "password" can be left blank. + 2. If you plan to use SQL Server authentication, this value will be + "false" and the "username" and "password" must be provided. + +This is an example of what a complete "install-config.json" file could look +like: + +**install-config.json** + +```json +{ + "installationDirectory": "C:\\Ed-Fi\\Admin App v1.7", + "odsApi": { + "apiUrl": "http://localhost:54746", + "apiMode": "SharedInstance", + "schoolYear": "" + }, + "database": { + "ods": { + "sqlServer": "(local)", + "name": "EdFi_Ods", + "trustedConnection": "true", + "username": "", + "password": "" + }, + "admin": { + "sqlServer": "(local)", + "name": "EdFi_Admin", + "trustedConnection": "true", + "username": "", + "password": "" + }, + "security": { + "sqlServer": "(local)", + "name": "EdFi_Security", + "trustedConnection": "true", + "username": "", + "password": "" + } + } +} +``` + +### Step 4. Run the Installation via PowerShell + +Ensure that you have permission to execute PowerShell scripts. For more +information, +see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). + +Launch PowerShell as an administrator, cd to the directory containing the +installation files, and run the "install.ps1" script. + +The PowerShell output should look like the following: + +![Pws Certificate](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2020-1-30_11-4-51.png) + +### Next Steps. Continue at Step 5 in the Admin App Installation (3.x) + +Continue Step 5 and beyond in the general Admin App installation +instructions: [Admin App v1.7 for ODS / API +v3.3](../getting-started/installation/older-versions-of-admin-app/admin-app-v17-for-ods-api-v33). + +:::info note: + The following are ZIP files needed for the successful on-premises + installation of Admin App v1.7 for Ed-Fi ODS / API v3.3 Source ZIP: + [Ed-Fi\_ODS\_AdminApp\_1.7\_3.3.zip](https://edfi.atlassian.net/wiki/download/attachments/25235508/EdFi.Ods.AdminApp.3.3.0.389.zip?version=1&modificationDate=1580420953863&cacheVersion=1&api=v2) + Installation ZIP: + [Ed-Fi\_ODS\_AdminApp\_Installation\_1.7\_3.3.zip](https://edfi.atlassian.net/wiki/download/attachments/25235508/EdFi.Ods.AdminApp.Installation.3.3.0.389.zip?version=1&modificationDate=1580420906613&cacheVersion=1&api=v2) +::: diff --git a/docs/reference/8-admin-app/technical-articles/readme.md b/docs/reference/8-admin-app/technical-articles/readme.md new file mode 100644 index 00000000..14893daa --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/readme.md @@ -0,0 +1,13 @@ +# Technical Articles + +This section contains Technical Articles for advanced use topics for Admin App: + +* [ASP.NET Identity (Preview in v1.8)](aspnet-identity-preview-in-v18) +* [Claim Set Editor Tab (Preview in v1.7)](claim-set-editor-tab-preview-in-v17) +* [Configuration Settings (v2.x)](configuration-settings-v2x) +* [Manually Restricting Access to a Single Education Organization](manually-restricting-access-to-a-single-education-organization) +* [PowerShell Installation (ODS / API v3.3)](powershell-installation-ods-api-v33) +* [Resetting Admin App Configuration](resetting-admin-app-configuration) +* [Resetting Admin App Configuration (Admin App 2.2+)](resetting-admin-app-configuration-admin-app-22) +* [Updating Admin App 2.2 for Ed-Fi ODS/API Cloud Deployment for Azure (Suite 3)](updating-admin-app-22-for-ed-fi-odsapi-cloud-deployment-for-azure-suite-3) +* [Year-Specific Mode (v1.x)](year-specific-mode-v1x) diff --git a/docs/reference/8-admin-app/technical-articles/resetting-admin-app-configuration-admin-app-22.md b/docs/reference/8-admin-app/technical-articles/resetting-admin-app-configuration-admin-app-22.md new file mode 100644 index 00000000..d69194da --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/resetting-admin-app-configuration-admin-app-22.md @@ -0,0 +1,235 @@ +# Resetting Admin App Configuration (Admin App 2.2+) + +# Environment: OnPrem + +**Admin App Version: >= 2.2.0** + +:::info note: + Admin App version 2.2+, the encryption and decryption operation are + using AES algorithm. So, it is very uncommon to encounter the "key and secret + cannot be used in that state" issue. +::: + +**Uncommon cases:** + +1. User missed to maintain/ retain the EncryptionKey while upgrading the + application from version 2.2+ to latest version (Please refer the + documentation on upgrading Admin App [here](#)) +2. Missing the encryption key on the appsettings.json after the first-time setup + completed on Admin App 2.2+ + +Note: Please make sure to create new EncryptionKey using the following +PowerShell command and update the appsettings.json with newly created value +before running the first-time setup again on Admin App. + +**Generate Encryption Key** Expand source + +```ps1 +$aes = [System.Security.Cryptography.Aes]::Create() +$aes.KeySize = 256 +$aes.GenerateKey() +$EncryptionKey = [System.Convert]::ToBase64String($aes.Key) +``` + +If user is in any of the above-mentioned situation, please follow the following +steps to recover the application and force the first-time setup on Admin App. + +## Steps for Recovering the Application on Shared Instance mode + +1. Please make sure to stop ODS API and Admin App websites under IIS. +2. Connect to SQL Server on SSMS. + +3. Select the EdFi\_Admin database. + +4. Execute following sql commands for clearing all the data records created + during first time setup process. + + ```sql + BEGIN TRAN DECLARE @ApplicationId INT; + + SELECT @ApplicationId = ApplicationId FROM dbo.Applications WHERE + ClaimSetName = 'Ed-Fi ODS Admin App' + + DELETE FROM dbo.ClientAccessTokens WHERE EXISTS ( SELECT 1 FROM + dbo.ApiClients WHERE ClientAccessTokens.ApiClient_ApiClientId = + ApiClients.ApiClientId AND Application_ApplicationId = + @ApplicationId ) DELETE FROM dbo.ApiClients WHERE + Application_ApplicationId = @ApplicationId DELETE FROM + dbo.ApplicationEducationOrganizations WHERE Application_ApplicationId = + @ApplicationId DELETE FROM dbo.ProfileApplications WHERE + Application_ApplicationId = @ApplicationId DELETE FROM dbo.Applications + WHERE ApplicationId = @ApplicationId DELETE FROM + adminapp.SecretConfigurations DELETE FROM + [EdFi_Admin].[adminapp].[OdsInstanceRegistrations] UPDATE dbo.Applications + set OdsInstance_OdsInstanceId = null -- making sure to remove the foreign + key constrain UPDATE [EdFi_Admin].[adminapp].[ApplicationConfigurations] + + SET FirstTimeSetUpCompleted = 0 + DELETE FROM dbo.OdsInstances COMMIT + TRAN + ``` + +5. Once successfully executed the above mentioned SQL script, please restart + the Admin App website under IIS + +6. Now browsing the Admin App will take user to the first time setup page + +7. For recovering already created vendor applications on Admin App, user needs + to manually update OdsInstance\_OdsInstanceId column on dbo.Applications + table to have default Ods instance id. On SharedInstance mode will be having + only one OdsInstance on dbo.OdsInstances table. + + ```sql + DECLARE @odsinstanceid INT SELECT TOP 1 @odsinstanceid = + OdsInstanceId FROM [dbo].[OdsInstances] + Update [EdFi_Admin].[dbo].[Applications] set OdsInstance_OdsInstanceId = + @odsinstanceid where OdsInstance_OdsInstanceId is null + ``` + +# Environment: Azure + +**Admin App Version: < 2.2.0** + +## Issues + +The application deployed and First-Time setup was successful, however you are +unable to proceed further with the Admin App settings page or you get an error +message saying that the key and secret can not be used in that state. + +## Cause + +Admin App secret configuration and/or Azure SQL configuration values became +corrupted for whatever reason. + +## Steps for Recovering the Application + +### 1) Clear Configuration Parameters & Force Admin App's First-Time Setup + +On this step, we need to clear all the data records created during first time +setup. + +1. Please make sure to stop ODS API and Admin App websites under IIS or within + the Azure portal App Service. + +        Ex (in Azure):  + `EdFiOdsApiWebSite-{environment}-{resourceGroupid}` + +         `EdFiOdsAdminAppWebSite-{environment}-{resourceGroupid}` + +      2. Connect to SQL Server on SSMS or use Azure Query Editor + +      3. Select the EdFi\_Admin database. + +      4. Execute the following sql commands for clearing all the data records +      created during first time setup process. + +**SQL** + +```sql +BEGIN TRAN    +DECLARE @ApplicationId INT; + +SELECT @ApplicationId = ApplicationId FROM dbo.Applications WHERE ClaimSetName = 'Ed-Fi ODS Admin App' + +DELETE FROM dbo.ClientAccessTokens WHERE EXISTS ( +        SELECT 1 FROM dbo.ApiClients +        WHERE ClientAccessTokens.ApiClient_ApiClientId = ApiClients.ApiClientId +        AND Application_ApplicationId = @ApplicationId +)  + +    DELETE FROM dbo.ApiClients WHERE Application_ApplicationId = @ApplicationId +    DELETE FROM dbo.ApplicationEducationOrganizations WHERE Application_ApplicationId = @ApplicationId +    DELETE FROM dbo.ProfileApplications WHERE Application_ApplicationId = @ApplicationId +    DELETE FROM dbo.Applications WHERE ApplicationId = @ApplicationId +    DELETE FROM dbo.OdsInstances +    DELETE FROM adminapp.SecretConfigurations +COMMIT  TRAN +``` + +     5. Once the SQL commands executed successfully. Please start the ODS API and Admin App websites under IIS or within the Azure portal App Service. + +### 2) Update the Admin App Configuration Parameters + +There is a table in the EdFi\_Admin database +called adminapp.AzureSqlConfigurations. This table holds the encrypted +configuration parameters used by the admin app. + +The format of this string is JSON and specifies a few key: value pairs. + +Here is a template of how it looks: +```json +{"AdminCredentials":{"Password":"\[dbpassword\]","UserName":"\[dbuser\]"},"HostName":"\[the +SQL Server: +sql.somthing.com\]","ProductionApiCredentials":{"Password":"\[SecurePassword\]","UserName":"EdFiOdsProductionApi"},"AdminAppCredentials":{"Password":"\[SecurePassword\]","UserName":"EdFiOdsAdminApp"}} +``` + +The following JSON code block explains the parameters required and their +intention: + +**SQL** + +```sql +{ + //These are the credentials used to access the EdFi_Admin database. + "AdminCredentials":{ + "Password":"[dbpassword]", + "UserName":"[dbuser]" + }, + // This is the address of the MsSQL server. This can be a DNS or an IP Address. + "HostName":"[the SQL Server: sql.somthing.com]", + // These are the credentials that will be stored encrypted that the Admin App will use to connect to the Ed-Fi ODS API + "ProductionApiCredentials":{ + "Password":"[SecurePassword]", + "UserName":"EdFiOdsProductionApi" + }, + "AdminAppCredentials":{ + "Password":"[SecurePassword]", + "UserName":"EdFiOdsAdminApp" + } +} +``` + +Modify the SQL statement below by providing the User Name and Password for the +required fields marked with square brakets "\[...\]" + +Following the steps above open SSMS or Azure Query Editor and execute the +following statement against the EdFi\_Admin database. + +**SQL** + +```sql +BEGIN TRAN    +UPDATE adminapp.AzureSqlConfigurations set field='{"AdminCredentials":{"Password":"PW Specified in Deployment Script","UserName":"SERVER Master UN"},"HostName":"","ProductionApiCredentials":{"Password":"Enter PW","UserName":"EdFiOdsProductionApi"},"AdminAppCredentials":{"Password":"","UserName":"EdFiOdsAdminApp"}}' WHERE Id=1; +COMMIT  TRAN +``` + +### 3) Update Admin App web site on IIS or Azure + +:::info note: + That older versions of Admin app need the presence of + “SetupRequired” file. This indicates to the first time setup process that it has + not run. If the file not present, this means that the first-time setup was + completed. Recreating the file will enforce the First time setup process to run + again. +::: + +To create this file just create text file with the name “SetupRequired” and set +the content of it to: Placeholder file to let the AdminApp know additional setup +of the system is required. + +On IIS or Azure, proceed to restart the application. Once the restart has +finished use your web browser and navigate to the Admin App URL. You should be +able to continue the First Time Setup within Admin App. + +Deployed pages and resources can be accessed on Azure portal. + +[https://www.gslab.com/blogs/kudu-azure-web-app](https://www.gslab.com/blogs/kudu-azure-web-app) + +#### References + +If you have any questions on how to connect to the EdFi-Admin database please +refer to this articles below: + +[https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-portal](https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-portal) + +[https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-ssms](https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-ssms) diff --git a/docs/reference/8-admin-app/technical-articles/resetting-admin-app-configuration.md b/docs/reference/8-admin-app/technical-articles/resetting-admin-app-configuration.md new file mode 100644 index 00000000..e61157aa --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/resetting-admin-app-configuration.md @@ -0,0 +1,139 @@ +# Resetting Admin App Configuration + +## Issues + +The application deployed and First-Time setup was successful, however you are +unable to proceed further with the Admin App settings page or you get an error +message saying that the key and secret can not be used in that state. + +## Cause + +Admin App secret configuration and/or Azure SQL configuration values became +corrupted for whatever reason. + +## Steps for Recovering the Application + +### 1) Clear Configuration Parameters & Force Admin App's First-Time Setup + +On this step, we need to clear all the data records created during first time +setup. + +1. Please make sure to stop ODS API and Admin App websites under IIS or within + the Azure portal App Service. + +            Ex (in Azure):  `EdFiOdsApiWebSite-{environment}-{resourceGroupid}` + +            `EdFiOdsAdminAppWebSite-{environment}-{resourceGroupid}` + +      2. Connect to SQL Server on SSMS or use Azure Query Editor + +      3. Select the EdFi\_Admin database. + +      4. Execute the following sql commands for clearing all the data records +      created during first time setup process. + +**SQL** + +```sql +BEGIN TRAN DECLARE @ApplicationId INT; + +SELECT @ApplicationId = ApplicationId FROM dbo.Applications WHERE ClaimSetName = +'Ed-Fi ODS Admin App' + +DELETE FROM dbo.ClientAccessTokens WHERE EXISTS ( SELECT 1 FROM dbo.ApiClients +        WHERE ClientAccessTokens.ApiClient_ApiClientId = ApiClients.ApiClientId +        AND Application_ApplicationId = @ApplicationId ) + +    DELETE FROM dbo.ApiClients WHERE Application_ApplicationId = @ApplicationId +    DELETE FROM dbo.ApplicationEducationOrganizations WHERE Application_ApplicationId = @ApplicationId +    DELETE FROM dbo.ProfileApplications WHERE Application_ApplicationId = @ApplicationId +    DELETE FROM dbo.Applications WHERE ApplicationId = @ApplicationId +    DELETE FROM dbo.OdsInstances +    DELETE FROM adminapp.SecretConfigurations +COMMIT  TRAN +``` + +     5. Once the SQL commands executed successfully. Please start the ODS API and Admin App websites under IIS or within the Azure portal App Service. + +### 2) Update the Admin App Configuration Parameters + +There is a table in the EdFi\_Admin database +called adminapp.AzureSqlConfigurations. This table holds the encrypted +configuration parameters used by the admin app. + +The format of this string is JSON and specifies a few key: value pairs. + +Here is a template of how it looks: + +```json +{"AdminCredentials":{"Password":"\[dbpassword\]","UserName":"\[dbuser\]"},"HostName":"\[the +SQL Server: +sql.somthing.com\]","ProductionApiCredentials":{"Password":"\[SecurePassword\]","UserName":"EdFiOdsProductionApi"},"AdminAppCredentials":{"Password":"\[SecurePassword\]","UserName":"EdFiOdsAdminApp"}} +``` + +The following JSON code block explains the parameters required and their +intention: + +**SQL** + +```json +{ + //These are the credentials used to access the EdFi_Admin database. + "AdminCredentials": { "Password":[dbpassword], "UserName":[dbuser] }, + // This is the address of the MsSQL server. This can be a DNS or an IP Address. + "HostName":"[the SQL Server: sql.something.com]", + // These are the credentials that will be stored encrypted that the Admin App will use to connect to the Ed-Fi ODS API "ProductionApiCredentials":\ + { + "Password":"[SecurePassword]", "UserName":"EdFiOdsProductionApi" }, + "AdminAppCredentials":\{ "Password":"[SecurePassword]", + "UserName":"EdFiOdsAdminApp" } + } + ``` + +Modify the SQL statement below by providing the User Name and Password for the +required fields marked with square brackets "\[...\]" + +Following the steps above open SSMS or Azure Query Editor and execute the +following statement against the EdFi\_Admin database. + +**SQL** + +```sql +BEGIN TRAN UPDATE adminapp.AzureSqlConfigurations set +field='{"AdminCredentials":{"Password":"PW Specified in Deployment +Script","UserName":"SERVER Master +UN"},"HostName":"","ProductionApiCredentials":{"Password":"Enter +PW","UserName":"EdFiOdsProductionApi"},"AdminAppCredentials":{"Password":"","UserName":"EdFiOdsAdminApp"}}' +WHERE Id=1; COMMIT  TRAN +``` + +### 3) Update Admin App web site on IIS or Azure + +:::info note: +That older versions of Admin app need the presence of +`SetupRequired` file. This indicates to the first time setup process that it has +not run. If the file not present, this means that the first-time setup was +completed. Recreating the file will enforce the First time setup process to run +again. +::: + +To create this file just create text file with the name `SetupRequired` and set +the content of it to: Placeholder file to let the AdminApp know additional setup +of the system is required. + +On IIS or Azure, proceed to restart the application. Once the restart has +finished use your web browser and navigate to the Admin App URL. You should be +able to continue the First Time Setup within Admin App. + +Deployed pages and resources can be accessed on Azure portal. + +[https://www.gslab.com/blogs/kudu-azure-web-app](https://www.gslab.com/blogs/kudu-azure-web-app) + +#### References + +If you have any questions on how to connect to the EdFi-Admin database please +refer to this articles below: + +[https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-portal](https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-portal) + +[https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-ssms](https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-ssms) diff --git a/docs/reference/8-admin-app/technical-articles/updating-admin-app-22-for-ed-fi-odsapi-cloud-deployment-for-azure-suite-3.md b/docs/reference/8-admin-app/technical-articles/updating-admin-app-22-for-ed-fi-odsapi-cloud-deployment-for-azure-suite-3.md new file mode 100644 index 00000000..9b51487c --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/updating-admin-app-22-for-ed-fi-odsapi-cloud-deployment-for-azure-suite-3.md @@ -0,0 +1,311 @@ +# Updating Admin App 2.2 for Ed-Fi ODS/API Cloud Deployment for Azure (Suite 3) + +## Installation Instructions + +Upgrading/ installing AdminApp 2.2.0 while resource group, ODS API and Admin app +older version already available and running on Azure. + +:::info note: + Please backup your ODS / API and related databases before running this + update procedure. +::: + +### Steps for upgrading + +1. Stop existing ODS API and AdminApp services on azure resource group + +2\. Connect to Azure SQL server from SSMS and run the following SQL commands to +delete records/ data to void the first-time setup from old AdminApp application. +Note: This step can be ignored if it is new installation. + +**Void First-Time Setup** Expand source + +```sql +DECLARE @ApplicationId INT; + +SELECT @ApplicationId = ApplicationId FROM dbo.Applications WHERE ClaimSetName = 'Ed-Fi ODS Admin App' + +DELETE FROM dbo.ClientAccessTokens WHERE EXISTS ( + +SELECT 1 FROM dbo.ApiClients + +WHERE ClientAccessTokens.ApiClient_ApiClientId = ApiClients.ApiClientId + +AND Application_ApplicationId = @ApplicationId + +) + +DELETE FROM dbo.ApiClients WHERE Application_ApplicationId = @ApplicationId + +DELETE FROM dbo.ApplicationEducationOrganizations WHERE Application_ApplicationId = @ApplicationId + +DELETE FROM dbo.ProfileApplications WHERE Application_ApplicationId = @ApplicationId + +DELETE FROM dbo.Applications WHERE ApplicationId = @ApplicationId + +DELETE FROM dbo.OdsInstances +``` + +3\. Deploy AdminApp 2.2.0 to an existing resource group using powershell script +from + +[Ed-Fi-X-Ods-Deploy-Azure-Deployment-Scripts-1.0.zip](https://odsassets.blob.core.windows.net/public/adminapp/Release/DeploymentScripts/Ed-Fi-X-Ods-Deploy-Azure-Deployment-Scripts-1.0.zip) + +Please follow the naming conventions +([https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best- +practices/resource-naming](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming)) +for AdminAppName + +Make sure to create Admin App specific sql user before the deployment +(AdminAppSqlUserName, AdminAppSqlPassword). Please refer **Step 5 on****Steps** +**for new installation** section below. + +**Deploy-EdFiOdsAdminApp** Expand source + +```json +$params = @{ + +        ResourceGroupName = " Existing resource group name " + +        AdminAppName = "AdminApp-Latest" + +        AppInsightLocation = "South Central US" + +        ProductionApiUrl = " Existing ODS API url " + +        SQLServerHostname = " Existing SQL server url " + +        SQLServerUserName = "sql administrator username" + +        SQLServerPassword = ConvertTo-SecureString "sql administrator password"  -AsPlainText -Force + + AdminAppSqlUserName = "admin app sql username" + + AdminAppSqlPassword = ConvertTo-SecureString "admin app sql password" -AsPlainText -Force + +    } + +Upgrade-AdminApp> .\Deploy-EdFiOdsAdminApp.ps1 @params +``` + +**EncryptionKey:** + +Base64-encoded 256 bit key appropriate for use with AES encryption. This is an + +optional parameter.  If user wants to provide own value, then use following +script to generate: + +**Generate AES Encryption Key** Expand source + +```ps1 + $aes = [System.Security.Cryptography.Aes]::Create() + $aes.KeySize = 256 + $aes.GenerateKey() + $EncryptionKey = [System.Convert]::ToBase64String($aes.Key) +``` + +:::info note: + If user is not providing Encryption key, then key will be generated + during deployment. +::: + +4. Once the application deployment done, user will be prompted to confirm +deleting and recreating Admin App specific database tables. If yes, then +deployment process will delete existing Admin App specific tables and re-create +them with latest table schemas on EdFi\_Admin database. + +5\. Data validations and update: + +:::info note: + This step can be ignored if it is new installation +::: + +1. We can persist existing vendor applications, key and secrets created. Need to +manually update OdsInstance\_OdsInstanceId column on dbo.Applications table to +have default Ods instance id. Since, latest AdminApp needs association between +dbo.Applications and dbo.OdsInstances tables to filter applications for selected +instance. On SharedInstance mode will be having only one OdsInstance +on dbo.OdsInstances table. + +**Update Applications** Expand source + +```sql + DECLARE @odsinstanceid INT + SELECT TOP 1 @odsinstanceid = OdsInstanceId FROM [dbo].[OdsInstances] + Update [EdFi_Admin].[dbo].[Applications] set OdsInstance_OdsInstanceId = @odsinstanceid where OdsInstance_OdsInstanceId is null +``` + +2\. Vendor applications created using older AdminApp have prefixed with +“Production”. May need to manually remove that prefix. + +### Steps for new installation + +1.Please refer [Ed-Fi ODS/API Cloud Deployment for Azure (Suite +3)](/getting-started/edfi-exchange/technology/ed-fi-odsapi-cloud-deployment-for-azure-suite-3/))  for new +installation on Azure ( Note: New installation will create new resource group +and resources). + +2\. Make sure to bypass Admin app installation by making $DoNotInstallAdminApp +flag to “$true” on \\Deploy-EdFiOds.ps1 file. + +3\. If user is not installing Admin app as part this deployment, then will be +prompted to enter SQL credentials for Ed-Fi ODS Production API + + ![Credentials](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-5-14_17-23-45.png) + +Please enter username: EdFiOdsProductionApi + +Password can be any value user wants to use (Make sure to satisfy the sql login +password requirements. Provided username and password will be used in upcoming +step to create user login on SQL server) + +4\. +:::info note: + User can skip this step if already knows how to do and access the db + server on local SSMS.Once the deployment completed, please white list your ip + address on the AzureSql server by clicking the “Set server firewall” on + EdFi\_Admin database on Azure resource group. +::: + +![Firewall](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-5-14_17-35-54.png) + +Once click on the “Set server firewall” will open up a page where user can add +their system IP address and save it. + +This will enable access to that provided IP. Now user can open the Azure sql db +server on their local SSMS. + +![Settings](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-5-14_17-38-15.png) + +5. EdFiOdsProductionApi(as mentioned on step3) and EdFiOdsAdminApp users and +logins creation on databases. + +We are creating EdFiOdsAdminApp user login as well in this step, so that these +credentials can be used during the AdminApp deployment. + +:::info note: + Please use individual query editor for different databases to exceute the + queries. +::: + +**Create EdFiOdsAdminApp user login** Expand source + +```sql +--Create EdFiOdsAdminApp login +use [master] +IF NOT EXISTS(SELECT name FROM sys.sql_logins WHERE name='EdFiOdsAdminApp') +BEGIN + CREATE LOGIN [EdFiOdsAdminApp] WITH PASSWORD = 'user provided password' +END; + +--Create database user for EdFiOdsAdminApp login on EdFi_Admin database +use [EdFi_Admin] +IF DATABASE_PRINCIPAL_ID('EdFiOdsAdminApp') IS NULL +BEGIN + CREATE USER [EdFiOdsAdminApp] FOR LOGIN [EdFiOdsAdminApp] WITH DEFAULT_SCHEMA=[dbo] +END +-- Assign roles to EdFiOdsAdminApp on EdFi_Admin database +EXEC sp_addrolemember 'db_datareader', 'EdFiOdsAdminApp' +EXEC sp_addrolemember 'db_datawriter', 'EdFiOdsAdminApp' +EXEC sp_addrolemember 'db_owner', 'EdFiOdsAdminApp' + +--Create database user for EdFiOdsAdminApp login on EdFi_Ods_Production database +use [EdFi_Ods_Production] +IF DATABASE_PRINCIPAL_ID('EdFiOdsAdminApp') IS NULL +BEGIN + CREATE USER [EdFiOdsAdminApp] FOR LOGIN [EdFiOdsAdminApp] WITH DEFAULT_SCHEMA=[dbo] +END +--Assign roles to EdFiOdsAdminApp on EdFi_Ods_Production database +EXEC sp_addrolemember 'db_datareader', 'EdFiOdsAdminApp' +EXEC sp_addrolemember 'db_datawriter', 'EdFiOdsAdminApp' +IF DATABASE_PRINCIPAL_ID('db_executor') IS NULL +BEGIN + CREATE ROLE [db_executor] +END +GRANT EXECUTE TO [db_executor] +EXEC sp_addrolemember 'db_executor', 'EdFiOdsAdminApp' +EXEC sp_addrolemember 'db_ddladmin', 'EdFiOdsAdminApp' +GRANT CREATE TABLE TO EdFiOdsAdminApp +GRANT CREATE SCHEMA TO EdFiOdsAdminApp +GRANT CREATE VIEW TO EdFiOdsAdminApp + +--Create database user for EdFiOdsAdminApp login on EdFi_Security database +use [EdFi_Security] +IF DATABASE_PRINCIPAL_ID('EdFiOdsAdminApp') IS NULL +BEGIN + CREATE USER [EdFiOdsAdminApp] FOR LOGIN [EdFiOdsAdminApp] WITH DEFAULT_SCHEMA=[dbo] +END +--Assign roles to EdFiOdsAdminApp on EdFi_Security database +EXEC sp_addrolemember 'db_datareader', 'EdFiOdsAdminApp' +EXEC sp_addrolemember 'db_datawriter', 'EdFiOdsAdminApp' +EXEC sp_addrolemember 'db_owner', 'EdFiOdsAdminApp' + +``` + +**Create EdFiOdsProductionApi user login** Expand source + +```sql +--For creating EdFiOdsProductionApi login +use [master] +IF NOT EXISTS(SELECT name FROM sys.sql_logins WHERE name='EdFiOdsProductionApi') +BEGIN +CREATE LOGIN [EdFiOdsProductionApi] WITH PASSWORD = 'user provided password' +END; + +--Create database user for EdFiOdsProductionApi login on EdFi_Admin database +use [EdFi_Admin] +IF DATABASE_PRINCIPAL_ID('EdFiOdsProductionApi') IS NULL +BEGIN + CREATE USER [EdFiOdsProductionApi] FOR LOGIN [EdFiOdsProductionApi] WITH DEFAULT_SCHEMA=[dbo] +END +-- Assign roles to EdFiOdsProductionApi on EdFi_Admin database +EXEC sp_addrolemember 'db_datareader', 'EdFiOdsProductionApi' +EXEC sp_addrolemember 'db_datawriter', 'EdFiOdsProductionApi' +IF DATABASE_PRINCIPAL_ID('db_executor') IS NULL +BEGIN + CREATE ROLE [db_executor] +END +GRANT EXECUTE TO [db_executor] +EXEC sp_addrolemember 'db_executor', 'EdFiOdsProductionApi' + +--Create database user for EdFiOdsProductionApi login on EdFi_Ods_Production database +use [EdFi_Ods_Production] +IF DATABASE_PRINCIPAL_ID('EdFiOdsProductionApi') IS NULL +BEGIN + CREATE USER [EdFiOdsProductionApi] FOR LOGIN [EdFiOdsProductionApi] WITH DEFAULT_SCHEMA=[dbo] +END +--Assign roles to EdFiOdsProductionApi on EdFi_Ods_Production database +EXEC sp_addrolemember 'db_datareader', 'EdFiOdsProductionApi' +EXEC sp_addrolemember 'db_datawriter', 'EdFiOdsProductionApi' +IF DATABASE_PRINCIPAL_ID('db_executor') IS NULL +BEGIN + CREATE ROLE [db_executor] +END +GRANT EXECUTE TO [db_executor] +EXEC sp_addrolemember 'db_executor', 'EdFiOdsProductionApi' + +--Create database user for EdFiOdsProductionApi login on EdFi_Security database +use [EdFi_Security] +IF DATABASE_PRINCIPAL_ID('EdFiOdsProductionApi') IS NULL +BEGIN + CREATE USER [EdFiOdsProductionApi] FOR LOGIN [EdFiOdsProductionApi] WITH DEFAULT_SCHEMA=[dbo] +END +--Assign roles to EdFiOdsAdminApp on EdFi_Security database +EXEC sp_addrolemember 'db_datareader', 'EdFiOdsProductionApi' +EXEC sp_addrolemember 'db_datawriter', 'EdFiOdsProductionApi' + +``` + +6\. Once EdFiOdsProductionApi user login creation done, now user should be able +to launch the ODS API website successful on Azure. + +![Launcher exe](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2021-5-14_17-49-15.png) + +7. Please use above mentioned Admin app upgrade steps for installing Admin App +2.2.0. + +:::info note: + The following is a ZIP package containing PowerShell scripts for the + installation of the Admin App 2.2 update**:** + [Ed-Fi-X-Ods-Deploy-Azure-Deployment-Scripts-1.0.zip](https://odsassets.blob.core.windows.net/public/adminapp/Release/DeploymentScripts/Ed-Fi-X-Ods-Deploy-Azure-Deployment-Scripts-1.0.zip) +::: diff --git a/docs/reference/8-admin-app/technical-articles/year-specific-mode-v1x.md b/docs/reference/8-admin-app/technical-articles/year-specific-mode-v1x.md new file mode 100644 index 00000000..4014edac --- /dev/null +++ b/docs/reference/8-admin-app/technical-articles/year-specific-mode-v1x.md @@ -0,0 +1,101 @@ +# Year-Specific Mode (v1.x) + +This section describes how to set up a "Year-Specific" configuration. This +information is only necessary for those implementers who need to set up an +instance of the Ed-Fi ODS / API that provides separate endpoints for data +related to specific years. The as-shipped configuration does not segment +information by year, and so no additional Year-Specific configuration is +required if that's the desired behavior. + +## Overview + +ODS / API platform hosts may choose a "Year-Specific" configuration mode within +their ODS environments to partition data per-year within a SQL Server instance. +Admin App v1.7 and above supports Year-Specific mode. Configuration instructions +are below. For more information on enabling year-specific mode for the Ed-Fi ODS +/ API platform, see [Year-Specific ODS +Configuration](https://edfi.atlassian.net/wiki/spaces/ODSAPI34/pages/24281298/Year-Specific+ODS+Configuration). + +## Checklist + +Use this checklist and the details below to modify your ODS and Admin App to run +in Year-Specific mode + +* ODS API: configure the ODS API Web.config for `YearSpecific` startup +* ODS SwaggerUI: configure the swagger.webApiMetadataUrl to contain the + configured year. For example, `` +* ODS Database: Rename the EdFi\_Ods database to `EdFi\_Ods\_2019` +* Admin App: update database value in `EdFi\_Ods\_Production` connectionString +* Admin App: enable and configure year specific app + settings `yearSpecific:isEnabled` and `yearSpecific:year` + +## Year-Specific Configuration + +### ODS Web API and SwaggerUI Config + +The ODS / API and SwaggerUI each require changes to configure them for +Year-Specific mode. If installed through .exe installers, you can locate the +Web.config for each using IIS Manager. Right-click "Explore" on the web +application and then find the Web.config file. + +![IIS Explore](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-2_10-10-0.png) + +In the SwaggerUI Web.config, make the following changes: + +* Update `swagger.webApiMetadataUrl` to contain a school year. + +![WebConfig](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-2_10-14-51.png) + +In the WebApi Web.config, make the following changes: + +* Update the `owin:appStartup` app setting to have the value of "YearSpecific". + +![WebConfig Keys](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-2_10-16-11.png) + +### ODS Database Year-Specific Naming Convention + +In Year-Specific mode, the database is identified with a `\_{year}` suffix value +in the database name. To enable, install the database as usual, either through +the [`initdev` +process](https://edfi.atlassian.net/wiki/display/ODSAPI32/Getting+Started+-+Installation+Steps) +or through the [Windows Installers for the Ed-Fi ODS / API Suite +3](https://exchange.ed-fi.org/). Once installed, you can manually rename the +database through SQL Server Management Studio by right-clicking the database +name and selecting "Rename": + +![SQL Rename DB](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-2_10-20-41.png) + +### Admin App Configuration + +Admin App requires three configuration changes in the Web.config file in order +to enable connections to a Year Specific ODS. + +#### Step 1. Locate the Web.config file + +To find the Web.config file, open IIS Manager and navigate to the AdminApp web +application. Right-click and select the "Explore" option. This will open the +installation directory of Admin App where you will find Web.config. + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-2_10-10-19.png) + +#### Step 2. Configure for Year-Specific mode + +In Web.config, make the following changes: + +`Change 1.` Set the "EdFi\_Ods\_Production" connection string to contain the +year-specific database name created while setting up the ODS. The example below +uses the "EdFi\_Ods\_2019" database and windows authentication: + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-1_10-3-3.png) + +`Changes 2 & 3.` To enable year-specific functionality inside Admin App, add the +two items shown below into the AppSettings node in Web.config, placing them +below any items that already exist. + +![](https://edfidocs.blob.core.windows.net/$web/img/reference/admin-app/technical-articles/image2019-8-2_10-22-32.png) + +## Reporting Issues + +If you encounter issues related to configuration of the Admin App, please create +a ticket in the [Ed-Fi Tracker system (in the EDFI +project)](https://tracker.ed-fi.org/projects/EDFI). diff --git a/docs/reference/8-admin-app/whats-new.md b/docs/reference/8-admin-app/whats-new.md new file mode 100644 index 00000000..b8091593 --- /dev/null +++ b/docs/reference/8-admin-app/whats-new.md @@ -0,0 +1,423 @@ +# What's New + +This section provides an overview of what's new in the latest versions of the +ODS / API Admin App for Technical Suite Two and Technical Suite Three. + +## Updates in Admin App v3.3 + +Latest Release + +* .NET 8 +* Updated NuGet package dependencies +* Improved messaging when editing a claimset + ([AA-1440](https://tracker.ed-fi.org/browse/AA-1440)) +* Updated base images for the Docker containers + +Admin App v3.3.1 update: + +* [AA-1747](https://tracker.ed-fi.org/browse/AA-1747) +* [AA-1748](https://tracker.ed-fi.org/browse/AA-1748) +* [AA-1744](https://tracker.ed-fi.org/browse/AA-1744) + +## Updates in Admin App v3.2 + +### Support for ODS/API Suite 3 and v6.x Security Model Updates + +Additional support for ODS/API 6.1 updates and to support field use cases. + +* [AA-1705](https://tracker.ed-fi.org/browse/AA-1705) Claimset export on adminapp will fail if there are multiple + default authorization strategies +* [AA-1711](https://tracker.ed-fi.org/browse/AA-1711) UI changes for Claimset export on adminapp will fail if there are + multiple default authorization strategies + +### Error Updating Large Claimsets + +* [AA-1651](https://tracker.ed-fi.org/browse/AA-1651) EdFi Admin App - Editing large claimsets produces an error on page + +## Updates in Admin App v3.1 + +### Support for ODS/API Suite 3 and v6.x Security Model Updates + +* [AA-1637](https://tracker.ed-fi.org/browse/AA-1637) Admin App v3.1 provides compatibility for both ODS/API Suite 3 (v3.4-v5.3) and +ODS/API v6.x. + +### Removal of Product Improvement features + +* [AA-1638](https://tracker.ed-fi.org/browse/AA-1638) Based on community feedback, we have removed product improvements features and +integrations with Google Analytics, Salesforce and Jira Tracker. + +### Update in installation packages + +* [AA-1603](https://tracker.ed-fi.org/browse/AA-1603) The installation package for Admin App has been incorporated into the Admin App +NuGet package. Please see Installation Instructions for updated instructions on +how to install using the included installation package. + +### Update to PowerShell Pre-Installation Check + +* [AA-1663](https://tracker.ed-fi.org/browse/AA-1663) The PowerShell pre-installation check has been updated in Admin App v3.1.1 to +respond to the reported field issue. + +### Changing Ed Org Id Leaves a Record Behind + +* [AA-1722](https://tracker.ed-fi.org/browse/AA-1722) A bug was discovered where changing an education organization identifier leaves +behind additional data affecting ed org hierarchy and data access. This Admin +App v3.1.2 update resolves the issue for this use case. + +## Updates in Admin App for Suite 3 v3.0 + +### Support for ODS/API v6 Security Model Updates + +* [AA-1412](https://tracker.ed-fi.org/browse/AA-1412) Admin App v3.0 provides support for the ODS/API v6 security model updates. + +### Single-Sign On Support via OpenID Connect + +* [AA-1073](https://tracker.ed-fi.org/browse/AA-1073) Admin App v3.0 offers authentication via OpenID Connect (OIDC) and third-party +systems using this well-known standard.  OIDC authentication is found in +enterprise and major online providers and has been highly requested by the +field.  [EdWire](https://www.edgraph.com/) has contributed main portions of this +feature with a community contribution to establish the pattern. + +### Claim Set Editor Bug Fixes + +* [AA-1594](https://tracker.ed-fi.org/browse/AA-1594) + [AA-1597](https://tracker.ed-fi.org/browse/AA-1597) + [AA-1600](https://tracker.ed-fi.org/browse/AA-1600) The following tickets have + also been resolved in the Admin App v3.0 release: + +## Updates in Admin App for Suite 3 v2.4 + +### Update to .NET 6 + +* [AA-1423](https://tracker.ed-fi.org/browse/AA-1423) Admin App has been updated to .NET 6 to match the ODS/API and other utilities in +the Ed-Fi suite of products. + +### Remove Azure support from Admin App + +* [AA-1460](https://tracker.ed-fi.org/browse/AA-1460) The prior ODS/API Cloud Deployment for Azure deployment methods used PowerShell +and features-specific to the Azure platform, which were state-of-the-art at time +of development.  These deployment methods have modernized and updated now +available as the [Docker Deployment +2.x](https://edfi.atlassian.net/wiki/spaces/EDFITOOLS/pages/24119348/Docker+Deployment+2.x), +for which Admin App has been updated to run in that context.  The prior methods +tied to Azure have been removed here.  Ed-Fi [Docker Deployment +2.x](https://edfi.atlassian.net/wiki/spaces/EDFITOOLS/pages/24119348/Docker+Deployment+2.x)s +are known to run on Azure.  The [Ed-Fi on +Azure](https://github.com/K12-Analytics-Engineering/edfi-on-azure) repository on +GitHub, by Marcos Alcozer of K12 Analytics Engineering, provides documentation +and scripts to help deploy Ed-Fi ODS/API and Admin App images to the Azure cloud +platform as an updated method. + +### Reported Issues + +The following implementation issues have been reported by the community and have +been resolved + +* [AA-1485](https://tracker.ed-fi.org/browse/AA-1485) A bug has been fixed in the Claim Set Editor of not preserving an intended + update +* [AA-1556](https://tracker.ed-fi.org/browse/AA-1556) A request has been made to disable the Product Improvement feature and now + available as an appSetting.json configuration variable + +## Updates in Admin App for Suite 3 v2.3 + +### Multiple Namespace Support + +Admin App now has the ability to register multiple namespaces per vendor within +the application. + +### Multiple Database Support for Docker + +Support for multiple database servers in Admin App for Docker configurations is +now supported. + +### Expanded Database Name Support + +Admin App now supports database names up to 1,024 characters long for +SaaS/auto-deploy configurations. + +### Upgrade Support + +Admin App supports upgrade installations via PowerShell installation script. + +### Product Improvement Updates + +Admin App now includes the ability to send instance information into Community +365 to offer better service to implementers. For more information, please see +the +[https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/25243154](https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/25243154) +page. + +### Submit Enhanced Log Information to Ed-Fi Tracker + +When errors occur in Admin App, a new global error handler can send information +to Ed-Fi Tracker to enhance the support experience. + +### User Experience Improvements + +Various updates to features such as Learning Standards for better error messages +and reporting. + +## Updates in Admin App for Suite 3 v2.2.1 + +### TPDM 1.0 Support for Post-Secondary Institutions + +To support TPDM, Admin App has added the ability to manage Post-Secondary +Institutions within the Education Organization section. Schools can also be +added to Post-Secondary Institutions. Please note, only TPDM 1.0 is supported +and prior TPDM versions will not enable this functionality. Also, for non-TPDM +users, this feature will be hidden based on extensions detected within the ODS / +API. + +### JavaScript Library Update + +The Lodash JavaScript library has been updated for a modern product version for +UI elements. + +### Asynchronous ODS / API Version Checking + +A performance update has been implemented in the ODS Instance section to load +ODS / API information more efficiently for page load. + +## Updates in Admin App for Suite 3 v2.2 + +### School Year Selection + +School year selection within an ODS / API in the past has been a script-level +task performed directly in SQL. Starting with Admin App 2.2, school year +selection can now be performed directly within the application with display next +to ODS / API instances. + +### AES Encryption + +Admin App encrypts information to keep safe and secure both in-use and while in +rest. Admin App now uses industry-standards AES encryption to safeguard +information such as keys and secrets used to administrate the ODS / API. + +### Extended Drop-Down Support + +Many UI selection elements have been expanded to support hundreds of items. As +Admin App started to serve small, self-serve districts and charter management +organizations, previously selection elements (school drop-downs for example) +where limited to a fixed number of items. Admin App has grown into multiple +instance scenarios and larger collaboratives and state installations, these +limitations have been removed for broader usage of Admin App in these scenarios. + +### ODS / API 5.2 and Docker Deployment 2.0 Support + +Admin App has been updated and tested to work with ODS / API 5.2 and packaged as +part of the [Docker Deployment +2.0](https://edfi.atlassian.net/wiki/display/EDFITOOLS/Docker+Deployment) +release. + +## Updates in Admin App for Suite 3 v2.1.0 + +### .NET Core Migration + +Admin App 2.1.0 is now 100% .NET Core-based, which allows it to run on +non-Microsoft platforms, such as [Linux +Docker](https://www.docker.com/resources/what-container) containers. This +requirement has been signaled by our [Technical Advisory +Group](https://edfi.atlassian.net/wiki/display/GOV/Technical+Advisory+Group) and +Ed-Fi community members, which we're excited by this release to deliver on. As +related, the Ed-Fi [Docker +Deployment](https://edfi.atlassian.net/wiki/display/EDFITOOLS/Docker+Deployment) offering +has been updated to include Admin App v2.1.0 and configured to run with ODS / +API v5.1.0. For more information on the migration, please see a recorded +webinar titled "[A .NET Core migration +story](https://headspring.com/about/events/a-net-core-migration-story-the-benefits-of-a-carefully-planned-process/)" +as recently presented by the ODS Tools Team. + +### **Display Version Numbers** + +To help with support and debugging issues, both Admin App and ODS / API version +numbers are displayed within the context of authenticated pages. + +### **Session Handling Optimizations** + +From external feedback, we've received technical notes on how to handle sessions +better including cleaning up cookies not in use after logout. As part of the +migration to .NET Core, we've also improved session handling within Admin App. + +### Improved Developer Experience + +Improvements have been made to improve the developer experience and starting +with source code with an ability to "clone and go". As Admin App is one of +Ed-Fi's open source offerings, please +see [https://github.com/Ed-Fi-Alliance-OSS/Ed-Fi-ODS-AdminApp](https://github.com/Ed-Fi-Alliance-OSS/Ed-Fi-ODS-AdminApp) for +more information and to get started with Admin App source code. + +### Improved User Experience + +Optimizations to first setup experience, dialogs, warning messages and bulk load +process have been made in this version of Admin App. + +## Updates in Admin App for Suite 3 v2.0.1 + +### Fix for Postgres installations with SSPI authentication + +Admin App 2.0.1 was released as an addition was necessary in the installation +process for Postgres installations using SSPI authentication. SSPI allows +Windows roles to be mapped to Postgres database users, similar to how is done +with SQL Server installations. This update was provided in this minor release +and Admin App installations running with Postgres will have less configuration +to modify. + +## Updates in Admin App for Suite 3 v2.0.0 + +### New Features + +#### Multi-instance Support for District-Specific and Year-Specific Modes + +As highly requested by the Ed-Fi community, starting with Admin App v2.0.0, +multiple Ed-Fi ODS / API instances can be administered using Admin App +configured for district-specific and year-specific modes. Shared instance mode +is still supported within Admin App. With multi-instance mode, users have the +ability to register numerous instances within their environment, then administer +individual functions within each ODS / API, such as manage API keys and secrets, +view descriptors, perform bulk uploads and populate learning standards. + +#### Bulk Registration of ODS / API Instances + +Along with the new multi-instance administration feature, Admin App v2.0.0 +supports the ability to bulk register existing ODS / API instances by uploading +a simple CSV file. The file contains instance values and a short description of +each instance. Once complete, this file can be uploaded via Admin App to +register multiple instances within your environment. + +#### Multiple Version Support for Ed-Fi ODS / API v3.4 and v5.0.0 + +Admin App v2.0.0 supports both ODS / API v3.4 and v5.0.0. + +#### ASP.NET Identity and Multiple Role Support + +Admin App 2.0.0 replaces Active Directory support with built-in web form +authentication using ASP.NET Identity. With ASP.NET Identity, Admin App supports +two primary roles within the application: Super-Administrator and Administrator. +The Super-Administrator role can register and view listings of all ODS / API +instances as well administer application management functions, view descriptors, +and perform bulk uploads. The Administrator role can only view the listings of +the ODS / API instances they are assigned to and administer the individual +functions within. + +## Updates in Admin App v1.8 for Ed-Fi ODS / API v3.4 + +### New Features + +#### Claim Set Editor + +Based on Ed-Fi community feedback and building on the Admin App v1.7 Claim Set +Editor preview, a graphical editor for claim sets is now available in Admin App. +This feature minimizes the complex work of writing SQL scripts to establish +claim sets. See +the [https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/25238340](https://edfi.atlassian.net/wiki/spaces/ADMIN/pages/25238340) documentation +for instructions on how to use the new feature. + +#### ASP.NET Identity (Preview) + +Based on Ed-Fi community feedback from those hosting instances on cloud +configurations, authorization approaches other than Active Directory have been +preferred by numerous implementers. ASP.NET Identity offers secure web-form +authentication as an alternative to the Active Directory support built-in today. +Currently, this feature is offered as a preview, and will become part of future +releases based on field usage. See the [ASP.NET Identity (Preview in +v1.8)](technical-articles/aspnet-identity-preview-in-v18) section for +information and instructions on how to enable this feature. + +#### Learning Standards 1.1 Update + +The Learning Standards feature within Admin App v1.8 has been updated to version +1.1. Optimizations have been updated to help with sequencing of learning +standard items as well as enhancements to learning standards updates from within +Admin App. Please see the [What's New - Learning Standards Sync Utility](#) +section for more information on this update. + +#### Postgres Support + +Admin App v1.8 is fully compatible with Postgres 11 Ed-Fi ODS / API +configurations. + +#### PowerShell Installation Process + +Admin App now provides an enhanced and customizable PowerShell installation +process based on Ed-Fi community feedback. Please see [Admin App v1.8.1 for +Ed-Fi ODS / API +v3.4](getting-started/installation/older-versions-of-admin-app/admin-app-v181-for-ed-fi-ods-api-v34) +for more information on how to use and take advantage of the PowerShell +installer. + +## Updates in Admin App v1.7 for Ed-Fi ODS / API v3.3 + +### New Feature + +#### Claim Set Editor (Preview) + +Starting with Admin App v3.3, a new graphical editor for Claim Sets is available +as a preview feature. Please see [this Technical +Article](technical-articles/claim-set-editor-tab-preview-in-v17) for +instructions on how to enable and preview the Claim Set Editor features. + +## Updates in Admin App v1.6 for Ed-Fi ODS / API v3.2 + +### New Feature + +#### On-Premises Year-Specific Mode + +Some Ed-Fi implementers choose "Year-Specific mode" configuration for their +Ed-Fi ODS / API platform for data partitioning requirements or other needs. +Admin App has been updated to support Year-Specific mode configurations, which +can be set initially at installation time. + +### Improvement + +#### On-Premises Cloud License Optimization + +On-premises installations have accepted the Ed-Fi license as part of access to +source code and other Ed-Fi community material. We have removed the "Cloud ODS" +licensing step for on-premises installations to optimize the installation +process. + +## Updates in Admin App v1.5.1 for Ed-Fi ODS / API v2.6 + +### New Features + +#### Student ID to Identification Code Translation + +Multiple student identifiers are commonly used in the education data ecosystem. +Several cases have emerged in the Ed-Fi Community where student IDs in API +transactions (i.e., the `studentUniqueId` field) are not known to the client +application. As a result, a related transaction fails. This issue has been +raised in, for example, +the [ODS-1824](https://tracker.ed-fi.org/browse/ODS-1824), [ODS-2664](https://tracker.ed-fi.org/browse/ODS-2664), +and [ODS-2791](https://tracker.ed-fi.org/browse/ODS-2791) tickets. + +The recommended long-term solution is to facilitate, push, and drive rostering +products to support configuration of different IDs for different agencies, and +to store all roster IDs. However, the Ed-Fi ODS / API v2.6 includes a student +identification code translation feature as a stopgap measure. + +![](https://techdocs.ed-fi.org/download/attachments/61705307/AdminAppFunctionAddApplication2.PNG?version=3&modificationDate=1561498133930&api=v2) + +**Admin App v1.5.1 for Ed-Fi ODS / API v2.6 Student Identification System +Descriptor selection drop-down** + +## Updates in Admin App v1.5 + +This Admin App v1.5 was the first version of the ODS / API Admin App in its +current form. However, many of its core features were part of previous products, +including a version distributed with the Ed-Fi ODS / API Cloud Deployment for +Azure and the Ed-Fi ODS / API Cloud Deployment for AWS, both published on the +[Ed-Fi Exchange](https://exchange.ed-fi.org). + +### New Features + +#### Built-In Support for AB Connect + +Admin App v1.5 comes with built-in integration to Certica's Academic Benchmark +product, an online resource for academic benchmarks and learning standards. The +integration includes a free license to several national and state-level learning +standards. See the [Ed-Fi Learning Standards Sync Utility](#) documentation for +details. + +#### Support for On-Premises Deployments + +Admin App v1.5 added an installer that provides support for existing enterprise +deployments of the Ed-Fi ODS / API. diff --git a/odsApi_versioned_docs/version-7.2/readme.md b/odsApi_versioned_docs/version-7.2/readme.md index af0adeab..35eca659 100644 --- a/odsApi_versioned_docs/version-7.2/readme.md +++ b/odsApi_versioned_docs/version-7.2/readme.md @@ -43,9 +43,7 @@ Here are some resource highlights for the ODS / API v7.2: This site contains the latest version of the Ed-Fi ODS / API for Suite 3, Version 7.2. -* Looking for previous versions of the Ed-Fi ODS / API? Visit the [Ed-Fi - Technology Version - Index](https://edfi.atlassian.net/wiki/spaces/ETKB/pages/20875717/Ed-Fi+Technology+Version+Index#Ed-FiTechnologyVersionIndex-Data-Standard). +* Looking for previous versions of the Ed-Fi ODS / API? Visit the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions). * Looking for another Ed-Fi Technology? Visit the [Ed-Fi Reference Documentation](/reference). ::: diff --git a/odsApi_versioned_docs/version-7.3/readme.md b/odsApi_versioned_docs/version-7.3/readme.md index 4b8720a8..3c27fea0 100644 --- a/odsApi_versioned_docs/version-7.3/readme.md +++ b/odsApi_versioned_docs/version-7.3/readme.md @@ -43,9 +43,7 @@ Here are some resource highlights for the ODS / API v7.3: This site contains the latest version of the Ed-Fi ODS / API for Suite 3, Version 7.3. -* Looking for previous versions of the Ed-Fi ODS / API? Visit the [Ed-Fi - Technology Version - Index](https://edfi.atlassian.net/wiki/spaces/ETKB/pages/20875717/Ed-Fi+Technology+Version+Index#Ed-FiTechnologyVersionIndex-Data-Standard). +* Looking for previous versions of the Ed-Fi ODS / API? Visit the [Ed-Fi Technology Suite Supported Versions](/reference/roadmap/supported-versions). * Looking for another Ed-Fi Technology? Visit the [Ed-Fi Reference Documentation](/reference). ::: diff --git a/src/pages/reference.jsx b/src/pages/reference.jsx index 525cefa0..79c8e8e0 100644 --- a/src/pages/reference.jsx +++ b/src/pages/reference.jsx @@ -34,6 +34,10 @@ const LinkList = [ title: 'Data Import', to: '/reference/data-import', }, + { + title: 'Admin App', + to: '/reference/admin-app', + }, { title: 'Docker Deployments', to: '/reference/docker',