starfish extract administrator guide south dakota...

1

Starfish Extract Administrator Guide South Dakota Board of Regents

September 11th, 2012

2

Table of Contents

1 Introduction ............................................................................................................................................ 4 1.1 Background ..................................................................................................................................................... 4 1.2 Config Form Overview ................................................................................................................................. 5

2 Process Flow ............................................................................................................................................ 6 2.1 Process Flow Diagram ................................................................................................................................. 6 2.2 Process Flow Description............................................................................................................................ 7 2.3 The Extract Files ............................................................................................................................................ 8

2.3.1 File Overview ............................................................................................................................................................................ 8 2.3.2 Initial Population selection ............................................................................................................................................... 9

2.3.2.1 Users selection criteria............................................................................................................................................ 10 2.3.2.2 Students selection criteria ..................................................................................................................................... 11 2.3.2.3 Sections selection criteria ...................................................................................................................................... 11 2.3.2.4 Enrollments selection criteria ............................................................................................................................. 11 2.3.2.5 Outcomes selection criteria .................................................................................................................................. 13

2.3.3 Understanding the Users file extract......................................................................................................................... 13 2.3.4 Understanding the Course Sections file extract .................................................................................................. 14 2.3.5 Understanding the Enrollments file extract .......................................................................................................... 14 2.3.6 Understanding the Teaching Assignments file extract .................................................................................... 15 2.3.7 Understanding the Admissions file extract ............................................................................................................ 15 2.3.8 Understanding the Demographics file extract ..................................................................................................... 16 2.3.9 Understanding the Course Outcomes file extract ............................................................................................... 17 2.3.10 Understanding the Academic Status file extract ................................................................................................. 17 2.3.11 Understanding the Relationships File extract (Advisors) .............................................................................. 18 2.3.12 Understanding the Organizations file extract ...................................................................................................... 18 2.3.13 Understanding the Organization Memberships file(s) extract .................................................................... 19 2.3.14 Understanding the Relationships (Org Roles) file extract ............................................................................. 20

3 Configuration Components .............................................................................................................. 21 3.1 Configuration Forms .................................................................................................................................. 21

3.1.1 XPAR - Starfish Import Parameters Form .............................................................................................................. 21 3.1.2 XPAR1 - Sections Extract Parameter Form ............................................................................................................ 23 3.1.3 XPAR2 - Admissions Extract Parameter Form ..................................................................................................... 25 3.1.4 XPAR3 - Enrollment Extract Parameter Form ..................................................................................................... 27 3.1.5 XPAR4 - Users Extract Parameter Form .................................................................................................................. 28 3.1.6 XPAR5 - Organizations Extract Parameter Form ................................................................................................ 30 3.1.7 XPAR6 - Outcome Extract Parameters Form ........................................................................................................ 32 3.1.8 XPAR7 - Admissions Score Parameters Form ...................................................................................................... 33 3.1.9 XPAR8 - Admissions Test Non-Courses ................................................................................................................... 34 3.1.10 XSOM - Starfish Org Members Configuration ....................................................................................................... 35 3.1.11 XSCM - Starfish Custom Org Members ..................................................................................................................... 37

3.1.11.1 Custom Org Members - Query Detail ............................................................................................................... 38 3.1.12 XSOA - Starfish Org Advisor Configuration ............................................................................................................ 39 3.1.13 XSOR - Starfish Org Members Room Configuration .......................................................................................... 41 3.1.14 XIDA - Attribute Configuration ..................................................................................................................................... 43 3.1.15 XIDA2 - Domain Argument List .................................................................................................................................... 45

3.2 Extract Process Execution (Front End Screen) ................................................................................... 46

3

3.2.1 XSFF - Starfish Extract Parameter Flags .................................................................................................................. 46 3.2.2 XSFE - Colleague to Starfish Extract Form ............................................................................................................. 47 3.2.3 XSFL - Starfish Extract Batch Locks ........................................................................................................................... 48

4 “How-To” guides .................................................................................................................................. 49 4.1 Adding a new Term ..................................................................................................................................... 49 4.2 Adding a new Campus Organization ...................................................................................................... 49

4.2.1 Adding Organizations ........................................................................................................................................................ 49 4.2.2 Adding Roles .......................................................................................................................................................................... 49 4.2.3 Adding Memberships ........................................................................................................................................................ 49

4.3 Running a single extract for testing purposes .................................................................................... 50 4.3.1 Process a single extract .................................................................................................................................................... 50 4.3.2 Reset the extract flags ....................................................................................................................................................... 50

4.4 Setting up the paragraph .......................................................................................................................... 51 4.4.1 Paragraph Examples .......................................................................................................................................................... 51 4.4.1.1 XSTARFISH.EXTRACT.DAILY ............................................................................................................................ 51 4.4.1.2 XSTARFISH.EXTRACT.WEEKLY ...................................................................................................................... 51

4.4.2 Batch Processes .................................................................................................................................................................... 52 4.4.2.1 XSFB01 – Users, Relationships, Sections, Enrollments .......................................................................... 52 4.4.2.2 XSFB02 – Organizations, Org Members .......................................................................................................... 52 4.4.2.3 XSFB03 – Attributes .................................................................................................................................................. 52 4.4.2.4 XSFB04 – Custom Organization Memberships ........................................................................................... 52 4.4.2.5 XSFB05 – Record Selection and Savedlist Creation .................................................................................. 52 4.4.2.6 XSFB06 – Admissions, Academic Status ......................................................................................................... 52

5 Appendix (Extract fields) ................................................................................................................. 53 5.1 Users Extract ................................................................................................................................................ 53 5.2 Course Sections Extract ............................................................................................................................. 54 5.3 Admissions Extract ..................................................................................................................................... 55 5.4 Student Demographics Extract ................................................................................................................ 57 5.5 Attributes Extract ........................................................................................................................................ 58 5.6 Enrollment Extract...................................................................................................................................... 59 5.7 Teaching Assignment Extract .................................................................................................................. 60 5.8 Relationships Extract ................................................................................................................................. 61 5.9 Course Outcomes Extract .......................................................................................................................... 62 5.10 Academic Status Extract ........................................................................................................................ 63 5.11 Organizations Extract ............................................................................................................................. 64 5.12 Organizations Membership Extract ................................................................................................... 65

4

1 Introduction

1.1 Background The South Dakota Board of Regents has purchased software from Starfish Retention Solutions, which requires data from Colleague. An extract process has been created to move the data from Colleague to Starfish. There are many factors to consider when determining the correct set of data to extract, such as user populations, number of semesters to include, organizations and organization membership. To make the extracts as configurable as possible, a set of configuration screens was developed to allow the user to choose which data flows from Colleague into Starfish. This document covers the information needed to configure, understand, and test the extracts.

5

1.2 Config Form Overview

6

2 Process Flow

2.1 Process Flow Diagram

7

2.2 Process Flow Description There are several steps involved when extracting data from the Colleague tables into Starfish. In general, the process is similar to any other Colleague data extract to a third-party vendor. A custom Colleague process, XSFE (Section 4.2) starts the process:

The following steps occur: Population selection (XSFB05) - The first batch creates a set of population SAVEDLISTS

that will be used by the subsequent batches to select and limit the users, sections, outcomes (grades), and enrollments.

Primary User batch (XSFB01) - This batch creates files for Users, Demographics, Course Sections, Advising Roles (relationships), Enrollments, Outcomes, and Teaching Assignments

Primary Organization batch (XSFB02) - This batch creates organizations, memberships and relationships (roles) for items in Campus Org Members, Home Locations, enrollment locations, room assignment members, and Campus Org advisors.

User Attributes Batch (XSFB03) – This batch creates the attributes extract including items set up in the custom attribute engine (XIDA) configuration.

Custom Org Members (XSFB04) - This batch creates additional custom org memberships for any orgs configured in the custom org membership screen (XSCM)

Admissions and Academic Status (XSFB06) - This batch creates files for the admissions and academic status extract.

8

2.3 The Extract Files

The Starfish extract process creates twelve data extracts. For more specific information about the fields in each file, see Appendix I. This section describes the purpose of each file, and the process for populating the data based on the configuration files and selection criteria. The Starfish SIS adapter is designed to pick up flat files with specific file name prefixes. If multiple files exist with the same prefix, it will concatenate/merge the data prior to sending it to Starfish. This allows the Colleague extract process to generate data for the same load file in multiple processes in order to optimize performance.

2.3.1 File Overview

The following list contains all the files produced to be picked up by Starfish:

Primary Starfish Import File

Files Produced Batch creating file

