Genesis Report Writer

Transcription

1 Genesis Educational Software, Inc. Genesis Report Writer User Guide Genesis Educational Services, Inc Spring 2008 July 8, 2008 DRAFT Page 1 of 58

2 REPORT WRITER GUIDE Report Writer Your reports Create a new Report Icons on the Report Writer screen: Run the report View the most recent run of the report View the report archive list of available report runs Edit the report. Change its form. Delete the report definition. This report was written with the Genesis Report Writer Report runs are stored per user Report runs are stored per school Report runs are stored 1 for the district July 8, 2008 DRAFT Page 2 of 58

3 Report Writer Guide Table of Contents 1 Report Writer Overview p. 4 2 Example: District or School Roster Report p. 5 3 Getting Started with Report Creation p Selecting the Base Table for a Report p. 14 4a Viewing a Table s Structure p Defining Report Columns and the Report Query P Adding in Columns from Other Tables - Linking p. 18 6a Building Report Queries p. 21 6b Linking Tables into a Query p. 22 6c Multiple Columns from One Linked Table p. 22 6d How Report Querying Works p Invisible Columns p Maximum Length Columns p Blank and Parameter-filled Columns p Built-In Macros p Parameters p Filters p Sorting p Report Sections, Totals and Page Breaks p Changing Basic Report Information p Controlling the Appearance of Reports p Publishing Reports p a Report Ownership p Running the Report p a Creating a Student List as Output p. 58 This is a draft manual. July 8, 2008 DRAFT Page 3 of 58

4 Report Writer Overview The Genesis Report Writer gives you the power to create new reports from scratch and to access virtually any table in the Genesis student records database. The process of creating a custom report can begin on any screen in Genesis and has 6 distinct steps: 1. Base table: Select the base table for the report 2. Columns: Select and specify the columns for the report, including columns which are linked in from additional tables. 3. Report Parameters: Specify what parameters the report will request from the user at runtime. 4. Filters: Specify the filters on the retrieved data that will exclude undesired data and narrow the selection based on what the user and the report designer wants in the report. 5. Sorts: Specify how to sort the data. 6. Totals and Sections: Divide the report into sections, if desired, and add totals to both the sections and the entire report. You may run a test report at any point in the development process. The Genesis Report Writer gives you complete control over the creation and deployment of custom reports. Additionally, when you run a custom report, you may choose to output the data in any one of three possible formats: Adobe PDF, MS Excel and flat text CSV. This choice is made at runtime. Custom reports that have been developed with the Report Writer can be deployed for use by any user via the usual Genesis Role system. The remainder of this document initially walks you through an example report and then proceeds to describe in detail all aspects of report development. July 8, 2008 DRAFT Page 4 of 58

5 Example 1: Creating a Student Roster Report Procedure to Create a Student Roster Part I: Create the Report Entry in the list of reports 1. Navigate to the Report Writer List Reports Screen 2. Locate the Add Report fields at the bottom of the screen: 3. Enter a Sequence Number ( Seq ) for the new report. This number is the report number and must be unique on your screen. 4. Enter the name of the report. 5. Click Add to begin the report creation process. This will add the report to the list of reports and bring up the Report Writer Reports Modify Tables screen: Part 2, Step 1: Select the base table for the report 6. Select the table the report is going to be based upon. This report will be based on the Student table. a. Choose the group or module. This changes the display to show only the database tables in that module. b. To select the Student table click the button. Note that each select button has the name of the table you are selecting. Part 2, Step 2: Specify the columns for the report, both visible and invisible 7. This brings up step 2 Select Columns for the Report The list of columns defaults to the columns which make up the primary key of the selected table. The primary key of the Student table consists of the school year, the school code for the school the student is currently attending and the student s StudentID. These columns are automatically placed in the list of columns. 8. Add the LastName and First Name columns to the report. a. Locate the area at the lower left. Select lastname from the drop down: b. Accept the sequence # ( ). c. Click to add the lastname column to the report. d. Select firstname from the drop down: e. Accept the sequence # ( ). f. Click to add the firstname column to the report. 9. Add currenthomeroom and currenthomeroomteacher: July 8, 2008 DRAFT Page 5 of 58

6 a. Select currenthomeroom from the drop down: b. Accept the sequence # ( ). c. Click to add the currenthomeroom column to the report. d. Select currenthomeroomteacher from the drop down: e. Accept the sequence # ( ). f. Click to add currenthomeroomteacher. 10. Add gradelevel, dateofbirth, speced, age, familycode. The report should now have 11 columns: 11. Add Address Information to the report. Addresses are stored in the Address table. Locate the Add a column that looks up its value from another table on the bottom right of the screen. a. Enter the column header you want for this new column in the Display As field: Mailing Line 1 b. Accept the code generated in the Code column. c. Accept the seq # ( ) d. Click to add the Mailing Line 1 column. The screen is displayed for Mailing Line 1 e. Part 1 of the Define Linked Column process is to select the table to link to the existing report column. Select Address. f. As soon as you select the Address table, the drop down appears. Select the addressmailingline1 field. g. Part 2 now appears: You have two options: - Field Value show the contents of the field - Count of Rows Count the number of rows and show the count. Select Field Value this will show the student s address. h. Click the button to finish defining the Mailing Line 1 column s contents. July 8, 2008 DRAFT Page 6 of 58

7 i. Part 3 now appears: You must specify how to link the new (Address) table to the existing columns of the report There are three links on the Address record that tie it to the Student record: schoolyear, studentid and familycode. All three automatic links are already present they are added automatically by Genesis. For this report, only the Legal Residence (LR) address will be used: a filter to extract only that address must be added to the report. This requires a filter on the addresstypecode field of the Address table. j. To add the addresstypecode link, use the Add Filter fields at the bottom of the existing set of links: - Select the addresstypecode field - Accept the = equals relation - Enter LR in the field. - Accept the sequence #.. - Click to add the addresstypecode filter to the list. k. Click tab to return to the Add a Column screen. The new Mailing Line 1 column is now there. Note that the new linked column has an edit icon corresponding to it. 12. Repeat all parts of Step 11 to add a City column to the report. a. Define the new column: b. Define what table and table column to get it from and how to display it: c. Specify how to link to the existing columns of the report: July 8, 2008 DRAFT Page 7 of 58

8 d. Return to the screen. The list of columns now contains two linked columns: Part 2, Step 3: Define the report parameters 13. Click the tab of the report. Add a Select School parameter to narrow the report to a single school: a. Locate the define a Parameter fields at the bottom left: b. Enter the question Select a School c. Select with the selection List: Schools : d. SCHOOLCHOICE e. Do not specify a default value. f. Do not check the Required or Hidden checkboxes. g. Accept the sequence #( ) h. Click to add the SCHOOLCHOICE parameter. Part 2, Step 4: Define the filters on the data 14. Click the tab of the report. This is where the filters to narrow the data displayed are built. Two filters will be added. The first will always eliminate the INACT school. The second will only display students selected with the SCHOOLCHOICE parameter created above. A list of automatically created filters already exists: a. Add the filter to eliminate the INACT school: i. Select School Code from the Column drop down ii. Change Operand to!= - NOT equals iii. Enter INACT in the Value field iv. Accept the sequence #. v. Click to add the filter. b. Add the filter to narrow the data to School Choice i. Select School Code from the Column drop down ii. Accept the = equals Operand iii. Locate the User Defined Macros list at the bottom of the screen: Click on the at the top: icon for ${SCHOOLCHOICE}. This copies it to the filter definition field July 8, 2008 DRAFT Page 8 of 58

9 iv. Accept the sequence # ( ) v. Click to add the filter. There are now four filters in the list: Part 2, Step 5: Define how to sort the data 15. Click the tab of the report. Three sorts will be added: a sort on the school code and sorts on the students last and first names. a. Add a sort on the School Code: i. Select School Code from the drop down. ii. Accept Ascending as the direction. iii. Click to add the sort. b. Add the Last Name column to the sort: i. Select Last Name from the drop down. ii. Accept Ascending as the direction. iii. Click to add the sort. c. Add the First Name column i. Select First Name from the drop down. ii. Accept Ascending as the direction. iii. Click to add the sort. Part 2, Step 6: Define report totals and any additional report sections 16. Click the tab of the report. A single total line will be added to the report and a Section by School will be defined. a. Add a Count of Students listed in Report Total. i. Enter Count of Students in Description field ii. Select Count of Rows as the Aggregate iii. Ignore the Column drop down July 8, 2008 DRAFT Page 9 of 58

