PowerSchool Plugin

Overview

The PowerSchool plugin is a free option that integrates with Powerschool’s Unlimited Contacts.

With the PowerSchool plugin, we offer schools control of their data and the ability to use our custom plugin to access PowerSchool’s API. This plugin pushes data from Finalsite Enrollment to PowerSchool, using a custom export template. 

Important Notes

We do not have an official partnership with PowerSchool and the use of our plugin is dependent on access to custom data plug-ins in PowerSchool.

To connect with the plugin:

• Your school must host your own PowerSchool instance.

• Your school must be utilizing contacts in PowerSchool.

Who can use this feature?

Admin Account Types: System Admin and Admin
Permissions: Data

---

In this article

• Setup/Timeline
• Process
• Important Notes
• FAQs
• Custom Fields
• Error Message Guide
  • How to Read Errors
  • Common Error Guide

Setup/Timeline

Setup

The initial setup and configuration of this integration will be done by the Finalsite Enrollment Client Services Team. Please contact our support team if you are interested. 

Timeline

The standard custom data export service level agreement from receipt of final requirements is 6-8 weeks.

This timeline can be expedited if you are moving from an export/import process already built into your site. The timeline to migrate from export/import to the data plug-in is approximately 1-2 weeks.

Please Note

The timeline is subject to change. Our team will let you know and give you a more specific timeline when you reach out if that is the case.

Process

Once the initial data export is configured, it can be pushed over to PowerSchool by running the export as you would for any custom data export.

• When the export is run, a button will appear at the top of the export screen that says, Push To PowerSchool. You can view and download the data that is being pushed, before or after pushing the data on the export page.
  
  
  
• Once that button is clicked, the data will be pushed to PowerSchool and then appear in your PowerSchool System.
  • New students will be “created” in PowerSchool.
    Existing/returning students in Finalsite Enrollment will be “updated” in PowerSchool.
    
    
• Once the push is complete, the errors, if any, will be listed at the top of the screen. See the Error Message Guide within this article for more details on interpreting errors.

Important Notes

• The plugin only supports parent, student, and household data. Exporting emergency contacts is not supported.
  
  
• Entry and exit dates must be entered every term.
  • In PowerSchool, set the Entry Date for the beginning of the school year you're moving into and the Exit Date for the day after your last day of school.
  • These dates will then need to be entered into the Finalsite Enrollment Terms page located within Settings > General > Terms.
  • Click on the edit pencil to the right of the term to add these dates.
    Enter the dates within the Entry and Exit Date boxes under the Required for PowerSchool section.
    

Custom Fields

The PowerSchool plugin contains multiple data connection points. Custom fields can be added but are dependent on PowerSchool's limitations and must be migrated to the database extension table within PowerSchool.

FAQs

How does Finalsite Enrollment handle PowerSchool IDs?

New contacts pushed through the plug-in will automatically have their DCID (student - power_school_id) or Contact ID (parents - power_school_contact_id) added to their record in your enrollment database.

These IDs are used for future Powerschool pushes to update an existing record and prevent a duplicate from being created. If contacts are manually added to PowerSchool or imported outside of the data plug-in, these IDs will need to be added manually to the contact record in Finalsite Enrollment.

How does this system know which contacts to update?

Existing users in PowerSchool must have their ID recorded in Finalsite Enrollment. If the system recognizes an ID match between Finalsite Enrollment and PowerSchool, the contact is updated. If no ID exists, a new record will be created.

What if I run an export again as “all records?

It will overwrite information in PowerSchool. However, once you start the push, the export will be automatically marked as having been exported so that the next time you run the export, you can choose “since last export.” You can see what records were exported from the “which records” column.

Error Message Guide

How to Read Errors

If you receive an error after pushing the data, you'll see an error message section when you view the export. The section will look like this and contain the following columns:

• ID: This column will include the Finalsite Enrollment ID of the student with the error. Clicking on the ID will direct you to the student's record in Finalsite Enrollment.
• Name: This is the name of the student encountering the error. (This will not always display).
• Action: Actions are INSERT or UPDATE. An INSERT is a new student that will be created in PowerSchool upon the push. An UPDATE is an existing student that will update in PowerSchool upon the push.
• Type: With any error, this will always be set to “error”.
• Field: This is the field we are pushing to in PowerSchool. It is also the column header in the export under which the data can be found.
• Code: PowerSchool's error code. See the list below for common codes, what they mean, and how to address them.
• Description: This will provide a short description of what is causing the error. An example of this is “Empty value is not allowed” which means that every student in the export must have a value set for that field.
• Message: This column will be blank.