Users users.txt XSFB01 Course Sections sections.txt XSFB01 Enrollments enrollment.txt XSFB01 Teaching Assignment teaching.txt XSFB01 Admissions info (test scores) admissions.txt XSFB06 Relationships relationships.txt (advisors) XSFB01 orgadvisorroles_relationships.txt

(roles) XSFB02

Student demographics demographics.txt XSFB01 User Custom Attributes attributes.txt XSFB03 Course Outcomes course_outcomes.txt XSFB01 Academic Status academic_status.txt XSFB06 Organizations organizations.txt XSFB02 Organization Membership orgmembership.txt XSFB02 custom_orgmembership.txt XSFB04

9

2.3.2 Initial Population selection

There are five different SavedLists that are generated during the initial population creation that are used by the subsequent batches. The names of these SavedLists are configurable on some of the individual parameter forms.

Savedlist Parm

Screen Purpose

Users XPAR4 List of all valid Starfish users (based on config). Used to generate the Users (users.txt) file, Attributes (attributes.txt) file, Demographics (demo.txt) file. Also used in the Org Membership (explained in later sections)

Students XPAR2 List of all valid Starfish students (based on config) . Used to generate the Academic Status (acad_status.txt) file, Relationships (relationships.txt) file and the Admissions Test Scores (admissions.txt) file.

Sections XPAR1 List of all Course Sections to be sent to Starfish (based on config). Used to generate the Course Sections (sections.txt) file and the Teaching Assignments (teaching.txt) file.

Enrollments XPAR3 List of all Valid Active Student Acad Cred (based on config). Used to generate the Course Enrollment (enrollment.txt) file.

Outcomes XPAR6 List of all Student Acad Cred (Regardless of status). Used to generate the Course Outcomes (course_outcomes.txt) file

10

2.3.2.1 Users selection criteria

Users are selected from the following population of Colleague Users:

Students o Selection Criteria:

Any student that registered for a section in the given list of terms (even if they dropped all classes)

o Query: SELECT STUDENT.ACAD.CRED WITH STC.TERM EQ '<list of terms>' SELECT STUDENT.ACAD.CRED SAVING UNIQUE STC.PERSON.ID

Staff (Current) o Selection Criteria:

Any staff with a status of “C” o Query:

SELECT STAFF WITH STAFF.STATUS EQ 'C' Faculty

o Selection Criteria: Any faculty teaching a section in the configured terms

o Query: <after selecting active sections> SELECT COURSE.SECTIONS SAVING UNIQUE SEC.FACULTY

REQUIRE.SELECT SELECT COURSE.SEC.FACULTY SAVING UNIQUE CSF.FACULTY

REQUIRE.SELECT

Users associated with Room Assignments o Selection Criteria:

SELECT ROOM.ASSIGNMENT WITH RMAS.TERM EQ " : X.TERMS : " AND RMAS.CURRENT.STATUS EQ 'A' SAVING UNIQUE RMAS.PERSON.ID

Users associated with Campus Org Memberships or Campus Org Advisors

o Selection Criteria: SELECT CAMPUS.ORG.ADVISORS SAVING UNIQUE CMPA.PERSON.ST.ID

Limiting Users to only people without Privacy flags for Deceased (DC) or Duplicate

(X) o SELECT PERSON WITH PRIVACY.FLAG NE 'DC''X'

NOTE: Additional filters are applied as each user is processed in XSFB01 that could eliminate some of the users:

They must have an Integration ID (Colleague ID) o Note: The method used to derive the integration ID is set using parameters

on XPAR4) They must have a Last Name (LAST.NAME) They must have a First Name (FISRT.NAME)

11

They must have a user ID (Web Advisor Login – OEE.USERNAME in ORG.ENTITY.ENV)

o Note: The method used to derive the user ID is set using parameters on XPAR4.

2.3.2.2 Students selection criteria

The student selection is part of the Users selection; however, an additional savedlist is created for just students to be used in student specific extracts:

Students o Selection Criteria:

Any student that registered for a section in the given list of terms (even if they dropped all classes)

o Query: SELECT STUDENT.ACAD.CRED WITH STC.TERM EQ '<list of terms>' SELECT STUDENT.ACAD.CRED SAVING UNIQUE STC.PERSON.ID

2.3.2.3 Sections selection criteria

Sections selection uses the following logic:

Sections o Selection Criteria:

Course sections in the selected terms with a Status Special Processing Action Code 1 equal to 1 and an Academic Level that is NOT equal to HS.

o Query: SELECT COURSE.SECTIONS WITH SEC.TERM EQ '<list of terms>' AND

SEC.STATUS.ACTION1 EQ '1' AND SEC.ACAD.LEVEL NE 'HS'

2.3.2.4 Enrollments selection criteria

Student Enrollments selection uses the following logic:

Enrollments o Selection Criteria:

Any active student academic credit (of any type) in the given terms list. o Query:

SELECT STUDENT.ACAD.CRED WITH STC.TERM EQ ‘<list of terms>' AND STC.CURRENT.STATUS EQ 'A''N'

NOTE: o The Enrollments extract is for registered sections. The selection may include

transfer and non-courses. However, the enrollments extract batch (in XSFB01) will NOT write any record that does not have a valid Course Section ID.

o If a student drops a section after they have already had the enrollment sent to Starfish, the dropped enrollment with NOT be sent to Starfish. Starfish treats any enrollments that “disappear” for a current term as a drop or withdraw (depending

12

on the dates). Any missing records for previous terms will be considered “archived”..

13

2.3.2.5 Outcomes selection criteria

Student Section Outcomes selection uses the following logic:

Outcomes o Selection Criteria:

Any active student academic credit (of any type) in the given terms list. o Query:

"SELECT STUDENT.ACAD.CRED WITH STC.TERM EQ ‘<list of terms>' NOTE: The outcomes file is selecting a wider set of data than will be included in Starfish.

The only records that make it into Starfish are valid enrollments with grade. The result is the same, but the filtering will happen on Starfish’s side.

2.3.3 Understanding the Users file extract

Possible Errors o Each row in the users file needs to have a Integration ID, Family Name, Given Name, User ID

for the row to be created. If any of this information is missing, an error will be logged in the XSFB01_ERROR.log file which is created and overwritten in the Log Directory configuration on XPAR.

Explanations of the mapping selection process The selection process to build the users files looks in all of the places where we may be extracting users

so that we try to pick up the users so they are there. o Students from the Student Acad Cred file for the terms are selected into the users file. o Instructors from the Course Sections being taught in the terms are selected into the users

file. o Students from the Room Assignments in the terms are selected into the file. o Advisors from the Campus Org Advisors file are selected into the users file. o Staff from the Staff file with a Current status will be selected into the users file.

Relationship to Parameter choices o Birth Date – This can be turned on or off on the XPAR4 form. o Home Phone Type – The Phone type can be chosen on the XPAR4 form. o Cell Phone Type – The Phone type for this can be chosen on the XPAR4 form. o Work Phone Type – The Phone type for this can be chosen on the XPAR4 form. o Email Type – The Phone type for this can be chosen on the XPAR4 form. o Include Users – If this parameter on the XPAR4 form is set to Y then the users.txt file will be

created. If it is set to N then the file will not be created. o User ID Type – This parameter will control the format of the integrationID in the user file,

and also any other file that includes a user integration ID (enrollments, courseoutcomes, admissions, demographics, academic status, org memberships, relationships, etc). This field can either be ID – which will use the Colleague ID as the User Integration ID; or CUSTOM – where a custom subroutine will be called to calculate the Colleague ID.

o User Login ID Type – This is similar to User ID, except it can be ID, LOGIN or CUSTOM. ID and CUSTOM are the same as they were for the User ID. LOGIN will use the Org Entity Env Username value (which is the same as what Colleague WebAdvisor would use).

How to view the logs (if any exist)

14

o Any errors will be put in the Error Log file (XSFB01_ERRORS.log) which is stored in the Log Directory on XPAR. An example of viewing the error file would be:ELE _HOLD_ XSFB01_ERRORS.log (assuming that _HOLD_ is the Log Directory).

How to view the outputted files (just a name and directory) o The users.txt file will be created in the Work Directory (on XPAR) and written to in the

Work Directory and copied to the Starfish Directory (on XPAR) when XSFB01 completes its processing.

ELE STARFISHSIS users.txt

2.3.4 Understanding the Course Sections file extract

Possible Errors o Currently no error is generated while building the Course Sections file. If the Course

Sections is selected, then it will have an ID Explanations of the mapping selection process

