Ellucian s Colleague Mapping Envision Files for SQL Server and Oracle

Size: px

Start display at page:

Download "Ellucian s Colleague Mapping Envision Files for SQL Server and Oracle"

Nancy Wilkinson
6 years ago
Views:

1 Ellucian s Colleague Mapping Envision Files for SQL Server and Oracle Release 18 June 16, 2006 For corrections and clarifications to this manual, see AnswerNet page 4891.

2 Banner, Colleague, PowerCAMPUS, Luminis and Datatel are trademarks of Ellucian or its affiliates and are registered in the U.S. and other countries. Ellucian, Advance, DegreeWorks, fsaatlas, Course Signals, SmartCall, Recruiter, MOX, ILP, and WCMS are trademarks of Ellucian or its affiliates. Other names may be trademarks of their respective owners Ellucian. All rights reserved. The unauthorized possession, use, reproduction, distribution, display or disclosure of this material or the information contained herein is prohibited. Contains confidential and proprietary information of Ellucian and its subsidiaries. Use of these materials is limited to Ellucian licensees, and is subject to the terms and conditions of one or more written license agreements between Ellucian and the licensee in question. In preparing and providing this publication, Ellucian is not rendering legal, accounting, or other similar professional services. Ellucian makes no claims that an institution's use of this publication or the software for which it is provided will guarantee compliance with applicable federal or state laws, rules, or regulations. Each organization should seek legal, accounting and other similar professional services from competent providers of the organization s own choosing. Prepared by: Ellucian 4375 Fair Lakes Court Fairfax, Virginia United States of America

3 Table of Contents 1. Mapping Envision Files Envision File Mapping Rules How Envision Files Map to SQL Server/Oracle Tables Data Structure Differences Data Structure Rule Changes Name Changes Single-Valued Data Fields Non-Associated, Multivalued Fields Associations PERSON Table: Exception to the Rule T-SQL User-Defined Functions Main Exceptions to the Naming Rules Associations in File Suites Appl Files Directories What Will Happen to My Files? Example 1: The VOCATIONS File Example 2: PERSON Example 3: ACAD.PROGRAMS Example 4: STUDENT.ACAD.LEVELS: Multi-Part Keys Example 5: File Suites - GLS.FYR Example 6: Tool Kit Specs: appl.prcs.def Example Case Studies Case 1: Faculty Report Case 2: HR Report Case 3: Course Sections Report Case 4: Admission Status Report Mapping Envision Files for SQL Server and Oracle, June 16, 2006 i

4 Table of Contents ii Mapping Envision Files for SQL Server and Oracle, June 16, 2006

5 Mapping Envision Files for SQL Server and Oracle 1. Mapping

7 Mapping 1 Envision Files 206 June16, In This Chapter This document explains the mapping from Envision UniData files into SQL Server or Oracle tables. Table 1-1 lists the topics covered in this chapter. Topic Envision File Mapping Rules 1-2 Page How Envision Files Map to SQL Server/Oracle Tables 1-3 Example 1: The VOCATIONS File 1-8 Example 2: PERSON 1-9 Example 3: ACAD.PROGRAMS 1-10 Example 4: STUDENT.ACAD.LEVELS: Multi-Part Keys 1-12 Example 5: File Suites - GLS.FYR 1-13 Example 6: Tool Kit Specs: appl.prcs.def 1-14 Example Case Studies 1-15 Table 1-1: Topics in this Chapter Mapping Envision Files for SQL Server and Oracle, June 16,

8 Mapping: Envision Files Envision File Mapping Rules Colleague s Envision files are logical implementations of physical UniData files (for UniData clients) or tables (for SQL Server and Oracle clients). An individual Envision file can be a representation of many physical tables that are combined. For example, the data you see in the Envision UniData file STUDENT.ACAD.CRED is actually stored in six different SQL Server or Oracle tables. There are specific and simple rules you can follow to locate a table in your database that corresponds to an Envision specification. If you are a SQL Server or Oracle client, you can also use the Envision to SQL File Map (EOFM) process to show you the physical database implementation for any Envision file. Note: The Envision to SQL File Map (EOFM) process is available only in Oracle or SQL Server environments. 1-2 Mapping Envision Files for SQL Server and Oracle, June 16, 2006

