Google Integration with Aeries
|[Aeries Web Version Google Integration - Updated September 2, 2016]|
This document will detail how to connect Aeries SIS with Google Apps for Education (GAFE) and Google Classroom. The Aeries integration with Google provides for streamlined account management and seamless data exchanges with Google.
In order to integrate Google with Aeries, you must have a Google Apps For Education (GAFE) domain created with Google. All of the following steps must also be configured on the Google side by a user account with Super Admin privileges in the Google domain. Also you must use Chrome to complete this setup.
Please ensure that you have enabled "Google Developers Console" and "Google Groups" in your Google Admin Console.
- Google Apps for Education Configuration – Part 1
2.1 - Create a Super Admin account
Aeries will use this account to manage your users, organizational units, groups, etc. for the GAFE integration. You can name the account anything, but we recommend using Aeries in the name of the account to easily identify it. For documentation purposes, we named our account "Aeries Service"
- Google Developer Console Configuration
3.1 - Create a New Project
Using the "Aeries Service" account you just created, login to https://console.developers.google.com and click on "Projects" in the menu to the left, and then click the "Create Project" button.
3.2 - Name Your Project
We suggest naming your project something like "Aeries Integration" or similar so it is easy to identify.
3.3 - Select Your New Project and Enable API
Select that newly created project from the dropdown if it is not already selected. You'll be taken to the Project Dashboard. Click on Enable and Manage APIs which will take you to the list of APIs enabled for your project. By default, Google enables a few of their APIs for you, you can safely turn those off. For this integration you will need the Admin SDK API enabled so search for and select this and click Enable API. For Google Classroom integration you will also need the Google Classroom API enabled.
3.4 - Create New Credentials
You will now create a set of credentials that will be tied to the Aeries Service user you created at the beginning of this process. This information will be copied and pasted into Aeries later in the setup.
Click on the Credentials node on the left hand menu.
Next, click on the New Credentials drop down and select Service Account Key.
Select New Service Account from the drop down, give your account a recognizable name, and select P12 for the key type. Select Project->Owner for the Role. When you click create, a P12 file will automatically download. This is the only time Google will issue this particular P12 file. If it's lost a new file with a new key will have to be generated.
This is a very important file. You must place this in the AppSettings folder of your web server and in the Service folder of your Aeries Reporting Server. Without this file, you will not be able to connect to Google successfully. You don't need to worry about the private key password. It is the same for everyone in the world. The file you just downloaded is the super-secret file that distinguishes your account from everyone else in the world.
Click Manage Service Accounts, then click the⋮ next to AeriesService, click Edit, and check Enable Google Apps Domain-wide Delegation and click Save. This will create a Client ID.
3.5 - Configure Consent Screen
You will be prompted to enter data into a Consent screen. This is never used, but you must put in minimal information in this form. Fill out only what is necessary (email, product name) and click Save to continue.
3.6 – Keep these credentials
Click View Client ID on your Service Account and keep this tab open as you will need the Client ID and Service account email address later in this setup.
- Google Apps For Education Configuration – Part 2
4.1 - Configure API Security
Back now at https://admin.google.com, from the dashboard (admin console), you will click on Security. Click on API reference and confirm that the Enable API access box is checked. If it is not checked check it and click Save on the bottom right.
4.2 - Advanced Settings
Click the Show more link underneath the Set up single sign-on (SSO) area to reveal Advanced Settings. In Advanced Settings click on Manage API client access.
4.3 - Manage API client access
In this screen, you will copy the Client ID value that you created in step 3.4 above and paste it into the Client Name field. Then, you will copy and paste the following API scopes into the One or More API Scopes section and separate them with a comma. After both fields (Client Name and One or More API Scopes) have a value, click the Authorize button.
Paste these into One or More API Scopes delimited by a comma.
https://www.googleapis.com/auth/classroom.coursework.me.readonly https://www.googleapis.com/auth/classroom.coursework.students https://www.googleapis.com/auth/classroom.coursework.students.readonly
4.4 - Google Configuration is now complete
You have successfully completed the Google configuration portion. Now, you'll put some information into Aeries.
5.1 - Login to Aeries
Login to Aeries as an Administrator and navigate to the Google Apps Integration form (School Info Configurations Google Apps Integration). Please note that while the navigation is currently under School Info, these settings are in fact for the district and need only be set once. You will see five tabs:
- Directory Sync Settings - pertain to how you want your student accounts formatted and how you want Aeries to interact with Google for directory synchronization.
- Google Classroom – configuration options for Google Classroom.
- Organizational Unit Structure - describes how your students will be organized inside of Google. This tab is only applicable to directory sync.
- Google Service Account Settings - should only need to be configured once and then can be left alone.
- Maintenance Functions - simply allows you to initiate a push of students from Aeries to create their Google Accounts immediately, or to remove all accounts from within the Organizational Units you've specified if a mistake has been made.
Note: Directory Sync is recommended but is not necessarily required to be used to integrate with Google Classroom for teachers. If you only want to integrate with Google Classroom to allow your teachers to import scores to gradebook, then only configure the Google Service Account Settings tab.
5.2 - Directory Sync Settings
- Synchronize all students nightly – This will add accounts for students who do not currently have a Google account associated with their Aeries account, or suspend accounts which are associated, but are no longer active in Aeries.
- Automatically sync student accounts when added via Aeries SIS Web - This will asynchronously sync the new student to your GAFE users whenever a student is added via Aeries SIS Web Version.
- Override Existing Student Emails (STU.SEM) with Pattern – Determines if the nightly process should override any existing values in the student email field that do not match the pattern and make them match the pattern.
- Student Root Org Unit – The top level Organizational Unit students will be added to. This is critical as you can take action on all student accounts from within the Google Admin Console by nesting them under one org unit.
- Student User Name Pattern - This is the pattern that will be applied to all student GAFE user accounts. Possible elements are first-name, last-name, middle-name, permanent-id etc. These pattern elements can be modified with left and right string functions to allow you to form a custom string with whole data or parts of each data element to build the pattern your students will have for their accounts.
- Student Password Pattern – Similar to the student user name pattern, but just for the password.
- Force New Students to Change Password on First Login to Google Apps – Newly created students will be forced to change their password.
- Match New Student PWA Passwords (Student Portal) to Password Pattern - Any newly added students that have PWA accounts (Student Portal) will have that password match their Google Apps password.
- Suspend accounts that are no longer linked to a student record
- Suspend accounts outside the age/grade ranges
- Schools to Synchronize – The set of schools that you want to participate in any of the synchronization processes.
5.3 - Google Service Account Settings
This is where you will copy from the https://console.developers.google.com area, the following fields:
- API Application Name – This is the project name you entered in step 3.2 above.
- User to Impersonate – This is the Aeries Service account you created in step 2.1 above
- Student Domain – This is the domain (NOT the organizational unit) your students will belong to and will serve as part of their Google account's address. Some districts like to separate their students from their employees. This is the place to tell Aeries that domain.
- Service Account Client ID – This is the Client ID that belongs to the Service Account and should be visible in the open Developers Console tab (from step 3.6 above).
- Service Account Email Address - This is the email address that was generated when you created the Service Account and should be visible in the open Developers Console tab (from step3.6 above).
- P12 Private Key File Name – This is very important. This is the name of the file you downloaded in step 3.4. It should be placed in your AppSettings folder of your web server and the AeriesReporting\Service folder of your Aeries Reporting Server.
5.4 - Connection Confirmation
You have now entered all the data elements necessary to connect to Google. Click the Save button at the top or bottom of the Google Service Account Settings tab, and the Configuration Status message should display a green check mark. If not, it will tell you what the error message is from Google and be red.
5.5 – Google Classroom
Enabling Google Classroom will allow your teachers to Import assignment scores from Google directly to their gradebook (scores by assignment page). It will also allow them to create a classroom with students already joined, or to link to an existing classroom (classroom summary).
- Synchronize all classrooms nightly - This will populate existing Google classrooms with scheduled students during a nightly process.
- Automatically add students to Google Classroom when scheduled in Aeries - This will asynchronously add new students into Google Classrooms whenever they are scheduled into a section in Aeries.
- Improve Performance – This should only be checked if your District is using Directory Sync and doesn't want to look users up in Google directly.
First review/enable permissions for your teachers to use Google Classroom. Follow this link to learn how to set up those permissions https://support.google.com/edu/classroom/answer/6071551?hl=en. Next, make sure that teachers who want to use Google Classroom have a properly set up Google teacher account set as their email address. They will then be able to create new Google Classrooms, or link to existing ones, and automatically join their students to those classrooms directly from the Classroom Summary within Aeries. Teachers can also import scores from Google Classroom into the Gradebook.
*IMPORTANT NOTE: For students to be added automatically when a classroom is created the students must also have valid Google accounts set up in the student email address field. (STU.SEM).
Staff must have their google email address populated in UGN.EM, or the Google SSO Email field (SSO.GEM). This is set on the Security Users form.
If your District is not using Directory Sync options, but wishes to use Google Classroom for your teachers, STU.SEM must be populated with the student's google email address.
5.6 - Organization Unit Structure
This section is where you will decide the nested structure you want for your Organization Units in Google. The process that copies your desired structure to Google will only add Org Units. It will never delete them. If you decide on a structure, and then decide to change it in the future, you will have to manually remove any unused org units from the Admin Console. Students will be added to whatever the current directory structure is.