o Course sections for the terms being processed are selected. Only sections with a status that has a special processing action 1 equal to 1 and that do not have an academic level of HS are selected.

Relationship to Parameter choices o Course Section Integration ID is determined by the Section ID Type form, the XPAR1 form.

This can be ID or CUSTOM. If it is ID, then the Colleague Course Sections ID is used. If CUSTOM, then the results of a custom subroutine call will be used in the Course Sections file for the integration, as well as any file that links to the course sections file (enrollments, outcomes, etc).

o Course Section ID – This file will be populated using the same configuration setting that is used to set the Course Section Integration ID.

How to view the logs (if any exist) o Errors generating the course sections file would be included with the XSFB01_ERROR.log

file that is written to the Log Directory on XPAR ELE _HOLD_ XSFB01_ERRORS.log

How to view the outputted files (just a name and directory) o The course_sections.txt file will be created in the Work Directory (on XPAR) and moved to

the Starfish Directory (on XPAR) when XSFB01 completes running. ELE STARFISHSIS course_sections.txt

2.3.5 Understanding the Enrollments file extract

Possible Errors o Currently, no errors are generated while building the Enrollments file. The Enrollments file

is built using STUDENT.ACAD.CRED and STUDENT.COURSE.SEC records for the terms being processed. If the records are found, then the fields required by Starfish will be populated.

o Course Section Integration ID, User Integration ID, User Role and Availability Indictor are all required. If the record is found in the STUDENT.ACAD.CRED / STUDENT.COURSE.SEC records, then the values will be present so no error checking is done.

Explanations of the mapping selection process

15

o Student Acad Cred records are selected for the terms being processed with a current status of A or N.

Relationship to Parameter choices o The only parameter that directly affects the enrollments extract is on XPAR3 to turn the file

on and off. If this flag is set to N then the enrollment extract will not be generated. o Indirectly the Terms on XPAR will affect which records are selected to be processed.

How to view the logs (if any exist) o Errors generated for this would be in the XSFB01_ERROR.log file in the Log Directory

specified on XPAR1. ELE _HOLD_ XSFB01_ERRORS.log

How to view the outputted files (just a name and directory) o The enrollment.txt file is written to the Work Directory (on XPAR) and moved to the

Starfish Directory (on XPAR) when XSFB01 completes. ELE STARFISHSIS enrollment.txt

2.3.6 Understanding the Teaching Assignments file extract

Possible Errors o Currently there are no errors generated while building the Teaching Assignments file; this is

due to the nature of the file. If the data is in Colleague, it will be enough to complete the file creation for the teaching.txt file.

o Course Sections Integration ID, User Integration ID, User Role (always INSTRUCTOR), Availability IND (always) are required. If the Course Section has a Course Section Faculty record, then all of the fields can be populated.

Explanations of the mapping selection process o The teaching assignments file is generated indirectly from the Sections savedlist specified

on XPAR1. As the course sections are processed any instructors teaching the sections are put into the teaching.txt file.


specified on XPAR. ELE _HOLD_ XSFB01_ERRORS.log

How to view the outputted files (just a name and directory) o The teaching.txt file is written out to the Work Directory (on XPAR) and moved to the

Starfish Directory (on XPAR) when XSFB01 completes. ELE STARFISHSIS teaching.txt

2.3.7 Understanding the Admissions file extract

Possible Errors o Several of the test scores stored in the admissions file have data validation checks to make

sure the scores are in a particular range. If a test score is outside the accepted range an error will be logged in the XSFB06_ERROR.log file, which is created and overwritten in the Log Directory configuration on XPAR.

16

o Note: If a test score has an offset associated, the test score is validated before the offset is added to the score and written to the admissions file.

Explanations of the mapping selection process o The records processed are determined by the Students savedlist. The PERSON.ST file is

read and the student non-courses are read from PST.STUDENT.NON.COURSES. Only Student Non-Courses with a status (STNC.STATUS) that matches the status defined on XPAR8 will be used (by default this status is AC – Accepted).

Relationship to Parameter choices o XPAR2 includes the output file name for the extract: admissions.txt o This screen also includes the flag to indicate whether or not to process and include the

Admissions file extract. o The parameter screens used for the Admissions file extract are XPAR7 ad XPAR8. On XPAR7

you indicate what transcript type(s) match a High School transcript record. If more than one are entered, the order will determine the hierarchy used. The tests that are accepted by Starfish are listed on XPAR7. For each test the score to extract is indicated by a type which includes Highest, Last (most recent), First, Average. If the test will include an offset, set this indicator to Non-Course Precedence. Detailing on a test will pull up the XPAR8 screen. On XPAR8, for a particular test, the associated non-course records are indicated along with the accepted status type. This also allows for a test score offset which is used to add a value to a test score to indicate a different test (when multiple tests are extracted to one starfish test). This is currently setup for the Math Placement test and incudes several possible tests to be extracted.


specified on XPAR. ELE _HOLD_ XSFB06_ERRORS.log

How to view the outputted files (just a name and directory) o The admissions.txt file is written out to the Work Directory (on XPAR) and moved to the

Starfish Directory (on XPAR) when XSFB06 completes. ELE STARFISHSIS admissions.txt

2.3.8 Understanding the Demographics file extract

Possible Errors o The user_integration_ID is required. If it is missing, the output record cannot be written and

an error will be logged. Explanations of any confusing selection process of mapping

o The records processed are determined by the Users savedlist. Relationship to Parameter choices

o XPAR4 includes the output file name for the extract: demographics.txt o This screen also includes the flag to indicate whether or not to process and include the

Demographics file extract. How to view the logs (if any exist)

o Errors generated for this would be in the XSFB01_ERROR.log file in the Log Directory specified on XPAR1.

ELE _HOLD_ XSFB01_ERRORS.log

17

How to view the outputted files (just a name and directory) o The demographics.txt file is written out to the Work Directory (on XPAR) and moved to the

Starfish Directory (on XPAR) when XSFB01 completes. ELE STARFISHSIS demographics.txt

2.3.9 Understanding the Course Outcomes file extract

Possible Errors o Currently, no error is generated while building the Course Outcomes file. The Course

Outcomes file is built using STUDENT.ACAD.CRED and STUDENT.COURSE.SEC records for the terms being processed. If the records are found\ then the fields required by Starfish will be populated.

o Course Section Integration ID, User Integration ID, User Role and Availability Indictor are all required. If the record is found in the STUDENT.ACAD.CRED / STUDENT.COURSE.SEC records, then the values will be present so no error checking is done.

Explanations of the mapping selection process o Student Acad Cred records are selected for the terms being processed. Additionally, a

Student Course Sec record will need to exist for the Student Acad Cred record as the Grading information is stored in the Student Course Sec record.

Relationship to Parameter choices o The only parameter that directly affects the course outcomes extract is on XPAR6 to turn

the file on and off. If this flag is set to N, then the course outcomes extract will not be generated.

o Indirectly the terms on XPAR will affect which records are selected to be processed. How to view the logs (if any exist)

o Errors generated for this would be in the XSFB01_ERROR.log file in the Log Directory specified on XPAR1.

ELE _HOLD_ XSFB01_ERRORS.log How to view the outputted files (just a name and directory)

o The course_outcomes.txt file is written out to the Work Directory (on XPAR) and moved to the Starfish Directory (on XPAR) when XSFB01 completes.

ELE STARFISHSIS course_outcomes.txt

2.3.10 Understanding the Academic Status file extract

Possible Errors o Currently there are no errors generated while building the Academic Status file, this is due

to the nature of the file. If the data is in Colleague it will be enough to complete the file creation for the academic_status.txt file.

Explanations of any confusing selection process of mapping o The records processed are determined by the Students savedlist.

Relationship to Parameter choices o XPAR2 includes the name of the Academic Status file extract: academic_status.txt o This screen also includes the flag that indicates whether or not to process and include the

Academic Status file extract. How to view the logs (if any exist)

18

o Errors generated for this would be in the XSFB06_ERROR.log file in the Log Directory specified on XPAR.

o ELE _HOLD_ XSFB06_ERRORS.log How to view the outputted files (just a name and directory)

o The academic_status.txt file is written out to the Work Directory (on XPAR) and moved to the Starfish Directory (on XPAR) when XSFB06 completes.

ELE STARFISHSIS academic_status.txt

2.3.11 Understanding the Relationships File extract (Advisors)

There are no possible errors associated with the Relationship File extract. Explanations of the mapping selection process:

o All students in the STUDENTS savedlist on the XPAR2 form will be processed and their STUDENT.ADVISMENT records examined to see if they match the relationship types defined on XPAR2.

