This chapter provides an overview of the File Parser process and discusses how to:
Set up field conversion definitions.
Set up context definitions.
Set up file mapping definitions.
Run the File Parser process.
Map the file parser for population selection.
The File Parser process enables you to convert key data from an external file into PeopleSoft data and place it into tables in your Campus Solutions database. The external file can be a delimited file or a flat file. It can be a simple file with one row type or a complex file with several row types. If your institution routinely receives an external file from which you need to move data into your database, consider using the File Parser process to expedite the entry of that data. Whether the file is a small one that your institution receives daily or a large one that is received annually, the one-time setup of the File Parser process for that file can save significant data entry time.
The PeopleSoft system delivers interfacing staging tables in SQL for the File Parser process. A staging table accepts data converted from the external file and makes it accessible to PeopleSoft Campus Solutions processes. A process can then access the converted data, validate it, and move it to the target Campus Solutions tables.
To set up and use the File Parser process for an external file:
Set up a field conversion definition that identifies a field values to convert from the external file to the target staging table.
Set up context definitions that identify how to convert the data and in which staging tables to place the converted data to hold it for processing. Each context must also identify the parent-to-child relationship of the staging tables.
Set up a file mapping definition that associates fields on the external file with the context definition to use.
View the layout of each staging table, modify it, and map the fields from it to the target tables.
Preview the hierarchical record layout and the converted data before you move the data into the staging tables.
Run the File Parser process to convert the data and place it into the staging tables.
Note. PeopleSoft Enterprise Financial Aid incorporates the File Parser utility automatically in its External Awards process to convert data from an external award data file into external award staging tables. The process uses a predefine file definition and conversion context delivered by the PeopleSoft system. You do not have to define the field conversion or set up the context. However, you must map fields from the required fields record in the context to the target table as described in this chapter.
See Setting Up External Awards.
See Managing External Award Reporting.
To set up field conversion definitions, use the Field Conversion (SCCFP_CNVR) and Copy Field Conversion Definition (SCCFP_CPY_FLD_CNVR) components.
This section discusses how to:
Set up a field conversion definition.
Copy a field conversion definition.
Page Name |
Object Name |
Navigation |
Usage |
SCCFP_CNVR |
Set Up SACR, System Administration, Utilities, File Parser, Field Conversion Definition |
Identify field values to convert from an external file. |
|
SCCFP_CPY_FLD_CNVR |
Set Up SACR, System Administration, Utilities, File Parser, Copy Field Value Conversion |
Copy an existing field conversion definition, save it with a new definition name, and change it as necessary to create another definition. |
Access the Field Conversion Definition page.
Field conversion definitions are optional. They are relevant only if the external file contains field values that are different from the PeopleSoft system values. Use the Field Conversion definition to define the mapping of external file values to the internal PeopleSoft system values. For example, if the external file uses the value FALSE but the internal value is F, you should create a mapping to convert the value when the file is loaded.
Conversion Profile |
Enter a name for the conversion of this external file. Consider naming the profile the same name as the external file or a name that otherwise reflects the type of data to load. (Optional) Enter a long description to further identify this conversion profile. |
Conversion Fields
Conversion Field |
Enter a name for converting each field. Add as many conversion fields as necessary to identify each field to convert from the external file. |
Record (Table) Name and Field Name |
Enter a record from which to prompt for target field names. |
Unmatched Value Handling |
Indicate what the File Parser process should do if it cannot map the field value of the conversion field to the field in the target staging table field value. The choices are: Default Value: Use the default value that you specify. Error - Halt Processing: Cease loading data into the staging table and display the message that you specify. |
Default Value |
When you enter Default Value in the Unmatched Value Handling field, the Default Value field appears. You must specify the default value to use. If you do not enter a default value, a blank or null value becomes the default value. If the value of the field cannot be mapped, the process will leave the value blank and continue mapping. |
Message Set Number and Message Number |
When you enter Error - Halt Processing in the Unmatched Value Handling field, the Message Set Number and Message Number fields appear. You must identify the error message to use. |
Conversion Field Value
File Value |
Enter each possible value for this field from the external file. |
Internal Value |
Enter the correlating PeopleSoft value. |
Access the Copy Field Value Conversion page.
After you copy a field conversion definition and save it with a different name, you can modify it as necessary to create another definition.
On the search page, select the field conversion definition to copy, and then enter the name of the new conversion definition and save the page. To edit the new definition, access it from the Field Conversion Definition page.
This section discusses how to:
Set up a context definition.
View the record tree.
Copy a context definition.
Page Name |
Object Name |
Navigation |
Usage |
SCCFP_CNTXT_DFN |
Set Up SACR, System Administration, Utilities, File Parser, Context Definition |
Identify the field names and formats to use for converted data and the staging tables in which to place the converted data and hold for processing. |
|
SCCFP_TREE_RECPRVW |
Set Up SACR, System Administration, Utilities, File Parser, Context Definition, Record Tree |
View the record tree to determine the hierarchical layout of the staging tables. |
|
SCCFP_CPY_CNTXT |
Set Up SACR, System Administration, Utilities, File Parser, Copy Context Definition |
Copy an existing context definition with a new definition name. |
Access the Context Definition page.
Note. The PeopleSoft system currently delivers a predefined External Award Load context definition for the Financial Aid External Awarding process. The context definition identifies the fields in the External Award staging table that can accept converted external file data. You can modify the context definition to prevent fields from being visible, but you should not make any other modifications to the predefined definition. Changing the record or field names or their values or making any other modifications can cause the External Award process to fail.
See Setting Up External Awards.
Context Name |
Enter a name for this set of staging tables. |
Conversion Profile |
Enter the field conversion profile to associate with this context. You can enter the profile here or on the File Mapping Defintion page when you map the files. If you enter a profile here, it appears as the default profile on the File Definition page. You can change it on the File Mapping Definition page. The conversion profile entered on the File Mapping Definition page takes precedence. |
Staging Table Records
Record |
Enter the staging table to use. When you enter a table name, the system displays the fields from that table. Add as many staging tables as needed for this conversion context. |
Sort Order |
Enter the order in which the table should appear in the hierarchy of staging files for mapping. |
Parent Record |
Enter the name of this staging table's parent record, if any. |
Synchronize Record Fields |
Click to compare fields in the staging table to fields in the target table. If the fields in the tables are different, the system adds and deletes fields in the staging table until it contains only the fields that are in the target table. The changes are for the staging table as associated with this context definition only. |
Staging Table Fields - Mapping Tab
Field Name |
The system lists each field in the specified staging table. When you synchronize the tables, the system updates the list to include only the synchronized fields. |
Mapping Action |
Enter the value to use for this field. Values are: Default Value: Enter a hard-coded value set for this field, including any variables that are supported. Supported variables include %Date, %DateTime, %OperatorID, %EmployeeID, %MapID (the current file parser map ID), %MapName (the current file parser map name), %FileName, and a number representing the file row number. Inherit from Parent: Enter the value from the field of the same name on the parent record. No Default: Enter no value. The field must be mapped from the File Mapping Definition component. Process Instance: Use the current process instance. Sequence: Enter a numerical sequence that is incremented by one for each record inserted. Unique Counter: Use the next number from the supplied counter record or field pair. |
Visible for Mapping |
Select this check box for the field to be available on pages in the File Mapping Definition component. If a field is premapped and the user should not change the mapping, clear the check box to prevent it from appearing on pages in the File Mapping Definition componentpage. Hiding premapped fields minimizes confusion. |
Value |
The corresponding hard-coded value appears when the Mapping Action field is set to Default Value. |
Staging Table Fields - Formatting Tab
The Formatting tab is available only if Date or Number is selected for one or more field types.
Access the Context Definition page.
Field Format |
This field appears if formatting options exist. Enter the format to use for the field value. Each field has options relevant to that data type. For example, a date type format can be DDMMMYY, DDMMMYYYY,DDMMYY, and so on. A character type format uses the case controls Lower, Proper, and Upper. |
Date Separator |
This field appears only for date fields. Enter the separator, if any, to use to separate day month and year in whatever date format you enter. For example, if you enter a format of MMDDYYYY and a separator of /, the value might be 06/25/2007. The system ignores leading zeros when a separator is used. If a separator is not used, leading zeros are required. |
Staging Table Fields - Counter Definition Tab
The Counter Definition tab is available only if Number is selected for one or more field types and the number field has a unique counter.
Access the Context Definition page - Counter tab.
Counter Record Nameand Counter Field |
Enter the record (table) and field from which to take the next sequential number. |
Access the Record Tree page.
Staging Table Mapping Tree
Click the Refresh Layout Tree link to view the hierarchy of staging tables for this conversion.
Refresh the layout tree after you add staging tables or change the sort order.
Access the Copy Context Definition page.
You can copy an existing context definition and save it with a different name. You can then change the new context definition as necessary.
On the search page, select the context definition to copy. Then, enter the name of the new context definition and save the page. To edit the new definition, access it from the Context Definition page.
This section discusses how to:
Create a file definition.
Define a file layout.
Map the file and convert the data.
Preview the record tree.
Preview the converted data.
Copy a file mapping definition.
Page Name |
Object Name |
Navigation |
Usage |
SCCFP_FILE_DFN |
Set Up SACR, System Administration, Utilities, File Parser, File Mapping Definition |
Map the external file to the context containing the destination records. |
|
SCCFP_FILE_LAYOUT |
Set Up SACR, System Administration, Utilities, File Parser, File Mapping Definition, File Layout |
Identify the fields from the external file, and specify the action to use to convert data and place it on the destination staging table records. |
|
SCCFP_FILE_MAP |
Set Up SACR, System Administration, Utilities, File Parser, File Mapping Definition, Mapping |
Map the fields in the external file to fields in the destination record. |
|
SCCFP_FILE_PRVW |
Set Up SACR, System Administration, Utilities, File Parser, File Mapping Definition, Preview Layout |
View the record tree to determine if the correct data is set to be mapped and converted. |
|
SCCFP_FILE_PRVW2 |
Set Up SACR, System Administration, Utilities, File Parser, File Mapping Definition, Preview Data |
Identify the external file and view the data as it will be converted before running the File Parser process to place the converted data into the destination records. |
|
SCCFP_CPY_MAP_DFN |
Set Up SACR, System Administration, Utilities, File Parser, Copy File Map Definition |
Copy an existing file map definition under a new definition name. |
Access the File Definition page.
Map Name
Map Name |
Enter a name for this mapping of the external file. |
Status |
Enter the status of file mapping definition. The default value is Pending when the mapping definition is initially added. Only file mapping definitions with an Active status are available for selection when converting external file data. |
Context Definition |
Enter the context definition to use for this mapping. Context definitions are set up on the Context Defintion page. If a conversion definition is associated with the context on the Context Definition page, the system displays the name of it in the Conversion Definition field. |
File Type |
Specify the type of the external file, either Flat or Delimited. If you enter Delimited, you must also verify or enter values for the delimiter and the qualifier. |
Delimiter |
Appears only if the file type is Delimited. Enter the item in the external file that signifies the end of one value and the beginning of another. Values are: Comma Pipe Semicolon Tab |
Qualifier |
Appears only if the file type is Delimited. Enter the item in the external file that qualifies the end of one field and the beginning of another. The default qualifier is ” (quotation mark). |
Conversion Definition |
Enter the conversion definition to use. Conversion definitions are set up on the Field Conversion Definition page. If a conversion definition is associated with this context on the Context Definition page, the system displays it as the default value. You can change the conversion definition. |
Multiple Row Types |
Select if the external file contains multiple row types. For example, the external file might have a header row, a detail row, and a trailer or total row. When Multiple Row Types is selected, the File Row Type Detail group box appears, which is where you must identify each row type to which data is to be converted. |
Row Types
This group box is available only when the Multiple Row Types check box is selected.
Name |
Enter a name to describe the general purpose or type of the row. |
Section ID Value |
Enter the type of value that appears in the row. |
Starting Position and Field Length |
Enter the position in which the field value for the row begins in the Starting Position field, and enter the maximum character length of the field to read in the Field Length field. |
Access the File Layout page.
You control the layout of the file by identifying the fields on the external file to be converted. You can either enter file field names from the external file or you can load and populate the fields from the staging table, view the field controls, and make changes as needed.
Row Types
The page contains a row for each row type identified on the File Definition page. Enter data for each row type.
Staging Table and Load Fields |
(Optional) Enter the name of the staging table into which data for this row type is to be placed. Only the staging tables associated with this context are available. Click Load Fields to load a list of the fields from the staging table into the File Fields group box. Loading the fields can save data entry. |
File Fields
The File Fields group box lists the field names to reference in the external file. Use these file names to map to fields on the staging tables on the Mapping page.
File Fields - Location Tab
The Location tab lists the location of the field on the external field. You can view and change the sort order, the field name, and the field type.
For a flat file, the location is the starting position and field length.
For a delimited file, the location is the field number.
Field Type |
Enter the type of field to use. The values are: Character Date Date Time Number Signed Decimal Time |
File Fields - Format Tab
The Format tab enables you to view and change field formats, trim leading and trailing spaces, enter date separators for date fields, and change decimal placement for currency amounts.
File Fields - Propagate Tab
This tab appears for flat files only. The Propagate tab enables you to adjust the starting position and length of a field when a new field is added to an existing definition.
|
Click to decrease the starting position of the field. |
|
Click to increase the starting position of the field. |
Access the Mapping page.
Enter data to define how to update the staging record when the external file is processed. Fields on the staging table may take data directly mapped from the external file or set with a default value when external file is processed.
Note. Click Save on the File Layout page before using the Mapping page. Saving the file mapping definition and layout causes the file field names to be available on the Mapping page.
Row Types
Each row type identified on the File Definition page and designed on the File Layout page is listed in this group box. View or enter mapping instructions for each field to map the field to the staging tables.
Field Mapping
Data in this group box defines how to update the staging tables and fields when the external file is processed.
Record |
Enter the record to use as the staging table. Available records are from the related context definition. When the process runs, it updates the specified staging table with the fields defined in the row type and File Layout page. Once a staging table is selected in the Record field, based on the context definition, all visible fields from the staging table are displayed. Note. If a staging table with mapped file fields has a parent record, you must include the parent record in the field mapping even if the parent has no mapped file fields. |
Row |
Identifies the row of the staging table into which the File Parser process will insert the converted data. Note. In most cases, the row number is 1. However, sometimes one row in the file may need to be normalized into more than one row in the staging tables. For example, PeopleSoft Enterprise Financial Aid's external awards have award files that contain more than one disbursement on a single file row. The External Award staging tables store disbursements in a normalized manner to support a large number of disbursements for each award. To map a single file row to more than one staging table record, you must add rows on the field mapping level. Each of these rows must be mapped to the correct file field. The disbursement table is keyed to a unique sequence and the keys must be correctly mapped. In most cases, set the Mapping Action to Default Value, and enter in the Value field a numeric sequence that equates to the number of disbursements. |
Auto Map |
(Optional) Click for the system to compare fields on the File Layout page to fields in the staging table and place fields with the same name into the staging tables. |
Synchronize to Content |
(Optional) Click for the system to compare fields on the Context Definition page to fields on the Mapping page and to remove fields from the mapping that are not in the context definition. Synchronizing content is helpful when the context definition has been updated after the file mapping definition is created. |
Field Mapping Detail - Mapping Tab
The Mapping tab appears for each record and displays all of the visible fields from the staging table and their mapping actions.
Mapping Action |
Enter the mapping action for the process to use when updating the target staging table. Values are: Default Value to enable you to hard code the value when the file is processed. The Value column appears where you can enter the default value to post to staging table. For example, the External Award staging table (SFA_EASTAGE_DTL) requires that a value posts to the external award report SFA_EA_REPORT_CD field. In most cases the external file will not have a corresponding field for this value. Select Default Value and provide appropriate value in the Value column. Direct from File to update the staging table with a field defined on the File Layout page. The File Field Name column appears, and the available values are fields defined in File Layout page. You can click the Auto Map button to cause the system to populate the File Field Name fields with the available values. Inherit from Parent to carry forward the value from the parent record. None to take no action nor update the staging table field. Process Instance to bring in the current process instance of the batch process. Sequence to assign a unique sequence number, used primarily to create unique key values. Sequencing starts at 1 and increments by 1 for each row retrieved. Unique Counter to assign a unique numeric index created from the next number on the referenced counter record and field. The Population Selection process uses the Peopletools GetNextNumberWithGapsCommit() function to get the next value and update the record. |
File Field Name |
Available when Mapping Action is Direct from File. Available values are fields defined in File Layout page. |
Value |
Available when Mapping Action is Default Value. Enter the value in the correct format for field. |
Field Mapping Detail - Format Tab
The Format tab appears when the mapping action is Default Value.
View and enter data to format the mapped fields.
Field Mapping Detail - Value Conversion Tab
The Value Conversion tab appears when the mapping action is Direct from File. You can optionally assign a conversion value to fields that are mapped directly from the external file.
Access the Preview Layout page.
After you design the layout and map the file fields to the staging tables, click the Refresh Layout Tree button to view the hierarchy of the staging tables and fields; and determine how each field will be updated when external file is processed. You should preview the layout before you run the process to move the data into the target tables.
Access the Preview Data page.
After mapping is complete, you can preview the data in a test file to confirm the file field layout, mapping to staging tables, and field formats and conversions. Perform this preview before you run the process to move the data to target tables. The preview feature shows only the first row of each row type, so you should use a small test file. Large files may waste system resources and be too large to upload as an attachment.
Add Attachment |
Click and browse to attach a sample file. The file to be attached should be small but have at least one row for each file type. |
Preview Data |
Click to display data in the attached file according to the specifications. |
View Attachment |
Click to view the sample file with data. |
Delete Attachment |
Click to delete the sample file. |
Access the Copy File Map Definition page.
This section discusses how to run the File Parser process.
Note. The External Awards process in PeopleSoft Enterprise Financial Aid automatically incorporates the File Parser utility to convert data from an external award data file into the External Award staging tables. Do not run the File Parser process separately, as described in this section, for the External Awards process.
See Managing External Award Reporting.
Page Name |
Object Name |
Navigation |
Usage |
SCCFP_RUNCNTL |
Set Up SACR, System Administration, Utilities, File Parser, Run File Parser |
Enter the path to the external file to be converted, and run the process to convert the data and place it into the staging tables. |
Access the Run File Parser page.
Enter parameters, and then run the File Parser process to convert the data and place it into the staging tables.
File Path |
Enter the path to the external file to be converted. The path must be accessible to Process Scheduler. |
File List Indicator |
Select this check box to indicate that the path contains a list of files to be converted. |
The Population Selection process uses the File Parser process when the selection tool for identifying the population is external file. When using an external file to select IDs for a process, you must map the fields required by the process to the target table fields for the application process that is integrated with Population Selection.
This section discusses how to map the File Parser process for Population Selection.
See Also
Using the Population Selection Process
Page Name |
Object Name |
Navigation |
Usage |
SCCFP_PS_FILE |
Set Up SACR, System Administration, Utilities, File Parser, Population Selection File Map Click the Create File Mapping or Edit File Mapping link in the Population Selection group box on any run control page when the Population Selection tool is an external file. |
Map the File Parser process for integration with the Population Selection process. |
Access the Population Selection File Map page.
If you access the Population Selection File Map page from the Population Selection group box, the system enters the required fields record from Population Selection Context for the application process, and displays the list of fields in the required fields record in the Field Mapping group box. If you manually navigated to the page, you must enter the name of the required fields records in the Required Flds field. When you exit the field, the system displays the fields from that record.
File Mapping Definition
File Mapping |
Enter a name for this mapping. |
Public |
Select to make this mapping accessible for all users to use and update. Clear to make this mapping accessible only to the user who created it. A public mapping is useful for example, when a mapping can be re-used for different files or for files that are refreshed regularly. |
Created/Updated History |
Click to view a history of who updated the mapping and when. |
Required Flds(required fields) |
Enter the name of the record that contains the fields required to identify the population. Note. If you access the page directly from a run control page for a process, the Required Flds field does not appear. The bind record containing the required fields is derived from the Population Context for the process, and the field is hidden. |
File Type |
Specify the type of external file, either Flat or Delimited. If you enter Delimited, you must also verify or enter the delimiter and qualifier. File types are translate values. Do not modify these values. |
Field Delimiter |
Appears only for a file type of Delimited. Enter the value in the external file that signifies the end of one value and the beginning of another. Values are: Comma (default value) Pipe Semicolon Tab Field Delimiter values are translate values. Do not modify these values. |
Field Qualifier |
Appears only for a file type of Delimited. Enter the value in the external file that qualifies the end of one field and the beginning of another. The default qualifier is ” (quotation mark). |
Header Row and Header Row Number |
The Header Row check box and the Header Row Number field appear only if the file type is Delmited. If the file that contains the IDs to process includes header rows, for example column titles or to display a title for the document, select the Header Row check box and enter the number of rows in the uploaded file used as the header. The Population Selection process evaluates values after the end of the number of header rows specified. If you are unsure if the uploaded file has header rows or unsure of which row to use as the header, click Cancel to return to the run control page. Then, click View File to view the delimited file and validate and count the header rows if they exist. Return to the mapping and continue. |
Map From Header |
Appears only when Header Row is selected. Click to map the column names in the uploaded spreadsheet to the fields required to run the process. The system reads the name of each column in the spreadsheet, compares it to the fields listed in the Field Mapping group box, and if it finds a match, enters the column number in theField Number field for that field. For example, assume that CAREER is the title of the second column in the spreadsheet that you uploaded. If the ACADEMIC_CAREER field appears in the list of fields in the File Mapping group box, then the system sets the Field Number field to 2. The Mapping From Header feature does not map columns in the spreadsheet that do not match any fields in the File Mapping group box. To map these, you must manually enter the column number in the Field Number column. Note. The system uses the short name of the fields to map to the columns in the spreadsheet because PS Query uses the short name as the default value to name the column names when the query results are downloaded into Microsoft Excel. See Enterprise PeopleTools PeopleBook: PeopleSoft Query,“Downloading Queries.” |
Upload File, Delete Attachment, and View Attachment |
These buttons appear onlly when you navigate to the Populations Selection File Map page from the menu. Click to upload, delete, or view the external file to use. Warning! Consider these conditions when uploading an external file to parse for use with the Population Selection process:
|
Field Mapping - Mapping Tab
Field Name and Required |
Displays the name of each field in the required fields record that is specified in the Population Selection Context, and indicates Yes if the uploaded file must have the same field for the process to run. Required fields also require a Field Number to map the field to the corresponding column in the uploaded spreadsheet. Fields marked No are optional. They do not need to be in the spreadsheet and do not required a Field Number value unless you choose to use them, in which case you can manually enter the corresponding column number in the Field Number field. |
File Column Header |
Appears only when File Type is Delimited. and Header Rowis selected. When the Header Row check box is selected, the system enters the short name of the field in the File Column Header column. |
Field Number |
Appears only when File Type is Delimited. Displays the number of the column in the uploaded file that corresponds to this field. |
Starting Position and Field Length |
Appear only when File Type is Flat. Enter the starting position and the field length for each required field. |
Field Mapping - Format Tab
Field Format |
Appears if formatting options exist. Enter the format to use for the field value. Each field has options relevant to the data type. For example, possible date type formats are DDMMMYY, DDMMMYYYY,DDMMYY, and so on. Possible character type formats include the case controls Lower,Proper, and Upper. |
Date Separator |
Appears only for date field types. Enter the symbol to use to separate the date parts. |
Decimal Position |
Appears only for number field types. Enter the position to use for placing the decimal. |
Trim |
Appears only for fields that are not date or time field types.. Select to trim leading or trailing spaces in fields. |
Warning! After entering mapping information, preview the results before running the File Parser process to confirm that the column titles match the information inside the columns and that the mapping and results are otherwise correct. To preview the results, access the standard Population Selection group box in the run control component of the application process. If the Population Selection check box is available, select it. Then set the Selection Tool to External File, upload the file, select the mapping name you just created, and click the Preview Selection Results link. The Preview Selection Results link appears only if your institution set the external file selection tool to allow preview results at installation.