9 How Envision Files Map to SQL Server/Oracle Tables How Envision Files Map to SQL Server/Oracle Tables Data Structure Differences When mapping Envision files to SQL Server or Oracle tables, Envision applications see the existing, familiar Envision file structure. Colleague applications also continue to see the Envision file structure. For the purposes of writing computed columns, rules, or Envision programs, you need to be aware of the Envision file structure. However, at the database level, you will see a new data structure. Envision programs frequently use multivalued fields and associations, but these are not supported in a SQL Server or Oracle database. Each Envision file can map to multiple SQL Server or Oracle tables. Querying at the database level requires an understanding of this table structure. For SQL Server and Oracle clients, it is important to be able to move back and forth between a SQL Server or Oracle table structure and an Envision file structure. Because there is not a way to query Envision files from the colon prompt using UniQuery for SQL Server and Oracle, research is done on the tables using SQL statements. Most ad-hoc reporting is done using tools that work off the SQL Server tables. Data Structure Rule Changes The breakdown of Envision files into SQL Server tables follows a systematic set of rules. Understanding these basic rules makes it easier to translate between Envision files and SQL Server or Oracle tables. Name Changes File and column names undergo the following changes: Any of the following characters are converted to nulls (removed from the table name): ] \:;,<>?/ and a space Any periods are converted to underscores. All letters are capitalized. Mapping Envision Files for SQL Server and Oracle, June 16,

10 Mapping: Envision Files Single-Valued Data Fields All single-valued data fields from an Envision file are stored as columns in a SQL Server table that bears the modified version of the name of the Envision file. For example, all single-valued data fields from the Envision PERSON file are stored in the SQL Server PERSON table. The SQL Server column names correspond to Envision field names (with the modifications noted in Name Changes on page 1-3). Therefore, if the data field is single-valued (type D for data or X for singlevalued pointer), text (type T), or comment (type C), then the column will exist in the primary table with the same name as the Envision file. For example, LAST.NAME in the PERSON file is type D, so it exists in the PERSON table as LAST_NAME. PREFERRED.ADDRESS is type X, so it also exists in the PERSON table. Technical Tip: To find the data type of a certain field, use the Database Element Linkages (DEL) form in the Tool Kit for the application the field belongs to; or query the table CDD in the database and look at the column DATABASE_USAGE_TYPE. Non-Associated, Multivalued Fields Non-associated, multivalued fields from an Envision file are stored in a SQL Server table that bears the modified Envision file name with an _LS appended to it. For example, non-associated, multivalued fields from the PERSON file are stored in the PERSON_LS table. The SQL Server column names correspond to Envision field names (with the modifications noted in Name Changes on page 1-3). Therefore, if the data field is multi-valued (type L for list or Q for multivalued pointer) and is not a part of an association, then the column will exist in a table with the _LS extension appended to the Envision file name. For example, AWARDS is type L, so it exists in the PERSON_LS table. PARENTS is type Q, so it exists in the PERSON_LS table. 1-4 Mapping Envision Files for SQL Server and Oracle, June 16, 2006