Relationship to Parameter choices o On XPR2, the Relationship Types field will be used to limit the Relationship Types that are

generated from the Student.Advisement file for the relationships.txt file. If no types are specified, then all relationship types valid for the terms listed on XPAR will be processed and included.


specified on XPAR1. ELE _HOLD_ XSFB01_ERRORS.log

How to view the outputted files (just a name and directory)

2.3.12 Understanding the Organizations file extract

Campus Organizations represent a group of users. They are generated based on data found in the config tables and various student data fields:

Any organization listed in the XSOM, XSOR, XSOA or XSCM form is added to the Organizations file. An organization representing the Home Locations are generated for each campus home location. Room Assignment Organizations (Residence Life) are created based on all room assignment halls

(as defined on XSOR). Organization for each Location Code defined in the Org Home Locations file based on the Location

Code and Location Description from Colleague.

Note: All the organizations are term-based. Separate term-coded organizations are generated for each term identified in the term config form (XPAR). The only exception to this is the “allstudents” role (not yet implemented).

19

2.3.13 Understanding the Organization Memberships file(s) extract

The Organization memberships file is designed to list members in one of three categories:

1) Students – Standard member role for all students 2) Instructor - this is currently used for residence halls only and can be mapped in Starfish to the

proper residence hall role. 3) TA* – Not used

Note: the organization membership’s import in Starfish is modeled after the course sections import, so it uses the “instructor/TA” terminology.

Organization memberships are created using the following sources:

Organizations are built for students who have a home location (that is specified on XPAR5) and are enrolled in a section for any of the terms specified on XPAR. The the student will have an organization membership record for that home location.

Enrollment Locations – Additional to the home location is any location for active registered sections for the student in the term.

Room assignments Campus Org Memberships (Datatel) – Any org listed in the XSOM screen will be checked for each

student to see if they are listed as active in the term in Datatel’s Campus Orgs files. Custom Org membership selections – Each Org listed in the XCSM config form will be separately

evaluated to produce membership records for the organization. This is to handle items not in any of the above locations.

20

2.3.14 Understanding the Relationships (Org Roles) file extract

The Relationships extract for Starfish will be used for both the advising relationships (advisor to student), but also to establish roles for individuals to organizations and the org memberships. For example, a team coach will get a relationship to the specific team with a role of “Athletic Advisor.” Roles are sources from the Campus org advisors table in Colleague. If the org has a role mapping in the XSOA screen, it will map any users listed in the Colleague Campus org advisors tables that are active for the term to the appropriate Starfish role for the organization. Note: Not all of the options are configurable from the XSOR form. Specifically, the Residence Life Director and Residence Life 1 roles cannot be distinguished by the parameters defined on XSOR. Custom code was added to differentiate these two roles during the extract process. The main difference is that the Residence Life 1 role will always have a term defined in the Colleague Room Assignments file record. Both roles have a Resident Staff indicator of “RD”. The Residence Life Director role will only be assigned to records from the Colleague Room Assignments file that have an active status, no term defined, and an end date that is in the future. If a term is defined, the role of Residence Life 1 will be assigned.

21

3 Configuration Components

3.1 Configuration Forms

3.1.1 XPAR - Starfish Import Parameters Form

The Starfish Import Parameters form allows the user to configure how the process is executed, including defining the local directories used during the extract creation process, terms to be included and which extracts are to be created. Users may detail to extract-specific configuration parameter screens from here as well.

Work Directory – Enter the VOC record that points to the directory or folder on the server to sequentially write the extract files to while the extract is running.

Starfish Directory – Enter the VOC record that points to the Starfish SIS Adapter Outbound Directory. This currently points to: /datatel/interface/STARFISH/outbound

Log Directory – Enter the VOC record that points to the directory or folder to write the log files generated by the extract programs.

22

Daily Files Flag – This flag is used for troubleshooting changes during development and/or maintenance cycles if daily copies of the extracted files are kept. The Starfish SIS Adapter also keeps track of changes so that it only sends the change set, or delta, to the Starfish Server. This setting would be for troubleshooting the extract process itself. Valid values are Y and N. (NOT CURRENTLY USED)

Daily Log Flag – This flag controls if the log files produced by the batch programs will be retained beyond a single run or if they will be copied to a second file with the date and time stamp of the running, so they can be examined if needed. Valid values are Y and N. (NOT CURRENTLY USED)

Terms – Enter the terms to use when limiting records within the programs. These are used to determine if a record is included or not, such as Student Acad Cred records, Campus Orgs, Room Assignments, etc. This field validates against the TERMS file.

Custom Attributes – This field allows the user to detail down to the Custom Attributes Extract configuration form, XIDA. See Section 3.1.11 for more information on the XIDA form.

Custom Org Members – This field allows the user to detail to the Custom Org Members Extract configuration form, XSCM. See Section 3.1.9 for more information on the XSCM form.

Sections Extracts – This field allows the user to detail to the XPAR1- Sections Extract Parameters Form. See Section 3.1.2 for more information on the XPAR1 form.

Admissions Extracts – This field allows the user to detail to the XPAR2 – Admissions Extract Parameter Form. See Section 3.1.3 for more information on the XPAR2 form.

Enrollment Extracts – This field allows the user to detail to the XPAR3 – Enrollment Extract Parameter Form. See Section 3.1.4 for more information on the XPAR3 form.

Users Extracts – This field allows the user to detail to the XPAR4 – Users Extract Parameter Form. See Section 3.1.5 for more information on the XPAR4 form.

Orgs Extracts – This field allows the user to detail to the XPAR5 – Organizations Extract Parameter Form. See Section 3.1.6 for more information on the XPAR5 form.

Outcome Extracts – This field allows the user to detail to the XPAR6 – Outcomes Extract Parameter Form. See Section 3.1.7 for more information on the XPAR6 form.

23

3.1.2 XPAR1 - Sections Extract Parameter Form

The Sections Extract Parameter form is a detail screen accessed from XPAR. It is used to configure the parameters for the Sections and Teaching Assignment extracts. The Sections extract contains information about the course section. The Teaching Assignments extract contains information for the instructor in each of the course sections. Please refer to the Appendix for the descriptions of each field in the Sections and Teaching Assignments extracts.

Section ID Type- Sections ID calculation, valid values are ID or CUSTOM. If ID is chosen, the standard COURSE.SECTIONS key will be used as the unique identifier for each section in the extract. If some other identifier must be used, enter CUSTOM in this field and specify a custom subroutine to be used to calculate the new identifier in the field below.

Section ID Subroutine – Enter the custom subroutine name to use if Section ID Type field is set to CUSTOM. If ID is chosen in Section ID Type field, leave this field blank. The subroutine interface must be S.SUBROUTINE(OUT, PERSON.ID).

Term ID Type – The Term ID calculation valid values are ID or CUSTOM. If ID is chosen, the standard TERMS file key will be used as the unique identifier for each term in the extract. If some other identifier must be used, enter CUSTOM in this field and specify a custom subroutine to be used to calculate the new identifier in the field below.

24

Term ID Subroutine – Enter the custom subroutine name to use if Term ID Type is set to CUSTOM. If ID is chosen in Term ID Type field, leave this field blank. The subroutine interface must be S.SUBROUTINE(OUT, PERSON.ID).

Sections Savedlist Name – Enter the Savedlist name used to generate the Sections and Teaching Assignments extracts. Since teaching assignments are derived from the course sections, one savedlist will get both. Users must maintain the query used to create the savedlist and include any limiting criteria within it to make sure the savedlist includes the appropriate keys.

Sections Include Flag - This flag is used to control the extraction of Section files. Valid values are Y and N. Enter Y to have the Sections extract included in the process.

Sections File – Enter the filename to use for the Sections extract. When the extract is processed this will be the name of the Sections extract.

Teach Include Flag - This flag is used to control the extraction of the Teaching Assignment files. Valid values are Y and N. Enter Y to have the Teaching Assignments extract included in the process.

Teach File – Enter the filename to use for the Teaching Assignments extract. When the extract is processed this will be the name of the Teaching Assignments extract.

25

3.1.3 XPAR2 - Admissions Extract Parameter Form

The Admissions Extract Parameter form is a detail screen accessed from XPAR. It is used to configure the parameters for the Relationships, Academic Status and Admissions extracts. The Relationships extract contains information about the advisor/advisee relationship. The Academic Status extract contains information about a student’s academic profile. The Admissions extract includes test score data for each student. Please refer to the Appendix for the descriptions of each field in the Relationships, Academic Status and Admissions extracts.

