Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The Cloud ODS / API Admin App provides a Web front-end to common administrative tasks for managing an Ed-Fi ODS / API. In general, the Admin App and solution provides access to functionality specific to Ed-Fi ODS / API management, and does not duplicate functionality provided through existing platform tools.

  • The Admin App is currently only available for the Cloud ODS / API product. The enterprise, on-premises ODS / API does not include this tool.
  • Some functionality of the Admin App may vary by platform due to differences in underlying platform services. These variations are noted below.
  • Some ODS / API administration functionality (e.g., database backups, direct database access or editing, inspection of logs) may require using platform tools or other Microsoft tools (e.g., SQL Server Management Studio). 
Info

The ODS / API Admin App is currently distributed with the Ed-Fi ODS / API Deployment Tools for Azure and Ed-Fi ODS/API on AWS solutions, available on the Ed-Fi Exchange.

This documentation covers the following topics:

Table of Contents
maxLevel1
exclude.*Contents.*

Detail on each topic follows.

Overview


The Admin App has three main sections, which will appear on first logging in:

  • Settings. This section holds common administrative functionality.
  • Reports. This section provides reports on system activity (please note that these reports are NOT intended to provide for business analytics functionality).
  • Updates. This section provides information on solution versioning and functionality related to updating the solution.

Click on one of the icons to move into that section. To return to the home screen, click the icon in the top-left corner of the window.

Settings Section


The Settings Section houses functionality used for changing settings and performing common administrative tasks.

Layout

The Settings section is laid out with tabs that show which ODS instances are present in the solution, as well as a "Global" settings tab. These tabs show the environments to which the settings apply, and correspondingly what will be affected if settings are modified.

The screen capture below shows an instance with two environments being managed by the Admin App (a "Staging" and a "Production" instance):

Settings surfaced or changes made in the first tab will apply to all environments, but changes made in the latter tabs will only apply to the Staging or Production environment (i.e., the Staging or Production ODS / API) respectively. Use the tabs to navigate between environments.

Under each main tab are a list of sub-tabs that provide access to specific configuration settings or functionality: 

Include Page
_Platform Developers' Guide - Sidebar
_Platform Developers' Guide - Sidebar

Setting Detail

The following table is a list of the main functions under the Admin App Settings, and where to find each function in the tab hierarchy. The "Availability" column describes on which platforms the functionality is available.

Function or SettingLocationAvailabilityDescription
Create, edit and remove vendorsProduction and Staging → VendorsAll

Vendor registrations apply across all ODS / API environments. To register a new vendor, use the Add Vendor button to bring up a form used to add a vendor. To edit or remove a vendor, use the buttons beside the existing vendor record.









Create, edit and remove vendor applications

Production → Applications

or

Staging → Applications

All

Applications are specific to each ODS / API environment. This allows you for example, to set up a vendor application so it initially can only access the Staging, then later register that application so it can access production resources.

Adding a new application can be accomplished by clicking the Add Application button on the Applications sub-tab, and filling out the form.

Existing applications can be removed or edited by clicking on the edit (pencil) or delete (trash) icons.

When adding an application, you will be asked to select a few options as to the scope of data in the ODS that the application can access. These are important settings for security reasons, as they determine what data the application can access.

  • Education Organization Type. This value is not stored, but is only used to bring up a list of Local Education Agencies or Schools.
  • Education Organization ID. This value is saved in the ODS Admin database and used to determine the organizational scope for the data accessible via the API.
  • Claim Set Name. The Claim Set defines the operations (view, edit/delete) available to a client system and also the relationships that are traversed off the education organizations selected. For example, you can establish whether the claim set allows an application to view Sections associated with the education organization, or to view Parents associated with Students associated with the education organization, or other similar data access permissions. The ODS ships with a set of default claim sets that have been field tested, but claim sets are also configurable (not supported by the Admin App directly).
  • Student Identification System Descriptor. This is an optional setting under advanced options. It configures API to translate StudentUniqueId to a student identification code in its transactions for this application. When this feature is being used application may be configured to access only one education organization.

It is strongly recommended to review the ODS / API Platform Dev. Guide - Security.

Image Modified

After clicking Add Application, the scree will show the application Key and Secret that are used by the API client to get an authorization token to exchange data. Copy these values into a secure location, as they need to be provided to the application provider. If you lose these values, you will need to regenerate them. Consult the instructions that follow regarding that feature.

For convenience, the API URI is also shown on the page with the key and secret. This URI can be looked up in the Admin App as well (consult the Admin App User Guide instructions).


Regenerate application key and secret

Production → Applications → Regenerate

or

Staging → Applications → Regenerate

All

Under the application registration, use the Regenerate button. Note that current applications using an existing key and secret will no longer be able to access the application.


Change timeout for API authorization tokensProduction and Staging → Advanced SettingsAzure

This setting determines how long a API token will last before expiring (requiring the API client to re-authenticate and get a new token). The timeout can be changed by updating the value under Bearer Token Timeout In Minutes and clicking Save Changes.


Lookup the API URI

Staging → Applications

or

Production → Applications

All

The API URI is specific to each ODS environment, and is displayed on the Applications page for that environment. Note that the Staging Applications page shows the Swagger URI as well, so be careful to choose the correct URI.

