Package: edfi-lms-harmonizer
lms-harmonizerUtility / process for linking LMS data with SIS data in an Ed-Fi ODS. Assumes
that LMS data have been retrieved from an LMS via an LMS Extractors and uploaded
into tables in the lms schema via LMS Data Store Loader.Harmonization ProcessThe primary duty of the LMS Harmonizer is to match Student and Sections found in
the data extracted from upstream Learning Management Systems (LMS) with the same
entities in an Ed-Fi ODS database, which are sourced from a Student Information
System (SIS). These systems often do not have perfect alignment, so that the
"harmonization" process used by this tool is imperfect and may need
customization to fit your implementation.Any LMS records that cannot be matched to SIS records are considered
"exceptions"; you can generate CSV exports listing the exceptions by using one
of the command line options described below. With that information, you can then
either update the LMS source system by providing it with additional information,
or you can customize this process.The out-of-the box solution has the following mapping logic:Student MappingFor Canvas and Schoology, the default assumption is that the SIS's unique
identifier for the student, which has been loaded into theStudent.StudentUniqueIdfield via the Ed-FI ODS / PAI, has also been loaded
into the LMS in the following field:Canvas:sis_user_id(API documentation)Schoology:school_uid(API documentation)Google Classroom does not have such a field. Instead, the Harmonizer assumes
that the student's email address used in Google Classroom is also recorded in
the SIS and loaded into the ODS. The Harmonizer then does a simple matching of
records by that email address, under the assumption that no two students have
the same email address.Section MappingThe solution currently assumes that the SIS has a globally-unique identifier,
which has been loaded into theSection.SectionIdentifierfield in the ODS /
API. This same value is then assumed to be loaded into the following field for each LMS:Canvas:sis_section_idon a course (API
documentation)Google Classroom:course.aliasesobject (API
documentation)Schoology:section_school_codeon a course section (API
documentation)CustomizationIf your implementation does not match the logic described above, then you can clone
this repository and modify the stored procedures to fit alternate logic.Getting StartedRequires Python 3.9+ and Poetry.Requires that you have the ODS/API Suite 3, Version 5.2 or Version 5.3 and haveinstalled the
Ed-Fi-LMS extension.Install required Python packages:poetryinstallCreate a.envfile, or plan to pass allconfigurationvia
command line arguments. See.env.example.ConfigurationSupported parameters:DescriptionRequiredCommand Line ArgumentEnvironment VariableDB Engineno-gor--engine(mssqlpostgresql)DB Serveryes-sor--serverDB_SERVERDB Portno (default: 1433)--portDB_PORTDB Nameyes-dor--dbnameDB_NAMEExceptions report directoryno (no default)-eor--exceptions-report-directoryEXCEPTIONS_REPORT_DIRECTORYDB Username **no (no default)-uor--usernameDB_USERNAMEDB Password **no (no default)-por--passwordDB_PASSWORDUse integrated security **no (default: false)-ior--useintegratedsecurityUSE_INTEGRATED_SECURITYLog level*no (default: INFO)-lor--log-levelLOG_LEVELEncrypt db connectionno (default: False)-nor--encryptENCRYPT_SQL_CONNECTIONTrust db server certificateno (default: False)-tor--trust-certificateTRUST_SERVER_CERTIFICATE* Valid values for the optionallog level:DEBUGINFO(default)WARNINGERRORCRITICAL** If using integrated security, DB Username and password won't be required,
otherwise they are required.Running the ToolFor detailed help, executepoetry run python edfi_lms_harmonizer -h.Sample call using full integrated security, loading from the sample files
directory:poetryrunpythonedfi_lms_harmonizer--serverlocalhost--dbnamelms_toolkit--useintegratedsecurityDeveloper NotesDev OperationsStyle check:poetry run flake8Static typing check:poetry run mypy .Run unit tests:poetry run pytest testsRun unit tests with code coverage:poetry run coverage run -m pytest testsView code coverage:poetry run coverage reportRun SQL Server integration tests:poetry run pytest tests_integration_mssqlRun PostgreSQL integration tests:poetry run pytest tests_integration_pgsqlAlso seebuild.pyfor use of the build script.Integration TestingSee Integration test setup instructions (SQL
Server|PostgreSQL) for information on
configuring integration testing to work in various environments.Legal InformationCopyright (c) 2022 Ed-Fi Alliance, LLC and contributors.Licensed under theApache License, Version
2.0(the
"License").Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.SeeNOTICESfor additional copyright and license notifications.