Package: edfi-google-classroom-extractor
Google Classroom ExtractorThis tool retrieves and writes out to CSV students, active sections,
assignments, and submissions by querying the Google Classroom API. For more
information on the this tool and its output files, please see the main
repositoryreadme.Getting StartedDownload the latest code fromthe project
homepageby clicking on
the green "CODE" button and choosing an appropriate option. If choosing the
Zip option, extract the file contents using your favorite zip tool.Open a command prompt* and change to this file's directory (* e.g. cmd.exe,
PowerShell, bash).Ensure you havePython 3.9+ and
Poetry.At a command prompt, install all required dependencies:poetryinstallOptional: make a copy of the.env.examplefile, named simply.env, and
customize the settings as described in the Configuration section below.Place the service-account.json file described below into
the root directory of this project.Run the extractor one of two ways:Execute the extractor with minimum command line arguments:poetryrunpythonedfi_google_classroom_extractor-a[adminaccountemail]-fassignmentsAlternately, run with environment variables or.envfile:poetryrunpythonedfi_google_classroom_extractorFor detailed help, executepoetry run python canvas_extractor -h.ConfigurationModule ConfigurationApplication configuration is provided through environment variables or command
line interface (CLI) arguments. CLI arguments take precedence over environment
variables. Environment variables can be set the normal way, or by using a
dedicated.envfilelike:CLASSROOM_ACCOUNT[<email address of the Google Classroom admin account, required]
LOG_LEVEL=[Log level, optional]
OUTPUT_DIRECTORY=[The output directory for the csv files, optional]
START_DATE=[start date for usage data pull in yyyy-mm-dd format, optional]
END_DATE=[end date for usage data pull in yyyy-mm-dd format, optional]Supported parameters:DescriptionRequiredCommand Line ArgumentEnvironment VariableThe email address of the Google Classroom admin account.yes-aor--classroom-accountCLASSROOM_ACCOUNTThe log level for the tool. **no (default: INFO)-lor--log-levelLOG_LEVELThe output directory for the generated csv files.no (default: [working directory]/data)-oor--output-directoryOUTPUT_PATHSync database directoryno (default: [working directory]/data)-dor--sync-database-directorySYNC_DATABASE_DIRECTORYStart date*, yyyy-mm-dd formatno (default: today)-sor--usage-start-dateSTART_DATEEnd date*, yyyy-mm-dd formatno (default: today)-eor--usage-end-dateEND_DATENumber of retry attempts for failed API callsno (default: 4)noneREQUEST_RETRY_COUNTTimeout window for retry attempts, in secondsno (default: 60 seconds)noneREQUEST_RETRY_TIMEOUT_SECONDSFeature***no (default: core, not removable)-for--featureFEATURE*Start DateandEnd Dateare used in pulling system activity (usage)
data and could span any relevant date range.** Valid values for the optionallog level:DEBUGINFO(default)WARNINGERRORCRITICAL*** When there's no specified feature, the extractor will always process Users,
Sections, and Section Associations, which are considered the core feature. Other
features (can combine two or more):assignments (Enables the extraction of assignments and submissions)activities (Enables the extraction of section activities and system
activities) -EXPERIMENTAL, subject to breaking changesgrades (Enables the extraction of grades) -COMING SOONWhen setting features via.envfile or through environment variable, combine
features by using a bracketed comma-separate list, e.g.FEATURE=[activities, attendance, assignments, grades]. To combine features at the command line,
simply list them together:--feature activities, attendance, assignments, grades.Note: in order to make the extractor work, you still need to configure yourservice-account.jsonfile. To do so, read the next sectionAPI PermissionsAPI PermissionsIn order to extract data, the Google Classroom APIs must be
enabled, and the application must be granted permission.A Google Classroom administrator will need to enable both the
Google Classroom API and the Admin SDK.  This can be donehere.Next, the administrator will need to create a Service Account
and API key.  This is the account the application will use for
access.  This can be donehere.Give the new service account a name like "Ed-Fi Extractor"
and click Create.Grant the service account the "Viewer" role and clickContinuethen
Done, skipping step 3: "Grant users access to this service account".The new service account will be displayed in a table.
Click on the three dots for the account and select Manage Keys.On the next page, click theAdd Keybutton, then choose JSON and clickCreatein the dialog box.A JSON file will be downloaded from your browser, which is the API key.
Rename it toservice-account.json. Save this into the project directory.Finally, click on the service account to view details and
copy the Unique ID field for the next step.Finally, the administrator will need to specify the scope of
access for the service account.  This can be donehere.Add a new API client and provide the service account Unique
ID (client_idin the json file) in theClient IDfield.Paste the following scopes into the OAuth scopes field and
clickAuthorize:https://www.googleapis.com/auth/admin.directory.orgunit, https://www.googleapis.com/auth/admin.reports.usage.readonly, https://www.googleapis.com/auth/classroom.courses, https://www.googleapis.com/auth/classroom.coursework.students, https://www.googleapis.com/auth/classroom.profile.emails, https://www.googleapis.com/auth/classroom.rosters, https://www.googleapis.com/auth/classroom.student-submissions.students.readonly, https://www.googleapis.com/auth/admin.reports.audit.readonlyGenerate LMS UDM CSV FilesTo pull data from Google Classroom and generate csv files, runpoetry run python edfi_google_classroom_extractorfrom the root
directory of this project. CSV files are output into thedata/ed-fi-udm-lmsdirectory.TLS/SSL proxyingUsers on a corporate network that intercepts TLS/SSL traffic will need to have a
copy of the corporate root certificate on file, and then add an environment
variable pointing to this file:HTTPLIB2_CA_CERTS=[absolute path to certificate]. NOTE: this does not load properly through the.envfile, and
must be set as an actual environment variable.Logging and Exit CodesLog statements are written to the standard output. If you wish to capture log
details, then be sure to redirect the output to a file. For example:poetryrunpythongoogle_classroom_extractor>2020-12-07-15-43.logIf any errors occurred during the script run, then there will be a final print
message to the standard error handler as an additional mechanism for calling
attention to the error:"A fatal error occurred, please review the log output for more information."The application will exit with status code1if there were any log messages at
the ERROR or CRITICAL level, otherwise it will exit with status code0.Course Aliases and SIS Section IdentifiersCourse Aliases in Google Classroom are expected to be used to provide a mapping
from a Google Classroom Course to a SIS section using a SIS section identifer.
To enable this behavior, create a domain-scoped Course Alias in Google Classroom
for each Course with the prefix "EdFiLMS." followed by the SIS section identifier.
For example, the domain-scoped Course Alias "d:EdFiLMS.ALG-123" would be used for
SIS section identifier "ALG-123". Only the first Course Alias found with the
"EdFiLMS." prefix will be used.Seecourse.aliasesfor more information on Course Aliases.Developer OperationsStyle check:poetry run flake8Static typing check:poetry run mypy .Run unit tests:poetry run pytestRun unit tests with code coverage:poetry run coverage run -m pytestView code coverage:poetry run coverage reportAlso seebuild.pyfor use of the build script.Visual Studio Code (Optional)To work in Visual Studio Code install the Python Extension.
Then typeCtrl-Shift-P, then choosePython:Select Interpreter,
then choose the environment that includes.venvin the name.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.