Student ID Type- Student ID calculation, valid values are ID or CUSTOM. If ID is chosen, the standard STUDENTS file key will be used as the unique identifier for each student in the extract. If some other identifier must be used, enter CUSTOM in this field and specify a custom subroutine to be used to calculate the new identifier in the field below.

Student ID Subroutine – Enter the custom subroutine name to use if Student ID Type field is set to CUSTOM. If ID is chosen in Student ID Type field, leave this field blank. The subroutine interface must be S.SUBROUTINE(OUT, PERSON.ID).

Student Savedlist Name – Enter the Savedlist name used to generate the Relationships, Academic Status and Admissions extracts. All three extracts can be created based on Colleague Student ID.

26

Users must maintain the query used to create the savedlist and include any limiting criteria within it to make sure the savedlist includes the appropriate keys.

Relationship Types – (NOT CURRENTLY USED) Relationships Include Flag- This flag is used to control the extraction of Relationships files. Valid

values are Y and N. Enter Y to have the Relationships extract included in the process. Relations File - Enter the filename to use for the Relationships extract. When the extract is

processed this will be the name of the Relationships extract. Acad Stat Include Flag - This flag is used to control the extraction of Academic Status files. Valid

values are Y and N. Enter Y to have the Academic Status extract included in the process. Academic Stat File - Enter the filename to use for the Academic Status extract. When the extract is

processed this will be the name of the Academic Status extract. Scores Include Flag - This flag is used to control the extraction of Admissions files. Valid values are

Y and N. Enter Y to have the Admissions extract included in the process. Scores File - Enter the filename to use for the Admissions extract. When the extract is processed

this will be the name of the Admissions extract.

27

3.1.4 XPAR3 - Enrollment Extract Parameter Form

The Enrollment Extract Parameter form is a detail screen accessed from XPAR. It is used to configure the parameters for the Enrollments extract. The Enrollments extract connects the students to the sections. Please refer to the Appendix for the descriptions of each field in the Enrollments extract.

Enrollment Savedlist Name - Enter the Savedlist name used to generate the Enrollments extract. This extract is created based on the Colleague Student ID. Users must maintain the query used to create the savedlist and include any limiting criteria within it to make sure the savedlist includes the appropriate keys.

Enrollment Flag - This flag is used to control the extraction of the Enrollment file. Valid values are Y and N. Enter Y to have the Enrollments extract included in the process.

Enrollment File - Enter the filename to use for the Enrollments extract. When the extract is processed this will be the name of the Enrollments extract.

28

3.1.5 XPAR4 - Users Extract Parameter Form

The Users Extract Parameter form is a detail screen accessed from XPAR. It is used to configure the parameters for the Users, Attributes and Demographics extracts. The User extract includes information about all users of the Starfish software. This can include students, faculty, advisors, teaching assistants administrators and coaches. The Attributes extract includes any name/value pair of data for a student. Examples are: Program, Major and Term GPA. The Attributes extract is flexible enough to include any data needed for a particular student. See Section 3.1.10 for more information about the Attribute Engine. The Demographics extract includes demographic information for the students. Please refer to the Appendix for the descriptions of each field in the Users, Attributes and Demographics extracts.

User ID Type- User ID calculation, valid values are ID or CUSTOM. If ID is chosen, the standard PERSON file key will be used as the unique identifier for each user in the extract. If some other identifier must be used, enter CUSTOM in this field and specify a custom subroutine to be used to calculate the new identifier in the field below.

User ID Subroutine – Enter the custom subroutine name to use if User ID Type field is set to CUSTOM. If ID is chosen in User ID Type field, leave this field blank. The subroutine interface must be S.SUBROUTINE(OUT, PERSON.ID).

29

User Login ID Type - User Login ID calculation, valid values are ID, LOGIN or CUSTOM. This is used for Single Sign On and should be the USERNAME the user is using to login to the client’s website, probably should always be LOGIN to pull the value from ORG.ENTITY.ENV

User Login ID Subroutine – Enter the custom subroutine name to use if User Login ID Type is set to CUSTOM. The subroutine interface must be S.SUBROUTINE(OUT, PERSON.ID).

User Savedlist Name – Enter the savedlist name used to generate the Users, Attributes and Demographics extracts. All three extracts can be created based on the Colleague Person ID. Staff must maintain the query used to create the savedlist and include any limiting criteria within it to make sure the savedlist includes the appropriate keys.

Home Phone Type – Enter the Colleague phone type code to use to generate the Home Phone Number value in the Users extract.

Cell Phone Type –Enter the Colleague phone type code to use to generate the Cell/Mobile Phone Number value in the Users extract.

Work Phone Type – Enter the Colleague phone type code to use to generate the Work Phone Number value in the Users extract.

Email Type – Enter the Colleague e-mail address type code to use to calculate the Email Address in the Users extract.

Users Flag - This flag is used to control the extraction of the Users file. Valid values are Y and N. Enter Y to have the Users extract included in the process.

Users File - Enter the filename to use for the Users extract. When the extract is processed this will be the name of the Users extract.

The User Attributes Flag - This flag is used to control the extraction of the Attributes file. Valid values are Y and N. Enter Y to have the Attributes extract included in the process.

Users Attr File - Enter the filename to use for the Attributes extract. When the extract is processed this will be the name of the Attributes extract.

The Demographics Flag - This flag is used to control the extraction of the Demographics file. Valid values are Y and N. Enter Y to have the Demographics extract included in the process.

Demographics File - Enter the filename to use for the Demographics extract. When the extract is processed this will be the name of the Demographics extract.

30

3.1.6 XPAR5 - Organizations Extract Parameter Form

The Organizations Extract Parameter form is a detail screen accessed from XPAR. It is used to configure the parameters for the Organizations extracts. Organizations can be based on existing Colleague organizations, student home locations, section locations, room assignments or custom organizations. Students can be a member of any of the organizations defined here. Please refer to the Appendix for the descriptions of each field in the Organizations extracts.

Org Home Locations – Enter the locations to use to create Organizations / Org Members that are associated with the STU.CURRENT.HOME.LOCATION and the SCS.LOCATION values.

Organizations File Flag - This flag is used to control the extraction of the Organizations file. Valid values are Y and N. Enter Y to have the Organizations extract included in the process. For now, this should always be set to Y.

Campus Org Members Flag – This flag is used to control the extraction of the Campus Org Members file. Valid values are Y and N. Enter Y to have the Campus Org Members extract included in the process.

Home Location Orgs Flag - This flag is used to control the extraction of the Home Location Orgs file. Valid values are Y and N. Enter Y to have the Home Location Orgs extract included in the process. These are based on the student’s home location.

31

Enrollment Location Org Flag - This flag is used to control the extraction of the Enrollment Location Org file. Valid values are Y and N. Enter Y to have the Enrollment Location Org extract included in the process. These are based on the section location.

Room Assignment Members Flag - This flag is used to control the extraction of the Room Assignment Members file. Valid values are Y and N. Enter Y to have the Room Assignment Members extract included in the process. These are based on the room assignments.

Custom Org Members Flag- This flag is used to control the extraction of the Custom Org Members file. Valid values are Y and N. Enter Y to have the Custom Org Members extract included in the process. See Section 3.1.11 for more information regarding the use of custom organization memberships.

Org Relationship Roles Flag - This flag is used to control the extraction of the Org Relationship Roles file. Valid values are Y and N. Enter Y to have the Org Relationship Members extract included in the process. See Section 3.1.9 for more information regarding the configuration of Org Relationship Roles.

Organizations File- Enter the filename to use for the Organizations extract. When the extract is processed this will be the name of the Organizations extract.

Org Membership File - Enter the filename to use for the Org Membership extract. When the extract is processed this will be the name of the Org Membership extract.

Org Relationships File - Enter the filename to use for the Org Relationships extract. When the extract is processed this will be the name of the Org Relationships extract.

32

3.1.7 XPAR6 - Outcome Extract Parameters Form

The Outcome Extract Parameter form is a detail screen accessed from XPAR. It is used to configure the parameters for the Outcomes extract. The Outcomes extract contains i the outcomes of courses completed such as mid-term and final grades. Please refer to the Appendix for the descriptions of each field in the Outcomes extract.

Outcome Savedlist Name - Enter the Savedlist name used to generate the Outcomes extract. This extract is created based on the Colleague Student ID. Users must maintain the query used to create the savedlist and include any limiting criteria within it to make sure the savedlist includes the appropriate keys.

Outcome file - Enter the filename to use for the Outcomes extract. When the extract is processed this will be the name of the Outcomes extract.

33

3.1.8 XPAR7 - Admissions Score Parameters Form