This value is required by vendor systems that use the API, as it tells them the endpoint for the ODS APIs their systems connect to.


Access the Swagger URIStaging → ApplicationsAll

The Swagger application and user interface is only installed on the Staging environment, and not on the Production environment. The Swagger application allows you to browse and manually the API surface by sending and receiving data.

The Swagger application link can be found on the Staging Applications page.


Lookup system enumeration values (descriptors)

Staging → Descriptors

or

Production → Descriptors

All

The Ed-Fi data model (also called the Ed-Fi Unifying Data Model or UDM) contains a set of standard values for all enumerations in the UDM. Those values can be looked up in the Admin App under the Descriptors sub-tab. Vendors frequently need to know what these values are to send data to the Ed-Fi APIs.

In some data exchange scenarios, an organization may wish to customize these values. The Admin App does not support this customization directly, but changing values (most commonly by adding new values) can be done via the ODS APIs in the descriptor section. However, it is not recommended that this is done unless an organization is fully aware of the responsibilities behind publishing its own values.


Create, edit or delete schools or districts

Staging → Education Organizations

or

Production → Education Organizations

All

In some cases, the ODS records for schools and school districts may be provided by a system connected to the ODS (usually by a Student Information System). If this is not the case, this data can be added manually using the Education Organization sub-tab.

The system accommodates multiple school districts as well, for use cases in which the ODS is a collaboration between school districts.


Reset the Staging sample dataStaging → Reset → Revert to Sample DataAzure

If the Staging ODS data needs to be reset, there is a function to reset the data. This will delete all data currently in the Staging and reset the Staging to the initial set of sample data that was present on the first install. This function should be involved only upon careful consideration, and the system will ask for a second confirmation of the change.

On the Reset sub-tab, select Revert to Sample Data and click the Reset Staging button.

Note that there is not a reset function for the production data. For safety reasons, that ODS database can only be reset using external tooling (for example, by using SQL Server Management Studio or other platform specific tools).


Remove the Staging sample dataStaging → Reset → Setup for my organizationAzure

In some cases, you may wish to remove all data from the Staging. The remove function removes all ODS data except the default Ed-Fi enumerations data (for users of the enterprise ODS, this function installs the "minimal" database template).

On the Reset sub-tab, select Setup for my organization and click the Reset Staging button.

Note that there is not a reset function for the production data. For safety reasons, that ODS database can only be reset using external tooling (for example, by using SQL Server Management Studio or other platform specific tools).


Upload a bulk data in Ed-Fi XML format

Staging → Bulk Load

or

Production → Bulk Load

Azure

The Admin App supports bulk uploads. This feature is only recommended for smaller bulk uploads, so be default the file size is constrained to 20MB.

On the Bulk Load sub-tab Select File Type, select the Ed-Fi Bulk Interchange type and then select the file on your computer. Click Upload to begin the process.

Note that the process may take a few minutes and does not display process precisely.

Users needing to upload larger files or needing a more interactive experience should consider using the Client-Side Bulk Upload Utility. Consult the Client-Side Bulk Load Utility documentation.


Prepare the production ODS for initial usageProduction → SetupAzure

There are two options for setting up production usage of the system.

The Interactive Setup option will ask you to configure all settings, including Schools and School Districts. It essentially begins with a blank copy of the database.

The option Initialize using data from the Staging copies over Schools and School Districts data from the Staging, as well as any customizations made to Ed-Fi Descriptors (Descriptor editing may have been accomplished via the ODS / API, and is not recommended for those not familiar with the responsibilities and impacts of changing enumeration sets).



Reports Section


The Reports section allows for monitoring system activity, allowing an administrator to inspect basic facts about data in the ODS databases and about related system usage, such as the addition of new records.

These reports allow for basic data quality inspection and system activity monitoring, but they are not intended to support day-to-day business analytics needs. As such (and for security and privacy reasons), these reports only display aggregate data. For more detailed analytics needs, we recommend other analytics and business intelligence (BI) tools and toolkits.

Usage

From the home page of the reports section, select the district whose data you want to inspect using the Select District drop-down:

When a district is selected, a variety of reports become available via the sub-tabs:

At a high level, these reports include the following:

  • Summary. Basic counts of users and schools.
  • Activity. The number of records modified within past time periods. Note that if a record is modified multiple times, multiple changes to a single record will be counted as a single modification. If the database is reset these counts will also be reset.
  • Demographics. A basic breakdown of student demographics.
  • Student by Program. The participation counts of students in various programs.
  • Other Student Data. Other reports on students.

For more information, we recommend inspecting the reports directly.

Updates Section


The Admin App will alert you when updates are available.

Note
titleMinor Version Only

The Cloud ODS / API only supports minor version updates that do not alter the data schemas of the underlying ODS databases. Support for updates that involve data migration are being evaluated.

If an update is available, you will see Update Available appear below the Updates icon on the home screen. Click on the Updates icon to get more information.

The updates section will then display information on the update. We recommend you consult any linked Release Notes for information on the update.

If you wish to install the update, please consult the instructions for updating specific to the platform instance you are using.