10 iv. Click to add the Total b. Add a School Section to the report. i. Enter School as the Section name ii. Accept Section starts on a new page iii. Click to add the section. The section must now be fully defined: Page break trigger, Header and Totals. c. Add a Page Break for the header on School Code i. Select School Code from the Column drop down. ii. Click to add the column to the page break trigger. d. Add School Code to the Section Header i. Select School Year ii. Click to add the column to the section header iii. Select School Code iv. Click to add the column to the section header e. Add a Count of Students in the School to the Section Totals i. Enter ii. Select Count of Rows as the Aggregate iii. Ignore the Columns drop down iv. Click to add the total to the section. The section is now fully defined. 17. Click at the top of the screen to test the report. This brings up the usual Genesis schedule report screen: July 8, 2008 DRAFT Page 10 of 58

11 a. Select a school from the Select School drop down b. Click to run. 18. Sample output: 19. Notice that the columns in the report are all of equal width. This can be controlled by the Width % fields on the Columns screen: a. Click on the tab to go set the relative columns widths. b. First, uncheck the Visible checkbox for the School Year to make it invisible: c. Set the widths and adjust the Display As as follows: Column Width % Display As School Code 5 School Student ID 5 ID First Name 10 First Name Last Name 10 Last Name Homeroom 4 HR Grade Level 3 GR July 8, 2008 DRAFT Page 11 of 58

12 Date of Birth 5 DoB Spec Ed 3 Sp Age 2 Age Family Code 5 Family Mailing Line 1 14 Address City 8 City d. Click to store the changes 20. Re-run the report with the adjusted relative column widths. Figure 1 The relative column widths and abbreviated column headers make the report appear more professional Figure 2 Section and Report Totals appear at bottom July 8, 2008 DRAFT Page 12 of 58

13 Getting Started with Report Creation Reports can be created on any Genesis tab. If a user s permissions allow, at the bottom of every screen there are Add a custom report fields: Custom reports can be identified in any list of reports by the presence of a the report: icon with The Report Writer Module Even though custom reports can be created on any tab, there is a new Report Writer module to serve as the central administrative point for custom reports. This module is currently only available to Sysadmins. Custom Report # s When you create a custom report you choose the last four digits of the report #. These four digits are pre-pended with 99, so that all custom report numbers are of the form 99xxxx. Procedure to Create a New Report 1. Navigate to a reports screen(e.g. Report Writer List Reports) 2. Locate the Add Report fields at the bottom of the screen: 3. Enter a Sequence Number ( Seq ) for the new report. This number is the report number and must be unique on your screen. 4. Enter the name of the report. 5. Click Add to begin the report creation process. This will add the report to the list of reports and bring up the Report Writer Reports Modify Tables screen: See below to continue developing a custom report. July 8, 2008 DRAFT Page 13 of 58

14 Selecting the Start or Base Table for a Report Figure 3 The Report Writer Reports Modify Table Screen Procedure to Begin Designing a Report & Choose the Base Table of a Report 1. Navigate to the Report Writer Reports List Reports Screen 2. Locate the Add Report fields at the bottom of the screen: 3. Enter a Sequence Number ( Seq ) for the new report. This number is the report number and must be unique on your screen. 4. Enter the name of the report. 5. Click Add to begin the report creation process. This will add the report to the list of reports and bring up the Report Writer Reports Modify Tables screen: 6. Select the group which contains the table you wish to use: 7. Select the table you want and click the corresponding pick this table button:. This selects that table and brings up the screen of the report. The list of report columns is pre-populated with the primary key fields of the selected table: 8. Now proceed to the Add Columns to a Report section of this document. Procedure to Redesign a Report & Selecting a new Base Table 1. Navigate to the Report Writer Reports List Reports Screen 2. Locate the Report you wish to redesign and click the edit button. This brings up the Report Writer Reports Report Info screen for the report. 3. Click on the Table tab for the Report. This brings up the Report Writer Modify Table screen. July 8, 2008 DRAFT Page 14 of 58

15 4. Select the group which contains the table you wish to use: 5. Select the table and click the corresponding button. E.g. If you click OK, the old table design is deleted and the newly selected table is now the base table of the report. 6. Once a new table is selected the screen of the report is re-displayed, now populated with the primary key fields of the newly selected table: 7. Proceed to the Add Columns to a Report section of this guide. Viewing the Structure of a Table To view the fields of the table, their type and size (width), click on the View first 200 rows of the table you wish to see. At the top of the screen, there is a small control that allows you to bring up the table schema: Click the control to bring up the table schema. E.g.: When you are done viewing the table schema, click the control on the line to return to the regular screen and view the first 200 rows of data in the table. The table schema, shown in the example to the left, lists all the fields in the table, their data type (e.g. String, Boolean, Integer, Timestamp), width and whether or not they can take a null value. A Timestamp is a date/time value (not just a time value). A Boolean takes a Y or a N value. Figure 4 Example Table Schema (part of the Student table) July 8, 2008 DRAFT Page 15 of 58

16 Defining Report Columns & the Report Query Columns serve two purposes in a report: 1. Add data to the report printout 2. Act as a link to attach one or more additional database tables to the report. Consequently columns can be either visible or invisible. Invisible columns, described in the next section below, are added to the report only to serve as links. Figure 5 The Report Writer Reports Modify Columns Screen Visible Columns Most of the fields in each column definition row on the screen specify information needed to print the column on the report. The Visibility column determines whether the column is to be printed or serve only as part of the report s database query. Code Code for this column. Not editable once created. Display As The Column header for this column Font (font, size and style) Three fields selecting the font, the font size and the style (regular, bold, italic, italic & bold). Type (of data) E.g. String, Date, Numeric (not editable) Align Left, right or center ML Maximum length of the field in characters. Extra characters are truncated. A Text field. Width % text field specifies the relative width of the column in the PDF version. Visible Is the column visible on the report or is it only part of the report query. Seq # Sequence number for the column column s sort order Invisible Columns Invisible columns, described more fully below, are added to a report only to server as links to add additional data to the report. They do NOT change the appearance of the printed report. July 8, 2008 DRAFT Page 16 of 58

17 Procedure to Add a Column from the Base Table to a Report 1. Navigate to the screen of a report 2. Locate the new column controls at the bottom of the screen. You will find three choices: The choice on the top left pulls a column from the base table. E.g. The choice on the bottom left pulls a column from another table: This choice requires you to specify from which table the data is to be taken and how that table will be linked in. That is: how will the new table be queried? This choice will be considered below. The choice on the right fills a column with the contents of a parameter: :. This choice allows you to select any built-in or user-defined macro and fill a column with it. 3. Select a column from the base table: Select the field from the list of all the fields in the base table: 4. Specify the sequence number that controls the position of the new column in the list of columns (and thus the order of the columns in the report). 5. Click the button. This adds the column to the report. 6. Control the Column s Appearance: Will the new column be visible? If Yes, you can control the appearance of the column in the output report: Specify the column header for the new column: This is required! Select the column s font from the list of available fonts: Helvetica is usually the default font. Select the font size for this column Select the font style (normal, bold, italic, italic & bold) Specify the alignment for the data in the column (Choose from Left, right or center) If necessary, specify the maximum length (ML) in characters additional characters will be truncated (field can be left blank): If desired, specify the Width % (field can be left blank): Finally, specify the sequence number for this column. The sequence number will always default to the next column to the right. You control the position of the column in the report by positioning the column numerically in the existing list. The columns appear left to right on the paper corresponding to top down in the list. Leave the Visibility checkbox checked. This keeps the column visible and printed on the report. Click button to save the changes to the new column. July 8, 2008 DRAFT Page 17 of 58

18 Adding in Columns from Other Tables - Linking Procedure to Add a Column from Other Tables to a Report 1. Navigate to the screen of a report 2. Locate the new column controls at the bottom of the screen. You will find two choices: The choice on the left pulls a column from the base table. E.g. The choice on the right pulls a column from another table: This choice requires you to specify from which table the data is to be taken and how that table will be linked in. That is: how will the new table be queried? This choice will be considered below. 3. Select a column from the other tables. The first step is to define the column header for the new column: The Display As field is the column header. 4. Specify a code for the new column. This will be automatically generated for you if you enter nothing in the text field. 5. Specify the sequence number that controls the position of the new column in the list of columns (and thus the order of the columns in the report). 6. Click the button. This adds the column to the report. But it is only the BEGINNING of the process of placing data into the new column. As soon as you click the Add button, you are taken to the screen where you must specify where and how to get the data for the new column: 7. Select the table from which to get the data for the column. Select the table group first. This narrows the list of tables to only those which apply to the selected category. Select the table from which to get the new column s data: Once you select the table (e.g. Address) the screen expands: July 8, 2008 DRAFT Page 18 of 58