The Admissions Scores Parameters form is used to configure the parameters for the Admissions test scores and High School GPA. The Admissions extract contains several test scores including the individual components for SAT, ACT and TOEFL.

High School Transcript Type (XIDP.SF.ADM.HS.GPA.TRAN.TYPE) - This indicates the transcript type

(from the TRANSCRIPT.TYPE valcode table in CORE) that corresponds to a High School INSTITUTIONS.ATTEND record. The INSTA.EXT.GPA field will be used to report the High School GPA on the extract.

Admissions Test Name (XIDP.SF.ADM.TEST.NAME) - These represent the tests that are available in the Starfish system. Additional tests cannot be added to this list.

Score Type to Extract (XIDP.SF.ADM.TEST.SCORE.TYPE) - This represents the manner in which the test scores will be extracted for the various tests. The values are controlled by the valcode table XSF.TEST.SCORE.TYPE (ST).

34

3.1.9 XPAR8 - Admissions Test Non-Courses

The Admissions Test Non-Courses Parameter form is used to further configure the admissions test scores. For each test score listed on XPAR7, the ability is available to detail down to XPAR8. On this form the Non-Course records are entered that correspond the test. Usually these non-courses will all correspond to the same test. In certain circumstances, such as a placement test, several tests may need to be included. All non-courses that correspond to the desired tests should be specified in the “Corresponding Non-Courses” list. To differentiate which test is being reported, a test score offset is used. This offset value is added to the non-course test score before the score is extracted.

Corresponding Non-Courses (XIDP.SF.ADM.TEST.NON.COURSE) - For each test the corresponding

Non-Course records need to be indicated. This is used by the extract process to identify the various tests.

Non-Course Status (XIDP.SF.ADM.TEST.NC.STATUS) - This indicates the accepted status of the non-courses. By default this is “AC”.

35

Test Score Offset (XIDP.SF.ADM.TEST.OFFSET) - If needed, this field allows for an offset score to be entered. This should be used if the list of non-course records correspond to more than one test. Each test included should have a corresponding offset. This offset score is added to the test score and will help differentiate the test being reported.

3.1.10 XSOM - Starfish Org Members Configuration

The Starfish Org Member Configuration form serves two purposes: First, an Organization will be created in Starfish and sent in the filename defined on XPAR5 in the Organization File option (generally this should be organizations.txt) for each unique Starfish Code and Starfish Org Description listed on the screen. Secondly, this form associates Members with the Organization. This is done by defining Colleague Campus Org IDs (and Optionally Org Roles) and associating them with the Organization in Starfish. Each membership row needs to have a Role in Starfish, which is set in the Starfish Role column.

Colleague Campus Orgs Code - Colleague Campus Orgs to include in the Organizations / Org Members extracts

Camp Org Role - Colleague Campus Org Roles to limit the selection to include

36

Starfish Org Code - Starfish Org Code to send; this can be used to merge two Campus Orgs form Colleague into one Organization in Starfish; it can also be used to translate Campus Org Codes from Colleague to different Organization codes in Starfish.

Starfish Org Description- Starfish Organization Name to put into the extract for the Organizations extract

Starfish Role- Starfish Role Description to send in the Membership rows of data.

37

3.1.11 XSCM - Starfish Custom Org Members

The Starfish Custom Org Members Configuration form builds Organizations and Organization Memberships based on the data entered on the form. Custom Organization Memberships can be defined in two ways, by query or by user attribute. If an Org Member Query is specified, the query will be executed and the selected PERSON records will be added to the organization, provided they are included in the users extract. If an Attribute Name is specified, the corresponding attribute, as defined on the XIDA form, will be used to determine whether the user belongs to the organization. Attributes must belong to the SFCUSTORG domain to be used on the form and must return a "Y" for users who belong to the organization.

Starfish Org Code – This is the organizations code that is sent to Starfish in both the Organizations

and the Org Members files. Starfish Org Description – This is the organization description that is sent to Starfish in the

Organization file. Starfish Role – This is the Role that is sent to Starfish for the members in the Org Membership file. Attribute Name – This field is the name of a SFCUSTORG attribute used to determine members of

the organization. If an Org Member Query is specified for the custom org, the Attribute Name cannot be used.

38

Org Member Query – This is a custom query that can be used to determine who the members of the organization are. Org Membership records will be created for each person that is selected by the associated query. If an Attribute Name is specified for the custom org, the Org Member Query cannot be used.

3.1.11.1 Custom Org Members - Query Detail

Data Entry for the Org Member Query can be done from the standard detail edit form or using the text editor.

39

3.1.12 XSOA - Starfish Org Advisor Configuration

The Starfish Org Advisors Configuration form allows Role-Based Relationships to be built and sent to Starfish. This form is based on records within the CAMPUS.ORG.ADVISORS file within Colleague. Advisors in Campus Org Advisors will be associated with the Starfish Organizations by relationships. Once the Membership Rows are imported into Starfish, a background process runs and builds the relation between the Advisors and the Organization Members built on the other Organization forms. Organizations are built based on the Starfish Organization Code and the Starfish Organization Description.

Colleague Campus Orgs Code – Enter the Colleague Campus Orgs IDs to be included in the Organizational Relationship mapping.

Camp Org Role – Enter the Colleague Role code to use for limiting matches. Starfish Org Code – Enter the Starfish Org Code to send; this can be used to merge two Campus Orgs

form Colleague into one Organization in Starfish; it can also be used to translate Campus Org Codes from Colleague to different Organization codes in Starfish

40

Starfish Org Description Role - Starfish Organization Name to put into the extract

41

3.1.13 XSOR - Starfish Org Members Room Configuration

The Starfish Org Members Room Assignment Configuration form will build Organizations based on the Starfish Org Code and the Starfish Org Description. Organization Memberships will be created for people who have a Room Assignment in Colleague matching the Location, Building and Status of the Room Assignment configured here.

Building Location – Colleague Location Code used to limit Room Assignment records to be included in the Org Membership.

Building Code - Colleague Building Code used to limit Room Assignment records to be included in the Org Membership.

RMAS Status - Colleague Room Assignment Status Code used to limit Room Assignment records to be included in the Org Membership.

RMAS Staff Code - Colleague Room Assignment Staff Indicator used to limit Room Assignment records to be included in the Org Membership.

Starfish Org Code – Starfish Organization Code used in the Organizations and Org Memberships files.

42

Starfish Org Description – Starfish Organization description to use in the Organizations file. Starfish Role – Starfish Role to send with the Org Memberships that are associated with the

configuration

43

3.1.14 XIDA - Attribute Configuration

The IData Attribute Engine allows the user to add named value pairs (attributes) to the standard Attributes extract. The extract calls the Attribute Engine with a predetermined array of data elements for each record processed. The Attribute Engine passes the appropriate data elements into each subroutine used to calculate the return values. The calculated values and their associated names are returned to the extract process. The data elements sent to the Attribute Engine by the extract process are identified in a Valcode table with the name of the extract and the position in the array. The Attribute Engine configuration form indicates the subroutines used to calculate the desired values and the data elements to send to the subroutine. The data elements from the extract can be used as input to the subroutine in any order. The data elements used and their order are indicated on the Attribute Engine configuration form.

Domain – This is the Domain that the attributes will be generated for. (e.g. STARFISH). The Domain must exist in the XID.DOMAIN Valcode table. When the Domain name is entered, the subroutines for that Domain will be displayed.

Argument List – This is a detail button to the XIDA2 form to display the arguments available to use in the subroutines for this Domain.

44

Attribute Name – This is the name used to identify the data value generated by the subroutine. It is used in a named value pair in the extract.

Req – This is a Y/N flag indicating whether a null value will be included in the return list of associated names and values if there is no data returned by the subroutine. If the flag is ‘Y’ and there is no value returned by the subroutine, the name of the attribute is returned with an associated null value.

Subroutine Name – This is the name of the subroutine used to calculate the value for this attribute. It must exist in the VOC.

Subroutine Arguments – This is a comma-delimited list of arguments to send to the subroutine. The values can be ‘OUT’, a literal within quotes, or a number corresponding to the argument list for the Domain.

45

3.1.15 XIDA2 - Domain Argument List

This form displays the arguments available to use in the subroutines for this Domain. It is used in conjunction with the XIDATA form to define the custom subroutines.

Num – This number corresponds to the number listed in the Subroutine Arguments field on the XIDATA form. It is used to translate into the field name in the Argument column.

Argument – This is the list of available arguments for the particular domain. Each argument corresponds to an argument number in the Num column.

46

3.2 Extract Process Execution (Front End Screen)