11 How Envision Files Map to SQL Server/Oracle Tables Associations Associations are frequently referred to as tables within a table.. Associations are each stored as their own table. The table bears the name of the association itself with the same modifications as the Envision files. For example, the fields from the PEOPLE. association in the PERSON file can be found in the PEOPLE_ table. Technical Tip: Association names are defined in the Define Sub-File Elements (DSF) form in the Tool Kit. All of the tables that come from an Envision file contain the key of the Envision file as a column. The column that corresponds to the Envision file key is named filename_id. For example, the filename_id column for STUDENT_ACAD_CRED and its related tables is STUDENT_ACAD_CRED_ID. Therefore, if the data field is part of an association (type A), the column will exist in a table with the same name as the association. For example, PREFERRED.RESIDENCE is type A in association P.PRFRES, so it exists in the P_PRFRES table. PERSON Table: Exception to the Rule An exception to the rule is the PERSON table and its related tables, whose primary key is ID. 1 The LS and association tables contain a column named POS. This column contains a sequential integer that represents the position of the value in the multivalued list. It is used in conjunction with the filename_id column to provide the unique identifier for the row. T-SQL User-Defined Functions Envision computed columns are implemented in a SQL Server or Oracle database as TSQL user-defined functions. They are not a part of a table in the SQL Server or Oracle database, but are separate database objects by themselves. 1. Other exceptions also exist. Many of these exceptions are in tables related to the FA application. Mapping Envision Files for SQL Server and Oracle, June 16,

12 Mapping: Envision Files These computed columns must be qualified with a dbo prefix when referenced in SQL statements. They typically bear the same name as the virtual field in Colleague with the field name modifications noted in Name Changes on page 1-3. For example, the computed column STTR.ACTIVE.PROGRAMS from the STUDENT.TERMS file is STTR_ACTIVE_PROGRAMS in the SQL Server and Oracle databases. See the T-SQL Functions for Colleague Computed Columns section of the Envision Computed Column Command Reference. Main Exceptions to the Naming Rules There are exceptions to the naming rules: exceptionally long text fields, associations in file suites, appl files, and directories. Associations in File Suites Associations are stored in a table of their own by the modified name of the association. Consider the following scenario: The SA.ACYR file suite contains the AWARDS association. The SA.1999, SA.2000, and SA.2001 files each contain the AWARDS association. Table names in a SQL Server or Oracle database must be unique, so we cannot have more than one AWARDS table. To address this, associations in file suites are stored in tables named FXX_association where XX is the last two digits of the year. The AWARDS association for SA.2002 is stored in the F02_AWARDS table. Appl Files The appl files are Envision files that are common to each application. They all begin with appl where appl is the application to which the file belongs. Two examples of appl files include: the appl.cdd files and the appl.file.specs files. To map an appl file to its corresponding SQL Server tables, use the Envision file name without the appl prefix. For the appl.file.specs files, start with FILE.SPECS. Then apply the same rules as discussed earlier. For some of the appl files, including appl.cdd and appl.file.specs, the primary key in SQL Server has been changed. The SQL Server primary key has an ~appl appended to the end to guarantee uniqueness between rows. For example, the LAST.NAME record of the CORE.CDD file translates to the LAST.NAME~CORE row of the CDD table. 1-6 Mapping Envision Files for SQL Server and Oracle, June 16, 2006

13 How Envision Files Map to SQL Server/Oracle Tables Directories Directory files from Envision remain as simple OS level directories. This type of file has VOC entries that to point to their location in the OS file system. What Will Happen to My Files? The following are file examples from the very simple to the very complex: A simple code file: Example 1: The VOCATIONS File beginning on page 1-8. Two files with associations and lists: Example 2: PERSON beginning on page 1-9 and Example 3: ACAD.PROGRAMS beginning on page A file with a multi-part key: Example 4: STUDENT.ACAD.LEVELS: Multi-Part Keys beginning on page Example 5: File Suites - GLS.FYR beginning on page Example 6: Tool Kit Specs: appl.prcs.def beginning on page Mapping Envision Files for SQL Server and Oracle, June 16,

14 Mapping: Envision Files Example 1: The VOCATIONS File All data fields in the VOCATIONS Envision file are single-valued, so we will have a single corresponding table in SQL Server or Oracle. UniData VOCATIONS.ID VOCATIONS.DESC (D) VOCD.USER1 VOCD.USER2 VOCD.USER3 SQL Server/Oracle VOCATIONS_ID VOCATIONS_DESC VOCD_USER1 VOCD_USER2 VOCD_USER3 Figure 1-1: VOCATIONS File 1-8 Mapping Envision Files for SQL Server and Oracle, June 16, 2006