19 You now must select the field from the new table to display in your new column: Once you select the field (e.g. addresscity) the screen expands again to have you choose whether to display the data from the field ( Field Value ) or to display a count of how many records contain that field: Choose how to display data for the new column. Click. This expands the screen again to have you specify how to link the new table (e.g. Address) to the existing columns in the report. 8. Specifying the Linkage for the new table. The new table must be linked to the existing report. The linkage is specified by the section in the middle of this Lookup screen. The list in this area of the screen contains a set of links which compare a field in the newly selected table with a field in the existing list of report columns. E.g. In this example, the schoolyear field in the new table ( Addresses ) is linked to the schoolyear field in the report (which, in this example, is from the Student table). Similarly, the July 8, 2008 DRAFT Page 19 of 58

20 studentid field in the new table ( Address ) is linked to the studentid field in the report (ultimately the studentid field is from the Student table). You may specify as many additional links or Filters as necessary: a) Select a field in the new table. E.g. b) Select a comparison operator. E.g. = for equals. c) Select the comparison value: One of the following: a. An existing report column b. One of the built-in macros (e.g. ${SCHOOL_CODE}) c. A report parameter macro (e.g. ${SCHOOLCHOICE}) d. A literal (e.g. LR ) e. Click to add the filter to the list. 9. Control the new Column s Appearance: This can be done at any time on the Columns tab: Specify the column header for the new column: This is required! Select the column s font from the list of available fonts: Helvetica is usually the default font. Select the font size for this column Select the font style (normal, bold, italic, italic & bold) Specify the alignment for the data in the column If necessary, specify the maximum length (ML) in characters additional characters will be truncated (field can be left blank): If desired, specify the Width % (field can be left blank): Finally, specify the sequence number for this column. The sequence number will always default to the next column to the right. You control the position of the column in the report by positioning the column numerically in the existing list. The columns appear left to right on the paper corresponding to top down in the list. Leave the Visibility checkbox checked. This keeps the column visible and printed on the report. Click button to save the changes to the new column. July 8, 2008 DRAFT Page 20 of 58

21 Building Report Queries Report queries are built as a compilation of several screens: The tab This is akin to the Top Data Element selected in Student Data Letters and Exports. It is the base of the report query. The tab This not only lists the fields in the base table but also lists linked columns which are where additional database tables are linked to the base table (or to other existing report columns). o Linked columns are identified by the icon adjacent to the icon. The linkage for the column is only visible on the screen which is displayed when the icon is clicked. The tab this screen is equivalent to the Links panel on the Student Data Letters Modify Query screen and the Exports Modify Query screen. It defines how to link a new table to existing columns in the report. The tab, which also uses report parameters defined on the tab. The tab contains filter information similar to the Filters on the Student Data Letters Modify Query screen and the Exports Modify Query screen. Unlike the Student Data Letters and the Exports facilities, there is no way to visualize the entire query. Linking Tables to a Query Tables are linked to an existing query by adding a new Column to the report. Genesis Data Export queries (in the Exports module) start the process of adding something to a query by selecting the table from which to get the data. In the Report Writer, the process of adding a new table is started by adding a Column to the Report. Procedure to Link a Database Table to a Report Query This procedure assumes that you have already begun creating the Report and have selected your base table. The procedure has three steps: - Name the new column you wish to add to the report - Specify which table to pull the data for the new column from and how to display that data. - Specify how to link the new table into the report. 1. On the screen of the report, locate the control at the bottom of the screen. 2. Define the name or column header for the new column: The Display As field is the column header. The Code field will be automatically generated for you if you enter nothing in the text field, as will the sequence # field. 3. Click the button. This brings up the screen it is here where you specify which table you want to link in (and from which you want to retrieve data for the new column). The steps you go through, on the screen, to link in the new table are: Part 1 Specify which table you want to link to: Choose the table group and the table. Then choose the field you wish to pull from the newly linked table. Part 2 Specify whether you want to display the field s value or count how many records you extract. Once you have chosen, click to move to part 3 Part 3 Specify how to link the new table to the existing tables. This is explained in Step 4 below. 4. Specify the Linkage for the new table. July 8, 2008 DRAFT Page 21 of 58

22 The linkage is specified in the section in the middle of the screen. The list in this area of the screen contains a set of links which compare a field in the newly selected table with a field in the existing list of report columns. You must determine what these links should be: Genesis generates the most obvious links but you must ensure that these are both correct and sufficient to do what you want to do. This procedure is explained fully above in the Procedure to Add a Column from Other Tables to a Report starting at the top of Page 18. Please review that procedure for complete instructions on how to create the linkage. Multiple Columns from One Linked Table Reports will run more quickly when multiple linked Columns can be extracted from one linked table. However, there is no direct, explicit way to say Include multiple columns from this table : So how can it be done? If you extract additional columns from a table that is already linked to the report and you express the links in exactly the same order, the Report Writer will recognize that you are extracting two (or more) pieces of data from the same table and it will only do one query instead of individual queries for each column. July 8, 2008 DRAFT Page 22 of 58

23 How Report Querying Works To produce a report, data is extracted from the database by a series of separate queries. First, the single query for the Base table is done. This pulls all columns of data from that table. Then, separate, individual queries are done for each column that is linked from another table: Base Table Step 1: Query Database for the Base table and all columns from that one table Linked Linked Column Linked Column Linked Column Linked Column Column Step Step 2: A separate database Step 2: A separate database Step 2: query A separate query is is done database Step 2: 2: A done for for each query A separate separate database each query linked is linked is Column. done database for each query linked is Column. done for each linked Column. done for each linked Column. Column. If two columns are extracted from the same linked table e.g. Mailing Line 1 and City from the Address table separate queries have to be done for each of those fields. That is a query is done to find the data for Mailing Line 1 and then a second query is done to find the data for City. This can take a considerable amount of time. Data extraction is done by column and not by table. However, there is a work-around that can radically speed up your reports: if you make the links for two columns exactly the same, the Report Writer recognizes that the columns come from the same linked columns and does only a single query to get both pieces of data. Base Table Step 1: Query Database for the Base table and all columns from that one table Linked Linked Column Linked Column Linked Column Linked Column Column Step Step 2: A separate database Step Step 2: 2: A separate database query A 2: separate Columns Step query is is done database that 2: have A separate done for for each query the database each query linked is exact linked is Column. done same for linkage each linked are Column. done for each linked Column. pulled by a single Column. query Now, if two columns are extracted from the same linked table e.g. Mailing Line 1 and City from the Address table and the links are exactly the same in the same order only a single query is done to get both pieces of data. This can represent a significant time savings when running reports. What does it mean to have the exact same links in the same order? On the screens for the linked columns, in Part 3 the list of links must be exactly the same (see below). This means that you must ensure that for each column extracted from the one table (e.g. the Address table), you build the list of links exactly the same way each time you add a column: Note that this query reduction will only work when you are extracting the field value of fields: it does not work when counting rows. July 8, 2008 DRAFT Page 23 of 58

24 Invisible Columns An invisible column is a column you have added to a report to serve as a link for additional pieces of data, but do not want the data it contains to show on the report printout itself. Visibility checkboxes On the screen, there is a visibility column containing a checkbox corresponding to each column of data. You add a column to the report to enable you to do either or both of two things: Display the data the column contains on the report printout As a link to additional data contained in other database tables A typical example: You wish to look up various types of data based on the student s studentid number but you do not wish to print the student s studentid on the report itself. To do this you must: 1. Add the studentid column to the table 2. Flag the studentid column as not being visible (uncheck the Visibility checkbox for the studentid column). How many invisible columns can a report have? You may add as many invisible columns as you need to serve as links for additional data. Can I make an invisible column visible? You make an invisible column visible by simply checking the Visibility checkbox for it and then clicking the button. Similarly, you can make a visible column invisible by simply unchecking the Visibility checkbox for it and saving the change. How are invisible columns used? Invisible columns continue to appear on all Columns drop downs and can be used on the screen, the Report Parameters screen and in report section page breaks, headers and totals as well as in the report totals. How do I use an Invisible Column as link to additional data? Every column in the list of columns on the tab appears in every list of columns. Thus, on the screen, the invisible columns are present to serve as link to points: Figure 6 In Part 3 on the Defined Linked Column screen, the list of Report Columns will contains every column listed on the Columns screen, visible and invisible ones alike. Using Invisible Column in Report Section Headers and Totals Invisible Columns can also be added to Report Section Headers and Totals area via the controls on the screen: July 8, 2008 DRAFT Page 24 of 58