3.2.1 XSFF - Starfish Extract Parameter Flags

This form allows the user to indicate which individual extract files should be built when the Colleague to Starfish Extract form is executed. This could be helpful if there is no need for all extracts. This can be especially useful during testing.

47

3.2.2 XSFE - Colleague to Starfish Extract Form

The Colleague to Starfish Extract form allows the user to toggle which batch processes will be executed. Each batch process builds one or more extract files. Extracts will only be built if the flag is set to Yes for each of the individual extracts. To change the individual extract flag parameters, use the XSFF form. For any of the batch processes marked as Yes, those will be executed immediately upon finishing out of the screen.

The Include flags allow the user to toggle individual extracts on and off. The valid values are Y and

N. Entering Y includes the extract in the process. Run User, Section, Teaching, Enrol, Outcome, Admissions Batch - This flag controls if XSFB01 is run

or not. This program produces the User, Section Teaching Assignments Enrollment, Course Outcome, Admissions and Demographics files. Valid values are Y and N.

Run Orgs, Members, Roles Batch - This flag controls if XSFB02 is run or not. This program will produce the Organizations, Org Members from Campus Org Members, Org Members from Room Assignments, Org Members from Student Home Locations, Org Members from Enrollment Locations. Valid values are Y and N.

Run User Attributes Batch - This flag controls if XSFB03 is run or not. This program will produce the User Attributes extract. Valid values are Y and N.

Run Custom Org Members Batch - This flag controls if XSFB04 is run or not. This program will produce the Custom Org Memberships extract. Valid values are Y and N.

Run Admissions and Acad Status Batch - This flag controls if XSFB06 is run or not. This program will produce the Admissions and Acad Status extract. Valid values are Y and N.

48

Copy files to Starfish SIS Adapter Directory - This controls if once the files extracted are copied from Work Directory to the SIS Adapter Directory. Valid values are Y and N.

3.2.3 XSFL - Starfish Extract Batch Locks

The Starfish Extract Batch Locks form is a utility screen that allows the user to check on the Colleague to Starfish Extract batch processing. Each batch process involved in building the extracts has a lock file associated with it that prevents the batch from being executed while it is currently in the process of running. If this were to occur, the extract files would be compromised. This screen will display the lock status for each of the extract batch processes. If a batch process shows a status of locked, it will include the date and time the lock was obtained. This indicates when the batch process was started. If it is clear that the batch process is no longer running, but the lock is still present – this will prevent subsequent execution of the batch process. To remove the lock manually, in this uncommon situation, enter a Y next to the batch that needs to be unlocked. Updating from the screen will unlock any batch process where this flag was set to Yes.

49

4 “How-To” guides

4.1 Adding a new Term Terms are defined on the XPAR form. The specified terms are used for record selection when extracting data from Colleague. Multiple terms can be specified on this form. The data extracted is associated with a term that is present in this list. If a term is removed, the extracts will no longer send information for data pertaining to that term. If terms are added to XPAR, subsequent extracts will send information related to the specified term(s).

4.2 Adding a new Campus Organization There are several steps involved in setting up a campus organization, roles and defining the associated memberships for use with the Starfish extracts. In some cases, the organization and org roles need to be created within Colleague before the membership information can be populated for the Starfish extracts.

4.2.1 Adding Organizations

For campus organization members and campus organization advisors, the organization needs to be created within Colleague using the Campus Organization and Campus Organization Roles forms. See Datatel's documentation for further information. Some organizations can be defined directly within the Starfish configuration forms. See section 4.2.3 Adding Memberships below for more information.

4.2.2 Adding Roles

Depending on how your organizations are setup, organization roles may also need to be created. This will provide a further level of detail to differentiate members of an organization. See Datatel's documentation for further information on how to create these records in Colleague. As it relates to the Starfish configuration, the organization members and organization advisors forms allow for the entry of an organization role. See section 4.2.3 Adding Memberships below for more information.

4.2.3 Adding Memberships

Each organization, whether or not it is created within Colleague, needs to be setup for Starfish to pull the corresponding organization members. Depending upon the type of organization, enter the organization member setup on one of the following forms:

XSOM – Starfish Org Members Configuration (based on campus org members) See section 3.1.10 for more information.

XSOA – Starfish Org Advisor Configuration (based on campus org advisors) See section 3.1.12 for more information.

XSCM – Starfish Custom Org Members (uses a custom query to select the members) See section 3.1.11 for more information.

XSOR – Starfish Org Members Room Configuration (based on room assignment) See section 3.1.13 for more information.

50

4.3 Running a single extract for testing purposes This section will explain how to process a single extract and subsequently how to reset it to run all the extracts again. Running one extract is very uncommon and most likely only needed for testing purposes.

NOTE: If a single extract is executed, make sure to reset the extract flags to their previous status afterwards as this will impact any scheduled extract processing. If there are nightly extracts scheduled, they will continue to process only the single extract for that particular batch until the flags are reset. Refer to the QuickStart guide for your institutions setup, which should indicate the appropriate settings for these extract flags.

4.3.1 Process a single extract

On the form XSFF – Starfish Extract Parms Flags, find the desired extract to be executed and make sure the flag is set to Yes. Note the corresponding batch for this extract. There are five batches listed on the form and the extracts included in each batch are listed below the batch with the Yes/No flags. For the other extracts in the same batch, set the individual extract flags to No. Make note of the flags that are changed, so they can be reset after testing. There is no need to change the flags for extracts under the other batches. For example, to run the Admissions extract, set the “Student Admissions Extract” flag to Yes. The only other extract in this batch is the “Student Acad Status” extract. Set that flag to No.

Now on the form XSFE – Colleague to Starfish Extract, find the same batch and set the batch flag to Yes. In our example this would be the last one listed - “Run Admissions and Academic Status Batch”. Set the flag for all the other batches to No. Depending on your testing needs, you can set the final flag on XSFE to Yes if you want the resulting data extract file to be copied to the Starfish SIS Adapter directory. Updating from this form will execute the batch and should produce the data file for the specified extract.

4.3.2 Reset the extract flags

Once the desired testing is complete, the extract flags need to be returned to their previous state. To do this, return to the XSFF – Starfish Extract Parms Flags form and reset the extract flags to Yes, referring to notes made on the status of these flags when previously changed for testing purposes. After updating from this form, all subsequent executions of the batch will process all the extracts with a Yes flag.

51

4.4 Setting up the paragraph A paragraph can be created to help with automation of the extract processes. Below is an example set of paragraphs that can be used for this purpose. One paragraph is for use on a daily basis, while the second is recommended for less frequent execution – typically once per week. Batch XSFB05 should always be executed first and run to completion before the other batches are started. This batch selects the records to be processed and rebuilds the savedlist records that are used by the other batches. The other batch processes can be executed in parallel by using the PHANTOM keyword. If it is preferred, they can be run in serial (without using the PHANTOM keyword). Just know that each of these processes can take an hour or longer to execute. Batch XSFB06 can be run less frequently, as it can take several hours to complete and the data being extracted may not change on a daily basis.

4.4.1 Paragraph Examples

In this example it is recommended that the daily paragraph be run on a daily basis, except the one day per week when the weekly paragraph is scheduled to run. Both paragraphs should not be run at the same time or on the same day, as the weekly paragraph includes all the processes that are executed in the daily paragraph.

4.4.1.1 XSTARFISH.EXTRACT.DAILY :ELE VOC XSTARFISH.EXTRACT.DAILY

0001: PA

0002: SETPTR ,,,,,3,NOFMT,BRIEF,BANNER XSTARFISH_EXTRACT_LOG

0003: XSFB05

0004: PHANTOM XSFB01




0008: * XSFB06 takes a while to process so it should not be run

0009: * on a daily basis. In addition it generates the Academic

0010: * Status and Admissions Test Scores; data that most likely

0011: * won't change on a daily basis.

0012: * PHANTOM XSFB06

4.4.1.2 XSTARFISH.EXTRACT.WEEKLY :ELE VOC XSTARFISH.EXTRACT.WEEKLY

0001: PA

0002: SETPTR ,,,,,3,NOFMT,BRIEF,BANNER XSTARFISH_EXTRACT_LOG

0003: XSFB05






52

4.4.2 Batch Processes

4.4.2.1 XSFB01 – Users, Relationships, Sections, Enrollments

This batch process will build the following extract files: Users Demographics Relationships Sections Teaching Enrollments Outcomes

4.4.2.2 XSFB02 – Organizations, Org Members

This batch process will build the following extract files: Organizations Organization Members Organization Role Relationships

