What is a Plugin?
A PowerSchool plugin is a convenient way for PowerSchool users to package and share custom content including the following
- Custom Pages and Page Fragments
- Database Extended Table/Field Definitions
- PowerQueries
~[wc:commonscripts]
~[wc:admin_header_css] ~[text:psx.html.admin_reports.runreports.start_page] > PowerSchool Customization ~[wc:admin_navigation_css] ~[SetPostValue:tab=plugin]A PowerSchool plugin is a convenient way for PowerSchool users to package and share custom content including the following
Plugins are managed via the Plugin Management Dashboard (System > System Settings > Plugin Management Configuration)
![]() |
A plugin is simply a zipped folder containing plugin.xml file and up to four optional folders
|
Below is a basic template for a plugin.xml file. There are more contents that the file may contain,
and you may see additional elements in
some third-party plugins, but the contents of this file are
all that is needed for a basic plugin containing custom pages, schema extensions, and/or PowerQueries.
The web_root folder will contain all custom pages to be included with the plugin.
This folder must contain the appropriate sub-folders to ensure that files are place in the appropriate locations.
After installation and activation of the plugin, all custom files will be uploaded to the corresponding locations in Custom Page Management.
The user_schema_root folder contains xml files which define database extensions.
These files should have the following naming format: U_[extensionname]
Below is a sample xml file for creating one-to-one extended fields.
The queries_root folder contains xml file(s) which define PowerQueries.
The PowerQuery filename must follow this format: [name].named_queries.xml
The example below includes a simple query which includes student, course, and grade information.
<query name="com.mba.psugDemo.studentGrades.storedGrades" flattened="true">
The query name must have five parts: com.[organization].[product_name].[area].[name]
<description> - provides a description of the PowerQuery
<summary> - provides a description of the PowerQuery as well, this is how the PowerQuery will be labeled in Data Export Manager
<columns> <column column="students.lastfirst" description="Student Name">student.fullname</column> <columns>
column="students.lastfirst" : tablename.fieldname
description="Student Name" : Not required but highly recommended
student.fullname : An alias for the column
* Note - A single file can contain multiple <queries></queries> tags; each with a different PowerQuery.
Working with current student selection
Add the following WHERE clause to a students table query to enable the ability
to limit results to students in the current selection
WHERE <@restricted_table table="students" selector="selectedstudents"/>
With the above query, a dofor parameter can be passed to the query to restrict to currently
selected students
/ws/schema/query/[queryname]?pagesize=0&dofor=selection:selectedstudents
If no dofor parameter is passed to the query, it will run for all students
The permissions_root folder contains xml file(s) which define access permissions to PowerQueries.
These files should have the following naming format: [name].permission_mappings.xml
The example below would provide access to the PowerQuery example above
to any user who has access to the page admin/tech/home.html
Portal | Permission |
---|---|
Admin | /admin/somepage.html |
Teacher | /teachers/somepage.html |
Guardian | /guardian/somepage.html |
Student | /student/somepage.html |
Note: - All public portal pages are maintained in the guardian folder. The student permission will not represent an actual page in the web root.
What follows is an example of accessing a PowerQuery from a PowerSchool page. The code has been displayed below (XML, JavaScript, and HTML).
For a deeper look at the structure and code, simply look at the contents of the MBA Customization Reference Plugin which contains the PowerQuery as well
as all necessary code on this page (admin/district/customizationDocs/plugin.html) to generate the table at the end of this section.
Notice the following lines in the above code:
<args> <arg name="enrollStatus" column="students.enroll_status" required="false" description="student enroll status" default="0" /> </args>
Adding arguments to a PowerQuery allows that query to be called with a specific parameter.
In this case a student enroll_status can be passed to the query.
If no enroll status is passed, a value of 0 will be used.
Notice also that schools.principal appears twice in the <columns> list.
The final value returned by the query is the result of a subquery.
There is no field representing this value in the schools table, but the PowerQuery expects each value to be associated with a valid table and column.
The schools.enrollment alias for this field will result in the value returned from the query having a label of enrollment.
For the HTML, there is simply the shell of a table. JavaScript will be used to append rows to this table for each result returned by the PowerQuery.
Document Ready Function
getPowerQueryResults()
buildSchoolsTable()
School | Abbreviation | School Number | Principal | Enrollment |
---|---|---|---|---|
The data restriction framework (DRF) rewrites PowerQueries to apply security.
This can cause unexpected results at times.
Adding the following parameter to the post body can help in debugging.
If the PQ is called with this parameter, the DRF version of the
query will be posted to the psj-runtime log.
{"__debug_query":"true"}
Query
DRF query at district
DRF query at school
Because the DRF rewrites queries in different ways depending on user context (portal, school, field-level security), the same query may result in different results in different scenarios.
The DRF can sometimes have trouble with more complex queries and result in query execution failure. This is not common, but it is worth keeping in mind.
The complexity of rewritten queries can have a significant impact on performance in many cases.