Common Error Guide

To better understand the error, you'll need to interpret the message within the code column of the error message section. Expand each section below to learn about each error code and what they mean.

If you see an error not listed here and/or you are unsure about how to fix the error, please don't hesitate to reach out to our Support team. We are happy to help you.

INVALID_ID

The DCID for this student is not valid. More than likely you will see an error description that states, “ID does not exist, can not perform update.” This error is thrown because this student does not exist in PowerSchool. 

FIX: The student's DCID will need to be cleared out in Finalsite Enrollment. This ID lives under the PowerSchool ID field which is typically found under the Personal Tab of the student's record within the ID grouping.

FIELD_VALIDATION_ERROR

This error code lets you know that there is something wrong with the format of the data being pushed. Refer to the error description for additional information on the formatting required.

Note: If the error description states, “Empty value is not allowed”, it is because there was no data set for that student and PowerSchool required a value to be set for that field.

FIX: You will need to update the student data for the offending field or contact our support team to request that we update the export to output the data in the required format.

REQUIRED_X

This error code will display the name of the offending field in place of the “X”. An example of this is “REQUIRED_PHYSICAL_CITY”. This error lets you know that the student did not have a value set for the corresponding required field.

FIX: Go to the student's record and update whatever information is missing. For example, if their city is missing, add a city to their address within the Households > Household Details tab.

UNKNOWN_ERROR: {:message =”Can’t update columns that are remapped”}

There is a duplicate field in the export or a column header may be incorrect.

FIX: Contact the support team. They will assist with updating your export file.

403 Forbidden: {"message":"no permission to update field: <<powerschool field name>>","errors":[]}

The error is being thrown on the <<powerschool field name>> field. This means we do not have access to push to this field in PowerSchool.

FIX: Contact the support team. If it's possible to add this field to your export, they will assist you in doing so.

No data submitted for required element

PowerSchool requires data for this field.

FIX:  The field will need to be updated with value before pushing again. This error is most commonly seen in the following fields:

• grade_level: The term used for the saved search most likely needs to be updated as the student is not in workflow for the term used. Update the term in the saved search that you've used for the export and try the export again.
   
  • Note:
    • If the term is not correct, this could cause errors in any other field that uses the student's grade, term, and/or status.
    • If the term is correct contact the support team for further assistance.
      
      
• entry_date or exit_date: The above issue may also cause this error on these fields.
  • If the term used for the saved search is correct, verify that the entry and exit dates are set for the term that the student is in. This can be done by navigating to the Terms page (Settings > General > Terms) and editing the term.

INVALID_NUMBER_OF_TERMS

You need to create a new term or update the existing term in PowerSchool that the entry/exit dates (first and last days of school) fall within.

 

The dates will then need to be entered in Finalsite Enrollment. This can be done by navigating to the Terms page (Settings > General > Terms) and editing the term.

MISSING_PARAMETER

One or more required parameters are missing. (this error refers to the address). This error can be caused by mistakenly setting the address type but not having an address listed.

FIX:  Verify that the contact has an address listed if there is an address type set. If not, add an address on the Households > Household Details tab of the student record.

INVALID_CONTACT_DATA

psx.html.contacts.validation.original_contact_type_already_assigned

FIX: Contact our support team to assist with correcting this issue.

INVALID_CODESET_VALUE

Value does not exist in the applicable code set. (e.g. relationship)

FIX: Verify that the relationships in PowerSchool match their values in Finalsite Enrollment. Contact support for assistance with this.

FIELD_VALIDATION_ERROR

Value <<field>> not valid for codeset <<field>>.

FIX: Contact our support team to assist with correcting this issue.

REQUIRED

No data was submitted for the required element (contact/phones/phoneNumber). This error will be thrown if a phone type is given without a phone number.

FIX: If this is a single case, remove the phone type or add a phone number to the contact, otherwise, contact Support for assistance with correcting this issue.

POWER_SCHOOL ERROR: 500 Internal Server Error

This error might be caused by other issues, but one reason is that 1 and/or 0 are set as an output for a field in the export file instead of TRUE and/or FALSE. All 1 outputs should be TRUE and all 0 outputs should be FALSE.

FIX: Contact Support for assistance with correcting this issue.

---

Additional Resources

• Office Hours & Past Session Recordings
• PowerSchool's documentation on moving from Hosted to Self Hosted
• Data Export
• Scheduled Exports