15 Example 2: PERSON Example 2: PERSON 2 PERSON ID LAST.NAME FIRST.NAME MIDDLE.NAME PERSON (Single Valued) ID LAST_NAME FIRST_NAME MIDDLE_NAME PERSON_LS (List Elements) ID POS CHILDREN WHERE_USED NAME.HISTORY.LAST.NAME NAME.HISTORY.FIRST.NAME NAME.HISTORY.MIDDLE.NAME CHILDREN WHERE.USED INTERESTS INTERESTS.ROLES NAME_HIST (Association) ID POS NAME_HISTORY_LAST_NAME NAME_HISTORY_FIRST_NAME NAME_HISTORY_MIDDLE_NAME INT (Association) ID POS INTERESTS INTERESTS_ROLES Figure 1-2: PERSON 2. This sample includes five of thirteen PERSON tables. Mapping Envision Files for SQL Server and Oracle, June 16,

16 Mapping: Envision Files Example 3: ACAD.PROGRAMS In Envision: File...: ACAD.PROGRAMS Field 6: ACPG.MAJORS (a list) Looking at the actual record (using an ELE editor) in UniData, you see something like the following: ELE ACAD.PROGRAMS UG.ENVISION -DICT : ACPG.MAJORS...: HIST}ECON}ACCT In SQL Server or Oracle, because ACPG.MAJORS is a list, it is a part of the ACAD_PROGRAMS_LS table: SELECT ACAD_PROGRAMS_ID, POST, ACPG_MAJORS FROM ACAD_PROGRAMS_LS WHERE ACAD_PROGRAMS_ID = UG.ENVISION ACAD_PROGRAMS_ID POS ACPG_MAJORS 1 UG.ENVISION 1 HIST 2 UG.ENVISION 2 ECON 3 UG.ENVISION 3 ACCT Table 1-2: ACAD.PROGRAMS An association behaves the same way as a multi-valued field, except that it has its own table. For example, ACAD_PROGRAMS has ACPG.STATUS as a part of the association PROGRAM.STATUS. Therefore, you can find ACPG_STATUS in the PROGRAM_STATUS table rather than in ACAD_PROGRAMS_LS. SELECT ACAD_PROGRAMS_ID, POS, ACPG_STATUS FROM PROGRAM_STATUS WHERE ACAD_PROGRAMS_ID = UG.ENVISION 1-10 Mapping Envision Files for SQL Server and Oracle, June 16, 2006

17 Example 3: ACAD.PROGRAMS ACAD_PROGRAMS_ID POS ACPG_STATUS 1 UG.ENVISION 1 A 2 UG.ENVISION 2 I Table 1-3: ACAD.PROGRAMS Associations Mapping Envision Files for SQL Server and Oracle, June 16,

18 Mapping: Envision Files Example 4: STUDENT.ACAD.LEVELS: Multi-Part Keys Multi-part keys are set up as a single key in SQL Server or Oracle. For example, in Envision, the file STUDENT.ACAD.LEVELS has a multipart key: STUDENT.ACAD.LEVELS STA.STUDENT STA.ACAD.LEVEL In SQL Server or Oracle, the table STUDENT_ACAD_LEVELS (and all other subtables from the Envision spec STUDENT.ACAD.LEVELS) will have a key: STUDENT_ACAD_LEVELS STUDENT_ACAD_LEVELS_ID where STUDENT_ACAD_LEVELS_ID contains a value like: *UG Multi-part keys are stored in a single column in SQL Server or Oracle, with an asterisk (*) separating each value. Note: You will still be able to perform selects from Colleague using separate parts of the key. For example, the following select is still valid: SELECT STUDENT.ACAD.LEVELS WITH STA.STUDENT = Mapping Envision Files for SQL Server and Oracle, June 16, 2006

