Mapping Envision Files for SQL Server and Oracleclientsearch.ellucian.com/DocumentExport/Home/DownloadDocument/... · Ellucian’s Colleague Mapping Envision Files for SQL Server

Ellucian’s ColleagueMapping Envision Files for SQL Server

and Oracle

Release 18June 16, 2006

For corrections and clarifications to this manual, see AnswerNet page 4891.

http://clients.datatel.com/support/support.cfm?TYPE=ABCARD&ID=FF819F0A60A24588BC4DCB0A75D59755&pagenum=4891&Action=Search

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.

©2006 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: Ellucian4375 Fair Lakes CourtFairfax, Virginia 22033United States of America

Table of Contents

1. MappingEnvision FilesEnvision File Mapping Rules .......................................................................1-2How Envision Files Map to SQL Server/Oracle Tables ...............................1-3

Data Structure Differences ...................................................................1-3Data Structure Rule Changes ...............................................................1-3

Name Changes ..............................................................................1-3Single-Valued Data Fields ..............................................................1-4Non-Associated, Multivalued Fields ...............................................1-4Associations ...................................................................................1-5PERSON Table: Exception to the Rule ..........................................1-5T-SQL User-Defined Functions ......................................................1-5

Main Exceptions to the Naming Rules ..................................................1-6Associations in File Suites ..............................................................1-6Appl Files .......................................................................................1-6Directories ......................................................................................1-7

What Will Happen to My Files? .............................................................1-7Example 1: The VOCATIONS File ..............................................................1-8Example 2: PERSON ..................................................................................1-9Example 3: ACAD.PROGRAMS ...............................................................1-10Example 4: STUDENT.ACAD.LEVELS: Multi-Part Keys ..........................1-12Example 5: File Suites - GLS.FYR ............................................................1-13Example 6: Tool Kit Specs: appl.PRCS.DEF ............................................1-14Example Case Studies ..............................................................................1-15

Case 1: Faculty Report .......................................................................1-15Case 2: HR Report .............................................................................1-16Case 3: Course Sections Report ........................................................1-17Case 4: Admission Status Report .......................................................1-18

Mapping Envision Files for SQL Server and Oracle, June 16, 2006 i© 2006 Datatel, Inc.

Table of Contents

ii Mapping Envision Files for SQL Server and Oracle, June 16, 2006© 2006 Datatel, Inc.

Mapping Envision Files for SQL Server and Oracle

1. Mapping

Mapping1

Envision Files June 16, 2006

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 Page

“Envision File Mapping Rules” 1-2

“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, 2006 1-1© 2006 Datatel, Inc.

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© 2006 Datatel, Inc.

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.



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 single-valued 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.

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 multi-valued 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.

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.



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.EMAIL association in the PERSON file can be found in the PEOPLE_EMAIL table.

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.

Technical Tip: Association names are defined in the Define Sub-File Elements (DSF) form in the Tool Kit.

1. Other exceptions also exist. Many of these exceptions are in tables related to the FA application.



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.



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 1-10.

■ A file with a multi-part key: “Example 4: STUDENT.ACAD.LEVELS: Multi-Part Keys” beginning on page 1-12.

■ “Example 5: File Suites - GLS.FYR” beginning on page 1-13.

■ “Example 6: Tool Kit Specs: appl.PRCS.DEF” beginning on page 1-14.



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.

Figure 1-1: VOCATIONS File

VOCATIONS.ID

VOCATIONS.DESC (D)

VOCD.USER1

VOCD.USER2

VOCD.USER3

VOCATIONS_ID

VOCATIONS_DESC

VOCD_USER1

VOCD_USER2

VOCD_USER3

UniData SQL Server/Oracle


Example 2: PERSON

Example 2: PERSON2

Figure 1-2: PERSON

2. This sample includes five of thirteen PERSON tables.

PERSON (Single Valued)

ID

LAST_NAME

FIRST_NAME

MIDDLE_NAME

PERSON_LS (List Elements)

ID

POS

CHILDREN

WHERE_USED

NAME_HIST (Association)

ID

POS

NAME_HISTORY_LAST_NAME

NAME_HISTORY_FIRST_NAME

NAME_HISTORY_MIDDLE_NAME

INT (Association)

ID

POS

INTERESTS

INTERESTS_ROLES

PERSON

ID

LAST.NAME

FIRST.NAME

MIDDLE.NAME

NAME.HISTORY.LAST.NAME

NAME.HISTORY.FIRST.NAME

NAME.HISTORY.MIDDLE.NAME

CHILDREN

WHERE.USED

INTERESTS

INTERESTS.ROLES



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

...

0006: 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’

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’

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


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



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 multi-part key:

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:

where STUDENT_ACAD_LEVELS_ID contains a value like:

0029382*UG

Multi-part keys are stored in a single column in SQL Server or Oracle, with an asterisk (*) separating each value.

STUDENT.ACAD.LEVELSSTA.STUDENT

STA.ACAD.LEVEL

STUDENT_ACAD_LEVELS STUDENT_ACAD_LEVELS_ID

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 = “0029382”.


Example 5: File Suites - GLS.FYR

Example 5: File Suites - GLS.FYR

An instance of the File Suite GLS.FYR is the file GLS.2003.

Figure 1-3: File Suites - GLS.FYR

GLS_2003

GLS_ID

OPEN_BAL

DEBITS_YTD

CREDITS_YTD

F03_M_ACTUALS

GLS_ID

POS

MDEBITS

MCREDITS

F03_M_FA_AMTS

GLS_ID

POS

GLS_FA_MACTUALS

GLS_FA_ENCUMBRANCES

GLS.2003

GLS.ID

OPEN.BAL

DEBITS.YTD

CREDITS.YTD

MDEBITS

MCREDITS

GLS.FA.MACTUALS

GLS.FA.ENCUMBRANCES

Envision SQL Server/Oracle



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.


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.

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.

Envision Field

Envision File

S/MAssoc Name

CCSQL Server

TableSQL 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



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.

Based on the data in Table 1-5, you can see that the tables involved in the query are:

■ PERSON

■ PERLEAVE

Envision FieldEnvision

FileS/M

Assoc Name

CCSQL Server

TableSQL 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



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.


■ APPLICATIONS

■ ACAD_PROGRAMS


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’

Envision Field Envision File S/MAssoc 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



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:


■ 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.

Envision Field Envision File S/M Assoc NameSQL Server

TableSQL 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




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




Documents

Mapping Envision Files for SQL Server and Oracleclientsearch.ellucian.com/DocumentExport/Home/DownloadDocument/... · Ellucian’s Colleague Mapping Envision Files for SQL Server