4.4.2.3 XSFB03 – Attributes

This batch process builds the user attribute extract file.

4.4.2.4 XSFB04 – Custom Organization Memberships

This batch process builds the custom organization membership attributes as defined on the XSCM form.

4.4.2.5 XSFB05 – Record Selection and Savedlist Creation

This batch process refreshes the savedlist records that will be processed by the extract batch programs. This should be executed prior to running the extract programs. The savedlist refresh takes place before the extract programs are executed when running the XSFE process to kick off the extract programs.

4.4.2.6 XSFB06 – Admissions, Academic Status

This batch process will build the following extract files: Admissions Academic Status

53

5 Appendix (Extract fields) This section lists each field that appears in each extract along with a description of each field.

5.1 Users Extract

Field Description

integration_id (REQUIRED) A unique identifier for this data row. This should

change in your SIS very rarely if at all. Not

shown to end users, only to your designated

Tenant Admin user. Do not send Social Security

Numbers.

family_name (REQUIRED) The last name of this person.

middle_name The middle name of this person.

given_name (REQUIRED) The first name of this person.

email (REQUIRED) Email address.

student_id Common ID for any students. Do not send Social

Security Numbers.

user_id (REQUIRED) Log in name for primary access point to Starfish

e.g. Portal.

Gender The gender of this person.

birth_dt The person’s birth date.

Company The employer of the person.

job_title This person’s title.

h_phone Home phone number.

b_phone Work phone number.

m_phone Mobile phone number.

54

available_ind Whether this user should be able to use Starfish.

modified_ts The timestamp of the last modification to this data row.

5.2 Course Sections Extract

Field Description

integration_id

(REQUIRED)

A unique identifier for this data row. This should

change in your SIS very rarely if at all. Not shown to

end users.

course_section_name

(REQUIRED)

The name of this course section.

course_section_id

(REQUIRED)

The ID for this course section.

start_dt The start date.

end_dt The end date.


term_id A unique identifier for the term. If your terms also have

multiple sessions, then a session identifier is required as

well.

These had to be previously provided to Starfish.

55

5.3 Admissions Extract

Field Description

user_integration_id (REQUIRED) A unique identifier for the user related to the attributes in

this record.

sat_composite A numeric value representing overall SAT score.

sat_math A numeric value representing the student’s SAT®

Mathematics score ranging from 200-800.

sat_reading A numeric value representing the student’s SAT®

Critical Reading score ranging from 200-800.

sat_writing A numeric value representing the student’s SAT® essay

score ranging from 2-12.

act_composite A numeric value representing overall ACT score.

act_math A numeric value representing the student’s ACT®

Mathematics score ranging from 1-36.

act_english A numeric value representing the student’s ACT®

English score ranging from 1-36.

act_science A numeric value representing the student’s ACT®

Science score ranging from 1-36.

act_writing A numeric value representing the student’s ACT®

Writing score ranging from 1-36.

act_reading A numeric value representing the student’s ACT®

Reading score ranging from 1-36.

toefl_composite A numeric value representing an international student’s

overall English language ability ranging from 310-677.

toefl_listening A numeric value representing an international student’s

English language listening ability ranging from 31 – 68.

toefl_structure A numeric value representing an international student’s English language structure / writing ability ranging from

31 – 68.

toefl_reading A numeric value representing an international student’s

English language reading ability ranging from 31 – 67.

56

high_school_gpa A numeric value (accurate to 3 decimal places) representing the student’s high school grade point average

range from 0 to 4, although over 4 is possible.

If a student attended more than one high school provide

their last high school GPA.

placement_math An institution specific placement test for mathematics skills with a numeric score.

placement_reading An institution specific placement test for reading skills

with a numeric score.

placement_writing An institution specific placement test for writing skills

with a numeric score.


57

5.4 Student Demographics Extract

Field Description

user_integration_id (REQUIRED) A unique identifier for the user related to the attributes in

this record.

pell_grant_eligible Is the student eligible for financial aid under the Pell Grant financial aid rules? In 2012 fields to track pell eligibility

changed.

race_ethnicity A student’s race/ethnicity provided as a space-separated list

of abbreviations: Hispanic or Latino (“HI”)

Alaskan Native or American Indian (“AI”)

Asian (“AS”)

Black or African American (“BL”)

Native Hawaiian or other Pacific Islander (“NH”)

White (“WH”)

gender A student’s gender.

first_generation_student Did none of the student’s parents attend any college?


58

5.5 Attributes Extract

Field Description

user_integration_id (REQUIRED) A unique identifier for the user related to the

attributes in this record.

attribute_key (REQUIRED) The unique identifier of the attribute you are setting for the user. A unique list of all attributes

must be sent to Starfish Product Support prior to

sending the first user attributes file.

attribute_value (REQUIRED) The current value for the attribute. This is not a

value displayed within the system, but should uniquely identity the current state of the attribute.

modified_ts The timestamp of the last modification to this

data row.

59

5.6 Enrollment Extract

Field Description

course_section_integration_id (REQUIRED) A unique identifier for the course section related to this

enrollment.

user_integration_id (REQUIRED) A unique identifier for the user related to this enrollment.

user_role (REQUIRED) The role of this user within the course section.

available_ind (REQUIRED) Whether this enrollment should be shown to students in

Starfish- assuming within term display dates.


60

5.7 Teaching Assignment Extract

Field Description

course_section_integration_id (REQUIRED) A unique identifier for the course section related to this

enrollment.

user_integration_id (REQUIRED) A unique identifier for the user related to this teaching assignment.

user_role (REQUIRED) This should always be set to INSTRUCTOR or TA.

available_ind (REQUIRED) Whether this enrollment should be shown to students in Starfish-

assuming within term display dates.


61

5.8 Relationships Extract

Field Description

parent_integration_id

(REQUIRED)

A unique identifier for the parent user in the role relationship.

parent_role (REQUIRED) The name of the parent role.

child_id (REQUIRED) Identify the user(s) for whom the parent user should be

assigned the parent role relationship.

child_role (REQUIRED) The name of the child role.

term_id (REQUIRED) The ID /prefix for the term in which the role relationship

should be assigned.

62

5.9 Course Outcomes Extract

Field Description

user_integration_id (REQUIRED) A unique identifier for the user related to this score.

course_section_integr ation_id

(REQUIRED)

A unique identifier for the course section related to these grades.

midterm_grade The numeric score value out of 4.0 or a letter score previous

provided as a grade scale to Starfish.

final_grade The numeric score value out of 4.0 or a letter score previous

provided as a grade scale to Starfish.

credit_hours A numeric (accurate to 3 decimal places) value for the number

of credit hours for the course.

enrollment_type The expected type of grade.


63

5.10 Academic Status Extract

Field Description

user_integration_id (REQUIRED) A unique identifier for the user related to this score.

cumulative_gpa A numeric value, accurate to 3 decimal places, for

student’s overall GPA.

degree_gpa A numeric value, accurate to 3 decimal places, for

student’s GPA within their degree.

total_credit_hours A numeric value, accurate to 3 decimal places, for the

number of credit hours the student has earned at the

institution.

primary_major The student’s major focus of study.

primary_major_code The initials used to identify the primary major.

secondary_major The student’s minor focus of study.

secondary_major_code The initials used to identify the secondary major.

class_level A numeric value representing the student’s class level

(Freshman, Sophomore, etc.) at the institution.

Program The student’s program of study at the institution.

admitted_term_id A unique identifier for the term in which the student was admitted to the institution. If your terms also have multiple

sessions, then a session identifier is required as well.

This ID had to previously provided to Starfish.


64

5.11 Organizations Extract

Field Description

integration_id

(REQUIRED)

A unique identifier for this data row. This should change in your

SIS very rarely if at all. Not shown to end users.

organization_name (REQUIRED) The name of this organization.

organization_id (REQUIRED) The ID for this organization.

start_dt The start date. Used if the section start date is different from the

term start date.

end_dt The end date. Used if the section end date is different from the

term end date.


term_id A unique identifier for the term. If your terms also have multiple

sessions, then a session identifier is required as well.

These had to be previously provided to Starfish.

65

5.12 Organizations Membership Extract

Field Description

course_section_integration_id (REQUIRED)

A unique identifier for the organization related to

this membership.

user_integration_id (REQUIRED)

A unique identifier for the user related to this

membership.

user_role (REQUIRED)

This should always be set to INSTRUCTOR, TA,

or STUDENT.

available_ind (REQUIRED)

Whether this enrollment should be shown to students in Starfish- assuming within term display

dates.


starfish extract administrator guide south dakota...

Documents