19 Example 5: File Suites - GLS.FYR Example 5: File Suites - GLS.FYR An instance of the File Suite GLS.FYR is the file GLS Envision GLS.2003 GLS.ID OPEN.BAL DEBITS.YTD CREDITS.YTD GLS_2003 GLS_ID OPEN_BAL DEBITS_YTD CREDITS_YTD SQL Server/Oracle F03_M_ACTUALS GLS_ID POS MDEBITS MCREDITS MDEBITS MCREDITS GLS.FA.MACTUALS GLS.FA.ENCUMBRANCES F03_M_FA_AMTS GLS_ID POS GLS_FA_MACTUALS GLS_FA_ENCUMBRANCES Figure 1-3: File Suites - GLS.FYR Mapping Envision Files for SQL Server and Oracle, June 16,

20 Mapping: Envision Files Example 6: Tool Kit Specs: appl.prcs.def appl.prcs.def records move into a single table in SQL Server or Oracle. CF.PRCS.DEF, ST.PRCS.DEF, and UT.PRCS.DEF records go into the PRCS_DEF table. Records in the Envision Tool Kit tables have an ~appl suffix to indicate which application they belong to. For example: S.POST.VOU in CF would become record S.POST.VOU~CF in the PRCS_DEF table. Tool Kit template files do not have separate tables for associations and lists Mapping Envision Files for SQL Server and Oracle, June 16, 2006

21 Example Case Studies Example Case Studies Case 1: Faculty Report You want to create a query to display a report of faculty members (ID, Name, and Department). The data for the report comes from the FACULTY file, (Names may come from the PERSON file if there are no computed columns/ functions to do this), and Department from the FAC.DEPTS field. The fields to display are: FACULTY.ID FIRST.NAME LAST.NAME FAC.DEPTS Table 1-4 shows the corresponding SQL Server tables and columns. Envision Field Envision File S/M Assoc Name CC SQL Server Table SQL Server Column FACULTY.ID FACULTY S NA NO FACULTY FACULTY_ID FIRST.NAME PERSON S NA NO PERSON FIRST_NAME LAST.NAME PERSON S NA NO PERSON LAST_NAME FAC.DEPTS FACULTY M DEPT.LOAD NO DEPT_LOAD FAC_DEPTS Table 1-4: Faculty Information Based on the information in Table 1-4, you can see that the tables involved in the query are FACULTY, PERSON, and DEPT_LOAD. The only column referenced in the FACULTY table is FACULTY_ID, which also exists in the DEPT_LOAD table. You really only need the PERSON and DEPT_LOAD tables in your query. Mapping Envision Files for SQL Server and Oracle, June 16,

22 Mapping: Envision Files If you pull up PERSON and DEPT_LOAD in SQL Server 2000 Enterprise Manager (or SQL Server 2005 Management Studio), you will see that the two tables are directly related. The FACULTY_ID from the FACULTY table can be used as a foreign key to the PERSON table. You can now construct your query: SELECT LAST_NAME, FIRST_NAME, FAC_DEPTS FROM PERSON INNER JOIN DEPT_LOAD ON ID = FACULTY_ID ORDER BY FAC_DEPTS, LAST_NAME, FIRST_NAME Case 2: HR Report The HR department wants to generate a report of employees (first and last names) and their leave balances. First and last name are stored in the PERSON file. Leave balance is stored in the PERLV.BALANCE field of the PERLEAVE file. The fields to display are: FIRST.NAME LAST.NAME PERLV.BALANCE Table 1-5 shows the SQL Server tables and columns involved. Envision Field Envision File S/M Assoc Name CC SQL Server Table SQL Server Column FIRST.NAME PERSON S NA NO PERSON FIRST_NAME LAST.NAME PERSON S NA NO PERSON LAST_NAME PERLV.BALANCE PERLEAVE S NA NO PERLEAVE PERLV_BALANCE Table 1-5: HR Information Based on the data in Table 1-5, you can see that the tables involved in the query are: PERSON PERLEAVE 1-16 Mapping Envision Files for SQL Server and Oracle, June 16, 2006