25 See Report Sections, Totals and Page Breaks Reports with No Detail Lines What happens when no column is visible? To completely suppress the detail lines in a report the ordinary columns and compose a report solely of section totals, mark all columns as not visible. What happens when no column is visible is that the detail lines of the report are completely suppressed. Maximum Length Columns A maximum length column is a visible column for which you have set a maximum number of characters. This is used when you must produce a report or a spreadsheet with columns of limited width. Maximum length (ML) text fields On the screen, there is an ML column containing a text field for each column of data. It is normally blank meaning that the field has no maximum length. If you put a number (e.g. 30) in the text field, the column is limited to that number of characters. The ML column does not appear if the column is not visible. Why would you limit the length of a column? This is most useful in preparing Excel spreadsheets or CSV files for use as input to other applications which require a maximum number of characters in certain fields. What happens if the data in the column is longer than the maximum length? For example, suppose the maximum length of a Street Address column is 30 characters and the actual data is longer? The extra characters are truncated: only the maximum number of characters permissible are displayed in the column. The other characters do not appear in the output. What is the difference between a Maximum Length Column and a Fixed Length Column? A fixed length column is a column which always has the exact same number of characters. For example, a fixed length column of 25 characters would always be exactly 25 characters wide. If the data were shorter than 25 characters the extra characters would be all blanks the field would be blank filled. A maximum length column is not blank filled. It simply cannot be longer than the specified maximum length. July 8, 2008 DRAFT Page 25 of 58

26 Blank and Parameter-filled Columns Adding Blank Columns to the Report A blank column is one where you choose the column header and the remainder of the column is blank. You can add as many blank columns as you wish to a report. Procedure to Add a Blank Column to a Report This begins just like a regular add a column from another table but a new table is never linked in: 1. Navigate to the screen of a report. 2. Locate the new column controls at the bottom of the screen. You will find two choices: The choice on the left pulls a column from the base table. E.g. The choice on the right pulls a column from another table: This choice requires you to specify from which table the data is to be taken and how that table will be linked in. That is: how will the new table be queried? This choice will be considered below. 3. Select a column from the other tables. The first step is to define the column header for the new column: The Display As field is the column header. 4. Specify a code for the new column. This will be automatically generated for you if you enter nothing in the text field. 5. Specify the sequence number that controls the position of the new column in the list of columns (and thus the order of the columns in the report). 6. Click the button. This adds the column to the report. This brings up the usual screen. 7. Locate the label and click it. This creates the Blank column. The blank column is added and the screen is re-displayed, now containing the new column. The Type field will be empty. Empty Type column Adding Parameter-filled Columns to the Report A parameter-filled column is one every cell in a column is filled with the same parameter s value. Procedure to Add a Parameter-filled Column to a Report 1. Navigate to the screen of a report. 2. Locate the new column controls at the bottom of the screen. The choice on the right fills a column from any parameter: 3. Select a parameter from the list of parameters in the drop down: The list of parameters contains all the built-in macros (see below) and any parameters that you have defined on the Parameters screen: July 8, 2008 DRAFT Page 26 of 58

27 4. Click the button. This adds the parameter-filled column to the report. The Type field contains. The name of the parameter is filled in as the Display As column header and can be adjusted by you: July 8, 2008 DRAFT Page 27 of 58