23 Example Case Studies If you pull up the tables in SQL Server 2000 Enterprise Manager (or SQL Server 2005 Management Studio), you can see that the tables are directly related. The relationship is: PERLV.HRP.ID (PERLV_HRP_ID) points to PERSON You can now construct your query: SELECT FIRST_NAME, LAST_NAME, PERLV_BALANCE FROM PERSON RIGHT OUTER JOIN PERLEAVE ON ID = PERLV_HRP_ID Case 3: Course Sections Report You want a report of all course sections offered in the 2004/FA term. For each section, the fields you want to display/reference are: APPLICATIONS.ID APPL.START.TERM ACPG.TITLE Table 1-6 shows the SQL Server tables and columns involved. Envision Field Envision File S/M Assoc Name CC SQL Server Table SQL Server Column APPLICATIONS.ID APPLICATIONS S NA NO APPLICATIONS APPLICATIONS_ID APPL.START.TERM APPLICATIONS S NA NO APPLICATIONS APPL_START_TERM ACPG.TITLE ACAD.PROGRAMS S NA NO ACAD_PROGRAMS ACPG_TITLE Table 1-6: Course Section Information Based on the data in Table 1-6, you can see that the tables involved in the query are: APPLICATIONS ACAD_PROGRAMS You can now construct your query: SELECT APPLICATIONS_ID, APPL_START_TERM, ACPG_TITLE FROM APPLICATIONS LEFT OUTER JOIN ACAD_PROGRAMS ON APPL_ACAD_PROGRAM = ACAD_PROGRAMS_ID WHERE APPL_START_TERM = 2004/FA Mapping Envision Files for SQL Server and Oracle, June 16,

24 Mapping: Envision Files Case 4: Admission Status Report You want a report of the admission status for all applications with a starting term of 05/FA. For each section, the fields you want to display/reference are: APPLICATIONS.ID APPL.APPLICANT APPL.START.TERM APPL.STATUS Table 1-7 shows the SQL Server tables and columns involved: Envision Field Envision File S/M Assoc Name SQL Server Table SQL Server Column APPLICATIONS.ID APPLICATIONS S NA APPLICATIONS APPLICATIONS_ID APPL.APPLICANT APPLICATIONS S NA APPLICATIONS APPL_APPLICANT APPL.START.TERM APPLICATIONS S NA APPLICATIONS APPL_START_TERM APPL.STATUS APPLICATIONS M APPL.STATUSES APPL_STATUSES APPL_STATUS Table 1-7: Admission Status Information Based on the data in Table 1-7, you can see that the tables involved in the query are: APPLICATIONS APPL_STATUSES You know that the current status of an application is always the first status in the association, therefore you only want to select records from the APPL_STATUSES table that have a position (POS) = 1. This will be the most current status for each application Mapping Envision Files for SQL Server and Oracle, June 16, 2006

25 Example Case Studies You can now construct your query: SELECT APPLICATIONS.APPLICATIONS_ID, APPLICATIONS.APPL_APPLICANT, APPLICATIONS.APPL_START_TERM, APPL_STATUSES.APPL_STATUS FROM APPLICATIONS INNER JOIN APPL_STATUSES ON APPLICATIONS.APPLICATIONS_ID = APPL_STATUSES.APPLICATIONS_ID WHERE APPL_START_TERM = 05/FA AND APPL_STATUSES.POS = 1 Mapping Envision Files for SQL Server and Oracle, June 16,

26 Mapping: Envision Files 1-20 Mapping Envision Files for SQL Server and Oracle, June 16, 2006

Banner Enterprise Data Warehouse Release Guide. Release February 2013

Banner Enterprise Data Warehouse Release Guide Release 8.4.3 February 2013 Banner, Colleague, Luminis and Datatel are trademarks of Ellucian or its affiliates and are registered in the U.S. and other countries.