28 Built-In Macros There are a set of built in macros that can be used when defining Columns and when specifying Filters for a report. The set of built in macros includes those listed in the table below. Macro Definition SCHOOL_YEAR The current school year: PREVIOUS_SCHOOL_YEAR Last school year: NEXT_SCHOOL_YEAR Next school year: SCHOOL_CODE School code selected school in screen header SCHOOL_NAME Name of the school. SCHOOL_START_DATE School start date for the selected school. E.g. SCHOOL_END_DATE DISTRICT_CODE DISTRICT_NAME LOGONID 9/6/2007 School end date for the selected school. E.g. June17, 2008 Code for the district. District name ( Genesis School District ) Users s login id REPORT_CODE Code for the report itself (e.g Figure 7 Appearance of the macro list on the screen In front of each macro in the list there is a icon. Click the icon to add the corresponding macro to the parameter or filter definition (depending on which screen you are on). You do not have to copy and paste the copy macro button does this for you. User Defined Macros: Parameters Parameters, described in the section below, as used the same way the built in macros are used: the difference is that they are user defined macros and you can add as many of them as you need to a report. July 8, 2008 DRAFT Page 28 of 58

29 Parameters Parameters are the data collected from questions on the Schedule Report screens. They are also user defined macros. Figure 8 Example of a Schedule Report screen with a question that populates a parameter. In Figure 7 above, the question Select Student List populates a parameter with the user s choice after the user has selected a Student List and clicked the button. The red asterisk (*) indicates that the field is required: the user must make a choice; the field cannot be left blank. How are Parameter questions added to a Report? Tab #3 in the Report definition is the tab: This screen is where you specify the parameter questions that will be asked on the Schedule Report screen. Adding Parameters to a Report At the bottom of the Report Writer Reports Modify Parameters screen are the fields used to add Parameters to the Report: There are several steps to defining a Parameter: 1. Define the question that will appear on the Schedule Report screen. E.g. Select Student List:. This is the Question to ask the user field. 2. Specify how the user will answer. This is the How would you like the user to answer the question? field. See below. 3. Provide a name for the macro which will hold the user s answer. This is the Macro Name field. 4. Indicate whether the user is required to answer the question. This is the Required checkbox. If you check it the user will not be able to run the report without answering the parameter question. July 8, 2008 DRAFT Page 29 of 58

30 5. Enter a sequence number (Seq) for this parameter question. Parameters are placed both in the list of this screen and on the Schedule Run screen in sequence number order. That is, they are sorted by their sequence numbers. 6. Click the button to add the new parameter/question to the list. Parameter Answers How Users Answer Parameter Questions Figure 9 Partial List of Available Parameter Choices There are six kinds of answer that you can set up for a Parameter: Text field: user types in the answer. Date: User selects a date from a calendar (or types it in). A user defined list the user selects from a drop down list of choices defined by you. Student Lists: User selects from a drop down list of their own student lists. A list of items in a database table The set of List options include many different things stored in Genesis. The user is presented with a drop down list containing the selected items. A list of the report s own columns One of the List options is Report Columns. The user is presented with a drop down containing the list of the report s own columns. Parameter Answers The Four Quick Picks There are four parameter answer types at the top of the drop down list that are assumed to be popular choices. The 4 Quick Picks at the top of the list of choices include: 1. Selecting a date Date selector appears 2. Filling in a text field (you may default the text in the field) 3. Selecting from a user defined set of choices 4. Selecting from a List of the user s Student Lists the user in this case meaning the individual who is running the report. Parameter Answers The Full Set of Items Available from the Database Below the four Quick Picks at the top there is a long list of items that can be pulled from the database so that the user can select from the list. These are described in the table below. There are five columns in the table below and they have the following meanings: - List of What will be placed in the drop down list the user will select from at report run time. - Coverage These items are unique to the district or school or current school year or the user. In some cases (E.g. months ) the Coverage column is meaningless. o District The set of items applies to the entire district o o School The set of items applies only to the user s school. Current School Year The set of items is unique only to the current school year other school years may be different. July 8, 2008 DRAFT Page 30 of 58

31 o The user The set of items is unique to the user (e.g. Student Lists) - Options Where filled in this gives examples of the options that are provided by this selection. - Codes Table The list of items is pulled from a codes table. Codes tables are listed on the Setup Codes screen. If this column is yes then the name of the codes table appears in the Table Name column. - Table Name Name of the Codes table containing the items for this selection. List of Coverage Gives choice of: Codes Table Name or Setup Screen table? Attendance Codes District All attendance codes Attendance Codes Adjusted Credit Loss School Reasons for loss of credit Yes ADJUSTED_CREDIT_REASONS Reasons Comment Codes School Grading Comment Codes Grading Setup Comments Counselors School Counselors in the school District Master District Parameters Teachers Course Sections School Available in the school Scheduling Sections Course Sections User Taught by user Scheduling Sections Course Type Singleton, Doubleton, Tripleton Curriculum Course Current All courses active in the Scheduling Curriculum Year current year Departments School District Master District Parameters Departments Discipline Action Codes District Conduct Setup Action Codes Exams School Grade collections flagged Grading Setup Collections as Exam GPA School Names of GPAs for the Grading GPA/Rank Setup school Grade Collections School All Grading Setup Collections Grade Collections School All but the interims Grading Setup Collections Grade Levels District All district grade levels. District Master District Parameters Valid Grades Grade Levels School Grade levels in school Schools School Parameters Valid Grades Homerooms School HRs in School Schools School Parameters Rooms Honor Roll definitions District List of honor rolls Grading Honor Rolls Immigration Status District Yes IMMIGRATION_STATUS Immunizations District List of all immunizations Yes VACCINE_CODES Marking Periods School Attendance Cycles Schools School Parameters Attendance Cycles Marking Periods & School Attendance Cycles Schools School Parameters Attendance Cycles Interims Medical Condition District All health conditions Yes MEDICAL_CONDITION_CODES Codes Months of the Year Jan, Feb, Mar, Apr, Schools School Parameters Attendance Cycles Nurses School List of nurses in school District Master District Parameters Teachers PCC Entry Codes NJ NJ PCC Entry codes Yes PCC_ENTRY_CDOES PCC Withdrawal Codes NJ NJ PCC Withdrawal codes Yes PCC_WITHDRAWAL_CODES Print Periods School Periods of the school day Scheduling Setup Print Periods Program Type Codes District/NJ NJ Program Type codes July 8, 2008 DRAFT Page 31 of 58

32 Related Services Spec Ed Residence Type Yes RESIDENCY_CODES Report Columns This report The report s own columns Schools District Current Year list Schools Schools Schools District Next Year list Schools Schools School Attendance Cycles School Attendance Cycle table entries School Case Managers School List of Case managers District Master District Parameters Teachers School Disciplinarians School List of disciplinarians District Master District Parameters Teachers School Year Last, current, next Schools School Parameters Attendance Cycles Semesters Genesis Built in set Schools School Parameters Attendance Cycles Service Providers District Yes SPEC_ED_SERVICE_PROVIDERS Sports School Sports in School No Located on Athletics Sports Streets District From the STREET_MAP No table Student Lists User The user s student lists Located on District Master District Parameters Street Map Maint. Teachers School All teachers assigned to District Master District Parameters Teachers the school Teachers Current User All teachers linked to the current user User Flag Descriptions District User flags defined for the District Master District Parameters User Flags district User Flag Descriptions School User flags used by the school User Text Descriptions District User text defined for the District Master District Parameters User Text district User Text Descriptions School User text fields used by the school Vice Principals School VPs assigned to the School School Parameters Teachers School Vice Principals District VPs in the District District Master District Parameters Teachers Security Users Modify User School School Parameters User Flags School School Parameters User Text Example: Add a Select a Date Parameter to a Report At the bottom of the Report Writer Reports Modify Parameters screen are the fields used to add Parameters to the Report: 1. Define the question that will appear on the Schedule Report screen. E.g. Select Start Date:. This is the Question to ask the user field. 2. Specify that the user will select a date. Click on the How would you like the user to answer the question? field a select the Select a Date option at the top of the list. This will cause a new Default to current date question to appear. Check yes to choose the current date automatically. 3. Provide a name for the macro which will hold the user s answer. E.g. type STARTDATE in the Macro Name field. 4. Indicate whether the user is required to answer the question. This is the Required checkbox. If you check it the user will not be able to run the report without answering the parameter question. July 8, 2008 DRAFT Page 32 of 58

33 5. Enter a sequence number (Seq) for this parameter question. Parameters are placed both in the list of this screen and on the Schedule Run screen in sequence number order. Select a number (e.g. 20 ): 6. Optionally specify a Default Value. The date can be defaulted to a specific date, or the following choices: To default to a specific date, use the mm/dd/yyyy format and enter the date in the Default Value field (e.g. 04/25/2008). 7. Click the button to add the new parameter/question to the list. Running a Report with Parameters When the report is run, all non hidden parameters will appear on the Schedule Report screen so that the user running the report can make their selections. In this example, three parameters have been defined for the report, a student list selector, a start date and an end date: When the report with the three parameters defined above is run, all three parameter questions appear: Figure 10 Sample Schedule Report screen for a report with 3 parameters defined. Note that the Student List parameter is required and is identified by a red asterisk (*). Both date fields default to today (whatever today is). More on Date Parameters You can default a date parameter to today (the Current date ), the first day of school for the year, ${SCHOOL_START_DATE}, the last day of school for the year, ${SCHOOL_END_DATE}, or a specific date. When you choose the Select a Date option you are shown the following choices: July 8, 2008 DRAFT Page 33 of 58

34 To select a date other than today, ${SCHOOL_START_DATE} or ${SCHOOL_END_DATE}, select the Nothing option and place the default date you want into the Default Value field: The specified date will appear with the parameter as the default: Parameters with User Defined Lists When one of the built in lists does not cover the necessary choices, you, the report designer, can create a parameter which offers your own choices. This is called a user defined list. In this example, three parameters have been defined for the report, a student list selector, a start Procedure to Create a user defined list Parameter In this example, the user (the individual running the report) will be asked to choose from a list of colors: 1. Define the question that will appear on the Schedule Report screen. E.g. Choose a color. This is the Question to ask the user field. 2. Specify that the user will select from a user defined list. Click on the How would you like the user to answer the question? field a select the Selecting from a drop down list that I create option at the top of the list. This will cause a new List Values control to appear. This is where you enter your set of possible user choices. 3. In the List Values field, enter a list of choices separated by semi colons: 4. Provide a name for the macro which will hold the user s answer. E.g. type COLOR in the Macro Name field. 5. Indicate whether the user is required to answer the question. This is the Required checkbox. 6. Enter a sequence number (Seq) for this parameter question. Select a number (e.g. 40 ). 7. Enter a default value, if you wish. Your default must exactly match one of the choices entered in the List Values field. 8. Specify whether the parameter will be hidden or not. 9. Review the parameter specification: July 8, 2008 DRAFT Page 34 of 58

35 10. Click the button to add the new parameter/question to the list. This adds the new parameter, with the user defined set of choices, and the default choice (if you defined one) to the list of parameters: When the report is run, the parameter is presented to the user along with the set of choices and with the pre chosen default: Using the Report s Own Columns in a Parameter The List: Report Columns option in the Parameter Answers drop down selector means you can use your report s own set of columns as choices for a parameter. This can, for example, be used to allow the user to choose which column to sort on at run time. See Sorting below. A Parameter that Exposes the Report s Columns You can allow the user to select from a list of the report s own columns. To do this you create a parameter whose answer type is Report Columns : This is especially useful if you wish to allow the user to select the column on which to sort the report. Create a Parameter to allow the user to choose a Report Column 1. Specify the question to ask the user in the Question to ask the user field (e.g. Sort by? ). 2. From the How would you like the user to answer the question? drop down, select the Report Columns option. 3. Provide a name for the macro which will hold the user s answer. E.g. type SORT_BY in the Macro Name field. July 8, 2008 DRAFT Page 35 of 58

36 4. Provide a Default Value. If no default value is provided, no sort column will be automatically selected. 5. Indicate whether the user is required to answer the question. This is the Required checkbox. 6. Enter a sequence number (Seq) for this parameter. 7. Click the button to add the new parameter/question to the list. Hidden Parameters Hidden Parameters give you, the report designer, the ability to define a parameter that is not shown to the user but maybe given a default value which is changed by the designer (that is, you) from time to time to adjust the behavior of the report. To make a parameter hidden, when creating the parameter check the Hidden checkbox ( ) that appears with the Parameter definition controls at the bottom of the Parameters tab. If you do this the parameter will not be displayed on the Schedule Report screen but can be used internally as a report macro. See the section on Filters below. July 8, 2008 DRAFT Page 36 of 58

37 Filters Filters allow you to further refine which records that are pulled from the database will be included in the report. Figure 11 Filters screen with the automatic filters generated for the report Filtering a Report by Report Parameters The primary use of report parameters, discussed above, is to filter the report so that only records which match the parameters are selected. Example: Filter a Report by a Selected Student List Parameter 1. Navigate to the Report Writer Modify Parameters tab for a report and create a Student List parameter for the report. 2. Navigate to the Report Writer Modify Filters tab for the same report so that you can create the filter based on the Student List parameter. 3. Locate the list of existing filters and the add filter control: 4. Select the column on which to filter. Since this is to be a filter based on a student list, select the Student ID column. 5. Select the Operand for the comparison. The default choice is an = sign. Because this is to locate all students on a list, choose the Student ID is in the list option: July 8, 2008 DRAFT Page 37 of 58

38 6. Choose the value to compare with. Since the value is the list the user will choose at run time, you must compare against the parameter which contain the user s choice. a. The list of parameters you have already set up appears at the bottom of this screen. Locate it: b. Click the icon corresponding to the parameter you choose. In this case, it is Student List parameter. Clicking the icon copies the parameter into the comparison field: 7. The Seq field contains the default sequence number. You may adjust this if need be. 8. Click the button to add the Student List filter to the list: Built In Report Filters Genesis automatically builds do the right thing filters if it can. For example, if the base table of the report is the Student table, Genesis automatically adds filters for: The current School Year only students with records for the current school year are selected. The current School Code only students with records for the school selected in the School drop down in the screen header when the user runs the report are selected. Any of the automatically created filters can be removed if you do not wish to have them. Procedure to Remove a Filter from a Report 1. Navigate to the report s Report Writer Modify Filters tab. 2. Locate the list of existing filters and identify the filter you wish to remove. July 8, 2008 DRAFT Page 38 of 58

39 1. Click the corresponding icon button. This removes the filter from the report. Procedure to add a Filter to a Report If you will be using report parameters as filters, be sure to navigate to the Report Writer Modify Parameters tab for a report and create the parameters you will need before you try to create the filters. 1. Navigate to the Report Writer Modify Filters tab for the report. 2. Locate the list of existing filters and the add filter control: 3. Select the column on which to filter. All the filters in the report are in this list, including the invisible columns: 4. Select the Operand for the comparison. The default choice is an = sign. Choose the operand you wish to use: 5. Choose or specify the value to compare with. You may do any of the following: a. Specify the exact piece of text to compare with b. Specify a date value (if the column you selected represents a date). E.g. 4/21/2008 c. Enter the name of a macro from which to get the compare to value. All macros appear in two lists at the bottom screen: i. The upper list consists of all built in macros ii. The lower list consists of all parameters you have defined for this report via the Parameters tab: To select one of the macros in either list click the the built in macro or to the parameter you choose. icon corresponding to the either July 8, 2008 DRAFT Page 39 of 58

40 6. The Seq field contains the default sequence number. You may adjust this if need be. 7. Click the button to add the completed filter to the list of filters: 8. Repeat Steps 3 to 7 to add additional Filters to the report. Procedure to Change a Filter All four fields in a filter can be updated. 1. Navigate to the report s Report Writer Modify Filters tab. 2. Locate the list of existing filters and identify the filter to change. 2. Update the fields you wish to change all can be updated. 3. Click the button to save your changes. The Effect of Sequence Numbers The sequence numbers in the list of filters on the Report Writer Modify Filters tab control the order in which the filters are applied to the records, as well as the order in which they appear on this list. The order probably does not matter much. The Relational Operators The sequence numbers in the list of filters on the Report Writer Modify Filters tab = The column exactly matches the Value field (equal to)!= The column does not match the Value field (not equal to) < The column value is less than the Value field <= The column value is less than or equal to the Value field. > The column value is greater than the Value field >= The column value is greater than or equal to the Value field. IN The column value matches some part of the Value field. E.g. Jan IN Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec CONTAINS The Value field is fully contained in the column value. E.g CONTAINS 200. Empty The column is empty. Contains nothing. Not Empty The column is not empty. Contains something. The Student ID is in this list The student ID is on the selected Student List. One row per value If there are multiple rows with the same value, e.g. Family Code, only one row will be output. This is designed to help you in getting one row per family for any report or MS Excel output. July 8, 2008 DRAFT Page 40 of 58

41 The Relational Operators: Working with Numbers and Dates The numeric comparison operators work with both numbers and with dates. The =,!=, <, <=, >, >= operators work equally well with numbers and date values. Dates can be expressed in mm/dd/yyyy format (e.g. 04/21/2008). Any text field can contain a literal date (e.g. mm/dd/yyyy). Text Operators: Working with Text Strings/Literals If a value is not a number and it is not a date, then it is a text string or literal. Six operators work with these strings or literals : = The equals operator requires that strings exactly match each other: same letters, same case. E.g. YES does not match Yes.!= The not equals operator matches everything the equals operator does not: anything that does not exactly and completely match. YES!= yes. IN The string in the column must exactly match some part of the Value field. Examples: o Jan in Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec o 2002 in 2002,2003,2004,2005,2006 o MHS in MHS,MMS,BES,TES,JSES CONTAINS The string in the column completely contains the string in the Value field. Examples: o contains 200 o TES contains ES Empty The string in the column is empty there is no value there. The value is null. Not Empty The string in the column is not empty; it contains something, anything. The value is not null. One Row per Value If a value is repeated in several students records and you only wish to get a single row with the value Family Code is the usual example the One Row per Value operator will do this for you. The operator works as follows: Rows where the specified column is null are removed (Null values do not count as a value so if a student does not have a family code; student will not appear). This has the same semantics of the UNIQUE operator in SQL. (Select unique value from table_name) The first row that has an occurrence of the value is kept; all further occurrences are discarded. This is important. You will want to sort your data with the row that you want to keep on top. It might be the youngest student; the oldest student; lowest grade. etc... The filtering out of the unique values happens LAST in the processing of data. So you can unique filter out on any column. It occurs after sorting as well. July 8, 2008 DRAFT Page 41 of 58

42 Sorting The Report Writer Reports Modify Sorting ( ) tab contains the set of Sorts for the report. Reports can have multiple, different sorts. If more than a single sort is defined, the user chooses which sort they want at the time they run the report. When any sort is defined a Sort: parameter is automatically added to the report. The Sort Option drop down contains the list of possible sorts for the report: Figure 12 The Sorting Screen before any sort is defined There is a built in default sort option the first sort order you define becomes the default sort. This is the order in which the report will be sorted if the user makes no other choice (a choice is possible only if you create additional sorts). The default sort initially contains no columns: that means that initially the records will not be sorted: they will appear in the report in the order in which they happen to pulled from the database: that is, random order. Each sort specifies the list of report columns to be used to sort the records. Figure 13 Sort Screen before any Columns are selected for the Default Sort Any or all columns including invisible columns can be used to sort the report. The tab contains controls to add columns to and remove columns from the sort, as well as to change the order in which the columns are sorted: Figure 14 Sort screen after a single sort by schoolcode has been added to the report Note that the Sort Option field is expanded with each selection to reflect the columns used for this sort July 8, 2008 DRAFT Page 42 of 58

43 Procedure to Specify the Default Sort for the Report 1. Navigate to the tab of a report. For the moment, ignore the button. 2. Select the primary column by which to sort the report from the drop down list. 3. Select the direction of the sort: Ascending or Descending 4. Click the button to add the new column to the sort: Note that as you add columns to the sort, the contents of the Sort Option drop down are expanded to list all columns used by the sort: 5. Repeat steps 2 to 4 to add additional columns to the sort. The number of columns you can add to the sort is limited only by the columns in the Report: you cannot sort on data that does not appear in a column. As you Procedure to Change the Order in which Columns are Sorted 1. Navigate to the tab of a report. 2. Select the sort you wish to work with. Note that the order the columns will be sorted in is represented by their position in the list of sorted columns: 3. Locate a column whose position in the sort you wish to change: Click the button to lower a column s position in the sort. Click the button to raise a column s position in the sort. 4. Note that no save is necessary the and the buttons take effect immediately. 5. Step 2 until the order of the columns is as you wish it to be: The choice of sort position for your columns will be dependent on what you wish your report to show. The Sort Options drop down is updated when you alter the order in which columns are sorted: July 8, 2008 DRAFT Page 43 of 58

44 Procedure to Add a New Sort to the Report 1. Navigate to the tab of a report 2. Click the button to add a different sort to the report. The new sort will appear as a blank line in the Sort Option drop down:. The name of the sort will be filled in as you add columns to the new sort. If you click the drop down you will see all previously defined sorts. The new sort, a blank line, is at bottom: A Sort parameter will appear on the Report to allow the user to both view the sort order for the report and, if multiple sorts are defined for the Report, to choose which sort to use. 3. The remainder of the procedure is identical to adding columns to the default sort. Select the primary column by which to sort the report from the drop down list. 4. Select the direction of the sort: Ascending or Descending 5. Click the button to add the new column to the sort: Note that as you add columns to the sort, the contents of the Sort Option drop down are expanded to list all columns used by the sort: 6. Repeat steps 3 to 5 to add additional columns to the new sort. Limits on Sorts? The number of columns you can add to the sort is limited only by the columns in the Report: you cannot sort on data that does not appear in a column. If you want to sort on data which is not (yet) in a report column, go back to the tab and create a column that contains the data you wish to sort on. You will then be able to add that column to your sorts. Procedure to Remove a Column from a Sort 1. Navigate to the tab of a report and select the Sort Option you wish to adjust. 2. Locate the column you wish to remove from the sort: 3. Click the corresponding icon button. This removes the column from the sort. The Sort Option name for the sort will be immediately updated to remove the deleted column. Procedure to Change the Direction of Sort for a Column Unfortunately, there is no simple change sort direction update that can be done for a column: the column must be removed and re-added: 1. Navigate to the tab of a report July 8, 2008 DRAFT Page 44 of 58

45 2. Locate the column whose sort direction you wish to change (either from ASCENDING to DESCENDING or from DESCENDING to ASCENDING): 3. Click the corresponding icon button. This removes the column from the sort. 1. Now re-add the column to the sort with the opposite Sort direction: Re-select the column from the drop down list. Select the new direction for the sort: Ascending or Descending. Click the button to add the new column to the sort. 4. Re-position the column in the sort if necessary: Click the button to lower a column s position in the sort. Click the button to raise a column s position in the sort. Sort by a Column Chosen at Runtime Runtime means when a user runs the report. Through the use of a of parameter whose answer type is Report Columns, you may allow a user to choose the sort column at runtime. To do this you must first create a parameter that displays the report s columns to the user to choose from. 1. Navigate to the tab of the report. 2. Create a parameter whose answer type is Report Columns. See instructions above at the bottom of Page Navigate to the tab of the report. Select the sort you wish to modify or create a new sort. Select from the sorts already defined for the report via the Sort Options drop down: 4. Parameters that have Report Columns as their answer type will appear in the list of possible sort columns: Figure 15 List of columns to sort on note that you can sort on a column chosen at runtime by the user. Select the Column specified in parameter choice to add a variable sort to the report. 5. Select your sort direction (default=ascending). 6. Click to add the variable sort. Note the Sort by? appears as the Sort Option: July 8, 2008 DRAFT Page 45 of 58

46 Report Sections, Totals and Page Breaks The Report Writer Modify Sections and Totals screen contains the controls to add totals to the bottom of the report and to divide the report into separate sections, each of which has both a header and a totals section and can be placed on a separate page via an inserted page break. Figure 16 The Report Writer Modify Sections and Totals screen before adding any Totals or Section definitions Procedure to Add Totals to a Report 1. Navigate to the tab of a report 2. Locate Section 1: Entire Report and the Totals line beneath it: 3. To add a Totals line to the Report, locate the Totals controls for the report: Specify a Description for the total Specify whether the total is a count of the rows in the section or a sum of a value. Select the column for the total from the Column drop down. 4. Click the button to add the new total to the report: 5. Repeat steps 3 & 4 to add additional totals to the report. Procedure to Add a Section to a Report 1. Navigate to the tab of a report 2. Locate the line and the section fields below: 3. Specify a Section Name for the new section 2. Specify whether you wish there to be a page break at the section division or not. The default is to generate a page break at the section boundary: July 8, 2008 DRAFT Page 46 of 58

47 If you do not want a page break on the section boundary, uncheck the checkbox. 3. Click the button to add the new section to the report: Note that there are three parts to defining the section: Specifying when to.generate a page break Specifying what fields to include in the section header Specifying what Totals to include at the end of the section. 4. If you have specified to start the section on a new page, you must specify the columns that will trigger the page break: 5. Locate the checkbox below the label and select a column on which to break: 6. Click the button to add the selected column to the list of those which will generate a page break. 7. Repeat steps 5 & 6 to add additional columns to the page break trigger. 8. To add columns to the section header, First locate the section header area: Then locate the checkbox below the label and select a column to add to the section header. 9. Click the button to add the selected column to those in the section header: 10. Repeat steps 8 & 9 to add additional columns to the section header. 11. To add information to the section totals, locate the section Totals area and find the fields below the label 12. Enter a description of the total. This is the text that will appear in the report: 13. Specify how to do the aggregation for the total: a Count of Rows or a Sum. 14. If you selected Sum as your aggregation method, then you must also specify the column on which to do the sum. 15. Click the button to add the total to the section. July 8, 2008 DRAFT Page 47 of 58

48 16. Repeat steps 11 to 15 to add additional totals to the section. When finished you will have a complete section definition: Figure 17 A Completed Section definition with a page break, section header and section totals areas all populated Procedure to Remove a Section from a Report 1. Navigate to the tab of a report 2. Locate the you wish to remove. Note the delete trashcan icon in the section header: 3. Click that trashcan icon to remove the section. You will be shown a verification dialog: Click OK to remove the specified section. Click Cancel to abandon the operation and leave the section as is. Note that there is no undo for this operation. If you remove a section mistakenly, you must go through the entire Add a Section to Report procedure to restore it. July 8, 2008 DRAFT Page 48 of 58

49 Changing Basic Report Information Figure 18 The Report Info Screen Information for Running and Role Access to the Report The Report Writer Reports Modify Report Info screen contains basic deployment information for the report. This includes the following data fields: Information to display on the Schedule Report screen for this report: Archive choices (last run or all runs): Page layout and orientation: Note that the default orientation is Landscape. Whether or not to show page numbers on the report: Storage option (per user, per school, for district): July 8, 2008 DRAFT Page 49 of 58

50 Controlling the Appearance of Reports Positioning Columns within a Report Columns are positioned by their sequence in the list of columns on the screen. When adding a new column to a report, its Sequence number will always default to the next column to the right. You control the position of the column in the report by positioning the column numerically in the existing list. The columns appear left to right on the paper corresponding to top down in the list. Procedure to Position a Column on a Report 1. Navigate to the Columns screen of a report 2. Locate the column whose left/right position you wish to change 3. Adjust the value in the Sequence number column (e.g. ) to position the column in the list of columns. 4. Click the button to save the changes to the column s position. The list of columns should re-sort so that the column is now placed in the list exactly in the order you wish it to appear on the pages of the printed report. Changing Font Size of a Column Font size is controlled by the Size drop down in the font set of parameters on the screen. Font sizes are built in and sizes not already built in with the font cannot be added by you. Procedure to Change a Column s Font Size 1. Navigate to the Columns screen of a report 2. Locate the column whose font size you wish to change 3. Adjust the value in the Size column (e.g. ) to one of the additional built-in sizes. 4. Click the button to save the changes to the column s font size. Changing the Font used for a Column A column s font is controlled by the Font drop down in the font set of parameters on the screen. Fonts are built in. Genesis provides three fonts (Helvetica, Courier and Times-Roman). Additional fonts can be acquired and uploaded by your System Administrator. Speak to your Genesis System Administrator if you need additional fonts than those currently available on your system. Procedure to Change a Column s Font 1. Navigate to the Columns screen of a report 2. Locate the column whose font size you wish to change 3. Adjust the value in the Font column (e.g. ) to one of the additional fonts. 4. Click the button to save the changes to the column s font size. Changing the Relative Width of a Column The relative width of a column is controlled by the Width % field for the column. Initially, all of the Width % fields are blank and all columns are the same width. The width of the report is divided by the number of visible columns and each column gets the same percentage of the width. The Width % fields allow you to control the relative amount of the total width each column receives. The value in each Width % field should fall between 1 and 100 each representing the % of the total width you wish that column to occupy. These Width % s are advisory only the report writer will use the information to partition the report s columns appropriately. The total percentages do not have to add up to 100%. The Width % field is suppressed for columns which are not visible. Procedure to Set Columns Relative Width 1. Navigate to the Columns screen of a report 2. For each column, select a value for the Width % column (e.g. ) to be the rough percentage of width you wish it to take up on the report. For example, a thin column will take up a small % - July 8, 2008 DRAFT Page 50 of 58

51 maybe a value of 5. A wider column requires a greater % - perhaps 15%. The total of all widths DOES NOT have to add up to 100%. 3. Select the relative width for all columns. 4. Click the button to save the changes to columns relative widths. Procedure to Change Columns Relative Width 1. Navigate to the Columns screen of a report 2. Locate the column whose width you wish to change 3. Adjust the value in the Width % column (e.g. ) to the rough percentage of width you wish it to take up on the report. 4. Repeat for other columns. 5. Click the button to save the changes to columns relative widths. Figure 19 Sample Report with Columns of Equal % Width (blank Width % fields) Figure 20 The same Report as above with Columns sized for Relative Width Figure 21 The Relative Widths for the above Example Changing Page Layout Orientation or Paper Size Reports all default to Landscape orientation and a paper size of 8.5 x 11. The Report Writer gives you the following options: Paper sizes of either Letter (8.5 x11 ) or Legal (8.5 x17 ) Either Landscape or Portrait orientation Either or both default settings can be changed at any time. Procedure to Change Page Orientation or Paper Size 1. Navigate to the screen of a report 2. Locate the Page Layout fields. July 8, 2008 DRAFT Page 51 of 58

52 3. To select paper size, click the Page Size drop down and select either Letter (8.5 x11 ) or Legal (8.5 x17 ). 4. To select paper orientation, click the Orientation drop down and select either Landscape or Portrait. 5. Click the button to save your changes. Figure 22 Upper portion of the report s Report Info tab Adding or Removing Page Numbers from a Report The Genesis Report Writer will automatically add page numbers to the bottom of each page of a report. There is a checkbox to control this and you may turn the feature off so that page numbers do not appear in the report. The default is always to have page numbers appear. Procedure to Turn Page Numbering On or Off. 1. Navigate to the screen of a report 2. Locate the Page Numbers at bottom of each page checkbox. 3. Check or uncheck depending on whether you do or don t want pages numbers in your report. 4. Click the button to save your changes. July 8, 2008 DRAFT Page 52 of 58

53 Publishing Reports Upon creation, a custom report is visible to its creator, who is its initial owner, and to system administrators. After one night, the custom report is automatically added to its module s special reports Role, although ability to use the custom report can be controlled by the owner (and system administrator) via the permissions specified on the report s tab. A report can be published to additional Roles by the owner and the administrator. Publishing Reports to Roles Reports can be published to additional Roles via the Publish section on the tab: Special Roles 1. All custom Reports are automatically added to the sysadmin Role. This ensures that System Administrators have access to all reports and can thus clear up any problems that occur. Reports cannot be removed from the sysadmin Role. System Administrators are not automatically granted the Modify permission to a report. They can administer the report but not, by default, edit it. 2. Additionally, each Genesis module has a special, magic reports Role. Each of these Roles is named for the module of which it is a part: E.g. reportwriter_reports, studentdata_reports, grading_reports, Each special reports Role is rebuilt every night during regular nightly processing: These Roles always contain every report located on the module s Reports screen. Every new custom Report Writer report will be added to the special reports Role of its module during regular nightly processing on the night following the initial creation of the report: Note that while you can remove the special module reports Role from the report, it will be automatically re added every night. Note that like the sysadmin, the special reports Roles can administer the report but not edit it (these permissions are also reset every night). Report Role Permissions There are six permission settings for reports and these permissions can be granted or withheld from any Role. The settings are: Run The ability to run the report Modify Edit the report change how it functions and appears View Output The ability to view the finished report Print The ability to actually print the report Delete The ability to delete the custom report definition Delete from Archive The ability to delete a run of the report from the report archive. E Mail The ability to a run of the report to other Genesis users. Procedure to Publish a Report to a Role 1. Navigate to the screen of the report 2. Select the Role to which you wish to add the report from the drop down list of Roles below the Save button: (by default a Role is not granted Delete or Delete from Archive permission) July 8, 2008 DRAFT Page 53 of 58

54 3. Specify/update the permissions users of the selected Role will have for this report. 4. Click the button. This adds the Role to the list of those which have access to this report. Procedure to Remove a Report from a Role 1. Navigate to the screen of the report 2. Locate the Role from which you wish to remove the Report in the list of Roles: 3. Click the corresponding icon button. This removes the Role from the list of those which have access to this report. Sysadmin cannot be removed. Procedure to Change Role Permissions for a Report 1. Navigate to the screen of the report 2. Select the Role to update permissions for; check/uncheck the permission checkboxes as desired: 3. Click the button immediately below the list of Roles. This updates the changes to the permissions. Report Ownership Initially, the creator of a custom report is its owner. This provides the creator with full update access to report regardless of what Roles the owner has. A custom report s owner may always run, edit and delete it. That is, report ownership is managed outside of the Roles system. A report s owner is listed and can be changed via the report s tab: Procedure to Change the Owner of a Role 1. Navigate to the screen of the report 2. Locate the Owner field in the My Report area at the top of the screen: 3. Select a new owner from the drop down list. 4. Click to change the report s owner to the newly selected user. July 8, 2008 DRAFT Page 54 of 58

55 Running Reports The Report can be run from any of the report definition screens. At the top of each of the Report definition screens the following line appears: Click the button to bring up the Schedule Report screen shown below. Custom reports also appear on the normal reports screens and can be run in the normal way: Figure 23 A list of reports. To the end user, custom reports are indistinguishable from regular, built in reports and appear normally on the Reports screen. Running a custom report from a regular Reports tab is exactly like running a regular built in report: click to schedule the report. Scheduling a Custom Report Step 1: Select the Output Format The tab for custom reports is slightly different from a regular tab. Specifically, there is an drop down with 3 options. Any custom report can be output in any of the formats: Adobe Acrobat (PDF) Produces a regular, normally formatted report Excel (XLS) Produces an MS Excel file with no header or totals information just raw columns of data. CSV Produces a Comma Separated Step 2: Make your parameter selections The Report Parameters you defined for the report are available: July 8, 2008 DRAFT Page 55 of 58

56 Step 3: Schedule the Report Click the button to run the report. Figure 24 Schedule Report Screen CAVEAT: Custom reports with linked columns run slower than normal reports. This is because of extra queries to the Genesis database. The normal report processing takes place with six phases. The phases are communicated through the Engine Message line of the display: Figure 25 The first phase of report generation is the querying of data for the base table. Figure 26 Additional phases include retrieving of the data for the linked columns. This is usually the lengthiest phase. Figure 27 The last phase of regular, PDF report generation is the creation of the PDF file. July 8, 2008 DRAFT Page 56 of 58

57 Step 4: Viewing the Report Regular, PDF reports are displayed in Adobe Reader when completed (See below). MS Excel reports are displayed in MS Excel and CSV files simply display a file dialog: Figure 28 File Dialog displayed when generating a CSV file. Note that the file name is the name of the report. If opened, CSV files are displayed via MS Excel as spreadsheets. View of Report Test Run: Figure 29 Test Run of Report displayed in ADOBE Reader within Genesis Re running Test Runs and Returning to Editing the Report When run from within the Report Writer, reports can be re run or the user can return to editing: Figure 30 Note the Re run this report and Modify this report links above the ADOBE reader header. July 8, 2008 DRAFT Page 57 of 58

58 Re running the report is useful for immediately trying a different set of parameter choices. Thus you can quickly run the report with various settings to judge how it is functioning and appearing. Modify this report the link allows you to quickly return to editing the report you have just run. You can quickly get back to making changes. Creating a Student List as Output When StudentID is one of the Columns (visible or invisible) in a report, the Report Writer will offer to create a student list in addition to one of the regular output forms of the Report. The field is displayed when the create a list option is available: Procedure to Create a Student List as Part of the Report Output 1. Bring up the Schedule Report screen of a report 2. Select an Output Format: Adobe Acrobat (PDF) Produces a regular, normally formatted report Excel (XLS) Produces an MS Excel file CSV Produces a Comma Separated Values text file 3. Select settings for any additional report parameters, including a Sort parameter if one exists. 4. Locate the field and enter the name of the list to create. If no field is available, a student list cannot be created from the report. 5. Click the button to run the report. The report is run in the normal fashion and, if student ids are included, the student list is silently created and can be found in your list of student lists (see the screen). July 8, 2008 DRAFT Page 58 of 58